Bank Withdrawals

Endpoints to send money to bank accounts in Colombia and the United States.

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

🇨🇴 Colombia Withdrawals (COP)

Complete flow to send money to Colombian bank accounts.

Get bank list

Query available banks.

Get document types

Query valid document types.

Create bank account

Create withdrawal

Execute the transfer.

Step 1: Get Bank List

Query available Colombian banks for withdrawals.

Endpoint

GET /bank_list_third_party_withdraw/

Headers

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

Response

200 OK

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

💡

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

Step 2: Get Document Types

Query valid identity document types.

Endpoint

GET /base/document_type/

Headers

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

Response

200 OK

[
  {
    "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`	Foreign ID
2	`NIT`	Tax ID
3	`TI`	Identity Card
4	`PPT`	Temporary Protection Permit

Step 3: Create Bank Account

Endpoint

POST /create_third_party_banks/

Headers

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

Request

Field	Type	Required	Description
`account_holder_name`	string	✅	Account holder’s 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 the 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 -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"
}'

Account Types

ID	Type
`0`	Savings Account
`1`	Checking Account

Response

200 OK

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

💾

Save the account id to use in the next step.

List Bank Accounts

Query registered bank accounts.

Endpoint

GET /list_third_party_banks/?country=CO

Query Parameters

Parameter	Type	Description
`country`	string	Filter by country: `CO`, `US`

Response

200 OK

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

Execute the transfer to the Colombian bank account.

Endpoint

POST /create/third_party_withdraw/

Headers

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

Request

Field	Type	Required	Description
`amount`	number	✅	Amount to send in COP
`currency`	string	✅	`COP`
`third_party_bank_id`	int	✅	Bank account ID
`full_name`	string	✅	Beneficiary’s full name
`email`	string	✅	Beneficiary’s email
`phone`	string	✅	Beneficiary’s phone
`platform`	string	✅	`API`, `WEB`, `MOBILE`
`is_for_quote`	boolean	✅	`false` to execute, `true` quote only
`longitude`	string	❌	GPS longitude
`latitude`	string	❌	GPS latitude
`client_callback`	string	❌	URL for notifications

request.json

{
  "amount": 100000,
  "currency": "COP",
  "full_name": "Sofia Martin",
  "email": "sofia@example.com",
  "phone": "+573001234567",
  "third_party_bank_id": 85,
  "platform": "API",
  "is_for_quote": false
}

curl -X POST "https://api.colurs.co/create/third_party_withdraw/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "COP",
    "full_name": "Sofia Martin",
    "email": "sofia@example.com",
    "phone": "+573001234567",
    "third_party_bank_id": 85,
    "platform": "API",
    "is_for_quote": false
}'

💰

Quote Mode: Use is_for_quote: true to get fee calculation without executing the withdrawal.

Response

200 OK

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

COP Withdrawal Statuses

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

🇺🇸 United States Withdrawals (USD)

Two methods available to send USD to US bank accounts.

Method 1: Digital Payment

Primary method for fast USD transfers.

Endpoint

POST /api/digital_payment/

Headers

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

Request

request.json

{
  "deposit_option": "RTP,BANK",
  "amount": 100.00,
  "currency": "USD",
  "ip": "192.168.1.100",
  "latitude": "40.7128",
  "longitude": "-74.0060"
}

Fields

Field	Type	Required	Description
`deposit_option`	string	✅	Options: `RTP`, `RTP_FORCE_BANK`, `BANK` (comma-separated)
`amount`	decimal	✅	Amount in USD
`currency`	string	✅	Must be `USD`
`ip`	string	✅	Client IP
`latitude`	string	❌	GPS latitude
`longitude`	string	❌	GPS longitude

Deposit Options

Option	Description
`RTP`	Real-Time Payment (fastest)
`RTP_FORCE_BANK`	RTP with bank fallback
`BANK`	Traditional bank transfer

⚠️

Requirement: User must have an active USD wallet account. If not, they’ll receive MarketPlaceUserRequired error.

Internal Process

Account validation

Verifies user has active USD wallet.

Fee calculation

Automatically calculates fees.

Balance validation

Verifies sufficient USD funds.

Payment creation

Generates the digital payment.

Balance deduction

Deducts amount + fees from balance.

Response

201 CREATED

{
  "check_id": "CHK_abc123xyz",
  "date": "2026-02-03T10:00:00Z",
  "amount": 100.00,
  "withdraw_id": 456
}

Possible Errors

Code	Error	Description
`400`	`MarketPlaceUserRequired`	User doesn’t have USD wallet
`400`	`UserHaveInsufficientBalance`	Insufficient balance
`400`	`InsufficientFunds`	No available funds

Method 2: Manual USD Transfer

For sending USD to US bank accounts using traditional transfer.

Step 1: Create USA Bank Account

Endpoint

POST /create_third_party_banks/

Request

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

Additional Fields for USA

Field	Type	Required	Description
`country_registered`	string	✅	Must be `US`
`routing_number`	string	✅	Bank routing/ABA number
`wire`	string	❌	Full bank name for SWIFT
`address`	string	❌	Bank address

🏦

The routing_number (ABA) is required for United States bank accounts.

Step 2: Create USD Withdrawal

Endpoint

POST /create/third_party_withdraw/

Request

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
}

💵

Important: For USA bank withdrawals only USD currency can be used. If you try with another currency you’ll receive InvalidCurrencyForQuoteWithDraw error.

Response

200 OK

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

Fee Summary

Fees are automatically calculated based on:

Profile configuration (CustomFees)
System global fees (GlobalFee)

The system calculates:

amount: Requested amount
fee_amount: Colurs fee
fee_iva_amount: VAT on fee
gmf_amount: GMF (4x1000) if applicable
payed_amount: Total to deduct from balance

Common Errors

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

Payment Links Exchange (FX)