Cobrar con débito directo

¿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 cliente	Recibe un link y elige cómo pagar	No interactúa, el cobro es automático
Requiere	Solo monto y título	Cliente + método de pago autorizado
Ideal para	Cobros únicos, facturas	Cobros recurrentes, suscripciones

Flujo: Debitar una tarjeta

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": "maria@ejemplo.com",
    "phone": "+573201112233",
    "document_type": "CC",
    "document_number": "1060500333"
  }'

Guarda el id del cliente para los siguientes pasos.

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.

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

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

Crear el cliente

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

Consultar bancos disponibles

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

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.

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

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

Error	Causa	Solución
`ACCOUNT_IS_NOT_AUTHORIZED`	La cuenta no tiene `authorization: true`	Crea la cuenta con `authorization: true`
`INSUFFICIENT_FUNDS`	Fondos insuficientes	Notifica al cliente y reintenta más tarde
`CARD_EXPIRED`	Tarjeta expirada	Solicita al cliente actualizar la tarjeta
`validation_error`	Falta `customer_id` o método de pago	Verifica 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.

Inicio rápido

Cobrar (Recaudo)

Pagar (Dispersiones)

Webhooks

IA (MCP)

Verificación

Configuración

Artículos

¿Qué vas a lograr?

Prerrequisitos

¿Cuándo usar Charges vs Payments?

Flujo: Debitar una tarjeta

Flujo: Debitar una cuenta bancaria

Usar escenarios de prueba

Errores comunes

Siguiente paso

Casos de uso de débitos

Tokenizar Nequi/Daviplata

Cobros recurrentes

​¿Qué vas a lograr?

​Prerrequisitos

​¿Cuándo usar Charges vs Payments?

​Flujo: Debitar una tarjeta

​Flujo: Debitar una cuenta bancaria

​Usar escenarios de prueba

​Errores comunes

​Siguiente paso

Casos de uso de débitos

Tokenizar Nequi/Daviplata

Cobros recurrentes

¿Qué vas a lograr?

Prerrequisitos

¿Cuándo usar Charges vs Payments?

Flujo: Debitar una tarjeta

Flujo: Debitar una cuenta bancaria

Usar escenarios de prueba

Errores comunes

Siguiente paso