{ "schemaVersion": "1.0.0", "contractVersion": "2026-08-25.9", "dictionaries": { "currencies": { "id": "currencies", "title": "Currency codes", "description": "Published ISO-style reference codes, with normalized three-digit numeric codes. This is not the complete internal currency dictionary or a list of currencies enabled for a profile. Currency input is a string key without lexical length or pattern validation; crypto may use asset/network keys such as USDT_TRC20. Submitting a key does not guarantee dictionary membership, access or routing.", "items": [ { "code": "AED", "numeric_code": "784", "documented_numeric_code": "784", "name": "UAE Dirham" }, { "code": "AFN", "numeric_code": "971", "documented_numeric_code": "971", "name": "Afghani" }, { "code": "ALL", "numeric_code": "008", "documented_numeric_code": "8", "name": "Lek" }, { "code": "AMD", "numeric_code": "051", "documented_numeric_code": "51", "name": "Armenian Dram" }, { "code": "ANG", "numeric_code": "532", "documented_numeric_code": "532", "name": "Netherlands Antillean Guilder" }, { "code": "AOA", "numeric_code": "973", "documented_numeric_code": "973", "name": "Kwanza" }, { "code": "ARS", "numeric_code": "032", "documented_numeric_code": "32", "name": "Argentine Peso" }, { "code": "AUD", "numeric_code": "036", "documented_numeric_code": "36", "name": "Australian Dollar" }, { "code": "AWG", "numeric_code": "533", "documented_numeric_code": "533", "name": "Aruban Florin" }, { "code": "AZN", "numeric_code": "944", "documented_numeric_code": "944", "name": "Azerbaijan Manat" }, { "code": "BAM", "numeric_code": "977", "documented_numeric_code": "977", "name": "Convertible Mark" }, { "code": "BBD", "numeric_code": "052", "documented_numeric_code": "52", "name": "Barbados Dollar" }, { "code": "BDT", "numeric_code": "050", "documented_numeric_code": "50", "name": "Taka" }, { "code": "BGN", "numeric_code": "975", "documented_numeric_code": "975", "name": "Bulgarian Lev" }, { "code": "BHD", "numeric_code": "048", "documented_numeric_code": "48", "name": "Bahraini Dinar" }, { "code": "BIF", "numeric_code": "108", "documented_numeric_code": "108", "name": "Burundi Franc" }, { "code": "BMD", "numeric_code": "060", "documented_numeric_code": "60", "name": "Bermudian Dollar" }, { "code": "BND", "numeric_code": "096", "documented_numeric_code": "96", "name": "Brunei Dollar" }, { "code": "BOB", "numeric_code": "068", "documented_numeric_code": "68", "name": "Boliviano" }, { "code": "BOV", "numeric_code": "984", "documented_numeric_code": "984", "name": "Mvdol" }, { "code": "BRL", "numeric_code": "986", "documented_numeric_code": "986", "name": "Brazilian Real" }, { "code": "BSD", "numeric_code": "044", "documented_numeric_code": "44", "name": "Bahamian Dollar" }, { "code": "BTN", "numeric_code": "064", "documented_numeric_code": "64", "name": "Ngultrum" }, { "code": "BWP", "numeric_code": "072", "documented_numeric_code": "72", "name": "Pula" }, { "code": "BYN", "numeric_code": "933", "documented_numeric_code": "933", "name": "Belarusian Ruble" }, { "code": "BZD", "numeric_code": "084", "documented_numeric_code": "84", "name": "Belize Dollar" }, { "code": "CAD", "numeric_code": "124", "documented_numeric_code": "124", "name": "Canadian Dollar" }, { "code": "CDF", "numeric_code": "976", "documented_numeric_code": "976", "name": "Congolese Franc" }, { "code": "CHE", "numeric_code": "947", "documented_numeric_code": "947", "name": "WIR Euro" }, { "code": "CHF", "numeric_code": "756", "documented_numeric_code": "756", "name": "Swiss Franc" }, { "code": "CHW", "numeric_code": "948", "documented_numeric_code": "948", "name": "WIR Franc" }, { "code": "CLF", "numeric_code": "990", "documented_numeric_code": "990", "name": "Unidad de Fomento" }, { "code": "CLP", "numeric_code": "152", "documented_numeric_code": "152", "name": "Chilean Peso" }, { "code": "CNY", "numeric_code": "156", "documented_numeric_code": "156", "name": "Yuan Renminbi" }, { "code": "COP", "numeric_code": "170", "documented_numeric_code": "170", "name": "Colombian Peso" }, { "code": "COU", "numeric_code": "970", "documented_numeric_code": "970", "name": "Unidad de Valor Real" }, { "code": "CRC", "numeric_code": "188", "documented_numeric_code": "188", "name": "Costa Rican Colon" }, { "code": "CUC", "numeric_code": "931", "documented_numeric_code": "931", "name": "Peso Convertible" }, { "code": "CUP", "numeric_code": "192", "documented_numeric_code": "192", "name": "Cuban Peso" }, { "code": "CVE", "numeric_code": "132", "documented_numeric_code": "132", "name": "Cabo Verde Escudo" }, { "code": "CZK", "numeric_code": "203", "documented_numeric_code": "203", "name": "Czech Koruna" }, { "code": "DJF", "numeric_code": "262", "documented_numeric_code": "262", "name": "Djibouti Franc" }, { "code": "DKK", "numeric_code": "208", "documented_numeric_code": "208", "name": "Danish Krone" }, { "code": "DOP", "numeric_code": "214", "documented_numeric_code": "214", "name": "Dominican Peso" }, { "code": "DZD", "numeric_code": "012", "documented_numeric_code": "12", "name": "Algerian Dinar" }, { "code": "EGP", "numeric_code": "818", "documented_numeric_code": "818", "name": "Egyptian Pound" }, { "code": "ERN", "numeric_code": "232", "documented_numeric_code": "232", "name": "Nakfa" }, { "code": "ETB", "numeric_code": "230", "documented_numeric_code": "230", "name": "Ethiopian Birr" }, { "code": "EUR", "numeric_code": "978", "documented_numeric_code": "978", "name": "Euro" }, { "code": "FJD", "numeric_code": "242", "documented_numeric_code": "242", "name": "Fiji Dollar" }, { "code": "FKP", "numeric_code": "238", "documented_numeric_code": "238", "name": "Falkland Islands Pound" }, { "code": "GBP", "numeric_code": "826", "documented_numeric_code": "826", "name": "Pound Sterling" }, { "code": "GEL", "numeric_code": "981", "documented_numeric_code": "981", "name": "Lari" }, { "code": "GHS", "numeric_code": "936", "documented_numeric_code": "936", "name": "Ghana Cedi" }, { "code": "GIP", "numeric_code": "292", "documented_numeric_code": "292", "name": "Gibraltar Pound" }, { "code": "GMD", "numeric_code": "270", "documented_numeric_code": "270", "name": "Dalasi" }, { "code": "GNF", "numeric_code": "324", "documented_numeric_code": "324", "name": "Guinean Franc" }, { "code": "GTQ", "numeric_code": "320", "documented_numeric_code": "320", "name": "Quetzal" }, { "code": "GYD", "numeric_code": "328", "documented_numeric_code": "328", "name": "Guyana Dollar" }, { "code": "HKD", "numeric_code": "344", "documented_numeric_code": "344", "name": "Hong Kong Dollar" }, { "code": "HNL", "numeric_code": "340", "documented_numeric_code": "340", "name": "Lempira" }, { "code": "HTG", "numeric_code": "332", "documented_numeric_code": "332", "name": "Gourde" }, { "code": "HUF", "numeric_code": "348", "documented_numeric_code": "348", "name": "Forint" }, { "code": "IDR", "numeric_code": "360", "documented_numeric_code": "360", "name": "Rupiah" }, { "code": "ILS", "numeric_code": "376", "documented_numeric_code": "376", "name": "New Israeli Sheqel" }, { "code": "INR", "numeric_code": "356", "documented_numeric_code": "356", "name": "Indian Rupee" }, { "code": "IQD", "numeric_code": "368", "documented_numeric_code": "368", "name": "Iraqi Dinar" }, { "code": "IRR", "numeric_code": "364", "documented_numeric_code": "364", "name": "Iranian Rial" }, { "code": "ISK", "numeric_code": "352", "documented_numeric_code": "352", "name": "Iceland Krona" }, { "code": "JMD", "numeric_code": "388", "documented_numeric_code": "388", "name": "Jamaican Dollar" }, { "code": "JOD", "numeric_code": "400", "documented_numeric_code": "400", "name": "Jordanian Dinar" }, { "code": "JPY", "numeric_code": "392", "documented_numeric_code": "392", "name": "Yen" }, { "code": "KES", "numeric_code": "404", "documented_numeric_code": "404", "name": "Kenyan Shilling" }, { "code": "KGS", "numeric_code": "417", "documented_numeric_code": "417", "name": "Som" }, { "code": "KHR", "numeric_code": "116", "documented_numeric_code": "116", "name": "Riel" }, { "code": "KMF", "numeric_code": "174", "documented_numeric_code": "174", "name": "Comorian Franc" }, { "code": "KPW", "numeric_code": "408", "documented_numeric_code": "408", "name": "North Korean Won" }, { "code": "KRW", "numeric_code": "410", "documented_numeric_code": "410", "name": "Won" }, { "code": "KWD", "numeric_code": "414", "documented_numeric_code": "414", "name": "Kuwaiti Dinar" }, { "code": "KYD", "numeric_code": "136", "documented_numeric_code": "136", "name": "Cayman Islands Dollar" }, { "code": "KZT", "numeric_code": "398", "documented_numeric_code": "398", "name": "Tenge" }, { "code": "LAK", "numeric_code": "418", "documented_numeric_code": "418", "name": "Lao Kip" }, { "code": "LBP", "numeric_code": "422", "documented_numeric_code": "422", "name": "Lebanese Pound" }, { "code": "LKR", "numeric_code": "144", "documented_numeric_code": "144", "name": "Sri Lanka Rupee" }, { "code": "LRD", "numeric_code": "430", "documented_numeric_code": "430", "name": "Liberian Dollar" }, { "code": "LSL", "numeric_code": "426", "documented_numeric_code": "426", "name": "Loti" }, { "code": "LYD", "numeric_code": "434", "documented_numeric_code": "434", "name": "Libyan Dinar" }, { "code": "MAD", "numeric_code": "504", "documented_numeric_code": "504", "name": "Moroccan Dirham" }, { "code": "MDL", "numeric_code": "498", "documented_numeric_code": "498", "name": "Moldovan Leu" }, { "code": "MGA", "numeric_code": "969", "documented_numeric_code": "969", "name": "Malagasy Ariary" }, { "code": "MKD", "numeric_code": "807", "documented_numeric_code": "807", "name": "Denar" }, { "code": "MMK", "numeric_code": "104", "documented_numeric_code": "104", "name": "Kyat" }, { "code": "MNT", "numeric_code": "496", "documented_numeric_code": "496", "name": "Tugrik" }, { "code": "MOP", "numeric_code": "446", "documented_numeric_code": "446", "name": "Pataca" }, { "code": "MRU", "numeric_code": "929", "documented_numeric_code": "929", "name": "Ouguiya" }, { "code": "MUR", "numeric_code": "480", "documented_numeric_code": "480", "name": "Mauritius Rupee" }, { "code": "MVR", "numeric_code": "462", "documented_numeric_code": "462", "name": "Rufiyaa" }, { "code": "MWK", "numeric_code": "454", "documented_numeric_code": "454", "name": "Malawi Kwacha" }, { "code": "MXN", "numeric_code": "484", "documented_numeric_code": "484", "name": "Mexican Peso" }, { "code": "MXV", "numeric_code": "979", "documented_numeric_code": "979", "name": "Mexican Unidad de Inversion" }, { "code": "MYR", "numeric_code": "458", "documented_numeric_code": "458", "name": "Malaysian Ringgit" }, { "code": "MZN", "numeric_code": "943", "documented_numeric_code": "943", "name": "Mozambique Metical" }, { "code": "NAD", "numeric_code": "516", "documented_numeric_code": "516", "name": "Namibia Dollar" }, { "code": "NGN", "numeric_code": "566", "documented_numeric_code": "566", "name": "Naira" }, { "code": "NIO", "numeric_code": "558", "documented_numeric_code": "558", "name": "Cordoba Oro" }, { "code": "NOK", "numeric_code": "578", "documented_numeric_code": "578", "name": "Norwegian Krone" }, { "code": "NPR", "numeric_code": "524", "documented_numeric_code": "524", "name": "Nepalese Rupee" }, { "code": "NZD", "numeric_code": "554", "documented_numeric_code": "554", "name": "New Zealand Dollar" }, { "code": "OMR", "numeric_code": "512", "documented_numeric_code": "512", "name": "Rial Omani" }, { "code": "PAB", "numeric_code": "590", "documented_numeric_code": "590", "name": "Balboa" }, { "code": "PEN", "numeric_code": "604", "documented_numeric_code": "604", "name": "Sol" }, { "code": "PGK", "numeric_code": "598", "documented_numeric_code": "598", "name": "Kina" }, { "code": "PHP", "numeric_code": "608", "documented_numeric_code": "608", "name": "Philippine Peso" }, { "code": "PKR", "numeric_code": "586", "documented_numeric_code": "586", "name": "Pakistan Rupee" }, { "code": "PLN", "numeric_code": "985", "documented_numeric_code": "985", "name": "Zloty" }, { "code": "PYG", "numeric_code": "600", "documented_numeric_code": "600", "name": "Guarani" }, { "code": "QAR", "numeric_code": "634", "documented_numeric_code": "634", "name": "Qatari Rial" }, { "code": "RON", "numeric_code": "946", "documented_numeric_code": "946", "name": "Romanian Leu" }, { "code": "RSD", "numeric_code": "941", "documented_numeric_code": "941", "name": "Serbian Dinar" }, { "code": "RUB", "numeric_code": "643", "documented_numeric_code": "643", "name": "Russian Ruble" }, { "code": "RWF", "numeric_code": "646", "documented_numeric_code": "646", "name": "Rwanda Franc" }, { "code": "SAR", "numeric_code": "682", "documented_numeric_code": "682", "name": "Saudi Riyal" }, { "code": "SBD", "numeric_code": "090", "documented_numeric_code": "90", "name": "Solomon Islands Dollar" }, { "code": "SCR", "numeric_code": "690", "documented_numeric_code": "690", "name": "Seychelles Rupee" }, { "code": "SDG", "numeric_code": "938", "documented_numeric_code": "938", "name": "Sudanese Pound" }, { "code": "SEK", "numeric_code": "752", "documented_numeric_code": "752", "name": "Swedish Krona" }, { "code": "SGD", "numeric_code": "702", "documented_numeric_code": "702", "name": "Singapore Dollar" }, { "code": "SHP", "numeric_code": "654", "documented_numeric_code": "654", "name": "Saint Helena Pound" }, { "code": "SLE", "numeric_code": "925", "documented_numeric_code": "925", "name": "Leone" }, { "code": "SOS", "numeric_code": "706", "documented_numeric_code": "706", "name": "Somali Shilling" }, { "code": "SRD", "numeric_code": "968", "documented_numeric_code": "968", "name": "Surinam Dollar" }, { "code": "SSP", "numeric_code": "728", "documented_numeric_code": "728", "name": "South Sudanese Pound" }, { "code": "STN", "numeric_code": "930", "documented_numeric_code": "930", "name": "Dobra" }, { "code": "SVC", "numeric_code": "222", "documented_numeric_code": "222", "name": "El Salvador Colon" }, { "code": "SYP", "numeric_code": "760", "documented_numeric_code": "760", "name": "Syrian Pound" }, { "code": "SZL", "numeric_code": "748", "documented_numeric_code": "748", "name": "Lilangeni" }, { "code": "THB", "numeric_code": "764", "documented_numeric_code": "764", "name": "Baht" }, { "code": "TJS", "numeric_code": "972", "documented_numeric_code": "972", "name": "Somoni" }, { "code": "TMT", "numeric_code": "934", "documented_numeric_code": "934", "name": "Turkmenistan New Manat" }, { "code": "TND", "numeric_code": "788", "documented_numeric_code": "788", "name": "Tunisian Dinar" }, { "code": "TOP", "numeric_code": "776", "documented_numeric_code": "776", "name": "Pa’anga" }, { "code": "TRY", "numeric_code": "949", "documented_numeric_code": "949", "name": "Turkish Lira" }, { "code": "TTD", "numeric_code": "780", "documented_numeric_code": "780", "name": "Trinidad and Tobago Dollar" }, { "code": "TWD", "numeric_code": "901", "documented_numeric_code": "901", "name": "New Taiwan Dollar" }, { "code": "TZS", "numeric_code": "834", "documented_numeric_code": "834", "name": "Tanzanian Shilling" }, { "code": "UAH", "numeric_code": "980", "documented_numeric_code": "980", "name": "Hryvnia" }, { "code": "UGX", "numeric_code": "800", "documented_numeric_code": "800", "name": "Uganda Shilling" }, { "code": "USD", "numeric_code": "840", "documented_numeric_code": "840", "name": "US Dollar" }, { "code": "USN", "numeric_code": "997", "documented_numeric_code": "997", "name": "US Dollar (Next day)" }, { "code": "UYI", "numeric_code": "940", "documented_numeric_code": "940", "name": "Uruguay Peso en Unidades Indexadas (UI)" }, { "code": "UYU", "numeric_code": "858", "documented_numeric_code": "858", "name": "Peso Uruguayo" }, { "code": "UYW", "numeric_code": "927", "documented_numeric_code": "927", "name": "Unidad Previsional" }, { "code": "UZS", "numeric_code": "860", "documented_numeric_code": "860", "name": "Uzbekistan Sum" }, { "code": "VED", "numeric_code": "926", "documented_numeric_code": "926", "name": "Bolívar Soberano" }, { "code": "VES", "numeric_code": "928", "documented_numeric_code": "928", "name": "Bolívar Soberano" }, { "code": "VND", "numeric_code": "704", "documented_numeric_code": "704", "name": "Dong" }, { "code": "VUV", "numeric_code": "548", "documented_numeric_code": "548", "name": "Vatu" }, { "code": "WST", "numeric_code": "882", "documented_numeric_code": "882", "name": "Tala" }, { "code": "XAF", "numeric_code": "950", "documented_numeric_code": "950", "name": "CFA Franc BEAC" }, { "code": "XAG", "numeric_code": "961", "documented_numeric_code": "961", "name": "Silver" }, { "code": "XAU", "numeric_code": "959", "documented_numeric_code": "959", "name": "Gold" }, { "code": "XBA", "numeric_code": "955", "documented_numeric_code": "955", "name": "Bond Markets Unit European Composite Unit (EURCO)" }, { "code": "XBB", "numeric_code": "956", "documented_numeric_code": "956", "name": "Bond Markets Unit European Monetary Unit (E.M.U.-6)" }, { "code": "XBC", "numeric_code": "957", "documented_numeric_code": "957", "name": "Bond Markets Unit European Unit of Account 9 (E.U.A.-9)" }, { "code": "XBD", "numeric_code": "958", "documented_numeric_code": "958", "name": "Bond Markets Unit European Unit of Account 17 (E.U.A.-17)" }, { "code": "XCD", "numeric_code": "951", "documented_numeric_code": "951", "name": "East Caribbean Dollar" }, { "code": "XDR", "numeric_code": "960", "documented_numeric_code": "960", "name": "SDR (Special Drawing Right)" }, { "code": "XOF", "numeric_code": "952", "documented_numeric_code": "952", "name": "CFA Franc BCEAO" }, { "code": "XPD", "numeric_code": "964", "documented_numeric_code": "964", "name": "Palladium" }, { "code": "XPF", "numeric_code": "953", "documented_numeric_code": "953", "name": "CFP Franc" }, { "code": "XPT", "numeric_code": "962", "documented_numeric_code": "962", "name": "Platinum" }, { "code": "XSU", "numeric_code": "994", "documented_numeric_code": "994", "name": "Sucre" }, { "code": "XTS", "numeric_code": "963", "documented_numeric_code": "963", "name": "Codes specifically reserved for testing purposes" }, { "code": "XUA", "numeric_code": "965", "documented_numeric_code": "965", "name": "ADB Unit of Account" }, { "code": "XXX", "numeric_code": "999", "documented_numeric_code": "999", "name": "The codes assigned for transactions where no currency is involved" }, { "code": "YER", "numeric_code": "886", "documented_numeric_code": "886", "name": "Yemeni Rial" }, { "code": "ZAR", "numeric_code": "710", "documented_numeric_code": "710", "name": "Rand" }, { "code": "ZMW", "numeric_code": "967", "documented_numeric_code": "967", "name": "Zambian Kwacha" }, { "code": "ZWG", "numeric_code": "924", "documented_numeric_code": "924", "name": "Zimbabwe Gold" } ], "inputContract": { "decision": "CUR-CRYPTO-001", "approvedAt": "2026-09-10", "lexicalFormatValidation": false, "paymentCreationProcessingOrder": [ "internal currency dictionary lookup", "route lookup using pipeline conditions" ], "illustrativeInput": "USDT_TRC20", "illustrativeInputGuaranteesSupport": false, "catalogScope": "Published ISO-style reference only; not an exhaustive internal currency dictionary or an enabled-currency list.", "unchanged": [ "string type", "field requiredness", "operation-specific HTTP outcomes", "amount rules" ], "unconfirmed": [ "crypto catalog and profile support", "dictionary casing and alias matching", "missing/null/empty business behavior" ], "balanceScope": "Shared lexical schema only; no order creation or route lookup is asserted for Balance." } }, "additionalFields": { "id": "additional-fields", "title": "Additional field keys", "description": "Candidate keys and formats. Requiredness is merchant-, flow-, route-, and downstream-provider-specific; confirm the exact schema with the PayStar manager.", "itemContract": { "key": "string", "value": "flow-specific" }, "requiredness": "varies by flow, route and downstream provider", "privacyRule": "Send only fields required by the confirmed flow; do not follow the broad 'send all' recommendation blindly.", "items": [ { "key": "productCode", "category": "payment_method_and_card", "description": "Internal product or service code.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "Merch-12345" }, { "key": "cardNumber", "category": "payment_method_and_card", "description": "Full card PAN. Only send through a PCI-authorized H2H flow.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "", "sensitivity": "PCI" }, { "key": "cardExpireMonth", "category": "payment_method_and_card", "description": "Card expiry month in MM format.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "05", "sensitivity": "PCI" }, { "key": "cardExpireYear", "category": "payment_method_and_card", "description": "Card expiry year in YY format.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "26", "sensitivity": "PCI" }, { "key": "cardCvv", "category": "payment_method_and_card", "description": "CVV/CVC, 3–4 digits. Must never be stored.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "", "sensitivity": "PCI_HIGH" }, { "key": "cardHolder", "category": "payment_method_and_card", "description": "Name printed on the card.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "JOHN DOE", "sensitivity": "personal_data" }, { "key": "cardToken", "category": "payment_method_and_card", "description": "Tokenized card identifier issued by a bank/provider.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "", "sensitivity": "secret_like" }, { "key": "cardStorageToken", "category": "tokenization", "description": "Token used for subsequent payments in the merchant tokenized flow; availability and storage responsibility depend on the assigned profile.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/deposits#token", "example": "" }, { "key": "type", "category": "payment_method", "description": "Payment type selector used in examples, e.g. card; not listed in the field catalog.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "card" }, { "key": "firstName", "category": "customer_identity_kyc", "description": "Customer first name.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "John", "sensitivity": "personal_data" }, { "key": "middleName", "category": "customer_identity_kyc", "description": "Customer middle name.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "Michael", "sensitivity": "personal_data" }, { "key": "lastName", "category": "customer_identity_kyc", "description": "Customer last name.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "Smith", "sensitivity": "personal_data" }, { "key": "customerDocumentId", "category": "customer_identity_kyc", "description": "Government-issued document identifier; include document type where required.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "Passport ", "sensitivity": "KYC_HIGH" }, { "key": "customerBirthdayDate", "category": "customer_identity_kyc", "description": "Date of birth in YYYY-MM-DD format.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "1990-04-05", "sensitivity": "personal_data" }, { "key": "customerNationality", "category": "customer_identity_kyc", "description": "Nationality, ISO 3166-1 alpha-3.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "NLD", "sensitivity": "personal_data" }, { "key": "email", "category": "customer_contact_and_address", "description": "Customer email address.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "customer@example.com", "sensitivity": "personal_data" }, { "key": "phoneNumber", "category": "customer_contact_and_address", "description": "Customer phone number.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "31612345678", "sensitivity": "personal_data" }, { "key": "telecomOperator", "category": "customer_contact_and_address", "description": "Mobile network enum/name used for telecom payments and routing.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "vodafone-uk" }, { "key": "dialingCode", "category": "customer_contact_and_address", "description": "International dialing code.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "31" }, { "key": "customerAddress", "category": "customer_contact_and_address", "description": "Customer street address.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "123 Main Street", "sensitivity": "personal_data" }, { "key": "customerCity", "category": "customer_contact_and_address", "description": "Customer city/locality.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "Amsterdam", "sensitivity": "personal_data" }, { "key": "customerState", "category": "customer_contact_and_address", "description": "State or region where applicable.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "Noord-Holland", "sensitivity": "personal_data" }, { "key": "customerZipCode", "category": "customer_contact_and_address", "description": "Postal or ZIP code.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "1012 AB", "sensitivity": "personal_data" }, { "key": "customerCountryCode", "category": "customer_contact_and_address", "description": "ISO 3166-1 alpha-3 country code.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "NLD", "sensitivity": "personal_data" }, { "key": "customerCountry", "category": "customer_contact_and_address", "description": "Full country name if required by the downstream PSP.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "Netherlands", "sensitivity": "personal_data" }, { "key": "beneficiaryName", "category": "bank_and_payment_details", "description": "Legal name of the beneficiary/account holder.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "John Smith", "sensitivity": "financial_personal_data" }, { "key": "bankName", "category": "bank_and_payment_details", "description": "Bank enum/name used for routing.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "all" }, { "key": "bankAccount", "category": "bank_and_payment_details", "description": "Beneficiary bank account number.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "", "sensitivity": "financial_high" }, { "key": "iban", "category": "bank_and_payment_details", "description": "International Bank Account Number.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "", "sensitivity": "financial_high" }, { "key": "bankCode", "category": "bank_and_payment_details", "description": "Country-specific national bank identifier.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "" }, { "key": "bankBranch", "category": "bank_and_payment_details", "description": "Local branch identifier/name.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "" }, { "key": "ifcsCode", "category": "bank_and_payment_details", "description": "Documented key for Indian IFSC code.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "HDFC0001234" }, { "key": "cryptoWalletAdress", "category": "crypto", "description": "Documented key for a crypto wallet address; chain may also be needed.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "", "sensitivity": "financial_high" }, { "key": "browserUserAgent", "category": "browser_and_3ds", "description": "Full browser User-Agent string.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "", "sensitivity": "device_data" }, { "key": "browserAcceptHeader", "category": "browser_and_3ds", "description": "Browser HTTP Accept header.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "text/html,application/xhtml+xml", "sensitivity": "device_data" }, { "key": "browserLanguage", "category": "browser_and_3ds", "description": "Browser language.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "en-GB", "sensitivity": "device_data" }, { "key": "browserJavaEnabled", "category": "browser_and_3ds", "description": "Whether Java is enabled.", "requiredness": "flow_specific", "value_type": "boolean", "source_url": "/api/reference#additional-fields", "example": true }, { "key": "browserJavascriptEnabled", "category": "browser_and_3ds", "description": "Whether JavaScript is enabled.", "requiredness": "flow_specific", "value_type": "boolean", "source_url": "/api/reference#additional-fields", "example": true }, { "key": "browserColorDepth", "category": "browser_and_3ds", "description": "Screen color depth in bits.", "requiredness": "flow_specific", "value_type": "integer", "source_url": "/api/reference#additional-fields", "example": 24 }, { "key": "browserScreenWidth", "category": "browser_and_3ds", "description": "Screen width in pixels.", "requiredness": "flow_specific", "value_type": "integer", "source_url": "/api/reference#additional-fields", "example": 1920 }, { "key": "browserScreenHeight", "category": "browser_and_3ds", "description": "Screen height in pixels.", "requiredness": "flow_specific", "value_type": "integer", "source_url": "/api/reference#additional-fields", "example": 1080 }, { "key": "browserTZ", "category": "browser_and_3ds", "description": "Timezone offset from UTC in minutes.", "requiredness": "flow_specific", "value_type": "integer", "source_url": "/api/reference#additional-fields", "example": -120 }, { "key": "browserChallengeWindowSize", "category": "browser_and_3ds", "description": "3DS challenge window code: 01=250x400, 02=390x400, 03=500x600.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "03", "enum": [ "01", "02", "03" ] }, { "key": "storeUrl", "category": "merchant_and_store", "description": "Merchant website or checkout URL.", "requiredness": "flow_specific", "value_type": "uri", "source_url": "/api/reference#additional-fields", "example": "https://merchant.example.com/" }, { "key": "ip", "category": "miscellaneous", "description": "End-user IP address.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "203.0.113.10", "sensitivity": "personal_data" }, { "key": "payeerIdentifier", "category": "miscellaneous", "description": "Payer/customer identifier on the merchant side.", "requiredness": "flow_specific", "value_type": "string_unless_flow_contract_says_otherwise", "source_url": "/api/reference#additional-fields", "example": "Merch-Customer-12345", "sensitivity": "personal_data" }, { "key": "ExpectedResult", "category": "sandbox", "description": "Legacy-documented sandbox control; casing, supported outcomes and profile applicability require confirmation. Not verified by this test set.", "requiredness": "optional_test_only", "value_type": "string", "source_url": "/api/integration#sandbox", "example": "status=failed", "enum": [ "status=failed", "status=success" ] } ] }, "orderStatuses": { "id": "order-statuses", "title": "Deposit and payout order statuses", "description": "Current state values returned by deposit and payout status endpoints.", "deposit": { "non_final": [ "Init", "Created", "Processing" ], "final": [ "Success" ], "finality_scope": "Only values final across the documented deposit flows are listed in deposit.final. Failed is flow-specific; use deposit.p2p or deposit.other_flows. This corrects the former unconditional Failed finality without adding a status.", "p2p": { "non_final": [ "Init", "Created", "Processing" ], "final": [ "Success" ], "correctable": [ "Failed" ], "correction": { "decision": "P2P-STATE-001", "confirmedAt": "2026-09-10", "scope": "P2P deposits, including merchant-side H2H/H2C presentation", "from": "Failed", "to": "Success", "sameOrder": true, "identifiersUnchanged": true, "usualInitiator": "merchant support", "callbackHandlingRequired": true, "reverseBusinessTransitionRequired": false, "liveCorrectionVerified": false, "liveCallbackDeliveryVerified": false, "correctionDeadlineConfirmed": false, "pollingStopPolicyConfirmed": false, "deliveryContract": "Payload, signature, acknowledgement and retry details still require approved fixtures; this lifecycle decision does not define them.", "handling": "Process an authenticated Success correction for the existing P2P order even if it was Failed. Do not discard it solely because the order ID has been seen. Apply the successful business effect idempotently. Do not downgrade a stored Success to Failed; this does not waive callback validation or the agreed acknowledgement protocol." } }, "other_flows": { "scope": "Other deposit flows: previous classification retained; the P2P correction does not change their lifecycle.", "non_final": [ "Init", "Created", "Processing" ], "final": [ "Success", "Failed" ] } }, "payout": { "non_final": [ "Created", "Processing" ], "final": [ "Success", "Failed" ] } }, "paymentHistory": { "id": "payment-history", "title": "Payment History codes and segments", "description": "Confirmed or documented examples and partial configuration codes. The catalog is not complete; unknown codes must be preserved and treated as catalog gaps.", "field": "orderHistory", "availability": [ "deposit status by PayStar ID", "deposit status by merchant ID", "payout status by PayStar ID", "payout status by merchant ID", "callbacks" ], "itemModel": { "time": "UTC timestamp in deposit/payout status responses only. Interpret an offset-less value as UTC, not local time (owner-confirmed 2026-09-08). Missing Z/offset remains a date-time serialization discrepancy.", "action": "string|null", "newCode": "string|null; additional Payment History code returned by the API. Preserve unfamiliar values without inferring meanings." }, "documentedActionFormat": "A.B.C.RR", "segments": { "A_stage": { "1": "PayStar", "2": "Gateway create", "3": "Hosted Payment Page / user interaction", "4": "Gateway polling" }, "B_operation_result": { "0": "Info", "1": "Success", "2": "Failed" }, "C_payment_state": { "0": "Init", "1": "Created", "2": "Processing", "3": "Success", "4": "Failed", "5": "Unchanged" }, "RR_reason_group": { "00": "None", "11..19": "TECH", "21..29": "AUTHZ", "31..39": "BUSINESS", "41..49": "RISK", "51..59": "USER", "61..69": "ISSUER" } }, "examples": [ { "code": "1.1.1.00", "meaning": "PayStar: payment created" }, { "code": "2.1.1.00", "meaning": "Gateway: payment created" }, { "code": "2.1.2.00", "meaning": "Gateway: processing" }, { "code": "4.1.3.00", "meaning": "Gateway polling: payment successful" }, { "code": "4.1.4.63", "meaning": "Gateway polling: failed, issuer insufficient funds" }, { "code": "2.2.4.16", "meaning": null } ], "partialConfigurationCodes": [ { "http": 500, "new_code": "1.2.4.18.1", "legacy_code": "1200-1-1", "description": "Pipeline configuration missing formUrl." }, { "http": 500, "new_code": "1.2.4.18.2", "legacy_code": "0000-911", "description": "Endpoint has no pipeline/routes configured." }, { "http": 500, "new_code": "1.2.4.18.3", "legacy_code": "0000-2", "description": "Pipeline has no channel configured." }, { "http": 500, "new_code": "1.2.4.18.4", "legacy_code": "0000-180924", "description": "Gateway integration configuration invalid." }, { "http": 500, "new_code": "1.2.4.18.5", "legacy_code": "0000-4", "description": "Gateway implementation configuration invalid." } ], "unknownCodePolicy": { "rule": "Never infer a description from neighboring codes." }, "completeness": { "asynchronous_enrichment": true, "recommended_additional_status_check_documented": "about 10 minutes later when a complete trace is needed", "scopeNotice": "Deposit status includes a non-empty orderHistory. This does not guarantee an exhaustive trace or forbid later enrichment. The legacy additional-check suggestion is not a new SLA or permission for empty deposit history; payout/callback rules are unchanged." }, "depositStatusAvailability": { "decision": "DEP-STATUS-001", "confirmedAt": "2026-09-11", "scope": [ "getDepositStatusByMerchantId", "getDepositStatusByPayStarId" ], "required": true, "minItems": 1, "currentStateField": "orderStatus", "completeTraceGuaranteed": false, "payoutAndCallbackRulesChanged": false }, "reviewNotice": "The owner confirmed UTC for orderHistory[].time in deposit and payout status responses on 2026-09-08. This does not establish callback or Events timestamp semantics. The current missing timezone suffix remains a strict date-time discrepancy. See /api/status#history." }, "businessErrors": { "id": "business-errors", "title": "Error catalog", "formatVersion": 2, "description": "This is not an exhaustive catalog. Owner-confirmed HTTP mappings are identified per item; other conditions retain their documented or observed scope.", "exhaustive": false, "globalCascadeRule": "For any create error, 499+, timeout, broken connection, or missing response, check order status before initiating another attempt/cascade.", "errorResponseContract": { "scope": "PayStar business errors; excludes HTTP/framework errors such as 415", "json_body_fields": [ { "name": "label", "type": "string", "required_when_json_body_present": true, "description": "Machine-readable error category. Observed values include VALIDATION_ERROR, REQUEST_VALIDATION_ERROR, TEMPORARY_ERROR, NOT_FOUND and INTERNAL_SERVER_ERROR." }, { "name": "message", "type": "string", "required_when_json_body_present": true, "description": "Human-readable or framework validation message; exact text is not stable enough for client branching." }, { "name": "statusDescrption", "type": "string|null", "required_when_json_body_present": false, "description": "Owner-approved current wire spelling, intentionally preserved including the typo." }, { "name": "externalTransactionId", "type": "string|null", "required_when_json_body_present": false }, { "name": "code", "type": "string|null", "required_when_json_body_present": false, "description": "Application error code when supplied. Do not branch on undocumented values." } ], "body_exceptions": [ "401 responses may have an empty body.", "Framework-level 415 responses use application/problem+json and are not PayStar business errors." ], "client_guidance": [ "Branch primarily on HTTP status and documented stable application codes, not exact message text.", "For create-order 5xx, timeout or missing response, query status using the original externalTransactionId before retrying." ] }, "groups": { "commonCreate": [ "created_failed", "channel_not_found", "limit_reached", "duplicate_merchant_id", "required_field_missing" ], "json": [ "created_failed", "channel_not_found", "insufficient_balance", "limit_reached", "duplicate_merchant_id", "required_field_missing", "deposit_unknown_currency", "validation_error", "temporary_or_no_route" ], "http": [ "unauthorized", "forbidden", "payment_not_found", "unsupported_media_type", "internal_or_configuration_error", "transport_failure" ], "payoutOnlyCreate": [ "insufficient_balance" ] }, "items": [ { "id": "created_failed", "title": "Order created, processing failed", "group": "json", "appliesTo": [ "P2P deposit H2H/H2C", "ECOM H2H deposit", "Hosted H2C deposit", "Tokenized deposit", "Payout" ], "orderCreated": true, "description": "The request produced an order, but processing failed. Keep the PayStar externalId and your original merchant order ID. This is not a rejection without an order.", "handling": "HTTP 200 means the order was created, not that the payment succeeded. This body uses orderStatus, not status, and does not include payment details or a form URL. Inspect orderStatus and retain both order identifiers.", "http": { "status": 200, "basis": "Owner-confirmed HTTP mapping (CREATE-HTTP-001, 15 September 2026) for this response example; not new per-flow live verification.", "scope": "Deposit creation and payout", "decision": "CREATE-HTTP-001", "approvedAt": "2026-09-15" }, "payload": { "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "orderStatus": "Failed" } }, { "id": "channel_not_found", "title": "No matching channel or route", "group": "json", "appliesTo": [ "P2P deposit H2H/H2C", "ECOM H2H deposit", "Hosted H2C deposit", "Tokenized deposit", "Payout" ], "orderCreated": false, "description": "The currency, amount, or other request parameters do not match available routing conditions for this pipeline. No order is created.", "handling": "Check the request parameters and the pipeline routing conditions with your manager.", "http": { "status": 423, "basis": "Owner-confirmed HTTP mapping (CREATE-HTTP-001, 15 September 2026) for this response example; not new per-flow live verification.", "scope": "Deposit creation and payout", "decision": "CREATE-HTTP-001", "approvedAt": "2026-09-15" }, "payload": { "label": "TEMPORARY_ERROR", "message": "TEMPORARY_ERROR", "statusDescrption": "0000-2", "externalTransactionId": null, "code": "1.2.4.3" }, "provenance": { "decision": "CREATE-ERRORS-001", "approvedAt": "2026-09-10", "flow": "Deposit H2H", "currency": "EUR", "observedAtUtc": "2026-09-08T10:16:16.62731Z", "evidence": "20260908T101615299Z-currency-three-cases.json#/results/4", "httpDecision": "CREATE-HTTP-001", "httpApprovedAt": "2026-09-15" } }, { "id": "insufficient_balance", "title": "Insufficient balance", "group": "json", "appliesTo": [ "Payout" ], "orderCreated": false, "description": "Insufficient balance to create the payout. No order is created.", "handling": "Confirm the balance involved with your manager; the payload alone does not identify an account or wallet.", "http": { "status": 422, "basis": "Owner-confirmed HTTP mapping (CREATE-HTTP-001, 15 September 2026) for this response example; not new per-flow live verification.", "scope": "Payout only", "decision": "CREATE-HTTP-001", "approvedAt": "2026-09-15" }, "payload": { "label": "TEMPORARY_ERROR", "message": "TEMPORARY_ERROR", "statusDescrption": "1-4010", "externalTransactionId": null, "code": "1.1.4.3" } }, { "id": "limit_reached", "title": "Configured limit reached", "group": "json", "appliesTo": [ "P2P deposit H2H/H2C", "ECOM H2H deposit", "Hosted H2C deposit", "Tokenized deposit", "Payout" ], "orderCreated": false, "description": "A configured limit was reached. No order is created.", "handling": "The limit ID is illustrative. This example has no code field; do not map the error by a particular UUID or exact message text.", "http": { "status": 400, "basis": "Owner-confirmed HTTP mapping (CREATE-HTTP-001, 15 September 2026) for this response example; not new per-flow live verification.", "scope": "Deposit creation and payout", "decision": "CREATE-HTTP-001", "approvedAt": "2026-09-15" }, "payload": { "label": "LIMITS_ERROR", "message": "Limit id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa was reached", "statusDescrption": "0001-0", "externalTransactionId": null } }, { "id": "duplicate_merchant_id", "title": "Duplicate merchant order ID", "group": "json", "appliesTo": [ "P2P deposit H2H/H2C", "ECOM H2H deposit", "Hosted H2C deposit", "Tokenized deposit", "Payout" ], "orderCreated": false, "description": "An order with this merchant ID already exists. No new order is created by this rejected attempt.", "handling": "Query the existing order using the original externalTransactionId from your request, even when externalTransactionId is null in this error. Do not replace the ID for a blind retry.", "http": { "status": 400, "basis": "Owner-confirmed HTTP mapping (CREATE-HTTP-001, 15 September 2026) for this response example; not new per-flow live verification.", "scope": "Deposit creation and payout", "decision": "CREATE-HTTP-001", "approvedAt": "2026-09-15" }, "payload": { "label": "VALIDATION_ERROR", "message": "Order with this external_transaction_id already exist", "statusDescrption": "1-4007", "externalTransactionId": null, "code": "1.1.5.1" }, "legacyIds": [ "duplicate_external_transaction_id" ], "legacyWireDifferences": { "label": "VALIDATION_ERROR.", "omittedFields": [ "code", "externalTransactionId" ], "note": "Historical reduced example, not a second current error or interchangeable label guarantee." } }, { "id": "required_field_missing", "title": "Required parameter missing", "group": "json", "appliesTo": [ "P2P deposit H2H/H2C", "ECOM H2H deposit", "Hosted H2C deposit", "Tokenized deposit", "Payout" ], "orderCreated": false, "description": "A field required by the configured terminal is missing. No order is created.", "handling": "BankAccount is an example of a configured requirement, not a mandatory field for every flow. Use the required-field list supplied for your terminal.", "http": { "status": 400, "basis": "Owner-confirmed HTTP mapping (CREATE-HTTP-001, 15 September 2026) for this response example; not new per-flow live verification.", "scope": "Deposit creation and payout", "decision": "CREATE-HTTP-001", "approvedAt": "2026-09-15" }, "payload": { "label": "VALIDATION_ERROR", "message": "additionalField BankAccount not found in request data. Description: Beneficiary’s bank account number, e.g. 1234567890", "statusDescrption": "0000-0", "externalTransactionId": null, "code": "1.2.4.8" } }, { "id": "deposit_unknown_currency", "title": "Unknown currency", "group": "json", "appliesTo": [ "deposit_h2h", "deposit_h2c" ], "description": "CUR-002 (9 Sep 2026): unrecognized currency values, including RU and ZZZ, return the unknown-currency response. This is distinct from routing failure.", "handling": "Use the exact currency key enabled for your integration; do not impose an alpha-3 format check. Unknown currency is detected during internal dictionary lookup, before route lookup. Do not branch on exact message text or automatically retry an unchanged request. The refined message is owner-confirmed, not yet live-verified.", "http": { "status": 423, "basis": "Owner-confirmed CUR-002; refined message not yet live-verified.", "scope": "Deposit H2H/H2C only; does not extend to Balance or payout" }, "payload": { "label": "TEMPORARY_ERROR", "message": "Currency value \"RU\" is unknown", "statusDescrption": "2-00100-2", "externalTransactionId": null, "code": "1.2.4.9" }, "provenance": { "decision": "CUR-002", "approvedAt": "2026-09-09", "discussedValues": [ "RU", "ZZZ" ], "messageTemplate": "Currency value \"{currencyKey}\" is unknown", "excluded": [ "Balance", "payout", "missing/null/empty currency", "lowercase policy", "retry policy", "request schema relaxation (separately approved by CUR-CRYPTO-001)" ] } }, { "id": "validation_error", "title": "General request validation", "group": "json", "appliesTo": [ "deposit_create", "payout_create" ], "description": "Malformed request, missing required field, or invalid field value.", "handling": "Fix the request contract. Confirm flow-specific additional fields with the Account Manager.", "http": { "status": 400, "basis": "Legacy documented examples; distinguish these from configured-field validation.", "scope": "Create requests" }, "payload": { "label": "VALIDATION_ERROR.", "message": "External_transaction_id is required property", "statusDescrption": "0-0000" }, "messageVariants": [ "Amount is required property", "Currency is required property", "currency has invalide value" ], "note": "Historical label VALIDATION_ERROR. and statusDescrption 0-0000 are retained verbatim. Message variants replace only message; do not match exact text or restore alpha-3 validation from the historical currency message." }, { "id": "temporary_or_no_route", "title": "Payment temporarily unavailable — legacy variant", "group": "json", "appliesTo": [ "deposit_create", "payout_create" ], "description": "Distinct legacy payload with statusDescrption 0000-1, not the owner-confirmed 0000-2 routing response.", "handling": "Contact the Account Manager and check route/amount/currency/additional-field constraints.", "http": { "status": 423, "basis": "Legacy/general reference, not a universal routing mapping.", "scope": "Legacy documented create response" }, "payload": { "label": "TEMPORARY_ERROR", "statusDescrption": "0000-1", "message": "There is currently no possibility to make a payment, please try again later" } }, { "id": "unauthorized", "title": "Authentication", "group": "http", "appliesTo": [ "all" ], "http": { "status": 401, "basis": "Documented outcome.", "scope": "All operations" }, "description": "Authorization header/key is missing or invalid.", "handling": "Verify the Bearer token and that the correct deposit/payout key is used.", "body": "May be empty; no JSON example is supplied." }, { "id": "forbidden", "title": "Forbidden", "group": "http", "appliesTo": [ "all" ], "http": { "status": 403, "basis": "Documented outcome.", "scope": "All operations" }, "description": "Access denied. The HTTP status or an empty body does not identify a single cause.", "handling": "Ask your manager to check the key, flow capability, pipeline and IP allowlist.", "body": "May be empty; no JSON example is supplied.", "possibleCauses": [ { "id": "forbidden_pipeline", "description": "The key/pipeline is not activated or lacks permission.", "handling": "Contact the Account Manager." }, { "id": "invalid_pipeline_type", "description": "The key is active but belongs to another flow type, e.g. payout key used for deposit.", "handling": "Use the dedicated key for the requested operation." }, { "id": "forbidden_ip", "description": "Source IP is not whitelisted.", "handling": "Ask the Account Manager to whitelist the IP; documentation says propagation can take up to one hour." } ], "note": "The legacy IP propagation estimate is not a newly verified SLA." }, { "id": "payment_not_found", "title": "Payment not found", "group": "http", "appliesTo": [ "status_endpoints" ], "http": { "status": 404, "basis": "Documented status-lookup outcome.", "scope": "Status lookups, not create rejection" }, "description": "No order found by this lookup.", "handling": "Verify whether a PayStar externalId or merchant externalTransactionId is expected by this endpoint. Continue the agreed uncertainty-resolution process.", "body": "Use the response model documented for the status method; this catalog does not invent a body." }, { "id": "unsupported_media_type", "title": "Media type", "group": "http", "appliesTo": [ "JSON requests" ], "http": { "status": 415, "basis": "Documented framework outcome.", "scope": "Request media type" }, "description": "Unsupported request content type.", "handling": "Send application/json. ProblemDetails is a separate response model.", "body": "application/problem+json; not the PayStar BusinessError envelope." }, { "id": "internal_or_configuration_error", "title": "Server or configuration error", "group": "http", "appliesTo": [ "create_and_some_status_endpoints" ], "http": { "status": 500, "basis": "Documented server-error outcome; other 5xx may also occur.", "scope": "Affected operations" }, "description": "A server or configuration failure does not establish whether an order was created.", "handling": "Do not assume the order was not created. Query status before any cascade/retry.", "body": "No universal JSON body is established." }, { "id": "transport_failure", "title": "No HTTP response", "group": "http", "appliesTo": [ "all" ], "http": { "status": null, "basis": "No HTTP response is a transport failure, not an API status code.", "scope": "Timeout, missing response or broken connection" }, "description": "The create result may be unresolved.", "handling": "Retain the original merchant ID. Query status by that ID before another create attempt or cascade; do not replace the ID for a blind retry.", "body": "No HTTP response body." } ] }, "telecomOperators": { "id": "telecom-operators", "title": "Telecom operator values", "description": "Documented telecomOperator values used for phone-based routing.", "usage": "additionalFields.telecomOperator; recommended when phone-based detection is unreliable", "items": [ { "country": "United Kingdom", "country_code": "GB", "enum": "vodafone-uk", "name": "Vodafone" }, { "country": "United Kingdom", "country_code": "GB", "enum": "o2-uk", "name": "O2 (Telefónica)" }, { "country": "United Kingdom", "country_code": "GB", "enum": "everything-everywhere-uk", "name": "Everything Everywhere (EE)" }, { "country": "United Kingdom", "country_code": "GB", "enum": "talk-talk-uk", "name": "TalkTalk" }, { "country": "Ukraine", "country_code": "UA", "enum": "kievstar-ua", "name": "Kievstar" }, { "country": "Ukraine", "country_code": "UA", "enum": "vodafon-ua", "name": "Vodafon Ukraine" }, { "country": "Ukraine", "country_code": "UA", "enum": "lifecell-ua", "name": "Lifecell" }, { "country": "Ukraine", "country_code": "UA", "enum": "intertelecom-ua", "name": "Intertelecom" }, { "country": "Republic of Moldova", "country_code": "MD", "enum": "orange-md", "name": "Orange Moldova" }, { "country": "Republic of Moldova", "country_code": "MD", "enum": "moldcell-md", "name": "Moldcell" }, { "country": "Republic of Moldova", "country_code": "MD", "enum": "unite-md", "name": "Unite" }, { "country": "Poland", "country_code": "PL", "enum": "tMobile-pl", "name": "tMobile Poland" }, { "country": "Poland", "country_code": "PL", "enum": "orange-pl", "name": "Orange Poland" }, { "country": "Poland", "country_code": "PL", "enum": "play-pl", "name": "Play" }, { "country": "Poland", "country_code": "PL", "enum": "plus-pl", "name": "Plus" }, { "country": "Poland", "country_code": "PL", "enum": "lykamobile-pl", "name": "Lykamobile" }, { "country": "Poland", "country_code": "PL", "enum": "virginMobile-pl", "name": "Virgin" }, { "country": "Hungary", "country_code": "HU", "enum": "magyarTelekom-hu", "name": "Magyar Telekom" }, { "country": "Hungary", "country_code": "HU", "enum": "telenor-hu", "name": "Telenor" }, { "country": "Hungary", "country_code": "HU", "enum": "vodafone-hu", "name": "Vodafone Hungary" }, { "country": "Slovakia", "country_code": "SK", "enum": "t-com-sk", "name": "T-Com" }, { "country": "Slovakia", "country_code": "SK", "enum": "t-mobile-sk", "name": "T-Mobile" }, { "country": "Slovakia", "country_code": "SK", "enum": "orange-sk", "name": "Orange Slovensko" }, { "country": "Slovakia", "country_code": "SK", "enum": "upc-sk", "name": "UPC" }, { "country": "Russia", "country_code": "RU", "enum": "beeline-ru", "name": "Beeline" }, { "country": "Russia", "country_code": "RU", "enum": "megafon-ru", "name": "Megafon" }, { "country": "Russia", "country_code": "RU", "enum": "mts-ru", "name": "МТС" }, { "country": "Russia", "country_code": "RU", "enum": "rostelecom-ru", "name": "Rostelecom" }, { "country": "Russia", "country_code": "RU", "enum": "tele2-ru", "name": "Tele2" }, { "country": "Russia", "country_code": "RU", "enum": "yota-ru", "name": "Yota" }, { "country": "Russia", "country_code": "RU", "enum": "tmobile-ru", "name": "Tinkoff Mobile" } ] } }, "reviewRevision": "2026-09-15.5" }