POST
/
v1
/
customers
/
{customerId}
/
beneficiaries
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>"
}
{
  "success": false,
  "code": "IDEMPOTENT_REQUEST_IN_PROGRESS",
  "message": "A request with this Idempotency-Key is already in progress"
}
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: 
"account": { "type": "uk", "sortCode": "040506", "accountNumber": "87654321" }
"account": { "type": "iban", "iban": "DE89…", "bic": "AGRIFRPP" }
The beneficiaries you can create depend on your program’s rails: a UK program accepts a uk account, an EU program accepts an iban account, and a program set up for both accepts either. Sending an account type your program doesn’t support is rejected. The iban variant also takes an optional bankName (required only on SEPA providers). See Program capabilities.
Some programs require the payee’s address (at least line1, city, and country) when you add a beneficiary; others don’t need it at all. If your program requires it and it’s missing, the create is rejected. See Program capabilities.

​
Choose a confirmation method

The confirmation object carries a method and that method’s fields:

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth 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.

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, an account object (the payee's bank details), and a confirmation object.

​
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

Step-up confirmation. Set method to passkey, totp, or pin and include that method's fields. pin is a program capability — see Program capabilities.

​
address
object
​
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; a key whose beneficiary is still being claimed returns 409.

Response

Created

​
success
boolean
Example:

true

​
data
object