1M1money
crate::connectivity::fiat::controller::openapi::external_accounts

POST /v1/customers/{customer_id}/external-accounts

Changed on

Request

Path parameters

customer_idstring required

Unique identifier of the customer to associate the account with

Headers

Idempotency-Keystring required

UUID v4 for idempotent requests. Prevents duplicate account creation.

Request body

networkstring 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)
  • US_FEDNOW: For US instant payments over FedNow
  • 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, including INR transfers to Indian bank accounts
  • CHATS: For Hong Kong USD transfers over CHATS
  • FPS: For Hong Kong HKD and CNY transfers over Faster Payment System (FPS)
  • SEPA: For EUR transfers to bank accounts in supported SEPA countries, addressed by IBAN
  • FASTER_PAYMENT: For GBP transfers to United Kingdom or Jersey bank accounts
  • UAEFTS: For AED transfers to the United Arab Emirates bank accounts
  • UPI: For INR transfers to Indian virtual payment addresses
nicknamestring nullable

User-defined nickname or label for the account (optional). Helps identify the account in listings. Blank values are treated as omitted.

account_holder_namestring required

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

currencystring required

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

country_code'AND' | 'ARE' | 'AFG' | 'ATG' | 'AIA' | 'ALB' | 'ARM' | 'AGO' | 'ARG' | 'ASM' | 'AUT' | 'AUS' | 'ABW' | 'AZE' | 'BIH' | 'BRB' | 'BGD' | 'BEL' | 'BFA' | 'BGR' | 'BHR' | 'BDI' | 'BEN' | 'BLM' | 'BMU' | 'BRN' | 'BOL' | 'BES' | 'BRA' | 'BHS' | 'BTN' | 'BWA' | 'BLR' | 'BLZ' | 'CAN' | 'CCK' | 'COD' | 'CAF' | 'COG' | 'CHE' | 'CIV' | 'COK' | 'CHL' | 'CMR' | 'CHN' | 'COL' | 'CRI' | 'CUB' | 'CPV' | 'CUW' | 'CXR' | 'CYP' | 'CZE' | 'DEU' | 'DJI' | 'DNK' | 'DMA' | 'DOM' | 'DZA' | 'ECU' | 'EST' | 'EGY' | 'ESH' | 'ERI' | 'ESP' | 'ETH' | 'FIN' | 'FJI' | 'FLK' | 'FSM' | 'FRO' | 'FRA' | 'GAB' | 'GBR' | 'GRD' | 'GEO' | 'GUF' | 'GGY' | 'GHA' | 'GIB' | 'GRL' | 'GMB' | 'GIN' | 'GLP' | 'GNQ' | 'GRC' | 'SGS' | 'GTM' | 'GUM' | 'GNB' | 'GUY' | 'HKG' | 'HND' | 'HRV' | 'HTI' | 'HUN' | 'IDN' | 'IRL' | 'ISR' | 'IMN' | 'IND' | 'IOT' | 'IRQ' | 'IRN' | 'ISL' | 'ITA' | 'JEY' | 'JAM' | 'JOR' | 'JPN' | 'KEN' | 'KGZ' | 'KHM' | 'KIR' | 'COM' | 'KNA' | 'PRK' | 'KOR' | 'KWT' | 'CYM' | 'KAZ' | 'LAO' | 'LBN' | 'LCA' | 'LIE' | 'LKA' | 'LBR' | 'LSO' | 'LTU' | 'LUX' | 'LVA' | 'LBY' | 'MAR' | 'MCO' | 'MDA' | 'MNE' | 'MAF' | 'MDG' | 'MHL' | 'MKD' | 'MLI' | 'MMR' | 'MNG' | 'MAC' | 'MNP' | 'MTQ' | 'MRT' | 'MSR' | 'MLT' | 'MUS' | 'MDV' | 'MWI' | 'MEX' | 'MYS' | 'MOZ' | 'NAM' | 'NCL' | 'NER' | 'NFK' | 'NGA' | 'NIC' | 'NLD' | 'NOR' | 'NPL' | 'NRU' | 'NIU' | 'NZL' | 'OMN' | 'PAN' | 'PER' | 'PYF' | 'PNG' | 'PHL' | 'PAK' | 'POL' | 'SPM' | 'PCN' | 'PRI' | 'PSE' | 'PRT' | 'PLW' | 'PRY' | 'QAT' | 'REU' | 'ROU' | 'SRB' | 'RUS' | 'RWA' | 'SAU' | 'SLB' | 'SYC' | 'SDN' | 'SWE' | 'SGP' | 'SHN' | 'SVN' | 'SJM' | 'SVK' | 'SLE' | 'SMR' | 'SEN' | 'SOM' | 'SUR' | 'SSD' | 'STP' | 'SLV' | 'SXM' | 'SYR' | 'SWZ' | 'TCA' | 'TCD' | 'TGO' | 'THA' | 'TJK' | 'TKL' | 'TLS' | 'TKM' | 'TUN' | 'TON' | 'TUR' | 'TTO' | 'TUV' | 'TWN' | 'TZA' | 'UKR' | 'UGA' | 'USA' | 'URY' | 'UZB' | 'VAT' | 'VCT' | 'VEN' | 'VGB' | 'VIR' | 'VNM' | 'VUT' | 'WLF' | 'WSM' | 'XKX' | 'YEM' | 'MYT' | 'ZAF' | 'ZMB' | 'ZWE' required

