Sign in
External Bank Accounts

Create an external account

Create an external account for bank transfers or proxy-based payments.

If the same bank details or proxy alias match an account previously closed through the API, that account is reopened and its existing ID is returned. Fixed routes disabled when the account was closed remain disabled and must be re-enabled separately.

Field Mapping

We use generic field names that adapt to country-specific identifiers:

FieldUSUKEUIndiaMexicoAustralia
routingNumberABA (9 digits)Sort code (6 digits)-IFSC (11 chars)-BSB (6 digits)
accountNumberAccount numberAccount (8 digits)-Account numberCLABE (18 digits)Account number
iban--IBAN---

Bank Account Requirements by Rail

RailRequired Fields
ACH/Wire (US)routingNumber + accountNumber
SWIFT (IBAN countries)swiftBic + iban
SWIFT (US)swiftBic + accountNumber (routingNumber optional)
SWIFT (AU)swiftBic + routingNumber (BSB) + accountNumber
SEPAiban (swiftBic optional)
Faster Payments (UK)routingNumber (sort code) + accountNumber
IMPS/NEFT (India)routingNumber (IFSC) + accountNumber
SPEI (Mexico)accountNumber (18-digit CLABE)

Proxy Accounts

For instant payment rails (PIX, UPI, PromptPay), provide alias details instead of bank details:

  • aliasType: phone, email, tax_id, national_id, or random
  • aliasValue: The identifier value

The payment network resolves the alias to the recipient's account.

post/v1/external-bank-accounts

Headers

X-API-Keystring

API key

Request body

correspondentBankNamestring

Correspondent/intermediary bank name

correspondentBankSwiftCodestring

Correspondent/intermediary bank SWIFT/BIC code (8 or 11 characters)

correspondentAccountNumberstring

Correspondent/intermediary account number

customerIdstring required

Customer ID

counterpartyIdstring

Existing counterparty ID. When provided for a third-party bank account, known counterparty data can be reused.

beneficiaryNamestring required

Full legal name of the account holder

paymentRailsstring[] required

Payment rails this account supports.

Bank rails: ACH, SWIFT, SEPA, WIRE, FASTER_PAYMENTS, IMPS, NEFT, SPEI, etc.

Proxy rails: PIX, UPI, PROMPTPAY, DUITNOW (require aliasType + aliasValue)

Compatible bank rails can be combined (e.g., a US account can support ["ach", "ach_same_day", "wire"]).

beneficiaryType'INDIVIDUAL' | 'BUSINESS'

Beneficiary type (individual or business)

isThirdPartyboolean

Whether the account holder differs from the customer (third-party payment). May require additional compliance checks.

aliasType'PHONE' | 'EMAIL' | 'NATIONAL_ID' | 'TAX_ID' | 'RANDOM' | 'CORPORATE_ID'

Required for proxy rails. The type of alias identifier.

Supported alias types vary by rail:

  • PIX (Brazil): phone, email, tax_id (CPF/CNPJ), random
  • UPI (India): phone, random (VPA)
  • PromptPay (Thailand): phone, national_id, tax_id
  • DuitNow (Malaysia): phone, national_id (NRIC), corporate_id
  • GhIPSS (Ghana): phone
  • SINPE (Costa Rica): phone

Note: Both aliasType and aliasValue must be provided together.

aliasValuestring

Required for proxy rails. The alias value. Format depends on aliasType:

  • phone: E.164 format (+5511912345678)
  • email: Standard email format
  • tax_id: Country-specific (Brazil CPF: 11 digits, CNPJ: 14 digits)
  • national_id: Country-specific (Thailand: 13 digits, Malaysia NRIC: 12 digits)
  • random: UUID format or provider-assigned key (e.g., UPI VPA like "user@upi")

Note: Both aliasType and aliasValue must be provided together.

Normalization: The value is normalized to lowercase and trimmed before storage. While some identifiers (e.g., UPI VPAs, emails) may display with mixed case, payment rails typically treat them as case-insensitive for routing.

beneficiaryPhonestring

Beneficiary phone number in E.164 format

beneficiaryDateOfBirthstring date

Account holder's date of birth. Required at payout time for individual beneficiaries on supported corridors.

bankNamestring

Bank name. Auto-enriched from routing codes (SWIFT/BIC, IFSC, sort code, etc.) if not provided. Required if enrichment is unavailable.

swiftBicstring

SWIFT/BIC code (8 or 11 characters).

  • SWIFT transfers: Always required
  • SEPA: Optional (IBAN-only supported)
ibanstring

IBAN (International Bank Account Number).

  • SWIFT to EU/UK: Required (with swiftBic)
  • SEPA/SEPA Instant: Required (swiftBic optional)
accountNumberstring

Bank account number or equivalent. Usage varies by country:

  • US (ACH/Wire): Account number (with 9-digit routingNumber)
  • UK (Faster Payments): 8-digit account (with 6-digit sort code in routingNumber)
  • India (IMPS/NEFT): Account number (with 11 char IFSC in routingNumber)
  • Mexico (SPEI): 18-digit CLABE (routingNumber not needed)
  • Argentina (COELSA): 22-digit CBU (routingNumber not needed)
  • Brazil (TED): Account number (with bank code in routingNumber)
