Managed accounts

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:

StateMeaning
PENDING_ALLOCATIONThe IBAN is being allocated. bankAccountDetails isn't usable yet.
ALLOCATEDThe IBAN is ready and bankAccountDetails can be shared and used.
UNALLOCATEDNo IBAN has ever been assigned to this account.

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.

post/managed_accounts/{id}/iban

Request

  • Base URL: https://sandbox.weavr.io/multi
  • URL: https://sandbox.weavr.io/multi/managed_accounts/{id}/iban
  • Auth: HTTP bearer and API key in header api-key

Path parameters

idstring required
Example:123456789

The unique identifier of the managed account.

Headers

idempotency-refstring
Example:transfer-2026-08-07-001

A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

Response

Success

state'UNALLOCATED' | 'PENDING_ALLOCATION' | 'ALLOCATED' required

The state of the Managed Account's IBAN as follows:

  • UNALLOCATED: The Managed Account has never been assigned an IBAN. Use the managedAccountsIBANUpgrade operation to assign an IBAN to a Managed Account.
  • PENDING_ALLOCATION: The IBAN is being allocated to the Managed Account.
  • ALLOCATED: An IBAN is allocated to the Managed Account.

Example response

{
  "bankAccountDetails": [
    {
      "beneficiaryNameAndSurname": "Alex Smith",
      "beneficiaryBank": "National Westminster Bank PLC",
      "beneficiaryBankAddress": "250 Bishopsgate, London EC2M 4AA",
      "paymentReference": "WVR-123456789",
      "details": {
        "iban": "GB29NWBK60161331926819",
        "bankIdentifierCode": "NWBKGB2L"
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.