ISO 3166-1 alpha-3 country codes.

account_numberstring required

The bank account identifier.

  • For US_FEDWIRE, US_ACH, US_RTP, and US_FEDNOW: Standard bank account number
  • For SWIFT: Account number format depends on the bank country. Germany requires a valid 22-character DE IBAN; Mexico requires a valid 18-digit CLABE. Both include checksum validation. United Arab Emirates accounts in USD require a valid 23-character AE IBAN.
  • For SPEI: 18-digit CLABE
  • For LOCAL_BANK_TRANSFER: Local bank account number; India requires 9 to 18 ASCII digits and Japan requires exactly 7 ASCII digits, including leading zeros
  • For CHATS: Hong Kong bank account number
  • For FPS: Hong Kong branch code followed by the account number, totaling 9-16 digits
  • For SEPA: IBAN matching the bank country, without spaces or separators; letters are stored uppercase
  • For FASTER_PAYMENT: Exactly 8 ASCII digits, preserving leading zeros; no spaces or separators
  • For UAEFTS: A valid 23-character AE IBAN without spaces or separators
  • For UPI: VPA in name@handle format, 3 to 50 characters, without spaces
institution_idstring nullable

The primary institution routing identifier.

  • For US_FEDWIRE, US_ACH, US_RTP, and US_FEDNOW: 9-digit ABA routing number
  • For SWIFT: 8 or 11-character SWIFT/BIC code of the destination bank
  • For SPEI: not required; the bank code is derived from CLABE. Submitted values are ignored.
  • 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

For SEPA, institution_id, institution_clearing_code, and intermediary_bank are ignored. For UAEFTS, the bank code is derived from the IBAN in account_number; institution_id is not used. For FASTER_PAYMENT, institution_id is the required 6-digit sort code, without spaces or separators; institution_clearing_code and intermediary_bank are ignored. This field is required for LOCAL_BANK_TRANSFER, CHATS, and FPS. For India LOCAL_BANK_TRANSFER, supply the 11-character IFSC instead of a catalog bank ID. For Singapore LOCAL_BANK_TRANSFER in SGD, supply the selected bank's four-digit ABS bank code. For Japan LOCAL_BANK_TRANSFER in JPY, supply the four-digit bank code and the three-digit branch code in institution_clearing_code, preserving leading zeros. For other LOCAL_BANK_TRANSFER destinations and FPS, do not derive or substitute an institution ID; use one of the canonical values listed in the guide. For UPI, institution_id, institution_clearing_code, and intermediary_bank are ignored.

institution_namestring nullable

Full legal name of the financial institution. For routing-code based networks and CHATS, it is resolved from institution_id when omitted. For SEPA, FASTER_PAYMENT, India LOCAL_BANK_TRANSFER, and UPI, this is an optional user-supplied bank name. Routing-code based networks and CHATS allow up to 80 characters; other networks allow up to 128. Blank values are treated as omitted. For SPEI, UAEFTS, FPS, and LOCAL_BANK_TRANSFER outside India, the bank name comes from the bank directory. Submitted values are ignored.

institution_clearing_codestring nullable

Additional local or regional routing code for SWIFT, required for certain countries. Required for Japan LOCAL_BANK_TRANSFER in JPY: exactly 3 ASCII digits representing the branch code (for example, 025). Ignored for other payment networks and destinations.

Example request

{
  "network": "SWIFT",
  "nickname": "Primary Operating Account",
  "account_holder_name": "TechStart Holdings LLC",
  "currency": "USD",
  "account_number": "4447891623",
  "institution_clearing_code": "021000021",
  "intermediary_bank": {
    "institution_id": "PNBPUS3NNYC"
  }
}

Response

External account created successfully - Returns the newly created account with assigned external_account_id

external_account_idstring required

Unique identifier for the external account (UUID format). Use this ID for all subsequent operations (retrieve, delete, withdrawals).

