Skip to main content
POST
/
invoices
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 '{
    "reference": "1060500333",
    "provider_id": "987654",
    "provider": "biller",
    "amount": 50000,
    "name": "Internet plan - Octubre",
    "description": "Factura de internet correspondiente al mes de octubre 2025",
    "phone": "+573167591030",
    "email": "cliente@ejemplo.com",
    "due_date": "2025-10-20",
    "document_url": "https://example.com/document.pdf",
    "metadata": {
      "key": "value"
    }
  }'

{
  "id": "9da58912-101d-46f8-86c9-20a52119c0bf",
  "name": "Internet plan - Octubre",
  "description": "Factura de internet correspondiente al mes de octubre 2025",
  "amount": 50000,
  "provider": "biller",
  "provider_id": "987654",
  "reference": "1060500333",
  "status": "CREATED",
  "remarks": null,
  "metadata": { "key": "value" },
  "due_date": null,
  "created_at": "2025-10-20T15:06:00.000000Z",
  "updated_at": "2025-10-20T15:06:00.000000Z",
  "payment_id": "c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
  "is_test": false,
  "partial_payment_config": null,
  "payment": {
    "id": "c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
    "source": "Internet plan - Octubre",
    "currency": "COP",
    "amount": 50000,
    "amount_label": "$ 50.000",
    "title": "Internet plan - Octubre",
    "description": "Internet plan - Octubre",
    "phone": "+573167591030",
    "expiration_at": null,
    "due_date": null,
    "document_link": "https://example.com/document.pdf",
    "external_id": "987654",
    "allows": { "accounts": true, "cards": true, "card_extra": false, "realtime": false },
    "status": "pending",
    "is_test": false,
    "created_at": "2025-10-20T15:06:00.000000Z",
    "paid_at": null,
    "payment_link": "https://pagos.onepay.la/payment/c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
    "redirect_url": null,
    "provider_id": null,
    "metadata": null,
    "customer": null,
    "method": null,
    "splits": [],
    "company": null,
    "commission": null
  }
}

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.

​
Headers

​
x-idempotency
string
required
Token único para garantizar la idempotencia de la petición

​
Body

​
reference
string
required
Valor con el que el usuario podrá consultar su deuda y realizar el pago en el portal de pagos. Se recomienda utilizar el documento de identidad del titular del servicio. El uso del número de contrato es posible, pero no es la opción más recomendada.
​
provider_id
string
Identificador único de cada factura utilizado internamente en su sistema. Usualmente corresponde al número de factura, número de contrato o UUID de identificación único.
​
provider
string
required
Proveedor del sistema que se está integrando. Para solicitar la asignación de un proveedor, contacte al equipo de soporte a través de la burbuja de chat ubicada en la esquina inferior derecha del panel de administración.
​
amount
number
required
Monto de la factura en pesos (COP). Debe estar entre 5.000 y 100.000.000.
​
name
string
required
Título con el que se le cobrará al usuario. Debe tener entre 5 y 100 caracteres.Ejemplos sugeridos:
  • Factura #12314235 de Febrero del 2024
  • Factura #2432543 | Mensualidad Internet
​
description
string
Descripción detallada de la factura. Se propaga al Payment asociado. Mínimo 4 y máximo 2000 caracteres.
​
phone
string
Número de WhatsApp del usuario al que desea cobrar, en formato E.164. Si no se incluye este valor, el usuario no será notificado por medio de WhatsApp.
​
email
string
Correo electrónico del usuario al que desea cobrar. Si no se incluye este valor, el usuario no será notificado por medio de correo electrónico.
​
due_date
date
Fecha de pago oportuno en la que el usuario debe realizar el pago de la factura. Este valor se utilizará para crear reglas de cobranza a partir de esta fecha específica para esta factura en concreto.
​
document_url
string
URL pública del documento PDF de la factura, en caso de tenerla.
​
metadata
object
Datos adicionales que desea persistir o guardar en la factura dentro de OnePay.
​
partial_payment
object
Configuración para pagos parciales. Permite que la factura sea pagada en múltiples transacciones.
Requiere que el feature Pagos Parciales esté habilitado en tu cuenta. Contacta a soporte para activarlo.
Al crear una factura, la respuesta incluye el campo id — este es el identificador único de la factura en OnePay. Guárdalo en tu sistema ya que lo necesitarás para actualizar o eliminar la factura posteriormente.Recomendación: Almacena este valor como external_id (o equivalente) en tu sistema de gestión para asociar fácilmente tus registros con OnePay.
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 '{
    "reference": "1060500333",
    "provider_id": "987654",
    "provider": "biller",
    "amount": 50000,
    "name": "Internet plan - Octubre",
    "description": "Factura de internet correspondiente al mes de octubre 2025",
    "phone": "+573167591030",
    "email": "cliente@ejemplo.com",
    "due_date": "2025-10-20",
    "document_url": "https://example.com/document.pdf",
    "metadata": {
      "key": "value"
    }
  }'

​
Response

{
  "id": "9da58912-101d-46f8-86c9-20a52119c0bf",
  "name": "Internet plan - Octubre",
  "description": "Factura de internet correspondiente al mes de octubre 2025",
  "amount": 50000,
  "provider": "biller",
  "provider_id": "987654",
  "reference": "1060500333",
  "status": "CREATED",
  "remarks": null,
  "metadata": { "key": "value" },
  "due_date": null,
  "created_at": "2025-10-20T15:06:00.000000Z",
  "updated_at": "2025-10-20T15:06:00.000000Z",
  "payment_id": "c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
  "is_test": false,
  "partial_payment_config": null,
  "payment": {
    "id": "c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
    "source": "Internet plan - Octubre",
    "currency": "COP",
    "amount": 50000,
    "amount_label": "$ 50.000",
    "title": "Internet plan - Octubre",
    "description": "Internet plan - Octubre",
    "phone": "+573167591030",
    "expiration_at": null,
    "due_date": null,
    "document_link": "https://example.com/document.pdf",
    "external_id": "987654",
    "allows": { "accounts": true, "cards": true, "card_extra": false, "realtime": false },
    "status": "pending",
    "is_test": false,
    "created_at": "2025-10-20T15:06:00.000000Z",
    "paid_at": null,
    "payment_link": "https://pagos.onepay.la/payment/c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
    "redirect_url": null,
    "provider_id": null,
    "metadata": null,
    "customer": null,
    "method": null,
    "splits": [],
    "company": null,
    "commission": null
  }
}