Skip to main content

​
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.

​
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.

​
Invoice (Factura)

La Invoice es un documento de cobro que genera automáticamente un Payment asociado. Útil para sistemas de facturación.
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.

​
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.

​
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:
Existen dos tipos de llaves:
  • 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:
Si envías la misma petición con el mismo token de idempotencia, OnePay retornará el resultado original sin crear un recurso duplicado.

​
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"