Skip to main content

​
¿Qué es un Cargo (Charge)?

Un cargo es un débito directo a un método de pago que el cliente ya autorizó previamente (tarjeta o cuenta bancaria). El cobro se ejecuta automáticamente sin que el cliente tenga que interactuar.
Si necesitas que el cliente abra un link y elija cómo pagar, usa Cobros (Payments) en su lugar.

​
¿Cuándo usar Cargos?

  • Cobros recurrentes a tarjetas o cuentas autorizadas
  • Suscripciones y membresías
  • Débitos automáticos programados
  • Pagos donde ya tienes un método de pago registrado

​
Cobros vs Cargos

Cobro (Payment)Cargo (Charge)
Interacción del clienteAbre un link y pagaNinguna, es automático
RequiereSolo amount y titlecustomer_id + card_id o account_id
Autorización previaNoSí (authorization: true al crear el método)
Ideal paraPagos únicos, facturasCobros recurrentes, suscripciones

​
Flujo de un cargo

  1. Crear un cliente - POST /customers
  2. Registrar un método de pago con autorización - POST /cards o POST /accounts con authorization: true
  3. Crear el cargo - POST /charges con el customer_id y card_id o account_id

​
Ejemplo rápido

curl https://api.onepay.la/v1/charges \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: cargo-001" \
  -d '{
    "title": "Mensualidad Enero",
    "customer_id": "CUSTOMER_ID",
    "amount": 85000,
    "card_id": "CARD_ID"
  }'

​
Estados del cargo

EstadoDescripción
succeededCargo procesado exitosamente
declinedCargo rechazado (fondos insuficientes, tarjeta bloqueada, etc.)
pendingCargo en proceso de verificación

​
Probar con escenarios

En ambiente test, usa el campo test_scenario para simular diferentes resultados: 
{
  "test_scenario": "INSUFFICIENT_FUNDS"
}
Consulta todos los escenarios de prueba disponibles.

​
Casos de uso detallados

Consulta los casos de uso de débitos automáticos para ver el flujo completo de captura, tokenización y cobro con cada método de pago (tarjetas, cuentas bancarias, Nequi y Daviplata).

​
Endpoints

MétodoEndpointDescripción
POST/chargesCrear cargo
GET/chargesListar cargos
GET/charges/Detalle de un cargo
POST/charges/pseCrear link de pago PSE
POST/charges/brebCrear cargo Bre-B
POST/charges//refundReembolsar cargo
POST/charges//resolveResolver cargo (solo testing)