Retiros Bancarios

Endpoints para enviar dinero a cuentas bancarias en Colombia y Estados Unidos.

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

Consulta los bancos colombianos disponibles para retiros.

Endpoint

GET /bank_list_third_party_withdraw/

Headers

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

Respuesta

200 OK

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

Consulta los tipos de documento de identidad válidos.

Endpoint

GET /base/document_type/

Headers

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

Respuesta

200 OK

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

Registra la cuenta bancaria del beneficiario.

Endpoint

POST /create_third_party_banks/

Headers

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

Request

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

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

Tipos de Cuenta

ID	Tipo
`0`	Cuenta de Ahorros
`1`	Cuenta Corriente

Respuesta

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

💾

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

Listar Cuentas Bancarias

Consulta las cuentas bancarias registradas.

Endpoint

GET /list_third_party_banks/?country=CO

Parámetros Query

Parámetro	Tipo	Descripción
`country`	string	Filtrar por país: `CO`, `US`

Respuesta

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

Paso 4: Crear Retiro COP

Ejecuta la transferencia a la cuenta bancaria colombiana.

Endpoint

POST /create/third_party_withdraw/

Headers

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

Request

Campo	Tipo	Requerido	Descripción
`amount`	number	✅	Monto a enviar en COP
`currency`	string	✅	`COP`
`third_party_bank_id`	int	✅	ID de la cuenta bancaria
`full_name`	string	✅	Nombre completo del beneficiario
`email`	string	✅	Email del beneficiario
`phone`	string	✅	Teléfono del beneficiario
`platform`	string	✅	`API`, `WEB`, `MOBILE`
`is_for_quote`	boolean	✅	`false` para ejecutar, `true` solo cotizar
`longitude`	string	❌	Longitud GPS
`latitude`	string	❌	Latitud GPS
`client_callback`	string	❌	URL para notificaciones

request.json

{
  "amount": 100000,
  "currency": "COP",
  "full_name": "Sofia Martin",
  "email": "sofia@ejemplo.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@ejemplo.com",
    "phone": "+573001234567",
    "third_party_bank_id": 85,
    "platform": "API",
    "is_for_quote": false
}'

💰

Modo Cotización: Usa is_for_quote: true para obtener el cálculo de fees sin ejecutar el retiro.

Respuesta

200 OK

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

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.

Método 1: Digital Payment

Método principal para enviar USD de forma rápida.

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

Campos

Campo	Tipo	Requerido	Descripción
`deposit_option`	string	✅	Opciones: `RTP`, `RTP_FORCE_BANK`, `BANK` (separadas por coma)
`amount`	decimal	✅	Monto en USD
`currency`	string	✅	Debe ser `USD`
`ip`	string	✅	IP del cliente
`latitude`	string	❌	Latitud GPS
`longitude`	string	❌	Longitud GPS

Opciones de Depósito

Opción	Descripción
`RTP`	Real-Time Payment (más rápido)
`RTP_FORCE_BANK`	RTP con fallback a banco
`BANK`	Transferencia bancaria tradicional

⚠️

Requisito: El usuario debe tener una cuenta wallet USD activa. Si no la tiene, recibirá error MarketPlaceUserRequired.

Proceso Interno

Validación de cuenta

Verifica que el usuario tenga wallet USD activa.

Cálculo de fees

Calcula comisiones automáticamente.

Validación de balance

Verifica fondos suficientes en USD.

Creación del pago

Genera el digital payment.

Descuento de balance

Deduce el monto + fees del balance.

Respuesta

201 CREATED

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

Errores Posibles

Código	Error	Descripción
`400`	`MarketPlaceUserRequired`	Usuario no tiene wallet USD
`400`	`UserHaveInsufficientBalance`	Balance insuficiente
`400`	`InsufficientFunds`	Sin fondos disponibles

Método 2: Transferencia Manual USD

Para enviar USD a cuentas bancarias USA usando transferencia tradicional.

Paso 1: Crear Cuenta Bancaria USA

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

Campos Adicionales para USA

Campo	Tipo	Requerido	Descripción
`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

🏦

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

Paso 2: Crear Retiro USD

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
}

💵

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

Respuesta

200 OK

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

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

Payment Links Exchange (FX)