Skip to main content

​
¿Qué es una Factura?

Una factura es un registro de cobro que genera automáticamente un Payment asociado. Al crear una factura, OnePay crea un cobro vinculado, lo envía al cliente y gestiona todo el ciclo de vida hasta el pago y la conciliación.
Si solo necesitas cobrar un monto sin vincular a un sistema de gestión externo, usa directamente Payments.
¿Quieres que OnePay emita la factura ante la DIAN? Es este mismo endpoint: manda items y customer_id en vez de provider y amount, y OnePay genera el documento fiscal con tu resolución. Ver Facturación electrónica.

​
¿Cuándo usar Facturas?

​
Flujo de integración

El flujo completo para integrar facturas tiene estos pasos clave:
Para homologar la integración de facturas, tu sistema debe implementar las siguientes capacidades:
  1. Crear facturas — POST /invoices para sincronizar facturas desde tu sistema de gestión hacia OnePay.
  2. Recibir confirmación de pago — Webhook invoice.paid para saber cuándo una factura fue pagada a través de OnePay.
  3. Actualizar facturas — PUT /invoices/{invoice} para reflejar cambios de valor o datos de la factura.
  4. Eliminar facturas — DELETE /invoices/{invoice} para cancelar facturas o marcarlas como pagadas por otro medio distinto a OnePay.

​
Crear factura

Al llamar a POST /invoices, OnePay:
  • Crea un registro de factura con estado CREATED
  • Genera un Payment asociado con source = INVOICE
  • Si ya existe una factura con el mismo company + provider + reference en estado CREATED, retorna la existente (idempotencia implícita)
  • Retorna la factura con los datos del payment y su payment_link
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.

​
Webhooks

OnePay notifica automáticamente los cambios de estado de cada factura. Configura los eventos de facturas en tu webhook para recibirlos. Para ver la estructura completa del payload que recibirás, consulta los ejemplos de webhooks de facturas.

​
Actualizar factura

Al llamar a PUT /invoices/{invoice}:
  • Si el payment aún no se pagó: OnePay cancela el payment anterior y crea uno nuevo con los datos actualizados. Se envía un nuevo cobro al cliente.
  • Si el payment ya se pagó: Solo se actualizan los campos informativos (nombre, monto, referencia), sin generar un nuevo cobro.
  • El campo provider no se puede modificar.

​
Eliminar factura

Al llamar a DELETE /invoices/{invoice}:
  • No se puede eliminar una factura con estado PAID o CONCILIATED (retorna HTTP 409)
  • OnePay cancela el payment asociado
  • La factura se marca según el reason: PAID_FROM_PROVIDER (pagada externamente) o DELETE_FROM_PROVIDER (eliminada)
  • Se detiene todo seguimiento y recordatorios de cobranza

​
Estados de una factura

​
Endpoints