Create Foreign Fiat External Bank Accounts

Overview

Create external bank account records for bank accounts that receive funds in foreign fiat currencies through local payment rails. Associate these accounts with customers or banks.

Cybrid supports five foreign fiat currencies with region-specific payment rails:

• MXN (Mexican Peso) via SPEI
• COP (Colombian Peso) via PSE
• BRL (Brazilian Real) via PIX
• ARS (Argentine Peso) via COELSA
• INR (Indian Rupee) via IFSC

Prerequisites

Before creating external bank accounts:

• Counterparty Verification: The associated counterparty must be KYC'd/KYB'd and in verified state
• Authentication: API access with external_bank_accounts:execute scope
• Compliance: Ensure adherence to country-specific data privacy regulations (LGPD for Brazil, LFPDPPP for Mexico)

⚠️

PSE requirements

Colombian Peso (COP) accounts via PSE require additional counterparty information: email_address and identification_numbers (passport, identification_card, residence_card, or tax_identification_number).

Create an external bank account

Create an external bank account by following these steps:

1. Create and verify a counterparty representing the account beneficiary
2. Gather payment rail details specific to the destination country
3. Submit account creation request with raw routing details
4. Monitor account state until creation completes

The platform securely stores routing information (encrypted at rest and in transit) and makes it available for transfer operations. The platform processes account creation asynchronously through payout provider payment infrastructure. To monitor creation, poll GET /api/external_bank_accounts/{guid} using the GUID returned from the creation response until the account state is completed (a failed state indicates that creation did not succeed).

Request format

POST /api/external_bank_accounts
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
Accept-Version: 2025-10-01

ℹ️

API versioning

Creating external bank accounts with foreign raw routing details requires Accept-Version: 2025-10-01 or later.

Account model

External bank accounts for foreign fiat use the raw_routing_details account kind. Here's the basic structure:

{
  "account_kind": "raw_routing_details",
  "name": "Descriptive account name",
  "asset": "MXN",
  "customer_guid": "customer_guid",
  "counterparty_guid": "counterparty_guid",
  "counterparty_bank_account_details": [
    {
      "bank_code_type": "CLABE",
      "bank_code": "032",
      "account_identifier": "032180000118359719",
      "account_identifier_type": "CLABE",
      "payment_rail": "SPEI"
    }
  ]
}

Key fields

Counterparty bank account details

Each object in the counterparty_bank_account_details array specifies routing information:

Payment rails

Mexican Peso (MXN) - SPEI

SPEI (Sistema de Pagos Electrónicos Interbancarios) is Mexico's electronic interbank payment system.

Requirements:

• CLABE: 18-digit bank account identifier
• Bank Code: First 3 digits of CLABE

Example:

{
  "account_kind": "raw_routing_details",
  "name": "Mexican beneficiary account",
  "counterparty_bank_account_details": [{
    "bank_code_type": "CLABE",
    "bank_code": "032",
    "account_identifier": "032180000118359719",
    "account_identifier_type": "CLABE",
    "payment_rail": "SPEI"
  }],
  "counterparty_guid": "counterparty_guid",
  "customer_guid": "customer_guid",
  "asset": "MXN"
}

Colombian Peso (COP) - PSE

PSE (Pagos Seguros en Línea) operates through Colombia's ACH network.

Requirements:

• Account Number: Colombian bank account number
• Bank Code: Colombian institution identifier
• Account Type: checking or savings
• Counterparty Information: Additional fields required:
  • email_address
  • identification_numbers - Accepted types:
    • passport - Passport
    • identification_card - CC (Cédula de Ciudadanía)
    • residence_card - Cédula de Extranjería
    • tax_identification_number - NIT (Número de Identificación Tributaria)

Counterparty example:

{
  "type": "individual",
  "name": {
    "first": "John",
    "last": "Doe",
    "full": "John Doe"
  },
  "address": {
    "street": "Carrera 43A # 1 Sur - 50",
    "city": "Medellín",
    "subdivision": "ANT",
    "postal_code": "050021",
    "country_code": "CO"
  },
  "email_address": "[email protected]",
  "identification_numbers": [
    {
      "type": "identification_card",
      "issuing_country_code": "CO",
      "identification_number": "1234567890"
    }
  ],
  "customer_guid": "customer_guid"
}

External bank account example:

{
  "account_kind": "raw_routing_details",
  "name": "Colombian beneficiary account",
  "counterparty_bank_account_details": [{
    "bank_code_type": "PSE",
    "bank_code": "064",
    "account_identifier": "87654321",
    "payment_rail": "PSE",
    "account_type": "checking"
  }],
  "counterparty_guid": "counterparty_guid",
  "customer_guid": "customer_guid",
  "asset": "COP"
}

Brazilian Real (BRL) - PIX

PIX is Brazil's instant payment system, operating 24/7 including weekends and holidays.

Settlement: Real-time

Requirements:

• PIX Key: Account identifier
• Key Type: RANDOM, CPF, CNPJ, PHONE_NUMBER, EMAIL, or EVP

Common PIX key types:

• RANDOM/EVP: UUID generated by receiving institution
• CPF: 11-digit individual tax ID
• CNPJ: 14-digit company tax ID
• PHONE_NUMBER: Registered mobile number
• EMAIL: Registered email address

Example:

{
  "account_kind": "raw_routing_details",
  "name": "Brazilian beneficiary account",
  "counterparty_bank_account_details": [{
    "account_identifier_type": "RANDOM",
    "account_identifier": "184d7eb9-c04b-46ce-b0a6-4145088371c2",
    "bank_code_type": "PIX",
    "payment_rail": "PIX"
  }],
  "counterparty_guid": "counterparty_guid",
  "customer_guid": "customer_guid",
  "asset": "BRL"
}

ℹ️

PIX bank codes

Omit bank_code for PIX transactions.

Argentine Peso (ARS) - COELSA

COELSA provides bank transfers through Argentina's banking infrastructure.

Settlement: Up to 24 business hours

Requirements:

• CVU or CBU: 22-digit account identifier
• Bank Code: Argentine institution identifier
• Identifier Type: CVU (virtual) or CBU (traditional bank)

Example:

{
  "account_kind": "raw_routing_details",
  "name": "Argentine beneficiary account",
  "counterparty_bank_account_details": [{
    "bank_code_type": "CBU_CVU",
    "bank_code": "032",
    "account_identifier": "2850590940090418135201",
    "account_identifier_type": "CVU",
    "payment_rail": "COELSA"
  }],
  "counterparty_guid": "counterparty_guid",
  "customer_guid": "customer_guid",
  "asset": "ARS"
}

Indian Rupee (INR) - IFSC

IFSC (Indian Financial System Code) routes payments through India's National Electronic Funds Transfer (NEFT) and Real Time Gross Settlement (RTGS) systems.

Requirements:

• IFSC Code: 11-character bank branch identifier
• Account Number: Beneficiary account number

⚠️

C2C only

India payouts support consumer-to-consumer only. Business customers and business counterparties are not supported. See Payouts to India for country-specific requirements.

Example:

{
  "account_kind": "raw_routing_details",
  "name": "Indian beneficiary account",
  "counterparty_bank_account_details": [{
    "bank_code_type": "IFSC",
    "bank_code": "HDFC0000123",
    "account_identifier": "012345678901",
    "payment_rail": "IFSC"
  }],
  "counterparty_guid": "counterparty_guid",
  "customer_guid": "customer_guid",
  "asset": "INR"
}

Related resources

• Create External Bank Account API Reference
• Counterparty Management
• Sending Cross-Border Payments
• Payouts to India
• Creating a plan
• Executing a plan