idempotency_keystring required

HTTP Idempotency-Key header value. Stricter than other IDs: ≤64 ASCII chars per the common REST API convention.

customer_idstring required

Portfolio ID — also exposed as customer_id in OpenAPI. Identifies one individual application / portfolio row within an entity.

status'PENDING' | 'APPROVED' | 'FAILED' required
failure_reasonstring nullable

Customer-readable failure reason and next steps. Present only when status is FAILED.

networkstring required

Public network identifier for bank, blockchain and internal transactions.

Allowed values:

  • Bank: US_ACH, US_FEDWIRE, US_RTP, US_FEDNOW, SWIFT, CUBIX, SPEI, PIX_TRANSFER, LOCAL_BANK_TRANSFER, CHATS, FPS, SEPA, FASTER_PAYMENT, UAEFTS, UPI, EREBOR_RAIL
  • Blockchain: ETHEREUM, POLYGON, ARBITRUM, AVALANCHE, BASE, BNBCHAIN, SOLANA, TRON, ONE_MONEY, BITCOIN
  • Internal: INTERNAL

Availability depends on the asset and customer account configuration.

nicknamestring nullable required

User-defined nickname or label for the account (optional). Helps identify the account in listings.

account_holder_namestring required

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

currencystring required
  • Stablecoin assets: USDC, USDT, PYUSD, RLUSD, USDG, USDP, EURC, MXNB, 1USD(1USD/USDC conversion only, deposit/withdrawal not supported)
  • Digital assets: BTC, ETH, SOL
  • Fiat currencies: USD, MXN
country_code'AND' | 'ARE' | 'AFG' | 'ATG' | 'AIA' | 'ALB' | 'ARM' | 'AGO' | 'ARG' | 'ASM' | 'AUT' | 'AUS' | 'ABW' | 'AZE' | 'BIH' | 'BRB' | 'BGD' | 'BEL' | 'BFA' | 'BGR' | 'BHR' | 'BDI' | 'BEN' | 'BLM' | 'BMU' | 'BRN' | 'BOL' | 'BES' | 'BRA' | 'BHS' | 'BTN' | 'BWA' | 'BLR' | 'BLZ' | 'CAN' | 'CCK' | 'COD' | 'CAF' | 'COG' | 'CHE' | 'CIV' | 'COK' | 'CHL' | 'CMR' | 'CHN' | 'COL' | 'CRI' | 'CUB' | 'CPV' | 'CUW' | 'CXR' | 'CYP' | 'CZE' | 'DEU' | 'DJI' | 'DNK' | 'DMA' | 'DOM' | 'DZA' | 'ECU' | 'EST' | 'EGY' | 'ESH' | 'ERI' | 'ESP' | 'ETH' | 'FIN' | 'FJI' | 'FLK' | 'FSM' | 'FRO' | 'FRA' | 'GAB' | 'GBR' | 'GRD' | 'GEO' | 'GUF' | 'GGY' | 'GHA' | 'GIB' | 'GRL' | 'GMB' | 'GIN' | 'GLP' | 'GNQ' | 'GRC' | 'SGS' | 'GTM' | 'GUM' | 'GNB' | 'GUY' | 'HKG' | 'HND' | 'HRV' | 'HTI' | 'HUN' | 'IDN' | 'IRL' | 'ISR' | 'IMN' | 'IND' | 'IOT' | 'IRQ' | 'IRN' | 'ISL' | 'ITA' | 'JEY' | 'JAM' | 'JOR' | 'JPN' | 'KEN' | 'KGZ' | 'KHM' | 'KIR' | 'COM' | 'KNA' | 'PRK' | 'KOR' | 'KWT' | 'CYM' | 'KAZ' | 'LAO' | 'LBN' | 'LCA' | 'LIE' | 'LKA' | 'LBR' | 'LSO' | 'LTU' | 'LUX' | 'LVA' | 'LBY' | 'MAR' | 'MCO' | 'MDA' | 'MNE' | 'MAF' | 'MDG' | 'MHL' | 'MKD' | 'MLI' | 'MMR' | 'MNG' | 'MAC' | 'MNP' | 'MTQ' | 'MRT' | 'MSR' | 'MLT' | 'MUS' | 'MDV' | 'MWI' | 'MEX' | 'MYS' | 'MOZ' | 'NAM' | 'NCL' | 'NER' | 'NFK' | 'NGA' | 'NIC' | 'NLD' | 'NOR' | 'NPL' | 'NRU' | 'NIU' | 'NZL' | 'OMN' | 'PAN' | 'PER' | 'PYF' | 'PNG' | 'PHL' | 'PAK' | 'POL' | 'SPM' | 'PCN' | 'PRI' | 'PSE' | 'PRT' | 'PLW' | 'PRY' | 'QAT' | 'REU' | 'ROU' | 'SRB' | 'RUS' | 'RWA' | 'SAU' | 'SLB' | 'SYC' | 'SDN' | 'SWE' | 'SGP' | 'SHN' | 'SVN' | 'SJM' | 'SVK' | 'SLE' | 'SMR' | 'SEN' | 'SOM' | 'SUR' | 'SSD' | 'STP' | 'SLV' | 'SXM' | 'SYR' | 'SWZ' | 'TCA' | 'TCD' | 'TGO' | 'THA' | 'TJK' | 'TKL' | 'TLS' | 'TKM' | 'TUN' | 'TON' | 'TUR' | 'TTO' | 'TUV' | 'TWN' | 'TZA' | 'UKR' | 'UGA' | 'USA' | 'URY' | 'UZB' | 'VAT' | 'VCT' | 'VEN' | 'VGB' | 'VIR' | 'VNM' | 'VUT' | 'WLF' | 'WSM' | 'XKX' | 'YEM' | 'MYT' | 'ZAF' | 'ZMB' | 'ZWE' required

