Recargas Colombia

Métodos de recarga disponibles en Colombia: Bancolombia, PSE, Nequi y Efecty. Endpoints para recibir pagos y recargas mediante Bancolombia, PSE, Nequi y transferencia bancaria (esta última con aprobación manual).

Todos estos endpoints requieren el header x-api-key para autorización.

Catálogos y estimación

Bancos por país: GET /banks/ — Query: country (código país, ej. CO, US).
Cuenta de transferencia: GET /base/transfer_account — Query: country.
Estimar recarga: POST /reload/estimate — Body: amount, currency (ej. COP), by_pse (según método).

Flujo General

Crear Pagador

Registra los datos del pagador con POST /api/reload/r2p/counterparty/.

Generar Link de Pago

Crea el link según el método: Bancolombia, PSE o Nequi.

Redirigir al Usuario

El usuario completa el pago en la plataforma bancaria.

Consultar Estado

Verifica el estado del pago con GET /api/reload/r2p/status/{id}/.

Recibir Confirmación

El sistema notifica cuando el pago se completa exitosamente.

Registra los datos de la persona que realizará el pago.

Crear Pagador

Autorización

Se requiere el header x-api-key para autorización.

Endpoint

POSThttps://api.colurs.co/api/reload/r2p/counterparty/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
fullname	string	✓	Nombre completo del pagador
id_type	string	✕	cc, ce, nit (default: cc)
id_number	string	✓	Número de documento
phone	string	✓	Teléfono con código de país
email	string	✓	Email del pagador

request.json{
"fullname": "Juan Pérez",
"id_type": "cc",
"id_number": "1234567890",
"phone": "+573001234567",
"email": "juan@ejemplo.com"
}

Respuesta

response.json

{
"id": "cp_vKXigiCryI",
"fullname": "Juan Pérez",
"id_type": "cc",
"id_number": 
"1234567890"}

💡

Guarda el `id` del pagador para usarlo en los siguientes endpoints.

Genera un link de pago para Botón Bancolombia.

Botón Bancolombia

Autorización

Se requiere el header x-api-key para autorización.

Endpoint

POSThttps://api.colurs.co/api/reload/r2p/bancolombia/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
counterparty_id	string	✓	ID del pagador creado
amount	decimal	✓	Monto en COP (mínimo 1,000)
external_id	string	✓	ID único de tu transacción
description_to_payer	string	✓	Descripción para el cliente (max 255)
description_to_payee	string	✓	Descripción interna (max 255)
redirect_url	string	✓	URL de redirección post-pago
fee_mode	string	✕	payer o receiver (default: payer)

request.json{
"counterparty_id": "cp_vKXigiCryI",
"amount": 50000.00,
"external_id": "ORDER_123456",
"description_to_payer": "Recarga Colurs - 50,000 COP",
"description_to_payee": "Recarga de Juan Pérez",
"redirect_url": "https://app.colurs.co/payment/success",
"fee_mode": "payer"
}

Ejemplo cURL

curl -X POST https://api.colurs.co/api/reload/r2p/bancolombia/ \
-H "Content-Type: application/json" \
-H "x-api-key: [API_KEY]" \
-d '{
  "counterparty_id": "cp_vKXigiCryI",
  "amount": 50000.00,
  "external_id": "ORDER_123456",
  "description_to_payer": "Recarga Colurs - 50,000 COP",
  "description_to_payee": "Recarga de Juan Pérez",
  "redirect_url": "https://app.colurs.co/payment/success",
  "fee_mode": "payer"
}'

Respuesta

response.json

{
"money_movement_id": "mm_gaO1SrCBN92BT5",
"type": "bancolombia",
"status": "initiated",
"payment_link": "https://pago.colurs.co/checkout/_VIwgp1lQI5",
"tracking_key": "917707780",
"amount": 50000.0,
"currency": "COP",
"external_id": "ORDER_123456",
"created_at": "2025-11-14T15:44:39Z",
"fee_breakdown": {
  "reload_amount": "50000.00",
  "fee_colurs": "1000.00",
  "fee_iva": "190.00",
  "total_fee": "1190.00",
  "total_to_pay": "51190.00",
  "fee_mode": "payer",
  "fee_percentage": "2.00",
  "iva_percentage": 
"19.00"}
}

