POST
Create an international beneficiary
Adds a payee for cross-border payments. You’ll use it with an international transfer. Send the payee’s bank details as an account object (IBAN-only here — international is type: "iban"; a uk account is rejected), their currency, and a Luxembourg (LU) debtorViban — take the debtorViban from the funding account’s virtualIbans in List accounts. Like a normal beneficiary, this needs a step-up confirmation — include a confirmation object (passkey, 2FA code, or PIN on programs that support it).
International payments are an optional feature. If your program isn’t eligible, this responds with not available. To enable them, contact the team.

Retry safely

Send an Idempotency-Key header (a UUID) and reuse the same key if you retry, so a lost response can’t add the same payee twice.
The header is optional today but will be required in a future release. Start sending it now.

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