Add an IBAN to an account

Use this when a managed account needs to send or receive wire transfers.

It assigns an IBAN, and the associated bank details, to the managed account identified by the id path parameter. Without one, the account can hold funds and fund cards, but can't take part in incoming or outgoing wire transfers. An outgoing wire transfer from an account with no IBAN fails with IBAN_UPGRADE_REQUIRED.

Prerequisites

The account must exist and be active (INSTRUMENT_IS_NOT_ACTIVE), and the owning identity must have completed due diligence (OWNER_NOT_VERIFIED). Whether an IBAN can be issued at all depends on the account's currency and your payment model; unsupported combinations fail with IBAN_NOT_SUPPORTED.

Allocation is asynchronous

Allocation may not complete during the request. Read state on the response:

When the state is PENDING_ALLOCATION, poll Get an account IBAN until it becomes ALLOCATED. Don't display bank details to the user before then.

Calling it more than once

An account holds at most one IBAN. Repeating the call once an IBAN exists fails with INSTRUMENT_ALREADY_UPGRADED_TO_IBAN, and calling it again while allocation is still in flight fails with IBAN_ALREADY_REQUESTED. Treat both as "already done" rather than retrying. Use Get an account IBAN to read the current state instead.

bankAccountDetails is a list because a payment model can support more than one IBAN provider. Where several sets are returned, each is a valid route for depositing into the same account.