🔗

Redirige al usuario al `payment_link` para que complete el pago.

Genera un link de pago para PSE (Pagos Seguros en Línea).

PSE

Autorización

Se requiere el header x-api-key para autorización.

Endpoint

POSThttps://api.colurs.co/api/reload/r2p/pse/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
counterparty_id	string	✓	ID del pagador
amount_cop	decimal	✓	Monto en COP
external_id	string	✓	ID único de la transacción
description_to_payer	string	✓	Descripción para el cliente
description_to_payee	string	✓	Descripción interna
redirect_url	string	✓	URL de redirección
financial_institution_code	string	✓	Código del banco PSE
fee_mode	string	✕	payer o receiver

request.json{
"counterparty_id": "cp_vKXigiCryI",
"amount_cop": 100000.00,
"external_id": "ORDER_123457",
"description_to_payer": "Recarga Colurs - 100,000 COP",
"description_to_payee": "Recarga PSE de Juan Pérez",
"redirect_url": "https://app.colurs.co/payment/success",
"financial_institution_code": "1007",
"fee_mode": "payer"
}

Respuesta

response.json

{
"money_movement_id": "mm_tjfcYXguVwrNWj",
"type": "pse",
"status": "initiated",
"payment_link": "https://pago.colurs.co/pse/mm_tjfcYXguVwrNWj",
"tracking_key": "PSE_917707781",
"amount": 100000.0,
"currency": "COP",
"external_id": "ORDER_123457",
"financial_institution_code": "1007",
"created_at": "2025-11-14T15:44:40Z",
"fee_breakdown": {
  "reload_amount": "100000.00",
  "fee_colurs": "2000.00",
  "fee_iva": "380.00",
  "total_fee": "2380.00",
  "total_to_pay": "102380.00",
  "fee_mode": "payer",
  "fee_percentage": "2.00",
  "iva_percentage": 
"19.00"}
}

Genera una solicitud de pago para Nequi.

Nequi

Autorización

Se requiere el header x-api-key para autorización.

Endpoint

POSThttps://api.colurs.co/api/reload/r2p/nequi/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
counterparty_id	string	✓	ID del pagador
amount	decimal	✓	Monto en COP
external_id	string	✓	ID único de la transacción
description_to_payer	string	✓	Descripción para el cliente
description_to_payee	string	✓	Descripción interna
redirect_url	string	✓	URL de redirección
fee_mode	string	✕	payer o receiver

request.json{
"counterparty_id": "cp_vKXigiCryI",
"amount": 25000.0,
"external_id": "ORDER_123458",
"description_to_payer": "Recarga Colurs - 25,000 COP",
"description_to_payee": "Recarga Nequi de Juan Pérez",
"redirect_url": "https://app.colurs.co/payment/success",
"fee_mode": "payer"
}

Respuesta

response.json

{
"money_movement_id": "mm_abc123def456",
"type": "nequi",
"status": "initiated",
"payment_link": null,
"tracking_key": "NEQUI_12345",
"amount": 25000.0,
"currency": "COP",
"external_id": "ORDER_123458",
"created_at": "2025-11-14T15:44:41Z",
"note": "El usuario debe completar el pago desde su app Nequi",
"fee_breakdown": {
  "reload_amount": "25000.00",
  "fee_colurs": "500.00",
  "fee_iva": "95.00",
  "total_fee": "595.00",
  "total_to_pay": "25595.00",
  "fee_mode": 
"payer"}
}

📱

**Importante:** Nequi NO genera `payment_link`. El usuario debe completar el pago desde su app Nequi usando el `tracking_key`.

Recarga por transferencia bancaria (BANK_TRANSFER)

Método de recarga manual: el usuario envía un comprobante de transferencia bancaria y un operador revisa y aprueba o rechaza para acreditar el saldo. A diferencia de Bancolombia, PSE y Nequi, no hay webhook automático.

👤

La aprobación o rechazo se hace desde el panel de operadores (POST /panel/reload/). Solo superusuarios u operadores pueden usar ese endpoint.

