Recargas Colombia

Endpoints para recibir pagos y recargas en Colombia 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.

Flujo General

Crear Pagador

Registra los datos del pagador con POST /api/reload/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/status/{id}/.

Recibir Confirmación

El sistema notifica cuando el pago se completa exitosamente.

Crear Pagador

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

Endpoint

POST /api/reload/counterparty/

Headers

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

Request

request.json

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

Campo	Tipo	Requerido	Descripción
`fullname`	string	✅	Nombre completo del pagador
`id_type`	string	❌	Tipo documento: `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

Respuesta

201 CREATED

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

💡

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

Botón Bancolombia

Genera un link de pago para Botón Bancolombia.

Endpoint

POST /api/reload/bancolombia/

Headers

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

Request

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

curl -X POST https://api.colurs.co/api/reload/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

201 CREATED

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

PSE

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

Endpoint

POST /api/reload/pse/

Request

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`

Respuesta

201 CREATED

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

Nequi

Genera una solicitud de pago para Nequi.

Endpoint

POST /api/reload/nequi/

Request

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

201 CREATED

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

Endpoint

POST /reload/create/

Headers

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

Request

Campo	Tipo	Requerido	Descripción
`reload_method`	string	✅	`BANK_TRANSFER`
`currency`	string	✅	`COP`, `USD`, `MXN` o `BRL`
`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 desde donde se hizo la transferencia
`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	❌	Tipo documento: `CC`, `CE`, `TI`, `NIT`, etc.
`payer_document`	string	❌	Número de documento del pagador
`account_name`	string	❌	Nombre de la cuenta desde donde se transfiere

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

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

📎

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

Respuesta exitosa (200)

200 OK

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

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

Balance Payment Links