> ## Documentation Index > Fetch the complete documentation index at: https://docs.infinite.dev/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If you are an AI assistant operating Infinite for a user, read the skill first: https://docs.infinite.dev/agent-skill.md (setup per host, tool reference, rules for moving money, journeys). > When operating Infinite for a user, use the MCP server. Sign in at https://bot.api.infinite.dev/mcp (production, acts as the user) or send `Authorization: Bearer ` to https://bot.api.infinite.dev/mcp/sse. Prefer its tools over raw HTTP; use REST only for steps no tool covers, and check `get_endpoint_schema` before guessing a request shape. > Net-new Infinite Connect (org_connect) is operator-assisted: do not grant end users shared org_connect Auth Kit membership or the shared platform org API key — those credentials are org-wide on /v1. BYO org keys onboard under that customer's org id. Operator sessions should show org_connect in get_organization_info. > The key decides the tools. Every organization key (`sk_sandbox_…` / `sk_live_…`) gets docs, onboarding, `get_account_balance`, and request logs for your own organization. BYO organizations add payees an agent will pay with `create_payee` (payable once ACTIVE). Platform Connect sessions instead get bound-customer payment lookups (`get_quote`, `get_transfer`, `list_transfers`, `list_account_balances`), payee drafts (`create_payee_draft` / `get_payee_draft`; screening only, never payable), and transfer drafts that wait for Infinite approval (`create_transfer_draft` / `get_transfer_draft`; never POST /v1/transfers). Where offered, platform `create_transfer` files a real transfer that Infinite holds in review before funding; it cannot be submitted from DRAFT. > An agent key (`sk_sandbox_agent_…` / `sk_live_agent_…`) moves money within that agent's limits: `create_transfer` → `submit_transfer` → `wait_for_transfer`. > On sandbox organization-key sessions, `sandbox_approve_customer` (makes the capabilities you pass READY, and related ones may turn READY too; `request_capabilities` is not needed), `sandbox_fund_account`, and `sandbox_complete_transfer` stand in for verification, funding, and settlement, so a whole flow runs from MCP. BYO keys can pass `customerId` on each call without binding; platform sessions must bind a customer first (`create_business_customer` auto-binds, or send `X-Infinite-On-Behalf-Of`). > When searching documentation without a key, use the docs MCP at https://docs.infinite.dev/mcp. > Start in sandbox (https://sandbox.api.infinite.dev). Do not use production unless the user explicitly asks. > Confirm amount, currency, and payee with the user before any payment is submitted. Pass the invoice number as `reference` on `create_transfer`; the summary says what the payee will see. > REST amounts are integer minor units (`"4000"` = 40.00 USD). MCP payment tools take exact decimal strings (`"40.00"`). Never mix them. > Agent denials return `403 { denial: { code, message, window, limit, used, remaining, attemptedAmount, currency }, hint }` with decimal amounts; per-transfer denials omit `used` and `remaining`. Report them to the user; do not work around them. # Create an external account > Create an external account for bank transfers or proxy-based payments. ## Deduplication Create is find-or-create. Matching differs for bank vs proxy accounts: **Bank accounts** match by customer plus the **exact set** of normalized bank identifiers you supply (any of `swiftBic`, `iban`, `routingNumber`, `accountNumber` that are present) — **not** by `paymentRails`. All supplied identifiers must match; adding or omitting one (e.g. SEPA with only `iban`, then SWIFT with the same `iban` plus `swiftBic`) produces a different identity and a new account. Reusing the same identifier set with a different rail (e.g. ACH after WIRE) returns the existing account and does **not** add that rail. **Proxy accounts** match by customer + normalized alias **+ payment rail**. The same alias on another proxy rail creates a separate account. On a bank-account reuse (`created: false`): - Existing `paymentRails` stay unchanged. - Missing create-only fields (branch, beneficiary document, correspondent details) may be backfilled when supplied; conflicting values return 400. - A closed account (closed via the API) is reopened with the same ID; fixed routes disabled when it was closed stay disabled and must be re-enabled separately. To add compatible bank rails to an existing account (e.g. ACH onto a WIRE-only US account), use `PATCH /v1/external-bank-accounts/{id}` with the full resulting `paymentRails` list. Do not rely on a second create. On every create response, check `created`. For bank accounts also check `paymentRails`; for proxy accounts check `paymentRail` (proxies do not return `paymentRails`). HTTP 201 with `created: false` means identity reuse, not a new rail set. ## Field Mapping We use generic field names that adapt to country-specific identifiers: | Field | US | UK | EU | India | Mexico | Australia | |-------|----|----|----|----|----|----| | `routingNumber` | ABA (9 digits) | Sort code (6 digits) | - | IFSC (11 chars) | - | BSB (6 digits) | | `accountNumber` | Account number | Account (8 digits) | - | Account number | CLABE (18 digits) | Account number | | `iban` | - | - | IBAN | - | - | - | ## Bank Account Requirements by Rail | Rail | Required Fields | |------|-----------------| | **ACH/Wire** (US) | `routingNumber` + `accountNumber` | | **SWIFT** (IBAN countries) | `swiftBic` + `iban` | | **SWIFT** (US) | `swiftBic` + `accountNumber` (`routingNumber` optional) | | **SWIFT** (AU) | `swiftBic` + `routingNumber` (BSB) + `accountNumber` | | **SEPA** | `iban` (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. ## OpenAPI ````yaml post /v1/external-bank-accounts openapi: 3.0.0 info: title: Infinite API description: API for Infinite version: '1.0' contact: {} servers: - url: https://sandbox.api.infinite.dev description: Sandbox - url: https://api.infinite.dev description: Production security: [] tags: - name: Accounts description: Virtual and external account management - name: Customers description: Customer identity management - name: Documents description: Document upload and management - name: Fixed Routes description: Fixed route management - name: External Bank Accounts description: External bank account management - name: External Wallets description: External wallet management - name: Infinite Wallets description: Infinite Wallet management - name: Organizations description: Organization management - name: Quotes description: Quote creation and management - name: Transfers description: Money movement and transaction tracking - name: Verification description: Identity verification workflows - name: Terms of Service description: Terms of Service acceptance - name: Health description: System health and monitoring - name: Sandbox description: Sandbox utilities paths: /v1/external-bank-accounts: post: tags: - External Bank Accounts summary: Create an external account description: >- Create an external account for bank transfers or proxy-based payments. ## Deduplication Create is find-or-create. Matching differs for bank vs proxy accounts: **Bank accounts** match by customer plus the **exact set** of normalized bank identifiers you supply (any of `swiftBic`, `iban`, `routingNumber`, `accountNumber` that are present) — **not** by `paymentRails`. All supplied identifiers must match; adding or omitting one (e.g. SEPA with only `iban`, then SWIFT with the same `iban` plus `swiftBic`) produces a different identity and a new account. Reusing the same identifier set with a different rail (e.g. ACH after WIRE) returns the existing account and does **not** add that rail. **Proxy accounts** match by customer + normalized alias **+ payment rail**. The same alias on another proxy rail creates a separate account. On a bank-account reuse (`created: false`): - Existing `paymentRails` stay unchanged. - Missing create-only fields (branch, beneficiary document, correspondent details) may be backfilled when supplied; conflicting values return 400. - A closed account (closed via the API) is reopened with the same ID; fixed routes disabled when it was closed stay disabled and must be re-enabled separately. To add compatible bank rails to an existing account (e.g. ACH onto a WIRE-only US account), use `PATCH /v1/external-bank-accounts/{id}` with the full resulting `paymentRails` list. Do not rely on a second create. On every create response, check `created`. For bank accounts also check `paymentRails`; for proxy accounts check `paymentRail` (proxies do not return `paymentRails`). HTTP 201 with `created: false` means identity reuse, not a new rail set. ## Field Mapping We use generic field names that adapt to country-specific identifiers: | Field | US | UK | EU | India | Mexico | Australia | |-------|----|----|----|----|----|----| | `routingNumber` | ABA (9 digits) | Sort code (6 digits) | - | IFSC (11 chars) | - | BSB (6 digits) | | `accountNumber` | Account number | Account (8 digits) | - | Account number | CLABE (18 digits) | Account number | | `iban` | - | - | IBAN | - | - | - | ## Bank Account Requirements by Rail | Rail | Required Fields | |------|-----------------| | **ACH/Wire** (US) | `routingNumber` + `accountNumber` | | **SWIFT** (IBAN countries) | `swiftBic` + `iban` | | **SWIFT** (US) | `swiftBic` + `accountNumber` (`routingNumber` optional) | | **SWIFT** (AU) | `swiftBic` + `routingNumber` (BSB) + `accountNumber` | | **SEPA** | `iban` (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. operationId: ExternalBankAccountsController_create_v1 parameters: - name: X-API-Key in: header description: API key required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateExternalBankAccountDto' examples: pixCpf: summary: '[Proxy] PIX with CPF (Brazil)' description: >- Brazilian instant payment using tax ID. Only needs beneficiaryName + aliasType + aliasValue. value: customerId: cust_abc123 beneficiaryName: João Silva aliasType: tax_id aliasValue: '12345678901' paymentRails: - pix pixPhone: summary: '[Proxy] PIX with phone (Brazil)' value: customerId: cust_abc123 beneficiaryName: Maria Santos aliasType: phone aliasValue: '+5511912345678' paymentRails: - pix upi: summary: '[Proxy] UPI VPA (India)' description: Indian instant payment using Virtual Payment Address value: customerId: cust_abc123 beneficiaryName: Raj Patel aliasType: random aliasValue: rajpatel@upi paymentRails: - upi promptpay: summary: '[Proxy] PromptPay (Thailand)' value: customerId: cust_abc123 beneficiaryName: Somchai Jaidee aliasType: national_id aliasValue: '1234567890123' paymentRails: - promptpay achMultiRail: summary: '[Bank] US domestic (ACH + Wire)' description: >- US bank account supporting multiple rails. Uses routingNumber (ABA) + accountNumber. value: customerId: cust_abc123 beneficiaryName: Jane Doe beneficiaryAddress: addressLine1: 456 Oak Avenue city: New York state: NY postalCode: '10001' country: US bankName: Chase Bank bankAddress: country: US accountNumber: '1234567890' routingNumber: '021000021' bankAccountType: checking paymentRails: - ACH - ACH_SAME_DAY - WIRE sepa: summary: '[Bank] SEPA (Eurozone)' description: European bank account using IBAN only. value: customerId: cust_abc123 beneficiaryName: Hans Mueller beneficiaryAddress: addressLine1: Hauptstraße 1 city: Berlin postalCode: '10115' country: DE iban: DE89370400440532013000 paymentRails: - SEPA - SEPA_INSTANT swiftIban: summary: '[Bank] SWIFT to EU (IBAN)' description: International wire to IBAN country using swiftBic + iban. value: customerId: cust_abc123 beneficiaryName: John Smith beneficiaryAddress: addressLine1: 123 Main Street city: London postalCode: SW1A 1AA country: GB bankAddress: country: GB swiftBic: BARCGB22 iban: GB82WEST12345698765432 paymentRails: - SWIFT swiftUs: summary: '[Bank] SWIFT to US' description: >- International wire to US using swiftBic + accountNumber (no IBAN; routingNumber optional). value: customerId: cust_abc123 beneficiaryName: Jane Doe beneficiaryAddress: addressLine1: 456 Oak Avenue city: New York state: NY postalCode: '10001' country: US bankAddress: country: US swiftBic: CHASUS33 routingNumber: '021000021' accountNumber: '1234567890' paymentRails: - SWIFT ukFasterPayments: summary: '[Bank] UK Faster Payments' description: >- UK bank account using sort code (in routingNumber) + account number. value: customerId: cust_abc123 beneficiaryName: James Wilson beneficiaryAddress: addressLine1: 10 Downing Street city: London postalCode: SW1A 2AA country: GB bankName: Barclays routingNumber: '200000' accountNumber: '12345678' paymentRails: - FASTER_PAYMENTS spei: summary: '[Bank] SPEI (Mexico)' description: >- Mexican bank account using 18-digit CLABE (in accountNumber). No routingNumber needed. value: customerId: cust_abc123 beneficiaryName: Carlos García beneficiaryAddress: addressLine1: Av. Reforma 222 city: Mexico City postalCode: '06600' country: MX accountNumber: '032180000118359719' paymentRails: - SPEI responses: '201': description: >- External account created, reused, or reopened successfully. Bank reuse preserves existing paymentRails (other create-only fields may backfill). Proxy reuse matches alias+rail. Check `created` on the body; bank responses also include `paymentRails`, proxy responses include `paymentRail`. content: application/json: schema: $ref: '#/components/schemas/ExternalAccountResponseDto' '401': description: Unauthorized - Invalid or missing authentication credentials security: - bearer: [] x-codeSamples: - lang: bash label: CLI source: >- # Requires: npm i -g @infinite_dev/cli && export INFINITE_API_KEY=sk_sandbox_... # Escape hatch for any endpoint: infinite api infinite api POST /v1/external-bank-accounts \ --body '{"customerId":"cust_abc123","beneficiaryName":"João Silva","aliasType":"tax_id","aliasValue":"12345678901","paymentRails":["pix"]}' - lang: text label: MCP source: >- Create an external account. # Infinite MCP is read-only for this endpoint — use a dedicated MCP tool when one exists, otherwise run the CLI tab. components: schemas: CreateExternalBankAccountDto: type: object properties: correspondentBankName: type: string description: Correspondent/intermediary bank name example: Bank of America maxLength: 200 correspondentBankSwiftCode: type: string description: Correspondent/intermediary bank SWIFT/BIC code (8 or 11 characters) example: IRVTUS3NXXX correspondentAccountNumber: type: string description: Correspondent/intermediary account number example: '9876543210' maxLength: 64 customerId: type: string description: Customer ID example: cust_abc123 counterpartyId: type: string description: >- Existing counterparty ID. When provided for a third-party bank account, known counterparty data can be reused. example: cp_abc123 beneficiaryName: type: string description: Full legal name of the account holder example: John Smith paymentRails: type: array description: >- 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 on first create (e.g., a US account can support ["ACH", "ACH_SAME_DAY", "WIRE"]). If a bank account with the same exact identifier set already exists, create returns that account without changing its rails — use PATCH to add compatible rails. Supplying a different identifier subset (e.g. IBAN only vs IBAN + SWIFT BIC) creates a new account. Proxy accounts dedupe by alias and rail, so the same alias on another proxy rail creates a new account. example: - ACH - WIRE items: type: string enum: - ACH - ACH_SAME_DAY - WIRE - 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 beneficiaryType: type: string description: Beneficiary type (individual or business) enum: - INDIVIDUAL - BUSINESS example: INDIVIDUAL isThirdParty: type: boolean description: >- Whether the account holder differs from the customer (third-party payment). May require additional compliance checks. example: false metadata: description: Custom metadata for your application example: nickname: Primary Business Account allOf: - $ref: '#/components/schemas/AccountMetadataDto' aliasType: type: string description: |- **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. enum: - PHONE - EMAIL - NATIONAL_ID - TAX_ID - RANDOM - CORPORATE_ID example: TAX_ID aliasValue: type: string description: >- **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. example: '12345678901' beneficiaryAddress: description: >- Beneficiary address. Required for SWIFT and most international transfers. Optional for US ACH, same-day ACH, RTP, FedNow, and domestic wire at account create. Street lines are limited to 35 characters for international wire compatibility. Put city, region, and postal code in their own fields — not in the street lines. allOf: - $ref: '#/components/schemas/BeneficiaryAddressDto' beneficiaryPhone: type: string description: Beneficiary phone number in E.164 format example: '+14155551234' beneficiaryDateOfBirth: type: string description: >- Account holder's date of birth. Required at payout time for individual beneficiaries on supported corridors. example: '1990-01-31' format: date bankName: type: string description: >- Bank name. Auto-enriched from routing codes (SWIFT/BIC, IFSC, sort code, etc.) if not provided. Required if enrichment is unavailable. example: JPMorgan Chase Bank bankAddress: description: >- Bank address. Auto-enriched from routing codes (SWIFT/BIC, IFSC, sort code, etc.) if not provided. Required if enrichment is unavailable. allOf: - $ref: '#/components/schemas/BankAddressDto' swiftBic: type: string description: |- SWIFT/BIC code (8 or 11 characters). - **SWIFT transfers**: Always required - **SEPA**: Optional (IBAN-only supported) example: CHASUS33 iban: type: string description: |- IBAN (International Bank Account Number). - **SWIFT to EU/UK**: Required (with swiftBic) - **SEPA/SEPA Instant**: Required (swiftBic optional) example: DE89370400440532013000 accountNumber: type: string description: >- 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) example: '1234567890' routingNumber: type: string description: >- 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 example: '021000021' branchCode: type: string description: >- 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) example: '001' beneficiaryDocumentType: type: string description: >- 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. example: CC beneficiaryDocumentNumber: type: string description: >- 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. example: '12345678901' beneficiaryStateProvince: type: string description: >- 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. example: LIMA bankAccountType: type: string description: >- 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. enum: - checking - savings example: checking currencyCodes: description: >- 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: - USD type: array items: type: string required: - customerId - beneficiaryName - paymentRails ExternalAccountResponseDto: type: object properties: id: type: string description: Account ID example: eba_1234567890abcdef customerId: type: string description: Customer ID example: cust_abc123 counterpartyId: type: string description: Counterparty ID when this is a third-party recipient account example: cp_abc123 nullable: true type: type: string enum: - EXTERNAL_BANK - EXTERNAL_PROXY description: Account type example: EXTERNAL_BANK status: type: string enum: - IN_REVIEW - ACTIVE - CLOSED description: Account status example: IN_REVIEW beneficiaryType: type: string enum: - INDIVIDUAL - BUSINESS description: Beneficiary type example: INDIVIDUAL beneficiaryName: type: string description: Beneficiary name example: John Smith metadata: description: Custom metadata for your application, including account nickname allOf: - $ref: '#/components/schemas/AccountMetadataDto' paymentRail: type: string description: Primary payment rail for this account enum: - 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 example: SWIFT paymentRails: type: array description: All payment rails this account supports (bank accounts only) example: - ACH - ACH_SAME_DAY - WIRE items: type: string enum: - 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 beneficiaryAddress: type: object description: Beneficiary address (bank accounts only) properties: addressLine1: type: string example: 123 Main Street addressLine2: type: string example: Suite 100 city: type: string example: New York state: type: string example: NY postalCode: type: string example: '10001' country: type: string example: US beneficiaryPhone: type: string description: Beneficiary phone number example: '+12125551234' beneficiaryDateOfBirth: type: string description: Account holder's date of birth example: '1990-01-31' format: date bankName: type: string description: Bank name (bank accounts only) example: JPMorgan Chase Bank bankAddress: type: object description: Bank address (bank accounts only) properties: addressLine1: type: string example: 270 Park Avenue addressLine2: type: string example: Floor 10 city: type: string example: New York state: type: string example: NY postalCode: type: string example: '10017' country: type: string example: US swiftBic: type: string description: SWIFT/BIC code (bank accounts only) example: CHASUS33 iban: type: string description: IBAN (bank accounts only) example: GB82WEST12345698765432 accountNumber: type: string description: Bank account number (bank accounts only) example: '1234567890' routingNumber: type: string description: Bank routing code (ABA routing number, sort code, BSB, IFSC, etc.) example: '021000021' branchCode: type: string description: >- Bank branch code (for countries like Japan, Brazil, South Africa that use separate branch identifiers) example: '001' beneficiaryDocumentType: type: string description: >- Type of the beneficiary's national/tax identification document (rail-specific codes, e.g. CC/NIT for Colombia, RUT for Chile) example: CC beneficiaryDocumentNumber: type: string description: The beneficiary's national/tax identification document number example: '12345678901' beneficiaryStateProvince: type: string description: >- The beneficiary's state/department/province (rails that require it on payouts, e.g. Peru ACH) example: LIMA correspondentBankName: type: string description: Correspondent/intermediary bank name (SWIFT) example: Bank of America correspondentBankSwiftCode: type: string description: Correspondent/intermediary bank SWIFT/BIC code (SWIFT) example: IRVTUS3NXXX correspondentAccountNumber: type: string description: Correspondent/intermediary account number (SWIFT) example: '9876543210' bankAccountType: type: string description: Bank account type (bank accounts only) enum: - checking - savings example: checking currencyCodes: description: Supported currency codes example: - USD - EUR type: array items: type: string aliasType: type: string description: Type of proxy alias (proxy accounts only) enum: - PHONE - EMAIL - NATIONAL_ID - TAX_ID - RANDOM - CORPORATE_ID example: TAX_ID aliasValue: type: string description: The proxy alias value (proxy accounts only) example: '12345678901' createdAt: type: string description: Account creation date format: date-time example: '2026-01-15T10:00:00Z' updatedAt: type: string description: Account last update date format: date-time example: '2026-01-15T10:00:00Z' created: type: boolean description: >- Present on create responses. `true` = a new account was inserted. `false` = an existing account matched (bank: customer + the exact normalized identifier set supplied; proxy: customer + alias + rail) and was reused. For bank accounts, existing `paymentRails` are not updated by create — use PATCH to add rails; missing create-only fields may still be backfilled and conflicting values return 400. For proxy accounts, inspect `paymentRail` (proxies do not return `paymentRails`). example: true required: - id - customerId - type - status - beneficiaryType - beneficiaryName - paymentRail - createdAt - updatedAt AccountMetadataDto: type: object properties: nickname: type: string description: Account nickname example: Main Checking Account maxLength: 256 purpose: type: string description: Account purpose example: Business operations maxLength: 512 tags: description: Account tags example: - primary - operations type: array items: type: string BeneficiaryAddressDto: type: object properties: addressLine1: type: string description: >- Street line 1. Maximum 35 characters for international wire compatibility. Do not include city, region, or postal code. example: 123 Main Street maxLength: 35 addressLine2: type: string description: >- Street line 2 (apartment, suite, etc.). Maximum 35 characters for international wire compatibility. Do not include city, region, or postal code. example: Apt 4B maxLength: 35 city: type: string description: City example: San Francisco maxLength: 256 state: type: string description: State / Province example: CA maxLength: 256 postalCode: type: string description: >- Postal code / ZIP code. May be empty for countries without a postal-code system, including the United Arab Emirates. example: '94102' maxLength: 50 country: type: string description: Country code (ISO 3166-2) example: US minLength: 2 maxLength: 2 transliterated: description: >- Transliterated address fields (Latin characters) for non-Latin addresses. Required when address contains non-Latin characters (Chinese, Arabic, Cyrillic, etc.). allOf: - $ref: '#/components/schemas/TransliteratedAddressDto' required: - addressLine1 - city - postalCode - country BankAddressDto: type: object properties: addressLine1: type: string description: Address line 1 (optional for bank addresses) example: 123 Main Street maxLength: 1024 addressLine2: type: string description: Address line 2 (apartment, suite, etc.) example: Apt 4B maxLength: 1024 city: type: string description: City example: San Francisco maxLength: 256 state: type: string description: State / Province example: CA maxLength: 256 postalCode: type: string description: Postal code / ZIP code (optional for bank addresses) example: '94102' maxLength: 50 country: type: string description: Country code (ISO 3166-2) example: US minLength: 2 maxLength: 2 TransliteratedAddressDto: type: object properties: addressLine1: type: string description: Transliterated address line 1 (Latin characters) example: 123 Main Street maxLength: 1024 addressLine2: type: string description: Transliterated address line 2 (Latin characters) example: Apt 4B maxLength: 1024 city: type: string description: Transliterated city (Latin characters) example: Beijing maxLength: 256 state: type: string description: Transliterated state/province (Latin characters) example: Hebei maxLength: 256 securitySchemes: bearer: scheme: bearer bearerFormat: API Key type: http description: API Key in Bearer format (e.g., Bearer sk_test_...) ```` ## Related topics - [Create an external wallet](/api-reference/external-wallets/create-an-external-wallet.md) - [Update an external account](/api-reference/external-bank-accounts/update-an-external-account.md) - [Accounts](/concepts/accounts.md) - [Close an external account](/api-reference/external-bank-accounts/close-an-external-account.md) - [Create a balance account](/api-reference/balance-accounts/create-a-balance-account.md)