POST
Create an international beneficiary
International payments are offered only on programs whose capabilities show payments.international: true, and most programs don’t have them. Check before you build this flow: on a program without them you can still save an international payee, but every transfer to it is refused with 501 (not_available). To enable them, contact the team.
Adds a payee for cross-border payments, linked to the account in the path. You’ll use it with an international transfer. Send:
  • name.
  • account: IBAN only (type: "iban"; a uk account is rejected). The IBAN can be from any country but must pass its length and checksum check. bic and bankName are optional and stored when sent.
  • currency: the payee’s currency, a 3-letter ISO 4217 code. It isn’t checked against a list when you save the payee.
  • debtorViban: a Luxembourg (LU) virtual IBAN. Take it from the funding account’s virtualIbans in List accounts. Only the LU prefix is checked here.
  • address: optional, validated and stored when sent.
  • A confirmation object, as for a normal beneficiary (passkey, 2FA code, or PIN). Who may leave it out is on Step-up confirmation.

The response

The saved beneficiary is under data. It carries the id both as id and as beneficiaryId (same value; beneficiaryId is kept for older clients). Pass that value as beneficiaryId when you make the transfer. An international beneficiary has no status.

Errors to expect

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. A retry with the same key returns the original payee when name, IBAN, BIC and currency match; a different value in any of them is a 400. debtorViban, address, isCorporate and the account in the path aren’t compared.
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 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 and debtorViban. A confirmation object is required too, except for the waivers on Step-up confirmation.

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). Only the LU prefix is checked here.

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. The full rule is on Step-up confirmation.

address
object

Optional. Validated and stored when sent.

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