> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.
# Conceptos clave
> Entiende los conceptos fundamentales de OnePay antes de integrar.
## Flujo del dinero en OnePay
```mermaid theme={null}
graph LR
A[Cliente paga] -->|Payment / Charge| B[Balance OnePay]
B -->|Cashout| C[Cuenta bancaria destino]
B -->|Split| D[Múltiples destinatarios]
```
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:
```
https://api.onepay.la/v1
```
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
```
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:
```
x-idempotency: pago-factura-1234
```
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"`
* La unidad no cambia por moneda ni por país
### La regla
**Si el campo se llama `amount`, va en pesos. Si el nombre termina en `_in_cents`, va en centavos.**
El nombre del campo es la unidad. Hay una sola excepción, marcada abajo.
### Dónde aplica cada unidad
Verificado contra el código en julio de 2026.
| Unidad | Campos |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pesos** (unidades mayores) | `amount` de [cobros](/client/charges/create), [Bre-B](/client/charges/bre-b), [pagos](/client/payments/create) y su [actualización](/client/payments/update), [dispersiones](/client/cashouts/create), [balances](/client/movimientos/dispersion), [facturas](/client/invoices/create), [Nequi](/client/request-to-pay/nequi) y [DaviPlata](/client/request-to-pay/daviplata) · `partial_payment.min_amount` y `max_amount` de facturas · `splits[].split_value` de tipo `fixed` · `filter[amount]` · el `amount` y el `balance` de **todas** las respuestas y webhooks |
| **Centavos** | Todo campo cuyo nombre termina en `_in_cents`: `unit_amount_in_cents`, `min_amount_in_cents`, `max_amount_in_cents`, `remaining_amount_in_cents`, `reference_price_in_cents`, `amount_in_cents`, `filter[amount_in_cents]` |
| **Porcentaje entero** | `splits[].split_value` de tipo `percentage`: `10` es 10%. La suma no puede pasar de `100` |
**La excepción:** [`POST /customers/session/charges`](/client/customer-session/create-charge) recibe
su `amount` en **centavos** aunque el campo no lo diga en el nombre. Es el único endpoint donde
`amount` no son pesos, y convive con [`POST /charges`](/client/charges/create), que sí los recibe
en pesos. Si integras los dos, revisa cuál estás llamando.
Los campos `*_label` (`amount_label`, `balance_label`) son cadenas ya formateadas para mostrar
(`"$150.000"`). No los parsees para hacer cuentas: usa el campo numérico.