Skip to main content

​
¿Qué vas a lograr?

Al terminar esta guía podrás debitar directamente tarjetas o cuentas bancarias que tus clientes hayan autorizado previamente, sin necesidad de que el cliente interactúe con un link de pago.
El débito directo requiere que el cliente haya autorizado previamente el método de pago. Este flujo es ideal para cobros recurrentes, suscripciones o pagos donde ya tienes la autorización del cliente.

​
Prerrequisitos

  • Cuenta de OnePay verificada con llaves API
  • Un cliente registrado con un método de pago autorizado (tarjeta o cuenta bancaria)

​
¿Cuándo usar Charges vs Payments?

Payment (Solicitud)Charge (Cargo)
El clienteRecibe un link y elige cómo pagarNo interactúa, el cobro es automático
RequiereSolo monto y títuloCliente + método de pago autorizado
Ideal paraCobros únicos, facturasCobros recurrentes, suscripciones

​
Flujo: Debitar una tarjeta

1

Crear el cliente

curl https://api.onepay.la/v1/customers \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: cliente-001" \
  -d '{
    "user_type": "natural",
    "first_name": "María",
    "last_name": "López",
    "email": "[email protected]",
    "phone": "+573201112233",
    "document_type": "CC",
    "document_number": "1060500333"
  }'
Guarda el id del cliente para los siguientes pasos.
2

Registrar la tarjeta con autorización

Si capturas datos de tarjeta directamente, debes cumplir con PCI DSS. Usa el SDK Elements para capturar datos de forma segura y obtener un token.
curl https://cards.onepay.la/v1/cards \
  -X POST \
  -H "Authorization: Bearer pk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "card_number": "4111111111111111",
    "expiration_year": "29",
    "expiration_month": "12",
    "ccv": "123",
    "holder_name": "MARIA LOPEZ",
    "customer_id": "CUSTOMER_ID",
    "authorization": true
  }'
Las tarjetas se crean en un dominio diferente (cards.onepay.la) por cumplimiento PCI DSS.
3

Crear el cargo

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

Verificar el resultado

La respuesta incluye el estado del cargo:
{
  "id": "9e5ccd4a-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "succeeded",
  "amount": 85000,
  "title": "Mensualidad Enero",
  ...
}
Estados posibles: succeeded, declined, pending.

​
Flujo: Debitar una cuenta bancaria

1

Crear el cliente

Mismo paso que el flujo de tarjeta (ver arriba).
2

Consultar bancos disponibles

curl https://api.onepay.la/v1/accounts/banks \
  -H "Authorization: Bearer sk_test_xxx"
3

Registrar la cuenta bancaria con autorización

curl https://api.onepay.la/v1/accounts \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: cuenta-001" \
  -d '{
    "customer_id": "CUSTOMER_ID",
    "bank_id": "BANK_ID",
    "subtype": "SAVINGS",
    "account_number": "123456789",
    "authorization": true
  }'
El campo authorization debe ser true para poder debitar la cuenta posteriormente. Sin autorización, la cuenta se crea pero no podrás cobrar.
4

Crear el cargo

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

Escuchar webhook

Implementa el Webhook de cargos para recibir la notificación cuando el cargo se procese.

​
Usar escenarios de prueba

En ambiente test, puedes simular diferentes resultados usando test_scenario: 
{
  "test_scenario": "INSUFFICIENT_FUNDS"
}
Consulta todos los escenarios de prueba disponibles.

​
Errores comunes

ErrorCausaSolución
ACCOUNT_IS_NOT_AUTHORIZEDLa cuenta no tiene authorization: trueCrea la cuenta con authorization: true
INSUFFICIENT_FUNDSFondos insuficientesNotifica al cliente y reintenta más tarde
CARD_EXPIREDTarjeta expiradaSolicita al cliente actualizar la tarjeta
validation_errorFalta customer_id o método de pagoVerifica que envías card_id o account_id

​
Siguiente paso

Casos de uso de débitos

Flujos detallados para tarjetas, cuentas ACH, Nequi y Daviplata.

Tokenizar Nequi/Daviplata

Vincula billeteras digitales para débitos automáticos.

Cobros recurrentes

Automatiza cobros periódicos con suscripciones.