Flujo del dinero en OnePay
Tu cuenta OnePay funciona como un intermediario: los fondos que cobras se acumulan en tu balance y desde ahí puedes dispersarlos a cuentas bancarias de terceros.
¿Cómo cobrar? Payment vs Charge vs Invoice
OnePay ofrece tres formas de cobrar. Cada una se adapta a un caso de uso diferente:
Payment (Solicitud de cobro)
El Payment es una solicitud que envías a tu cliente para que pague. OnePay genera un link de pago donde el cliente elige su método de pago.
| Característica | Detalle |
|---|
| Endpoint | POST /payments |
| El cliente interactúa | Sí, abre un link y paga |
| Métodos disponibles | Tarjeta, PSE, Nequi, Daviplata, Bre-B |
| Ideal para | Cobros únicos, facturas, pagos por WhatsApp/email |
Charge (Cargo / Débito directo)
El Charge debita automáticamente un método de pago que el cliente ya autorizó. No requiere interacción del cliente.
| Característica | Detalle |
|---|
| Endpoint | POST /charges |
| El cliente interactúa | No, el cobro es automático |
| Requiere | customer_id + card_id o account_id autorizados |
| Ideal para | Cobros recurrentes, suscripciones, débitos automáticos |
Invoice (Factura)
La Invoice es un documento de cobro que genera automáticamente un Payment asociado. Útil para sistemas de facturación.
| Característica | Detalle |
|---|
| Endpoint | POST /invoices |
| Genera automáticamente | Un Payment con link de pago |
| Ideal para | Facturación electrónica, conciliación contable |
Regla rápida: Si tu cliente debe elegir cómo pagar, usa Payment. Si ya tienes autorización para cobrar, usa Charge. Si necesitas trazabilidad contable, usa Invoice.
¿Cómo pagar? Tipos de dispersión
Las dispersiones (cashouts) son transferencias de dinero desde tu balance OnePay a cuentas bancarias de terceros.
| Tipo | Velocidad | Destinatarios | Costo |
|---|
| ACH | 1-3 días hábiles | Personas naturales y jurídicas | Menor |
| TURBO | Menos de 2 horas | Personas naturales y jurídicas | Intermedio |
| INSTANT | Inmediata | Solo personas naturales con Transfiya | Mayor |
Recursos principales
Estos son los objetos principales con los que interactuarás en la API:
Customer (Cliente)
Representa a una persona natural o jurídica. Es el objeto central al que se asocian métodos de pago, cobros y dispersiones.
Customer
├── Accounts (Cuentas bancarias)
├── Cards (Tarjetas)
├── Payments (Cobros recibidos)
└── Cashouts (Dispersiones enviadas)
Account (Cuenta bancaria)
Representa una cuenta bancaria asociada a un cliente. Se usa para:
- Débitos: Cobrar directamente de la cuenta (requiere
authorization: true)
- Transferencias: Enviar dinero a la cuenta (no requiere autorización)
- Billeteras digitales: Vincular Nequi o Daviplata
Card (Tarjeta)
Representa una tarjeta de crédito o débito tokenizada. Se crea en un dominio separado (cards.onepay.la) por cumplimiento PCI DSS.
Subscription (Suscripción)
Automatiza cobros recurrentes según un plan definido. Maneja automáticamente reintentos de pago fallidos.
Ambientes
OnePay usa la misma URL base para sandbox y producción:
La diferencia está en las llaves API:
sk_test_xxx / pk_test_xxx → Ambiente de pruebas (sandbox)sk_live_xxx / pk_live_xxx → Ambiente de producción
Los datos de test y producción están completamente aislados. Clientes, cuentas y transacciones creados en test no existen en producción.
Autenticación
Todas las peticiones requieren un header Authorization con tu llave secreta:
Authorization: Bearer sk_test_xxx
- Secret Key (
sk_): Para operaciones del backend (cobros, dispersiones, consultas)
- Public Key (
pk_): Para operaciones del frontend (tokenización de tarjetas)
Nunca expongas tu Secret Key en el frontend o en repositorios públicos.
Idempotencia
Las operaciones que crean recursos (POST) requieren un header x-idempotency con un token único. Esto previene duplicados si una petición se reenvía por error de red:
x-idempotency: pago-factura-1234
Moneda y montos
- La moneda por defecto es COP (Peso colombiano)
- Los montos se envían en pesos (no en centavos):
150000 = $150.000 COP
- En la respuesta,
amount_label muestra el monto formateado: "$150.000"
