Add Counterparty External Bank Accounts

Overview

Create external bank accounts for counterparties to enable third-party payouts. You provide bank routing details and beneficiary information to create accounts using raw routing details.

Counterparty external bank accounts support credit operations only. You can send funds to them but cannot withdraw.

Important Notes for Self-Transfer (US to India) Use Cases:

When creating a counterparty for self-transfers (e.g., a US customer sending to their own Indian bank account), create the counterparty with the customer_guid and using a customer-scoped token. This ensures the counterparty is only visible to that customer and avoids scoping errors.
The counterparty's address should use the most relevant address for the customer (often their US address, especially for NRE accounts that may not have an Indian address).
Required fields for counterparties include: type (must be individual), name.first, name.last, address.city, and address.country_code. Additional fields such as address.street and address.postal_code may also be required depending on the country.
After creating and verifying the counterparty, create the external bank account using both the customer_guid and the counterparty_guid.
If you encounter errors such as "Counterparty not found" or "Invalid bank configuration," ensure that the counterparty was created with the correct scoping and that your bank is configured to support counterparty external bank accounts. Contact support if you need this enabled for your sandbox or production bank.
For more details on required fields for counterparties, see the counterparty creation guide.

⚠️
Payment direction
Counterparty external bank accounts can only receive payments (credits), not send them (debits).

ℹ️
Feature availability
Cybrid disables this feature by default in Production. Contact Cybrid Support to enable it for your bank.

Prerequisites

Before creating a counterparty external bank account:

Create a counterparty. See Creating a Counterparty.
Verify the counterparty's identity. See Verifying a Counterparty.

Create a counterparty external bank account

After you complete the prerequisites, create an external bank account for the counterparty using the POST /api/external_bank_accounts endpoint.

⚠️
Accept-Version header required
Include the header Accept-Version: 2025-10-01 or later in your request. Requests without this header may result in errors about missing required fields.

The following example creates a domestic USD external bank account:

POST /api/external_bank_accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "name": "external_bank_account_name",
  "account_kind": "raw_routing_details",
  "customer_guid": "customer_guid",
  "counterparty_guid": "counterparty_guid",
  "asset": "USD",
  "counterparty_bank_account_details": [
    {
      "bank_code_type": "ABA",
      "bank_code": "routing_number",
      "account_identifier": "account_number",
      "payment_rail": "ACH"
    }
  ]
}

{
  "guid": "external_bank_account_guid",
  "name": "external_bank_account_name",
  "account_kind": "raw_routing_details",
  "customer_guid": "customer_guid",
  "counterparty_guid": "counterparty_guid",
  "asset": "USD",
  "state": "completed",
  "counterparty_bank_account_details": [
    {
      "bank_code_type": "ABA",
      "bank_code": "routing_number",
      "account_identifier": "account_number",
      "payment_rail": "ACH"
    }
  ]
}

For foreign fiat external bank accounts, see Foreign Fiat External Bank Accounts.

For detailed API reference, see Create External Bank Account.

Failure codes

The following error occurs when creating a counterparty external bank account without verification:

unverified_counterparty: Verify the counterparty before creating a counterparty external bank account.