ISO 3166-1 alpha-3 country codes.

account_numberstring required
institution_idstring

Routing identifier of the destination bank. For local bank transfers, this is the bank code selected from the supported institution list. Absent for SPEI, where the CLABE in account_number already encodes the bank.

institution_namestring required

Full legal name of the bank institution.

institution_clearing_codestring nullable required

Additional local or regional routing codes required by specific payment networks or countries. Examples: Sort codes (UK), BSB numbers (Australia), transit numbers (Canada). For Japan LOCAL_BANK_TRANSFER in JPY, this is the three-digit branch code.

reference_codestring nullable required

Reference code for wire transfers (optional). A unique identifier that should be included in wire transfer memos to help identify and reconcile incoming payments.

created_atstring required
modified_atstring required

Example response

{
  "external_account_id": "381b013e-8893-11f0-b308-2eaa4f6974f2",
  "customer_id": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
  "failure_reason": "Intermediary bank required. Confirm the details and re-add this account.",
  "network": "ETHEREUM",
  "nickname": "Primary Operating Account",
  "account_holder_name": "TechStart Holdings LLC",
  "currency": "USDC",
  "account_number": "4447891623",
  "institution_id": "CHASUS33",
  "institution_name": "JPMorgan Chase Bank, N.A.",
  "institution_clearing_code": "021000021",
  "intermediary_bank": {
    "institution_id": "PNBPUS3NNYC"
  },
  "reference_code": "36AC1ECAF659",
  "created_at": "2025-08-21T07:56:57.981Z",
  "modified_at": "2025-08-21T07:56:57.981Z",
  "recipient": {
    "recipient_id": "4728c2b9-6df7-11f0-b1f6-6a7838eca3f8",
    "customer_id": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
    "business_type": "INDIVIDUAL",
    "full_name": "John Doe",
    "nickname": "John's Business",
    "email": "john.doe@example.com",
    "relationship": "VENDOR",
    "status": "success",
    "address": {
      "full_address": "490 2nd St Suite 300, San Francisco, CA 94107",
      "country_code": "USA",
      "address_line1": "490 2nd St",
      "address_line2": "Suite 300",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94107"
    },
    "action_required": {
      "type": "RFI",
      "case_id": "TC-WXYZ-2345",
      "action": "SUBMIT_INFORMATION"
    },
    "created_at": "2025-10-29T02:46:25.096305Z",
    "modified_at": "2025-10-29T02:46:25.096305Z"
  }
}

Changes

  • d213edbaccb6Revision changes
    • breaking

      the request property's minLength was increased from 0 to 1

    • breaking

      the response property became nullable for the status

    • breaking

      the response property became nullable for the status

    • breaking

      the response property became nullable for the status

    • breaking

      the response property became optional for the status

    • warning

      the request property's maxLength was set to 64

    • warning

      the request property's maxLength was set to 32

    • warning

      the request property's maxLength was set to 64

    • warning

      the ///// request property's maxLength was set to 64

    • warning

      the request property's maxLength was set to 64

    • warning

      added the new BES enum value to the response property for the response status

    • info

      api tag crate::connectivity::fiat::controller::openapi::external_accounts added

    • info

      api tag External Accounts (Withdraw to Self) removed

    • info

      added the new optional request property

    • info

      the request property became nullable

    • info

      the request property became optional

    • info

      added the new BES enum value to the request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property ///// to the response with the status