Sign in

v1

latestOpenAPI 3.1.0Proprietary2026-07-2464170247.4 KB
Recipients (Send to Others)

Add Bank Account to Recipient

Add a new bank account to an existing recipient.

⚠️ Important: Accurate Account Holder Information Required

  • The account_holder_name must exactly match the name registered with the bank
  • 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
  • Supports US Fedwire, US ACH, and SWIFT international wires (US RTP is not supported for recipients)
  • 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
post/v1/customers/{customer_id}/recipients/{recipient_id}/bank_accounts

Path parameters

customer_idstring required

Unique identifier of the customer

recipient_idstring required

Unique identifier of the recipient

Request body

networkstring required

Bank network type for the external account. External account creation supports standard bank networks only.

  • US_FEDWIRE: For US domestic wire transfers (same-day settlement)
  • US_ACH: For US domestic ACH transfers (next-day settlement, lower fees)
  • US_RTP: For US real-time payments (instant settlement)
  • SWIFT: For international wire transfers via the SWIFT network
nicknamestring nullable

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

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' | '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 domestic networks (FEDWIRE/ACH/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
institution_idstring required

The primary institution routing identifier.

  • For US domestic networks (FEDWIRE/ACH/RTP): 9-digit ABA routing number
  • For SWIFT international wires: 8 or 11-character SWIFT/BIC code of the destination bank
institution_clearing_codestring nullable

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.

Example request

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

Response

Bank account added successfully

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
networkstring required
nicknamestring 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
  • Fiat currencies: USD
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' | '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 required
institution_namestring required

Full legal name of the bank institution.

institution_clearing_codestring required

Additional local or regional routing codes required by specific payment networks or countries. Examples: Sort codes (UK), BSB numbers (Australia), transit numbers (Canada).

reference_codestring 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
recipient_idstring required

Counterparty ID. Empty values are still allowed for legacy DB columns where an empty cpid means the record is not tied to a recipient.

Example response

{
  "external_account_id": "381b013e-8893-11f0-b308-2eaa4f6974f2",
  "customer_id": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
  "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": "active",
    "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"
    },
    "created_at": "2025-10-29T02:46:25.096305Z",
    "modified_at": "2025-10-29T02:46:25.096305Z"
  },
  "recipient_id": "4728c2b9-6df7-11f0-b1f6-6a7838eca3f8"
}