Colombia bank accounts

All endpoints require authentication with Authorization: Bearer [TOKEN] and x-api-key.

Endpoint Summary

Endpoint	Method	Description
`/banks/`	GET	List available banks by country (query: country)
`/base/country`	GET	List countries
`/states/`	GET	List states by country (query: country)
`/base/document_type/`	GET	List document types
`/create_third_party_banks/`	POST	Create bank account
`/list_third_party_banks/`	GET	List user accounts (query: country)
`/thirdpartybank`	PUT	Update account (pk and editable fields: alias, account_number, etc.)
`/usd/user/account`	GET / POST	List or create USD accounts

🔒

Third Party accounts (classic CO/US) are immutable: there are no endpoints to edit or delete them. USD accounts (identified by alphanumeric ID) do allow alias updates and deactivation (hide).

Countries and Account Types

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

Account types by country

Country	account_type	Description
CO, US	`0`	Savings
CO, US	`1`	Checking

US accounts: required fields

For country_registered: "US", the following are required: wire, routing_number, address, and nickname.

List Available Banks

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

GET/banks/

Required Headers

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Response

response.json

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

💡

Use the bank `id` in `bank_name` when creating the account. Query: `country` (CO, US).

List Document Types

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

GET/base/document_type/

Required Headers

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Response

response.json

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

The `id` is used in `account_holder_document_type`. Valid types depend on country.

Create Bank Account

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

POST/create_third_party_banks/

Required Headers

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Field	Type	Required	Description
account_holder_name	string	✓	Account holder full name
account_type	int	✓	0 = Savings, 1 = Checking (CO/US)
account_holder_document_type	int	✓	Document type ID
account_holder_document	string	✓	Document number
account_number	string	✓	Account number
bank_name	int	✓	Bank ID
country_registered	string	✓	CO or US
nickname	string	✕	Alias (required in US)
wire	string	✕	SWIFT bank name (required in US)
routing_number	string	✕	Routing/ABA (required in US)
address	string	✕	Bank address (required in US)

request.json{
"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"
}

Response

response.json

{
"code_transaction": "OK",
"data": {
  "id": 85,
  "account_holder_name": "Sofia Martin",
  "account_number": "58200011161",
  "bank_name": 0,
  "country_registered": "CO",
  "nickname": 
"Main Account"}
}

Possible Errors

Code	Error	Description
400	Bad Request	Invalid bank, account type, or document for the country
400	Bad Request	Account is already registered in the system
400	Bad Request	For US: missing wire, routing_number, address, or nickname

💾

Save `id` (`data.id`) to use in withdrawals (`third_party_bank_id`) or Exchange (`bank_account_id`).

Validations: valid `bank_name` for country; `account_type` 0 or 1; valid document type; no duplicate account. US requires `wire`, `routing_number`, `address`, and `nickname`.

List User Bank Accounts

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

GET/list_third_party_banks/

Required Headers

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Response

response.json

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

Optional query: `country` (CO, US). States: Created, Enrollment in progress, Registered, Has an issue.

USD Accounts (Alphanumeric ID)

USD accounts identified by alphanumeric ID allow USD withdrawals and deposits. Unlike Third Party accounts (numeric ID), these accounts let you change alias/name and deactivate (hide) the account.

Differences vs Third Party Banks

	Third Party (CO, US)	USD Accounts (Alphanumeric ID)
ID	Numeric (e.g. `85`)	Alphanumeric (e.g. `account_abc123`)
Alias	Field `nickname` (only on create)	Field `name` (editable with PUT)
Edit / Deactivate	Not available	Yes: PUT to update `name` or `status: DEACTIVATED`

Update USD Account (rename or deactivate)

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

PUT/thirdpartybank

Required Headers

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Field	Type	Required	Description
bank_account_id	string	✓	USD account ID (alphanumeric)
name	string	✕	New alias (only one: name or status)
status	string	✕	Use DEACTIVATED to deactivate/hide

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

Response

response.json

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

Possible Errors

Code	Error	Description
400	Bad Request	Do not send `name` and `status=DEACTIVATED` together
400	Bad Request	Name already used by another account
404	Not Found	USD account not found

In the same request, send only `name` or only `status: DEACTIVATED`. Deactivation is permanent; the account no longer appears in the list.

List USD Accounts

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

GET/usd/user/account

Required Headers

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Response

response.json

{
"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 `account_id` as `bank_account_id` in PUT to update or deactivate. Deactivated accounts are excluded. Only name can be changed; routing and account number cannot.

Account Usage

Once created, the account is used in:

Bank withdrawals: POST /create/third_party_withdraw/ with third_party_bank_id (Colombia COP) or USD flows.
Exchange (FX): POST /v2/exchange/initiate/ with bank_account_id for automatic payout when movement is completed.

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

📄

For the full country-based withdrawal flow, see Bank withdrawals. For cross-border movements with payout, see Exchange (FX).

How to manage bank accounts US bank accounts