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,
"data": {
"id": "ben_4b8e1c9d",
"customerId": "cust_3f9a2b7e",
"accountId": "acc_7c1d8e4a",
"name": "Ada Lovelace",
"status": "ACTIVE"
}
}{
"success": false,
"code": "<string>",
"message": "<string>"
}{
"success": false,
"code": "<string>",
"message": "<string>"
}Create a beneficiary
Adds a payee to a customer’s account. Send the destination fields that match the payee’s account: a UK account needs accountNumber + sortCode; an EU / international account needs iban. You can only create beneficiaries for the rails your program supports (UK and/or EU) — sending details for an unsupported region returns an error. Creating a beneficiary needs a step-up confirmation: include a confirmation object with method: "passkey", "totp", or "pin" (see the Beneficiaries guide).
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,
"data": {
"id": "ben_4b8e1c9d",
"customerId": "cust_3f9a2b7e",
"accountId": "acc_7c1d8e4a",
"name": "Ada Lovelace",
"status": "ACTIVE"
}
}{
"success": false,
"code": "<string>",
"message": "<string>"
}{
"success": false,
"code": "<string>",
"message": "<string>"
}Authorizations
The user's id_token from authentication — the ID token, not the access_token. 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.
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
Step-up confirmation. Set method to passkey, totp, or pin and include that method's fields. pin is a program capability — see Program capabilities.
- Passkey
- 2FA code
- PIN
Show child attributes
Show child attributes
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; a key whose beneficiary is still being claimed returns 409.