routingNumberstring

Bank routing code. This field adapts to country-specific identifiers:

  • US: 9-digit ABA routing number
  • CA: 8-9 digits (transit + institution)
  • AU: 6-digit BSB
  • UK: 6-digit sort code
  • India: 11 character IFSC code
branchCodestring

Bank branch code. Required for countries that use separate bank and branch identifiers:

  • Japan: 3-digit branch code (used with 4-digit bank code)
  • Brazil: 4-5 digit agency/branch number
  • South Africa: 6-digit branch code
  • New Zealand: 4-digit branch code
  • Bolivia: 3-letter branch city code (e.g. LPZ, SCZ)
beneficiaryDocumentTypestring

Type of the beneficiary's national/tax identification document. Required for payouts on rails whose clearing system carries the beneficiary document — the valid codes are rail-specific:

  • Colombia (ACH): CC, NIT, CE, PA, PPT, TI, RC, TE, DIE, ND
  • Chile (TEF): RUT, RUN, PAS, CE
  • Paraguay (SIPAP): CI, PAS, CRP, CRC, RUC, DNI
  • Peru (ACH): RUC, DNI, PAS, CE

Brazil (TED) and Bolivia take only beneficiaryDocumentNumber (Brazil infers CPF vs CNPJ from the digit count). Optional at creation; payouts on these rails fail without it.

beneficiaryDocumentNumberstring

The beneficiary's national/tax identification document number (e.g. CPF/CNPJ digits for Brazil, cédula number for Colombia/Paraguay, RUT for Chile). Format is validated per rail at payout time. Optional at creation; payouts on rails that require it fail without it.

beneficiaryStateProvincestring

The beneficiary's state/department/province, for rails whose clearing system requires it on payouts (Peru ACH, e.g. LIMA). Optional at creation; payouts on those rails fail without it.

bankAccountType'checking' | 'savings'

Bank account type (checking vs savings). Required for US ACH, and for payouts on rails whose clearing system carries it (e.g. Brazil TED, Colombia ACH, Chile TEF, Peru ACH) — accounts on those rails cannot receive payouts without it.

currencyCodesstring[]

ISO 4217 currency codes this account can receive. If omitted, inferred from the payment rails. Can only be specified for Hong Kong (CHATS) or SWIFT payment rails.

Example request

{
  "correspondentBankName": "Bank of America",
  "correspondentBankSwiftCode": "IRVTUS3NXXX",
  "correspondentAccountNumber": "9876543210",
  "customerId": "cust_abc123",
  "counterpartyId": "cp_abc123",
  "beneficiaryName": "John Smith",
  "paymentRails": [
    "ACH",
    "WIRE"
  ],
  "beneficiaryType": "INDIVIDUAL",
  "metadata": {
    "nickname": "Main Checking Account",
    "purpose": "Business operations",
    "tags": [
      "primary",
      "operations"
    ]
  },
  "aliasType": "TAX_ID",
  "aliasValue": "12345678901",
  "beneficiaryAddress": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US",
    "transliterated": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "city": "Beijing",
      "state": "Hebei"
    }
  },
  "beneficiaryPhone": "+14155551234",
  "beneficiaryDateOfBirth": "1990-01-31",
  "bankName": "JPMorgan Chase Bank",
  "bankAddress": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  },
  "swiftBic": "CHASUS33",
  "iban": "DE89370400440532013000",
  "accountNumber": "1234567890",
  "routingNumber": "021000021",
  "branchCode": "001",
  "beneficiaryDocumentType": "CC",
  "beneficiaryDocumentNumber": "12345678901",
  "beneficiaryStateProvince": "LIMA",
  "bankAccountType": "checking",
  "currencyCodes": [
    "USD"
  ]
}

Response

External account created, reused, or reopened successfully

idstring required

Account ID

customerIdstring required

Customer ID

counterpartyIdstring nullable

Counterparty ID when this is a third-party recipient account

type'EXTERNAL_BANK' | 'EXTERNAL_PROXY' required

Account type

status'IN_REVIEW' | 'ACTIVE' | 'CLOSED' required

Account status

beneficiaryType'INDIVIDUAL' | 'BUSINESS' required

Beneficiary type

beneficiaryNamestring required

Beneficiary name

