{ "schemaVersion": "1.0.0", "contractVersion": "2026-08-25.9", "externalDictionaries": [ { "id": "banks", "path": "banks.json", "description": "Bank-related values are maintained separately because the available source is incomplete and organized mainly by geographic/currency scope." } ], "dictionaries": { "currencies": { "id": "currencies", "title": "Currency codes", "description": "Alpha-3 and normalized three-digit numeric codes reconstructed from the public currency page. Presence here does not guarantee support by a merchant or pipeline route.", "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" } ] }, "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/deposit-by-token-h2h", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "example": true }, { "key": "browserJavascriptEnabled", "category": "browser_and_3ds", "description": "Whether JavaScript is enabled.", "requiredness": "flow_specific", "value_type": "boolean", "source_url": "https://apidoc.paystar.uk/additionalfields", "example": true }, { "key": "browserColorDepth", "category": "browser_and_3ds", "description": "Screen color depth in bits.", "requiredness": "flow_specific", "value_type": "integer", "source_url": "https://apidoc.paystar.uk/additionalfields", "example": 24 }, { "key": "browserScreenWidth", "category": "browser_and_3ds", "description": "Screen width in pixels.", "requiredness": "flow_specific", "value_type": "integer", "source_url": "https://apidoc.paystar.uk/additionalfields", "example": 1920 }, { "key": "browserScreenHeight", "category": "browser_and_3ds", "description": "Screen height in pixels.", "requiredness": "flow_specific", "value_type": "integer", "source_url": "https://apidoc.paystar.uk/additionalfields", "example": 1080 }, { "key": "browserTZ", "category": "browser_and_3ds", "description": "Timezone offset from UTC in minutes.", "requiredness": "flow_specific", "value_type": "integer", "source_url": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "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": "https://apidoc.paystar.uk/additionalfields", "example": "Merch-Customer-12345", "sensitivity": "personal_data" }, { "key": "ExpectedResult", "category": "sandbox", "description": "Forces the expected test result in test mode; has no effect in production.", "requiredness": "optional_test_only", "value_type": "string", "source_url": "https://apidoc.paystar.uk/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", "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": "ISO-8601 UTC string", "action": "string|null" }, "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" } }, "businessErrors": { "id": "business-errors", "title": "Business error catalog", "description": "Documented error entries and the owner-approved wire body. Exact message text is not stable; the complete stable application-code catalog remains incomplete.", "globalCascadeRule": "For any create error, 499+, timeout, broken connection, or missing response, check order status before initiating another attempt/cascade.", "items": [ { "http_status": 400, "id": "validation_error", "applies_to": [ "deposit_create", "payout_create" ], "description": "Malformed request, missing required field, or invalid field value.", "documented_examples": [ { "label": "VALIDATION_ERROR.", "message": "External_transaction_id is required property", "statusDescrption": "0-0000" }, { "label": "VALIDATION_ERROR.", "message": "Amount is required property", "statusDescrption": "0-0000" }, { "label": "VALIDATION_ERROR.", "message": "Currency is required property", "statusDescrption": "0-0000" }, { "label": "VALIDATION_ERROR.", "message": "currency has invalide value", "statusDescrption": "0-0000" } ], "handling": "Fix the request contract. Confirm flow-specific additional fields with the Account Manager." }, { "http_status": 400, "id": "duplicate_external_transaction_id", "applies_to": [ "deposit_create", "payout_create" ], "documented_example": { "label": "VALIDATION_ERROR.", "statusDescrption": "1-4007", "message": "Order with this external_transaction_id already exist" }, "handling": "Do not create another order blindly. Query status using the same externalTransactionId." }, { "http_status": 400, "id": "limit_reached", "applies_to": [ "deposit_create", "payout_create" ], "documented_example": { "label": "LIMITS_ERROR", "message": "Limit id: was reached", "statusDescrption": "0001-0", "externalTransactionId": null }, "handling": "Check configured limits and contact the Account Manager if they must be changed." }, { "http_status": 401, "id": "unauthorized", "applies_to": [ "all" ], "body_documented": null, "description": "Authorization header/key is missing or invalid.", "handling": "Verify the Bearer token and that the correct deposit/payout key is used." }, { "http_status": 403, "id": "forbidden_pipeline", "applies_to": [ "all" ], "body_documented": null, "description": "The key/pipeline is not activated or lacks permission.", "handling": "Contact the Account Manager." }, { "http_status": 403, "id": "invalid_pipeline_type", "applies_to": [ "all" ], "body_documented": null, "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." }, { "http_status": 403, "id": "forbidden_ip", "applies_to": [ "all" ], "body_documented": null, "description": "Source IP is not whitelisted.", "handling": "Ask the Account Manager to whitelist the IP; documentation says propagation can take up to one hour." }, { "http_status": 404, "id": "payment_not_found", "applies_to": [ "status_endpoints" ], "body_documented": null, "handling": "Verify whether a PayStar externalId or merchant externalTransactionId is expected by this endpoint." }, { "http_status": 423, "id": "temporary_or_no_route", "applies_to": [ "deposit_create", "payout_create" ], "description": "Payment parameters do not match active routing/limits, e.g. amount below minimum.", "documented_example": { "label": "TEMPORARY_ERROR", "statusDescrption": "0000-1", "message": "There is currently no possibility to make a payment, please try again later" }, "handling": "Contact the Account Manager and check route/amount/currency/additional-field constraints." }, { "http_status": 500, "id": "internal_or_configuration_error", "applies_to": [ "create_and_some_status_endpoints" ], "central_error_body_documented": false, "handling": "Do not assume the order was not created. Query status before any cascade/retry." } ], "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." ] } }, "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" } ] } } }