POST
Create an international beneficiary

Authorizations

Authorization
string
header
required

The user's id_token from authentication — the ID token, not the access_token. 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).

accountId
string
required

The id of the account the beneficiary is linked to. A customer can hold several accounts (for example one per currency); a beneficiary belongs to one of them. Take the accountId of the account the payment will be sent from, from the customer's account list.

Body

application/json

The account this payee is linked to is the accountId in the path. Required in the body: name, an account object (must be type: "iban" — international is IBAN-only), currency, debtorViban, and a confirmation object.

name
string
required

Required. The payee's name.

account
IBAN · object
required

The payee's IBAN details. International beneficiaries are IBAN-only — a uk account is rejected.

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.

currency
string
required

Required. The payee's currency (ISO 4217), e.g. USD.

Required string length: 3
debtorViban
string
required

Required. The source virtual IBAN to pay from (must start with LU). Take it from the funding account's details (the account in the path).

Pattern: ^LU
address
object
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