Flujo

Usuario crea la recarga

Envía POST /reload/create con reload_method: BANK_TRANSFER, monto, moneda, evidence (URL del comprobante), banco origen y banco destino.

Backend crea el registro

La recarga queda en estado Creado (pendiente de aprobación). Los fees se calculan al crear.

Operador revisa el comprobante

Desde el panel, el operador revisa la evidencia (imagen o PDF).

Operador aprueba o rechaza

POST /panel/reload con reload_id y status: APPROVED o REJECTED.

Si se aprueba

El sistema acredita el saldo al usuario, registra fees (Colurs, IVA) y comisión a referidor si aplica.

Paso 1: Crear recarga con comprobante (usuario)

El usuario indica que recargó por transferencia bancaria y adjunta la URL del comprobante.

Crear recarga BANK_TRANSFER

Autorización

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

Endpoint

POSThttps://api.colurs.co/reload/create

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
reload_method	string	✓	BANK_TRANSFER
currency	string	✓	COP o USD
amount	decimal	✓	Monto a recargar (hasta 20 dígitos, 2 decimales)
evidence	string	✓	URL del comprobante (imagen o PDF)
bank_id	int	✓	ID del banco origen
target_bank_id	int	✓	ID del banco destino (cuenta Colurs)
ip	string	✓	IP del cliente
latitude	string	✓	Latitud GPS
longitude	string	✓	Longitud GPS
payer_email	string	✕	Email del pagador
payer_phone	string	✕	Teléfono del pagador
payer_type_document	string	✕	CC, CE, TI, NIT, etc.
payer_document	string	✕	Número de documento
account_name	string	✕	Nombre de la cuenta origen

request.json{
"reload_method": "BANK_TRANSFER",
"currency": "COP",
"amount": 500000,
"evidence": "https://storage.colurs.co/evidence/recarga-123.pdf",
"bank_id": 1,
"target_bank_id": 2,
"ip": "192.168.1.1",
"latitude": "4.60971",
"longitude": "-74.08175",
"payer_email": "pagador@ejemplo.com",
"account_name": "Juan Pérez"
}

Ejemplo cURL

curl -X POST "https://api.colurs.co/reload/create" \
-H "Authorization: Bearer [TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{
  "reload_method": "BANK_TRANSFER",
  "currency": "COP",
  "amount": 500000,
  "evidence": "https://storage.colurs.co/evidence/recarga-123.pdf",
  "bank_id": 1,
  "target_bank_id": 2,
  "ip": "192.168.1.1",
  "latitude": "4.60971",
  "longitude": "-74.08175"
}'

Respuesta

response.json

{
"message": "OK",
"data": {
  "id": 316,
  "state": "Creado",
  "owner": "colurs@colurs.io",
  "reload_method": "BANK_TRANSFER",
  "currency": "COP",
  "bank_name": "BANCO_BAN100",
  "transfer_account": "BANCO_BBVA",
  "payed_amount": "989.00",
  "evidence": "url-to-evidence",
  "ip": "192.168.1.1",
  "latitude": "4.60971",
  "longitude": "-74.08175",
  "checkout": null
}
}

📎

El campo `evidence` debe ser una **URL** accesible del comprobante (imagen o PDF subido previamente a tu almacenamiento).

La recarga queda en estado Creado hasta que un operador la apruebe o rechace.

Modos de Fee

El sistema soporta dos modos para el cobro de comisiones:

Modo	Descripción	Ejemplo (monto: $50,000, fee: $1,190)
`payer`	El usuario paga monto + fees	Usuario paga: $51,190 → Se acredita: $50,000
`receiver`	El usuario paga solo el monto	Usuario paga: $50,000 → Se acredita: $48,810

Los fees se calculan automáticamente según la configuración del perfil (CustomFees) o los fees globales.

Errores Comunes

Código	Error	Descripción
`400`	Validación fallida	Datos de request inválidos
`404`	No encontrado	Money Movement no existe
`500`	Error interno	Error en procesamiento

Cómo fondear una cuenta Depósitos México (MXN)