A beneficiary is a saved payee. Add the people and businesses a customer wants to pay, then reference the saved payee when you make a payment.

​
What you send

The payee’s bank details: sort code and account number for a UK account, IBAN for anything else. Which of the two an account accepts depends on the account the customer will pay from, and some accounts also require the payee’s address. Read the account’s entry in program capabilities before you build the form: details lists the identifiers it uses, and beneficiaries.addressRequired says whether you need the address.

​
Adding a payee, end to end

Step 2 is optional but recommended. Steps 3 and 4 happen in one request: the confirmation travels in the create call.

​
What you can do

​
Check the name first

Verify a payee’s name checks that the name the customer typed matches the account (Confirmation of Payee in the UK, Verification of Payee in the EU). A close match still counts, and the response carries the name the bank holds. Show it so the customer can decide whether to continue.

​
Add a payee

Create a beneficiary saves a payee. It needs a confirmation from the customer (see below) and an idempotency key so a retry can’t add the same payee twice. Create an international beneficiary is the version for cross-border payments. IBAN only, plus the payee’s currency and the virtual IBAN the payment will be sent from. Same confirmation, same idempotency key. Only available when program.payments.international in program capabilities is on.

​
Manage payees

List, get, and delete saved payees. A payee that a pending or scheduled payment still uses can’t be deleted until that payment completes or is cancelled.

​
Confirming a sensitive action

Adding a payee is a sensitive action, so the customer proves it’s really them. Three methods, and program.beneficiaries.stepUpMethods in program capabilities says which ones your program offers:
  • Passkey (recommended). Request a step-up passkey challenge, complete it on the device the same way as a passkey login, and send the result with the request.
  • 2FA code. Send the 6-digit code from the customer’s authenticator app.
  • PIN. Request a security PIN. It reaches the customer by SMS, lasts 60 seconds, and allows two attempts, so request it right before the action.
The confirmation travels in the request body of the action it confirms. Each endpoint’s reference page shows the exact shape. The same mechanism protects every other sensitive action in the API, such as ad-hoc international and batch payments.