¿Qué es una Factura?
Una factura es un documento de cobro que genera automáticamente un Payment asociado. Es útil cuando necesitas combinar la creación de un cobro con información de facturación (cliente, descripción detallada, líneas de items).
Si solo necesitas cobrar un monto sin información de facturación, usa directamente Payments. Ejemplo Rápido
Crear una factura con múltiples items y obtener un link de pago:
curl https://api.onepay.la/v1/invoices \
-X POST \
-H "Authorization: Bearer sk_test_xxx" \
-H "Content-Type: application/json" \
-H "x-idempotency: invoice-001" \
-d '{
"customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"amount": 250000,
"currency": "COP",
"items": [
{
"name": "Plan Premium - Mes de Febrero",
"quantity": 1,
"price": 150000,
"subtotal": 150000
},
{
"name": "Soporte técnico adicional",
"quantity": 2,
"price": 50000,
"subtotal": 100000
}
],
"metadata": {
"invoice_number": "INV-2025-001",
"billing_period": "2025-02"
}
}'
{
"id": "9e5a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"amount": 250000,
"amount_label": "$250.000",
"currency": "COP",
"status": "pending",
"customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"payment": {
"id": "9e5a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5d",
"payment_link": "https://checkout.onepay.la/p/9e5a2b3c"
},
"items": [
{
"name": "Plan Premium - Mes de Febrero",
"quantity": 1,
"price": 150000,
"subtotal": 150000
},
{
"name": "Soporte técnico adicional",
"quantity": 2,
"price": 50000,
"subtotal": 100000
}
],
"created_at": "2025-02-08T15:30:00.000000Z"
}
payment_link al cliente para que complete el pago.
¿Cuándo usar Facturas?
| Escenario | Solución |
|---|
| Cobro simple con link de pago | Usa Payments |
| Cobro con detalle de items y datos de facturación | Usa Facturas |
| Dividir el pago entre múltiples destinatarios | Usa Facturas con splits |
| Cobro automático a método autorizado | Usa Charges |
Flujo de una factura
Crear factura (POST /invoices)
└── Se genera un Payment automáticamente
├── payment_link disponible para enviar al cliente
├── El cliente paga
├── Webhook payment.approved
└── Dispersión a beneficiarios (si hay splits)
Cobros
Al crear una factura, OnePay genera un Payment que:
- Contiene el monto, la referencia y los metadatos del cobro
- Expone un
payment_link para que el cliente pague
- Mantiene su estado (
pending, approved, cancelled)
Las facturas pueden incluir datos del cliente (phone, email) para habilitar notificaciones automáticas.
Pagos divididos (Splits)
El pago originado por una factura puede dividirse entre varios destinatarios:
- Definir múltiples receptores con montos o porcentajes
- Mantener trazabilidad de quién recibe qué parte
- Preparar la información para dispersiones automáticas
La configuración de splits se realiza en el Payment asociado a la factura.
Dispersiones
Una vez cobrado el pago, los fondos se pueden dispersar a los beneficiarios:
- El Payment de la factura sirve como fuente de la dispersión
- Puedes dispersar de forma total o parcial
- Las dispersiones respetan los splits definidos
Endpoints
| Método | Endpoint | Descripción |
|---|
POST | /invoices | Crear factura |
GET | /invoices | Listar facturas |
GET | /invoices/ | Detalle de una factura |
DELETE | /invoices/ | Eliminar factura |
