Bank withdrawals

Withdraw funds to a registered bank account in Colombia in COP or USD.

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

Summary by currency

Country	Currency	Method
🇨🇴 Colombia	COP	Direct bank transfer
🇺🇸 United States	USD	Digital payment / manual transfer

🇨🇴 Withdrawals Colombia (COP)

Complete flow to send money to Colombian bank accounts.

Get bank list

Check available banks.

Get document types

Check valid document types.

Create bank account

Create withdrawal

Execute transfer.

Step 1: Get bank list

Get bank list

Authorizations

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

Endpoint

GEThttps://dev.backend.colurs.co/list_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
country	string	✓	Code e.g. CO, US

Response

response.json

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

💡

Save bank `id` to use when creating bank account.

Step 2: Get document types

Get document types

Authorizations

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

Endpoint

GEThttps://dev.backend.colurs.co/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"}
]

Document types

ID	Code	Description
0	`CC`	Citizenship ID
1	`CE`	Foreigner ID
2	`NIT`	Tax identification number
3	`TI`	Identity card
4	`PPT`	Temporary protection permit

Step 3: Create bank account

Create bank account

Authorizations

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

Endpoint

POSThttps://dev.backend.colurs.co/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
account_holder_document_type	int	✓	Document type ID
account_holder_document	string	✓	Document number
account_number	string	✓	Bank account number
bank_name	int	✓	Bank ID
country_registered	string	✓	CO for Colombia
nickname	string	✕	Alias to identify account

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"
}

cURL Example

curl -X POST "https://dev.backend.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"
}'

Response

response.json

{
"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"}
}

**Account types:** `0` = Savings, `1` = Checking.

💾

Save account `id` to use in the next step.

List bank accounts

Authorizations

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

Endpoint

GEThttps://dev.backend.colurs.co/list_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
country	string	✕	Filter by country: CO, US

Response

response.json

{
"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
  }
]
}

Step 4: Create COP withdrawal

Create COP withdrawal

Authorizations

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

Endpoint

POSThttps://dev.backend.colurs.co/create/third_party_withdraw/

Required Headers

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

Request Body

Field	Type	Required	Description
dispersions	array	✓	Objects with third_party_bank_id, amount, client_idempotency_key
currency	string	✓	COP or USD
longitude	string	✕	Longitude
latitude	string	✕	Latitude
platform	string	✕	API

Response

response.json

{
"code_transaction": "OK",
"data": {
  "thirdpartywithdraw_id": 102,
  "sales_crypto_id": 0
}
}

💰

**Quote mode:** Use `is_for_quote: true` to get fee calculation without executing withdrawal. For estimate, use `POST /send/estimate/user/` with send_channel: DALE.

COP withdrawal statuses

Status	Code	Description
Created	`0`	Withdrawal created, pending process
In process	`1`	Transfer in progress
Deposited	`2`	Funds deposited
Completed	`3`	✅ Withdrawal completed successfully
Rejected	`4`	❌ Rejected by bank

🇺🇸 United States withdrawals (USD)

Two available methods to send USD to US bank accounts.

⚠️

The endpoint POST /api/digital_payment/ does not exist in OpenAPI (swagger.json). For USD sends, see endpoints documented in USD Wallet and US bank accounts.

Manual USD transfer

Step 1: Create US bank account

Create US bank account

Authorizations

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

Endpoint

POSThttps://dev.backend.colurs.co/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 name
account_type	int	✓	0 = Savings, 1 = Checking
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	✓	Must be US
routing_number	string	✓	Bank routing/ABA number
wire	string	✕	Full bank name for SWIFT
address	string	✕	Bank address

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

🏦

`routing_number` (ABA) is required for US bank accounts.

Step 2: Create USD withdrawal

Create USD withdrawal

Authorizations

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

Endpoint

POSThttps://dev.backend.colurs.co/create/third_party_withdraw/

Required Headers

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

Request Body

Field	Type	Required	Description
amount	decimal	✓	Amount
currency	string	✓	USD
full_name	string	✓	Full name
email	string	✓	Email
phone	string	✓	Phone
third_party_bank_id	int	✓	Account ID
platform	string	✓	API
is_for_quote	boolean	✕	false

request.json{
"amount": 500.00,
"currency": "USD",
"full_name": "John Doe",
"email": "john@example.com",
"phone": "+14155551234",
"third_party_bank_id": 90,
"platform": "API",
"is_for_quote": false
}

Response

response.json

{
"code_transaction": "OK",
"data": {
  "withdraw_id": 789
}
}

💵

**Important:** For withdrawals to US banks, only `USD` currency is allowed. If you use another currency, you will receive `InvalidCurrencyForQuoteWithDraw`.

Fee summary

Fees are calculated automatically based on:

Profile configuration (CustomFees)
System global fees (GlobalFee)

The system calculates:

amount: Amount solicitado
fee_amount: Colurs commission
fee_iva_amount: VAT over commission
gmf_amount: GMF (4x1000) si aplica
payed_amount: Total deducted from balance

Common errors

Code	Error	Description
`400`	`BalanceInsufficient`	Insufficient balance for withdrawal
`400`	`InvalidCurrencyForQuoteWithDraw`	Invalid currency for country
`400`	`MarketPlaceUserRequired`	Active wallet is required
`404`	`BankAccountNotFound`	Bank account not found
`422`	`UnsupportedBankName`	Unsupported bank
`422`	`UnsupportedDocumentType`	Invalid document type

How to make payments and withdrawals Mexico withdrawals (MXN)