POST
Create an international beneficiary

Authorizations

Authorization
string
header
required

The user's access_token from authentication. 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.

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
confirmation
Passkey · object

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.

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.

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.

Response

Created

success
boolean
Example:

true

message
string

What happened, for display.

data
object