Introducción

¿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 cliente	Abre un link y paga	Ninguna, es automático
Requiere	Solo `amount` y `title`	`customer_id` + `card_id` o `account_id`
Autorización previa	No	Sí (`authorization: true` al crear el método)
Ideal para	Pagos únicos, facturas	Cobros recurrentes, suscripciones

Flujo de un cargo

Crear un cliente - POST /customers
Registrar un método de pago con autorización - POST /cards o POST /accounts con authorization: true
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

Estado	Descripción
`succeeded`	Cargo procesado exitosamente
`declined`	Cargo rechazado (fondos insuficientes, tarjeta bloqueada, etc.)
`pending`	Cargo 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étodo	Endpoint	Descripción
`POST`	/charges	Crear cargo
`GET`	/charges	Listar cargos
`GET`	/charges/	Detalle de un cargo
`POST`	/charges/pse	Crear link de pago PSE
`POST`	/charges/breb	Crear cargo Bre-B
`POST`	/charges//refund	Reembolsar cargo
`POST`	/charges//resolve	Resolver cargo (solo testing)

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

¿Qué es un Cargo (Charge)?

¿Cuándo usar Cargos?

Cobros vs Cargos

Flujo de un cargo

Ejemplo rápido

Estados del cargo

Probar con escenarios

Casos de uso detallados

Endpoints

​¿Qué es un Cargo (Charge)?

​¿Cuándo usar Cargos?

​Cobros vs Cargos

​Flujo de un cargo

​Ejemplo rápido

​Estados del cargo

​Probar con escenarios

​Casos de uso detallados

​Endpoints

¿Qué es un Cargo (Charge)?

¿Cuándo usar Cargos?

Cobros vs Cargos

Flujo de un cargo

Ejemplo rápido

Estados del cargo

Probar con escenarios

Casos de uso detallados

Endpoints