Creating payees

A payee is a saved beneficiary. Every outbound payment references one by payeeId, so creating the payee correctly is the first thing you do in any payment integration. This guide covers what to send, how the requirements change with the destination country, and how to check a payee before you create it.

You need the payees:write scope, and clientId must name a client your credential may act for.

The request

POST /v1/payees

Which bank details to send

The four bank-detail fields are all optional in the schema because the combination you need depends on bankCountry. Each country has its own rule set on our side, which is why a request that works for one corridor fails for another.

Rather than encode a country matrix in your client, send what you have and let the API tell you:

• For GB, send domesticBankCode (the sort code) and accountNumber.
• For countries that use IBANs, send iban. Add swiftBic when the corridor is Swift rather than SEPA.
• For everywhere else, send accountNumber with swiftBic or the local domesticBankCode.

You never send bankName. It is resolved from the bank details and returned on the payee.

GB payees need Confirmation of Payee first

A GB sort-code payee cannot be created until the name has been checked against the receiving bank under the UK Confirmation of Payee scheme.

1. Call POST /v1/account-name-verifications with clientId, accountHolderName, sortCode, accountNumber and accountType. It needs the verifications:check scope.
2. Read the outcome: answer tells you whether the name matched, actualName gives the real name where the bank discloses it, and reasonCode explains a non-match.
3. Pass the returned id as accountNameVerificationId when you create the payee.

A verification that came back with reason code AC01, meaning the account does not exist, cannot be used to create a payee. Correct the details and run the check again.

POST /v1/account-name-verifications enforces maximum lengths on its request fields: accountHolderName 140 characters, sortCode 50 and accountNumber 50. Exceeding one returns 400 with AccountHolderName must be 140 characters or fewer., SortCode must be 50 characters or fewer. or AccountNumber must be 50 characters or fewer.

Send accountNameVerificationId only for a GB payee that has both a domesticBankCode (sort code) and an accountNumber. On any other payee it is now rejected with 400; it used to be accepted and ignored.

IBAN-based checks under the SEPA Verification of Payee scheme are planned but not yet available.

What comes back

201 returns the full payee and its URL in the Location header. Alongside everything you sent, the payee carries fields the platform derives for you:

The accountNameVerification object

accountNameVerification has the same shape as the POST /v1/account-name-verifications response, and is the verification recorded on the payee.

What each answer means:

When it is populated

accountNameVerification is the verification object only for a GB payee that has a sort code (domesticBankCode) and an accountNumber and was created with a verification. It is null for every other payee: non-GB payees, GB payees identified only by an IBAN, payees with no sort code or account number, and GB sort-code payees whose verification record cannot be found.

The verification shown is the one recorded on the payee, whichever channel created it. That includes payees created in the Portal or by our operators, not only payees created through this API.

Where you can read it

GET /v1/payees/{id} and the 201 body of POST /v1/payees carry accountNameVerification.

Errors worth handling

Deleting a payee

DELETE /v1/payees/{id} returns 204. Deletion is a soft delete: the payee stops appearing in your list but isDeleted on historical records stays truthful, so payments that already reference it keep resolving.

Next: Payment lifecycle and statuses.