paymentRail'ACH' | 'ACH_SAME_DAY' | 'WIRE' | 'FEDWIRE' | 'FED_NOW' | 'RTP' | 'EREBOR' | 'EREBOR_RAIL' | 'BALANCE' | 'SWIFT' | 'SEPA' | 'SEPA_INSTANT' | 'TIPS' | 'FASTER_PAYMENTS' | 'BACS' | 'CHAPS' | 'ELIXIR' | 'NICS' | 'EFT' | 'INTERAC' | 'NPP' | 'BECS' | 'UPI' | 'IMPS' | 'IMPS_WITH_FIRC' | 'NEFT' | 'RTGS' | 'BI_FAST' | 'ARTAJASA' | 'PIX' | 'TED' | 'TEF' | 'SPEI' | 'COELSA' | 'SINPE' | 'CIPS' | 'CFXPS' | 'CHATS' | 'ZENGIN' | 'KFTC' | 'FAST_SG' | 'MEPS' | 'DUITNOW' | 'PROMPTPAY' | 'INSTAPAY' | 'PESONET' | 'NAPAS' | 'BEFTN' | 'SLIPS' | 'ZAHAV' | 'GHIPSS' | 'NIBSS' | 'PESALINK' | 'RTC_ZA' | 'TZS_RTGS' | 'EGP_ACH' | 'JOD_ACH' | 'NPSS' | 'MADA' | 'QPS' | 'DOP_ACH' | 'GTQ_ACH' | 'HNL_ACH' | 'PEN_ACH' | 'JMD_ACH' | 'USD_ACH_SV' | 'USD_ACH_EC' | 'CLP_TEF' | 'PSE' | 'COP_ACH' | 'BOB_RTGS' | 'PYG_ACH' | 'CERTIS' | 'DKK_TIPS' | 'SENT' | 'NKS' | 'BANKGIROT' | 'HKD_FPS' | 'IBFT' | 'TRY_FAST' required

Primary payment rail for this account

paymentRailsstring[]

All payment rails this account supports (bank accounts only)

beneficiaryPhonestring nullable

Beneficiary phone number

beneficiaryDateOfBirthstring date

Account holder's date of birth

bankNamestring nullable

Bank name (bank accounts only)

swiftBicstring nullable

SWIFT/BIC code (bank accounts only)

ibanstring nullable

IBAN (bank accounts only)

accountNumberstring nullable

Bank account number (bank accounts only)

routingNumberstring nullable

Bank routing code (ABA routing number, sort code, BSB, IFSC, etc.)

branchCodestring nullable

Bank branch code (for countries like Japan, Brazil, South Africa that use separate branch identifiers)

beneficiaryDocumentTypestring

Type of the beneficiary's national/tax identification document (rail-specific codes, e.g. CC/NIT for Colombia, RUT for Chile)

beneficiaryDocumentNumberstring

The beneficiary's national/tax identification document number

beneficiaryStateProvincestring

The beneficiary's state/department/province (rails that require it on payouts, e.g. Peru ACH)

correspondentBankNamestring nullable

Correspondent/intermediary bank name (SWIFT)

correspondentBankSwiftCodestring nullable

Correspondent/intermediary bank SWIFT/BIC code (SWIFT)

correspondentAccountNumberstring nullable

Correspondent/intermediary account number (SWIFT)

bankAccountType'checking' | 'savings' nullable

Bank account type (bank accounts only)

currencyCodesstring[] nullable

Supported currency codes

aliasType'PHONE' | 'EMAIL' | 'NATIONAL_ID' | 'TAX_ID' | 'RANDOM' | 'CORPORATE_ID' nullable

Type of proxy alias (proxy accounts only)

aliasValuestring nullable

The proxy alias value (proxy accounts only)

createdAtstring date-time required

Account creation date

updatedAtstring date-time required

Account last update date

createdboolean

Whether this account was newly created in this request or returned from an existing match

Example response

{
  "id": "eba_1234567890abcdef",
  "customerId": "cust_abc123",
  "counterpartyId": "cp_abc123",
  "type": "EXTERNAL_BANK",
  "status": "IN_REVIEW",
  "beneficiaryType": "INDIVIDUAL",
  "beneficiaryName": "John Smith",
  "metadata": {
    "nickname": "Main Checking Account",
    "purpose": "Business operations",
    "tags": [
      "primary",
      "operations"
    ]
  },
  "paymentRail": "SWIFT",
  "paymentRails": [
    "ACH",
    "ACH_SAME_DAY",
    "WIRE"
  ],
  "beneficiaryAddress": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  },
  "beneficiaryPhone": "+12125551234",
  "beneficiaryDateOfBirth": "1990-01-31",
  "bankName": "JPMorgan Chase Bank",
  "bankAddress": {
    "addressLine1": "270 Park Avenue",
    "addressLine2": "Floor 10",
    "city": "New York",
    "state": "NY",
    "postalCode": "10017",
    "country": "US"
  },
  "swiftBic": "CHASUS33",
  "iban": "GB82WEST12345698765432",
  "accountNumber": "1234567890",
  "routingNumber": "021000021",
  "branchCode": "001",
  "beneficiaryDocumentType": "CC",
  "beneficiaryDocumentNumber": "12345678901",
  "beneficiaryStateProvince": "LIMA",
  "correspondentBankName": "Bank of America",
  "correspondentBankSwiftCode": "IRVTUS3NXXX",
  "correspondentAccountNumber": "9876543210",
  "bankAccountType": "checking",
  "currencyCodes": [
    "USD",
    "EUR"
  ],
  "aliasType": "TAX_ID",
  "aliasValue": "12345678901",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-01-15T10:00:00Z",
  "created": true
}

Changes

No recorded changes to this endpoint across all 3 revisions of this API.