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": "passkey",
"passkeySession": "3f1c2e8a-6b0d-4c1e-9a7f-2d5e8b1c4a90",
"assertion": "{\"credentialIdB64\":\"q1w2e3...\",\"userHandleB64\":\"ZGVtby11c2Vy\",\"clientDataJSON_B64\":\"eyJ0eXBlIjoid2ViYXV0aG4uZ2V0Ii4uLn0\",\"authenticatorDataB64\":\"SZYN5YgO...\",\"signatureB64\":\"MEUCIQ...\"}"
}
}
'{
"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"
}
}Add a beneficiary
Create a payee, confirmed with a passkey, 2FA code, or PIN.
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": "passkey",
"passkeySession": "3f1c2e8a-6b0d-4c1e-9a7f-2d5e8b1c4a90",
"assertion": "{\"credentialIdB64\":\"q1w2e3...\",\"userHandleB64\":\"ZGVtby11c2Vy\",\"clientDataJSON_B64\":\"eyJ0eXBlIjoid2ViYXV0aG4uZ2V0Ii4uLn0\",\"authenticatorDataB64\":\"SZYN5YgO...\",\"signatureB64\":\"MEUCIQ...\"}"
}
}
'{
"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"
}
}account object plus a confirmation object.
The account object is discriminated by type — it carries exactly the fields that
type needs:
"account": { "type": "uk", "sortCode": "040506", "accountNumber": "87654321" }
"account": { "type": "iban", "iban": "DE89…", "bic": "AGRIFRPP" }
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-06comes back as040506). - 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 (line1andcitynon-empty,country2 letters); some accounts store it and others discard it.
accountId must be ACTIVE. A blocked, closed or pending account
answers 409 ACCOUNT_NOT_ACTIVE.
Retry safely
Send anIdempotency-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.
Choose a confirmation method
Theconfirmation object carries a method and that method’s fields. Who must send one,
and who may leave it out, is on Step-up confirmation.
- Passkey (recommended)
- 2FA code
- PIN
passkeySession and fido2options. Unlock the passkey on the device as you would for a
passkey login, but send the result here, in the confirmation, not to a login
endpoint:"confirmation": {
"method": "passkey",
"passkeySession": "3f1c2e8a-…",
"assertion": "{\"credentialIdB64\":\"…\",\"userHandleB64\":\"…\",\"clientDataJSON_B64\":\"…\",\"authenticatorDataB64\":\"…\",\"signatureB64\":\"…\"}"
}
passkeySession is valid for 3 minutes and one request.accessToken — the
access_token from the same sign-in, even if your program uses the ID
token as the Authorization bearer:"confirmation": {
"method": "totp",
"totp": "123456",
"accessToken": "eyJraWQiOi…"
}
"confirmation": {
"method": "pin",
"pin": "1234"
}
When a confirmation is refused
A refused confirmation is always422 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.
{ "success": false, "code": "SCA_FAILED", "message": "PIN does not match for identity" }
confirmation (a field its method needs is missing) is a
400 VALIDATION_ERROR.Authorizations
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
Body
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.
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.
- Passkey
- 2FA code
- PIN
Show child attributes
Show child attributes