Retiros Bancarios

Retira fondos a una cuenta bancaria registrada en Colombia en COP o USD.

Todos los endpoints requieren autenticación con Authorization: Bearer [TOKEN] y x-api-key.

Resumen por Moneda

País	Moneda	Método
🇨🇴 Colombia	COP	Transferencia bancaria directa
🇺🇸 Estados Unidos	USD	Digital Payment / Transferencia manual

🇨🇴 Retiros Colombia (COP)

Flujo completo para enviar dinero a cuentas bancarias colombianas.

Obtener lista de bancos

Consulta los bancos disponibles.

Obtener tipos de documento

Consulta los tipos de documento válidos.

Crear cuenta bancaria

Registra la cuenta del beneficiario.

Crear el retiro

Ejecuta la transferencia.

Paso 1: Obtener Lista de Bancos

Obtener Lista de Bancos

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GEThttps://dev.backend.colurs.co/list_third_party_banks/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
country	string	✓	Código ej. CO, US

Respuesta

response.json

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

💡

Guarda el `id` del banco para usarlo al crear la cuenta bancaria.

Paso 2: Obtener Tipos de Documento

Obtener Tipos de Documento

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GEThttps://dev.backend.colurs.co/base/document_type/

Headers Requeridos

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

Respuesta

response.json

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

Tipos de Documento

ID	Código	Descripción
0	`CC`	Cédula de Ciudadanía
1	`CE`	Cédula de Extranjería
2	`NIT`	Número de Identificación Tributaria
3	`TI`	Tarjeta de Identidad
4	`PPT`	Permiso por Protección Temporal

Paso 3: Crear Cuenta Bancaria

Crear Cuenta Bancaria

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POSThttps://dev.backend.colurs.co/create_third_party_banks/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
account_holder_name	string	✓	Nombre completo del titular
account_type	int	✓	0 = Ahorros, 1 = Corriente
account_holder_document_type	int	✓	ID del tipo de documento
account_holder_document	string	✓	Número de documento
account_number	string	✓	Número de cuenta bancaria
bank_name	int	✓	ID del banco
country_registered	string	✓	CO para Colombia
nickname	string	✕	Alias para identificar la cuenta

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": "Cuenta Principal"
}

Ejemplo cURL

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": "Cuenta Principal"
}'

Respuesta

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": 
"Cuenta Principal"}
}

**Tipos de Cuenta:** `0` = Ahorros, `1` = Corriente.

💾

Guarda el `id` de la cuenta para usarlo en el siguiente paso.

Listar Cuentas Bancarias

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GEThttps://dev.backend.colurs.co/list_third_party_banks/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
country	string	✕	Filtrar por país: CO, US

Respuesta

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": "Creada",
    "country_registered": "CO",
    "wire": null,
    "routing_number": null
  }
]
}

Paso 4: Crear Retiro COP

Crear Retiro COP

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

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

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
dispersions	array	✓	Objetos con third_party_bank_id, amount, client_idempotency_key
currency	string	✓	COP o USD
longitude	string	✕	Longitud
latitude	string	✕	Latitud
platform	string	✕	API

Respuesta

response.json

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

💰

**Modo Cotización:** Usa `is_for_quote: true` para obtener el cálculo de fees sin ejecutar el retiro. Para estimar usa `POST /send/estimate/user/` con send_channel: DALE.

Estados del Retiro COP

Estado	Código	Descripción
Creada	`0`	Retiro creado, pendiente de proceso
En proceso	`1`	Transferencia en curso
Consignada	`2`	Fondos consignados
Depositada	`3`	✅ Retiro completado exitosamente
Rechazada	`4`	❌ Rechazada por el banco

🇺🇸 Retiros Estados Unidos (USD)

Dos métodos disponibles para enviar USD a cuentas bancarias estadounidenses.

⚠️

El endpoint POST /api/digital_payment/ no existe en el OpenAPI (swagger.json). Para envíos USD consulta los endpoints documentados en Wallet USD y en Cuentas bancarias EEUU.

Transferencia Manual USD

Paso 1: Crear Cuenta Bancaria USA

Crear Cuenta Bancaria USA

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POSThttps://dev.backend.colurs.co/create_third_party_banks/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
account_holder_name	string	✓	Nombre del titular
account_type	int	✓	0 = Ahorros, 1 = Corriente
account_holder_document_type	int	✓	ID tipo documento
account_holder_document	string	✓	Número de documento
account_number	string	✓	Número de cuenta
bank_name	int	✓	ID del banco
country_registered	string	✓	Debe ser US
routing_number	string	✓	Número de routing/ABA del banco
wire	string	✕	Nombre completo del banco para SWIFT
address	string	✕	Dirección del banco

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

🏦

El `routing_number` (ABA) es obligatorio para cuentas bancarias de Estados Unidos.

Paso 2: Crear Retiro USD

Crear Retiro USD

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

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

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
amount	decimal	✓	Monto
currency	string	✓	USD
full_name	string	✓	Nombre completo
email	string	✓	Email
phone	string	✓	Teléfono
third_party_bank_id	int	✓	ID de la cuenta
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
}

Respuesta

response.json

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

💵

**Importante:** Para retiros a bancos USA solo se puede usar moneda `USD`. Si intentas con otra moneda recibirás error `InvalidCurrencyForQuoteWithDraw`.

Resumen de Fees

Los fees se calculan automáticamente según:

Configuración del perfil (CustomFees)
Fees globales del sistema (GlobalFee)

El sistema calcula:

amount: Monto solicitado
fee_amount: Comisión de Colurs
fee_iva_amount: IVA sobre la comisión
gmf_amount: GMF (4x1000) si aplica
payed_amount: Total a descontar del balance

Errores Comunes

Código	Error	Descripción
`400`	`BalanceInsufficient`	Balance insuficiente para el retiro
`400`	`InvalidCurrencyForQuoteWithDraw`	Moneda inválida para el país
`400`	`MarketPlaceUserRequired`	Se requiere wallet activa
`404`	`BankAccountNotFound`	Cuenta bancaria no encontrada
`422`	`UnsupportedBankName`	Banco no soportado
`422`	`UnsupportedDocumentType`	Tipo de documento no válido

Cómo realizar pagos y retiros Retiros México (MXN)