Bank accounts

Endpoints to list banks, document types, and create or list third-party bank accounts associated with the user. These accounts are used for Withdrawals and Exchange (FX) disbursement.

Endpoints summary

Countries and account types

The system supports Colombia (CO), United States (US), Mexico (MX), and Brazil (BR). Each country has its own account types and validations.

Account types by country

US accounts: required fields

For country_registered: "US", required fields: wire, routing_number, address, and nickname.

List available banks

Returns the list of banks available for withdrawals/transfers by country.

Endpoint

GET /bank_list_third_party_withdraw/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Response (200)

[
  { "id": 0, "name": "Bancolombia" },
  { "id": 1, "name": "Banco de Bogota" },
  { "id": 2, "name": "Davivienda" },
  { "id": 3, "name": "BBVA Colombia" }
]

List document types

Returns valid identity document types for the account holder.

Endpoint

GET /base/document_type/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Response (200)

[
  { "id": 0, "name": "CC" },
  { "id": 1, "name": "CE" },
  { "id": 2, "name": "NIT" },
  { "id": 3, "name": "TI" },
  { "id": 4, "name": "PPT" }
]

Use the id in account_holder_document_type. Valid types depend on country.

Create bank account

Registers a third-party bank account for the user. The account is then used for withdrawals or Exchange (disbursement).

Endpoint

POST /create_third_party_banks/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Content-Type: application/json

Request (common and country-specific fields)

{
  "account_holder_name": "Sofia Martin",
  "account_type": 0,
  "account_holder_document_type": 0,
  "account_holder_document": "12345678",
  "account_number": "58200011161",
  "bank_name": 0,
  "country_registered": "CO",
  "nickname": "Main Account"
}

{
  "account_holder_name": "John Doe",
  "account_type": 0,
  "account_holder_document_type": 0,
  "account_holder_document": "123456789",
  "account_number": "1234567890",
  "bank_name": 103,
  "country_registered": "US",
  "routing_number": "021000021",
  "wire": "JPMorgan Chase Bank",
  "address": "270 Park Avenue, New York, NY 10017",
  "nickname": "Main Account"
}

curl -X POST "https://api.colurs.co/create_third_party_banks/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "account_holder_name": "Sofia Martin",
    "account_type": 0,
    "account_holder_document_type": 0,
    "account_holder_document": "12345678",
    "account_number": "58200011161",
    "bank_name": 0,
    "country_registered": "CO",
    "nickname": "Main Account"
  }'

Validations

• Bank by country: bank_name must be a valid bank for country_registered.
• Account type by country: account_type must be one allowed for that country.
• Account format: For CLABE (MX) and PIX (BR), format is validated by regex (e.g. CLABE 18 digits, PIX CPF 11 digits).
• Document type by country: Document type must be valid for the country.
• Duplicate account: The same account (same number, document, holder, type, country) cannot be registered twice.
• US: For country_registered: "US", wire, routing_number, address, and nickname are required.

Success response (200)

{
  "code_transaction": "OK",
  "data": {
    "id": 85,
    "account_holder_name": "Sofia Martin",
    "account_type": 0,
    "account_holder_document_type": 0,
    "account_holder_document": "12345678",
    "account_number": "58200011161",
    "bank_name": 0,
    "country_registered": "CO",
    "wire": null,
    "routing_number": null,
    "address": null,
    "nickname": "Main Account"
  }
}

Possible errors

List user bank accounts

Lists the user’s registered bank accounts, with optional country filter.

Endpoint

GET /list_third_party_banks/?country=CO

Query parameters

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Response (200)

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "pk": 85,
      "account_holder_name": "Sofia Martin",
      "account_type": 1,
      "account_holder_document_type": 0,
      "account_holder_document": "12345678",
      "account_number": "58200011161",
      "bank_name": 0,
      "state": "Created",
      "country_registered": "CO",
      "wire": null,
      "routing_number": null
    }
  ]
}

Account states

USD accounts (alphanumeric ID)

USD (dollar) accounts identified by an alphanumeric ID support withdrawals and deposits in USD. Unlike Third Party accounts (numeric ID), these accounts allow changing the name/alias and deactivating the account (hiding it).

Differences from Third Party Banks

Update USD account (change name or deactivate)

Allows changing the alias (name) or deactivating the account. You cannot deactivate and change name in the same request.

Endpoint

PUT /api/v1/thirdpartybank/thirdpartybank

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Content-Type: application/json

Request

Rules: In a single request send either name or status=DEACTIVATED, not both. The name must be unique among the user’s accounts.

{
"bank_account_id": "account_abc123",
"name": "My Main USD Account"
}

{
"bank_account_id": "account_abc123",
"status": "DEACTIVATED"
}

curl -X PUT "https://api.colurs.co/api/v1/thirdpartybank/thirdpartybank" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{"bank_account_id": "account_abc123", "name": "My Main USD Account"}'

Success response (200)

{
  "code_transaction": "OK",
  "result": "The bank account have been updated"
}

When deactivating (status: DEACTIVATED), the system updates the local state and removes the account from the provider; the account no longer appears in the list.

Possible errors

List USD accounts

Returns the user’s USD accounts. Deactivated accounts are not included.

Endpoint

GET /api/v1/usd/accounts

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Response (200)

{
  "data": {
    "payment_types": [
      {
        "id": 1,
        "payment_method": "BANK_TRANSFER",
        "account_id": "account_abc123",
        "name": "My Main USD Account",
        "routing": "021000021",
        "account_number": "1234567890",
        "status": "DEPOSIT_ONLY",
        "type": "CHECKING",
        "created_at": "2026-02-03T10:00:00Z"
      }
    ]
  },
  "message": "ok"
}

Use each account’s account_id as bank_account_id in the PUT request to update or deactivate.

Using the accounts

Once created, the account is used in:

• Bank withdrawals: POST /create/third_party_withdraw/ with the third_party_bank_id field (Colombia COP) or in USD flows.
• Exchange (FX): POST /v2/exchange/initiate/ with the bank_account_id field for automatic disbursement when the movement completes.

The system validates that the account belongs to the authenticated user before executing the withdrawal or movement.