curl --request POST \
--url https://api.next.orenda.finance/v1/customers/{customerId}/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"accountId": "acc_7c1d8e4a",
"name": "Ada Lovelace",
"account": {
"type": "uk",
"sortCode": "040506",
"accountNumber": "87654321"
},
"confirmation": {
"method": "totp",
"totp": "123456",
"accessToken": "eyJraWQiOi..."
}
}
'{
"success": true,
"message": "Beneficiary created successfully",
"data": {
"id": "ben_4b8e1c9d",
"customerId": "cust_3f9a2b7e",
"accountId": "acc_7c1d8e4a",
"name": "Ada Lovelace",
"account": {
"type": "uk",
"sortCode": "040506",
"accountNumber": "87654321"
},
"accountNumber": "87654321",
"sortCode": "040506",
"type": "LOCAL_BENEFICIARY",
"status": "ACTIVE",
"accountType": "CONSUMER",
"isCorporate": false,
"currency": "GBP"
}
}Create a beneficiary
Saves a payee. Send the bank details as an account object discriminated by type: uk takes sortCode and accountNumber; iban takes iban, an optional bic (filled in for you where we can), and bankName for the few accounts that need it.
What’s accepted depends on the account named in accountId: a GBP account takes uk or iban, any other currency takes iban only, and an IBAN must be from a supported SEPA country and pass its checksum. Some accounts require the payee’s address (line1, city, country); read accounts[].beneficiaries.addressRequired in capabilities. Fields the request doesn’t define are ignored.
Needs a confirmation object with method: "passkey", "totp", or "pin" and that method’s fields. See the Beneficiaries guide. The step-up is checked before an Idempotency-Key replay is resolved, so a retry still has to prove it’s the customer; a fresh confirmation on a retry returns the payee you already created rather than a second one.
curl --request POST \
--url https://api.next.orenda.finance/v1/customers/{customerId}/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"accountId": "acc_7c1d8e4a",
"name": "Ada Lovelace",
"account": {
"type": "uk",
"sortCode": "040506",
"accountNumber": "87654321"
},
"confirmation": {
"method": "totp",
"totp": "123456",
"accessToken": "eyJraWQiOi..."
}
}
'{
"success": true,
"message": "Beneficiary created successfully",
"data": {
"id": "ben_4b8e1c9d",
"customerId": "cust_3f9a2b7e",
"accountId": "acc_7c1d8e4a",
"name": "Ada Lovelace",
"account": {
"type": "uk",
"sortCode": "040506",
"accountNumber": "87654321"
},
"accountNumber": "87654321",
"sortCode": "040506",
"type": "LOCAL_BENEFICIARY",
"status": "ACTIVE",
"accountType": "CONSUMER",
"isCorporate": false,
"currency": "GBP"
}
}Authorizations
The user's access_token from authentication. The program and environment come from the token.
Headers
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
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
Always required: accountId, name, an account object (the payee's bank details), and a confirmation object.
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, and beneficiaries.addressRequired says whether a payee address is mandatory. 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.
On accounts where the address is not required it is also not stored — a value you send is still validated (line1 and city non-empty, country exactly 2 letters), because the shared request schema runs before the account's own rules, and is then discarded; omit it. The same accounts neither need nor keep a bic (a BIC already stored on an existing beneficiary is still used when paying), and do not require bankName. Accounts that route on the BIC store it, and derive a missing one from the IBAN for you. This applies to THIS endpoint only — the cross-border beneficiary endpoint stores both.
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).
Required. The payee's name.
Destination bank details. Set type to uk or iban and send that type's fields.
- UK
- IBAN
Show child attributes
Show child attributes
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.
- Passkey
- 2FA code
- PIN
Show child attributes
Show child attributes
Optional on some accounts, required on others — read accounts[].beneficiaries.addressRequired in GET /v1/capabilities. Where it is not required it is not stored either: a value you send is validated first (so a malformed object is rejected) and then discarded; omit the field entirely to avoid that.
Show child attributes
Show child attributes
Optional. true if the payee is a business, false (default) for an individual. The accountType you see on the beneficiary is derived from this.
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.