Use this guide to validate payee data client-side before calling POST /v1/payees. It also explains which payment rails a given payee is eligible for.
1. Fields required on every payee
| Field | Notes |
|---|---|
clientId | |
nameOnAccount | |
bankCountry | ISO 3166-1 alpha-2 |
type | Individual or Business |
country | ISO 3166-1 alpha-2 — the payee's residential/registered country |
accountNumber or iban | At least one, subject to the bank-identifier rules below |
2. Bank identifier rules
The required bank identifier depends on bankCountry:
SCAN (sort code + account number) — bankCountry = GB only:
Use domesticBankCode and accountNumber. iban is optional.
IBAN — use iban for these countries:
Åland Islands, Albania, Algeria, Andorra, Angola, Austria, Azerbaijan, Bahrain, Belarus, Belgium, Benin, Bosnia and Herzegovina, Brazil, Bulgaria, Burkina Faso, Burundi, Cabo Verde, Cameroon, Central African Republic, Chad, Comoros, Congo (Republic), Costa Rica, Côte d'Ivoire, Croatia, Cyprus, Czech Republic, Djibouti, Dominican Republic, Egypt, El Salvador, Equatorial Guinea, Estonia, Faroe Islands, Falkland Islands, Finland, France, French Guiana, French Southern Territories, Gabon, Georgia, Gibraltar, Greece, Greenland, Guadeloupe, Guernsey, Guinea-Bissau, Honduras, Hong Kong, Hungary, Iceland, Iran, Iraq, Ireland, Isle of Man, Israel, Italy, Jersey, Jordan, Kazakhstan, Kosovo, Kuwait, Latvia, Lebanon, Libya, Liechtenstein, Lithuania, Luxembourg, Madagascar, Mali, Malta, Martinique, Mauritania, Mauritius, Mayotte, Moldova, Monaco, Mongolia, Montenegro, Morocco, Mozambique, Netherlands, New Caledonia, Nicaragua, Niger, North Macedonia, Norway, Oman, Pakistan, Poland, Portugal, Qatar, Réunion, Romania, Russia, Saint Kitts and Nevis, Saint Pierre and Miquelon, San Marino, São Tomé and Príncipe, Saudi Arabia, Senegal, Serbia, Seychelles, Slovakia, Slovenia, Somalia, Sudan, Sweden, Switzerland, Timor-Leste, Togo, Tunisia, Turkey, Ukraine, United Arab Emirates, Vatican City, Wallis and Futuna, Yemen
All other countries — use swiftBic or domesticBankCode as the bank requires.
- If you provide both IBAN and BIC, their country codes must match.
- Confirmation of Payee (
accountNameVerificationId):bankCountry = GBonly — not supported for other GBP-domestic territories (Guernsey, Gibraltar, Isle of Man, Jersey). - Intermediary BICs (
intermediaryBics): optional, SWIFT payments only, max 10.
3. Which payment rail applies
At payment creation, the system selects the rail from the payment's currency, sender and receiver countries, amount, and the payee's bank fields.
| Currency | Sender & receiver country | Amount | Available rails |
|---|---|---|---|
| GBP | Both parties domestic | ≤ £1,000,000 | Faster Payments, CHAPS, SWIFT |
| GBP | Both parties domestic | > £1,000,000 | CHAPS, SWIFT |
| GBP | Cross-border | — | SWIFT only |
| EUR | Receiver in a SEPA country | — | SEPA, SWIFT |
| Any other currency | — | — | SWIFT only |
Each rail requires specific payee fields:
| Rail | Payee fields needed |
|---|---|
| Faster Payments | Sort code + account number |
| CHAPS | Sort code + account number |
| SWIFT | SWIFT BIC (or an alternative national bank identifier where BIC isn't required) + IBAN or account number |
| SEPA | SWIFT BIC + IBAN |
A payment needs to clear both the currency/country/amount check and the payee-field check. If a EUR payment to a SEPA country has no IBAN on the payee, it falls back to SWIFT. It won't fail outright if the payee has the required SWIFT fields.
4. Address requirements
Address requirements follow bankCountry (the bank's country), not country (the payee's own country). Countries not in the table below need no address fields.
For countries in the table, provide streetName, buildingNameNumber, and city. Also provide postalCode where the table shows Yes.
| Country | Postal code required |
|---|---|
| Algeria | Yes |
| Angola | No |
| Armenia | Yes |
| Australia | Yes |
| Azerbaijan | Yes |
| Bangladesh | Yes |
| Barbados | Yes |
| Benin | No |
| Botswana | No |
| Burkina Faso | Yes |
| Burundi | No |
| Cabo Verde | Yes |
| Cameroon | No |
| Canada | Yes |
| Central African Republic | No |
| Chad | No |
| China | Yes |
| Colombia | Yes |
| Comoros | No |
| Congo (Republic) | No |
| Congo (DRC) | Yes |
| Côte d'Ivoire | No |
| Cyprus | Yes |
| Djibouti | No |
| Egypt | Yes |
| Equatorial Guinea | No |
| Eritrea | No |
| Eswatini | Yes |
| Ethiopia | No |
| Gabon | No |
| Gambia | No |
| Ghana | Yes |
| Guinea | No |
| Guinea-Bissau | No |
| Hong Kong | No |
| India | Yes |
| Indonesia | Yes |
| Kazakhstan | Yes |
| Kenya | Yes |
| Kyrgyzstan | Yes |
| Lesotho | Yes |
| Liberia | Yes |
| Libya | No |
| Madagascar | Yes |
| Malawi | Yes |
| Mali | Yes |
| Mauritania | No |
| Mauritius | Yes |
| Moldova | Yes |
| Morocco | Yes |
| Mozambique | Yes |
| Namibia | Yes |
| Niger | Yes |
| Nigeria | Yes |
| Oman | Yes |
| Philippines | Yes |
| Qatar | No |
| Rwanda | No |
| São Tomé and Príncipe | No |
| Senegal | Yes |
| Serbia | Yes |
| Seychelles | No |
| Sierra Leone | No |
| Somalia | No |
| South Africa | Yes |
| South Korea | Yes |
| South Sudan | No |
| Sudan | No |
| Taiwan | Yes |
| Tanzania | Yes |
| Togo | No |
| Tunisia | Yes |
| Turkey | Yes |
| Uganda | Yes |
| United Arab Emirates | No |
| Uzbekistan | Yes |
| Vietnam | Yes |
| Zambia | No |
| Zimbabwe | No |
5. Worked examples
Example 1 — GBP, Jersey, £500
Domestic GBP payee with sort code and account number, no address needed. Routes via Faster Payments.
Example 2 — EUR, Germany
German payee needs an IBAN and SWIFT BIC, no address required. Routes via SEPA.