Add Bank Account to Recipient

post

https://api.1money.com/v1/customers/{customer_id}/recipients/{recipient_id}/bank_accounts

Add a new bank account to an existing recipient.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

⚠️ Important: Accurate Account Holder Information Required

Provide the account_holder_name as registered with the bank
The submitted name must also satisfy the API's recipient-name matching requirements
Ensure all bank account details (account number, routing number, SWIFT code, etc.) are accurate
Incorrect or mismatched information may result in failed, delayed, or returned transfers
The bank may reject transfers if the beneficiary name does not match their records

Functionality:

Registers a bank account that can be used for fiat withdrawals to this recipient
Accepts US_ACH, US_FEDWIRE, SWIFT, SPEI, LOCAL_BANK_TRANSFER, CHATS, and FPS; availability depends on the account country, currency, customer configuration, and active payment routes
US_RTP and PIX_TRANSFER are not supported by this endpoint
Uses the External Accounts routing-field rules for the supported shared rails
Automatically assigns a unique bank_account_id upon successful creation

Status:

Bank account is created with PENDING status
Status changes to APPROVED after vendor approval (async process)
Status changes to FAILED if vendor rejects the account
Subscribe to external_account.approved and external_account.failed webhooks for status updates

Idempotency & Duplicate Detection:

Required: Include an Idempotency-Key header with a unique UUID

Path Params

customer_id

string

required

Unique identifier of the customer

recipient_id

string

required

Unique identifier of the recipient

Body Params

Request body for creating a new external bank account

network

string

required

Bank network type for the external account.

US_ACH: For US domestic ACH transfers (next-day settlement, lower fees)
US_FEDWIRE: For US domestic wire transfers (same-day settlement)
US_RTP: For US real-time payments (instant settlement)
SWIFT: For international wire transfers via the SWIFT network
SPEI: For Mexican domestic transfers, addressed by an 18-digit CLABE
LOCAL_BANK_TRANSFER: For bank-account transfers over a local clearing network
CHATS: For Hong Kong USD transfers over CHATS
FPS: For Hong Kong HKD and CNY transfers over Faster Payment System (FPS)

nickname

string | null

User-defined nickname or label for the account (optional).
Helps identify the account in listings. Must be 1-64 characters if provided.

account_holder_name

string

required

Full legal name of the account holder (individual or entity).
This is the name registered with the bank for compliance and verification.

currency

string

required

Currency of the bank account (e.g., USD, EUR, GBP).
Must be supported by the selected network type.

country_code

string

enum

required

ISO 3166-1 alpha-3 three-letter country code in uppercase (e.g., USA, GBR, DEU).
Represents the country where the bank account is held. Must be exactly 3 characters.

account_number

string

required

length between 1 and 64

The bank account identifier.

For US_FEDWIRE, US_ACH, and US_RTP: Standard bank account number
For SWIFT international wires with USD: Must be a valid IBAN
For SWIFT with other currencies: Local account number format
For SPEI: 18-digit CLABE
For LOCAL_BANK_TRANSFER: Local bank account number
For CHATS: Hong Kong bank account number
For FPS: Hong Kong branch code followed by the account number, totaling 9-16 digits

institution_id

string | null

The primary institution routing identifier.

For US_FEDWIRE, US_ACH, and US_RTP: 9-digit ABA routing number
For SWIFT: 8 or 11-character SWIFT/BIC code of the destination bank
For SPEI: omit it; the CLABE already encodes its bank in the first three digits
For LOCAL_BANK_TRANSFER: select the applicable canonical institution ID from the
Local Institution ID guide
based on the destination country and currency, then submit it exactly as documented
For CHATS: 8 or 11-character SWIFT/BIC code of the destination bank
For FPS: select the destination bank's three-digit Hong Kong clearing code from the
Local Institution ID guide
based on the destination currency, then submit it exactly as documented

This field is required for LOCAL_BANK_TRANSFER, CHATS, and FPS. For
LOCAL_BANK_TRANSFER and FPS, do not derive or substitute an institution ID; use one of
the canonical values listed in the guide.

institution_name

string | null

Full legal name of the financial institution. For routing-code based networks and
CHATS, it is resolved from institution_id when omitted.

institution_clearing_code

string | null

Additional local or regional routing codes required by specific payment networks or countries.
Examples: Sort codes (UK), BSB numbers (Australia), transit numbers (Canada).
Optional field used when standard institution_id is insufficient for routing.

intermediary_bank

Headers

Idempotency-Key

string

required

UUID v4 for idempotent requests. Prevents duplicate account creation.

Responses

201Bank account added successfully

400Validation failed - Invalid request body

401Authentication failed

404Recipient not found

405Method not allowed

409Conflict - Account with same idempotency key already exists

500Internal server error