Creating External Bank Accounts for Foreign Fiat

This guide explains how to use the Cybrid API to create external bank account records for foreign fiat payouts. If you're looking to implement this feature internally, refer to the architecture documentation.

Overview

External bank accounts enable you to create records for bank accounts that receive funds in foreign fiat currencies through local payment rails. These accounts can be associated with customers or banks.

Cybrid supports four 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

How It Works

Creating an external bank account involves:

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 the routing information (encrypted at rest and in transit) and makes it available for transfer operations. Account creation is processed asynchronously through our payout providers' payment infrastructure.

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, etc.)

Request

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

👍

Note that creating external bank accounts with foreign raw routing details requires Accept-Version: 2025-10-01 or later to access this functionality.

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: Optional (handled at transfer time)

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"
  }],
  "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, 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: 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"
}

Note: bank_code is omitted 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"
}

Related Resources

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