POST
Creating a beneficiary needs a step-up confirmation: the customer proves it’s really them. Send the payee’s bank details as an account object plus a confirmation object. The account object is discriminated by type — it carries exactly the fields that type needs:
The beneficiaries you can create depend on the account you’ll pay from: a GBP account accepts a uk account or an iban account; any other currency requires iban. Sending an account type the paying account doesn’t support is rejected. Read the account’s entry in GET /v1/capabilities — details lists the identifier fields it carries.

Bank details

  • Sort code: 6 digits, with or without dashes. It’s stored and returned without them (04-05-06 comes back as 040506).
  • IBAN: must pass its checksum and be from one of these countries: AT, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GI, GR, HR, HU, IE, IT, LT, LU, LV, MC, MT, NL, PL, PT, RO, SE, SI, SK. For a payee elsewhere, use an international beneficiary.
  • bankName: optional. No account requires it, and this endpoint doesn’t store it.
  • address: optional. If you send one it’s validated (line1 and city non-empty, country 2 letters); some accounts store it and others discard it.
The account named in accountId must be ACTIVE. A blocked, closed or pending account answers 409 ACCOUNT_NOT_ACTIVE.

Retry safely

Send an Idempotency-Key header (a UUID) and reuse the same key if you retry, so a lost response can’t leave the customer with the same payee added twice.
The header is optional today but will be required in a future release. Start sending it now.
A key doesn’t replace the confirmation below. The step-up is verified before the replay is resolved, so a retried request still has to prove it’s the customer — but a fresh confirmation on a retry returns the beneficiary you already created rather than a second one.

Choose a confirmation method

The confirmation object carries a method and that method’s fields. Who must send one, and who may leave it out, is on Step-up confirmation.

When a confirmation is refused

A refused confirmation is always 422 with an SCA_* code: SCA_MISSING, SCA_INVALID_METHOD, SCA_FAILED, SCA_EXPIRED or SCA_ATTEMPTS_EXCEEDED. A 401 only ever means the bearer token is missing or bad. What each code means and what to do is on Step-up confirmation.
An incomplete confirmation (a field its method needs is missing) is a 400 VALIDATION_ERROR.

Authorizations

Authorization
string
header
required

The user's access_token from authentication. The program and environment come from the token.

Headers

Idempotency-Key
string<uuid>

Optional. Makes the request retry-safe: a retry with the same key resolves to the same resource instead of creating a duplicate. Must be a UUID, and is scoped to the authenticated customer. Preferred over any idempotencyKey body field (a header value wins if both are sent). Optional today, but will be required in a future release — send one on every create now so a retry can never produce a duplicate.

Path Parameters

customerId
string
required

The customer's id. It's the customerId from the signed-in user's application (the onboarding response, also returned on the customer's accounts).

Body

application/json

Always required: accountId, name and an account object (the payee's bank details). A confirmation object is required too, except for the waivers on Step-up confirmation.

Which bank details you must send is decided by the account named in accountId, not by anything in the body. Read that account's entry in GET /v1/capabilities before building the request: details lists the identifier fields it carries. By currency: a GBP account accepts either a uk account (6-digit sortCode + 8-digit accountNumber) or an iban account; every other currency, EUR included, requires an iban account.

address is optional here. A value you send is validated (line1 and city non-empty, country exactly 2 letters); some accounts then store it and others discard it. Accounts that discard the address also discard bic (a BIC already stored on an existing beneficiary is still used when paying); accounts that route on the BIC store it. bankName is accepted but not stored on this endpoint. This applies to THIS endpoint only — the cross-border beneficiary endpoint stores address, bic and bankName.

accountId
string
required

Required. The customer account this payee is linked to. A customer can have several accounts; use the accountId of the one the payment will come from (from the customer's account list).

name
string
required

Required. The payee's name.

account
UK · object
required

Destination bank details. Set type to uk or iban and send that type's fields.

confirmation
Passkey · object

Required for an ordinary customer. Omit it only when the caller is waived: an SSO session on a program not ramped onto passkey-only step-up, or the sandbox demo account. A back-office operator is NOT waived and sends their own TOTP or passkey. A missing confirmation is a 422 SCA_MISSING. The full rule is on Step-up confirmation.

address
object

Optional. A value you send is validated first (so a malformed object is rejected); some accounts store it and others discard it.

isCorporate
boolean

Optional. true if the payee is a business, false (default) for an individual. The accountType you see on the beneficiary is derived from this.

idempotencyKey
string<uuid>

Optional. Idempotency key for retry-safety. The Idempotency-Key header is preferred and overrides this field. Reusing a key with different core parameters returns 400.

Response

Created

success
boolean
Example:

true

message
string

What happened, for display.

data
object