Facturas - Z2Pay Developers

La factura (invoice) es el documento de cobro generado en cada ciclo de una suscripción. Acumula los line items (ítems cobrados), tiene un total en centavos y recorre un ciclo de vida de estados (scheduled → open → paid, con desvíos hacia past_due, unpaid, canceled y refunded). Esta API expone la lectura de las facturas, acciones administrativas de reconciliación (pago fuera del gateway y cancelación) y la página de factura hospedada — el enlace público que el pagador anónimo abre para pagar mediante PIX, boleto o tarjeta.

Todos los endpoints autenticados usan el header x-api-key (vea Autenticación). Los endpoints bajo /public/invoices/* son públicos — la credencial es la posesión del token de alta entropía generado al emitir la factura. Los valores monetarios son siempre enteros en centavos (ej: 18990 = R$ 189,90).

Endpoints

Método	Ruta	Descripción
`GET`	`/invoices`	Lista facturas con filtros y paginación
`GET`	`/invoices/:id`	Detalla una factura
`GET`	`/invoices/:id/line-items`	Lista los ítems (line items) de una factura
`POST`	`/admin/invoices/:id/mark-paid-out-of-band`	Reconcilia un pago realizado fuera del gateway
`POST`	`/admin/invoices/:id/void`	Cancela (void) una factura antes del pago
`GET`	`/public/invoices/:token`	(Público) Obtiene la factura para la página hospedada
`POST`	`/public/invoices/:token/pay`	(Público) Genera el slip de PIX/boleto
`POST`	`/public/invoices/:token/pay-card`	(Público) Cobra la factura con tarjeta tokenizada

Estados de la factura

El campo status de la factura sigue este ciclo de vida:

Estado	Significado
`scheduled`	Creada con anticipación; se activa cuando llega el `chargeAt` (emisión del slip diferida)
`suspended`	Congelada por pausa de la suscripción — fuera de los ciclos de cobro
`open`	Activa, en espera de pago (el slip de PIX/boleto ya existe cuando corresponde)
`paid`	Completamente pagada
`past_due`	El cobro falló; en proceso de reintento (dunning)
`unpaid`	Reintentos agotados — cobro abandonado
`canceled`	Cancelada (void) por el comercio antes del pago
`refunded`	Reembolsada tras el pago

Los estados terminales (paid, canceled, refunded, unpaid) rechazan acciones de cancelación. La reconciliación fuera del gateway solo acepta facturas en open, past_due o unpaid.

Listar facturas

status

string[]

Filtra por uno o más estados. Acepta CSV (status=open,past_due) o repetido (status=open&status=past_due). Valores: scheduled, suspended, open, paid, past_due, unpaid, canceled, refunded.

subscriptionId

string

Filtra las facturas de una suscripción específica.

customerId

string

Filtra las facturas de un cliente específico.

paymentMethods

string[]

Filtra por forma de pago (CSV o repetido). Valores: card, pix, boleto, other.

string

Búsqueda libre por nombre/email/documento del cliente o por el código de la factura (prefijo).

code

string

Búsqueda parcial por el número formateado de la factura (ej: 2026-0007, 2026-, 42). Máx. 20 caracteres.

customer

string

Búsqueda parcial por nombre, email o documento del cliente. Máx. 255 caracteres.

totalMin

integer

Valor total mínimo de la factura, en centavos.

totalMax

integer

Valor total máximo de la factura, en centavos.

dateField

string

Campo de fecha al que aplicar dateFrom/dateTo. Valores: issued, due, paid, created, charge.

dateFrom

string

Inicio del intervalo de fechas. ISO 8601 con timezone (ej: 2026-06-01T00:00:00-03:00) o fecha simple (2026-06-01).

dateTo

string

Fin del intervalo de fechas. Mismo formato que dateFrom.

orderBy

string

Campo de ordenación. Valores: createdAt (predeterminado), dueAt, code, customer, paidAt, value.

order

string

Dirección de la ordenación: asc o desc (predeterminado).

page

integer

Página de la paginación.

limit

integer

Ítems por página.

curl "https://billing-api.sandbox.z2pay.com/invoices?status=open,past_due&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "inv_7Hf2kLpQ9mWxYz",
      "number": { "year": 2026, "sequence": 7 },
      "customerId": "cust_3Kd8mNvB2pQr",
      "customerName": "Maria Souza",
      "customerEmail": "maria@exemplo.com",
      "currency": "BRL",
      "subscriptionId": "sub_9Lp4qWrT6yUi",
      "status": "open",
      "kind": "recurring",
      "chargeAt": "2026-06-20T09:00:00.000Z",
      "dueAt": "2026-06-25T00:00:00.000Z",
      "subtotal": 18990,
      "taxTotal": 0,
      "total": 18990,
      "amountPaid": 0,
      "amountRemaining": 18990,
      "amountRefunded": 0,
      "installments": 1,
      "createdAt": "2026-06-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}

El formato exacto del sobre de paginación sigue la convención de la API — consulte Convenciones.

Detallar una factura

string

requerido

ID de la factura (prefijo inv_).

curl https://billing-api.sandbox.z2pay.com/invoices/inv_7Hf2kLpQ9mWxYz \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

La respuesta es el objeto de la factura. Campos principales:

string

ID de la factura (inv_).

number

object

Número de la factura: { year, sequence }. Único y secuencial por empresa/año.

status

string

Estado actual (vea la tabla de estados).

kind

string

Naturaleza de la factura: enrollment (adhesión), recurring (ciclo regular) o manual (suelta). Inmutable.

customerId

string

ID del cliente (cust_).

customerName

string | null

Nombre del cliente (snapshot).

customerEmail

string | null

Email del cliente (snapshot).

customerDocument

string | null

Documento del cliente (snapshot).

currency

string

Moneda ISO de 3 letras (ej: BRL).

subscriptionId

string | null

Suscripción de origen (sub_), cuando corresponda.

chargeAt

string

Cuándo la factura deja de estar scheduled y pasa a ser pagable. ISO 8601.

dueAt

string | null

Fecha de vencimiento. ISO 8601.

issuedAt

string | null

Fecha de emisión. ISO 8601.

paidAt

string | null

Fecha del pago. ISO 8601.

canceledAt

string | null

Fecha de la cancelación. ISO 8601.

subtotal

integer

Suma de los ítems, en centavos.

taxTotal

integer

Total de impuestos, en centavos.

total

integer

Valor total de la factura, en centavos.

amountPaid

integer

Valor ya pagado, en centavos.

amountRemaining

integer

Valor restante a pagar, en centavos.

amountRefunded

integer

Valor acumulado reembolsado, en centavos.

installments

integer

Cuotas en tarjeta para el cobro (1-12; 1 = al contado).

periodStart

string | null

Inicio del período de servicio. Nulo para kind=manual. ISO 8601.

periodEnd

string | null

Fin del período de servicio. Nulo para kind=manual. ISO 8601.

createdAt

string

Fecha de creación. ISO 8601.

updatedAt

string

Fecha de la última actualización. ISO 8601.

El controller declara los siguientes estados para este endpoint:

200 — factura encontrada
404 — factura no encontrada

Vea Errores para el formato del cuerpo de error.

Listar line items

Retorna los ítems (líneas de cobro) de una factura.

string

requerido

ID de la factura (inv_).

curl https://billing-api.sandbox.z2pay.com/invoices/inv_7Hf2kLpQ9mWxYz/line-items \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

[
  {
    "id": "line_2Wq8xZ4mTnRb",
    "invoiceId": "inv_7Hf2kLpQ9mWxYz",
    "subscriptionId": "sub_9Lp4qWrT6yUi",
    "type": "subscription",
    "description": "Plano Pro - mensal",
    "quantity": 1,
    "unitAmount": 18990,
    "amount": 18990,
    "periodStart": "2026-06-25T00:00:00.000Z",
    "periodEnd": "2026-07-25T00:00:00.000Z",
    "createdAt": "2026-06-13T09:00:00.000Z"
  }
]

type

string

Tipo del ítem: subscription, proration, one_time o metered_usage.

quantity

integer

Cantidad.

unitAmount

integer

Valor unitario, en centavos.

amount

integer

Valor total del ítem, en centavos.

Reconciliar pago fuera del gateway

Marca la factura como paid cuando el pago fue recibido por fuera (transferencia bancaria, efectivo, cheque). No pasa por el gateway. Acepta facturas en open, past_due o unpaid.

Este endpoint vive bajo el prefijo /admin. Úselo solo para reconciliación real — transiciona el estado de la factura sin cobro electrónico.

Este endpoint es idempotente: envíe el header Idempotency-Key para evitar el reprocesamiento en reintentos. Vea Convenciones.

string

requerido

ID de la factura (inv_).

amount

integer

requerido

Valor recibido, en centavos. Entero positivo.

method

string

predeterminado:"other"

Forma del pago fuera de canal: bank_transfer, cash, check o other.

paidAt

string

Fecha/hora de recepción, ISO 8601 en UTC (con sufijo Z, ej: 2026-06-22T17:30:00.000Z). Opcional.

note

string

Observación libre (máx. 500 caracteres). Opcional.

curl -X POST https://billing-api.sandbox.z2pay.com/admin/invoices/inv_7Hf2kLpQ9mWxYz/mark-paid-out-of-band \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 5a9c1e2f-7b3d-4f8a-9c0e-1d2b3a4c5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 18990,
    "method": "bank_transfer",
    "paidAt": "2026-06-22T17:30:00.000Z",
    "note": "TED recebida em conta"
  }'

{
  "id": "inv_7Hf2kLpQ9mWxYz",
  "status": "paid",
  "amountPaid": 18990,
  "amountRemaining": 0,
  "paidAt": "2026-06-22T17:30:00.000Z"
}

Estados declarados:

200 — factura actualizada (status=paid)
409 — factura en estado terminal (no permite la reconciliación)

Cancelar (void) una factura

Cancela una factura antes del pago. Acepta scheduled, open o past_due. Los estados terminales y unpaid son rechazados. reason y reasonDetails son obligatorios. Este endpoint es idempotente: envíe el header Idempotency-Key.

string

requerido

ID de la factura (inv_).

reason

string

requerido

Motivo de la cancelación: duplicate, wrong_amount, customer_agreement, issued_by_mistake o other.

reasonDetails

string

requerido

Detalles del motivo (1 a 500 caracteres).

curl -X POST https://billing-api.sandbox.z2pay.com/admin/invoices/inv_7Hf2kLpQ9mWxYz/void \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 7c1b9d3e-2a4f-4c6b-8d0a-3e5f7a9b1c2d" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "issued_by_mistake",
    "reasonDetails": "Fatura emitida em duplicidade para o cliente"
  }'

{
  "id": "inv_7Hf2kLpQ9mWxYz",
  "status": "canceled",
  "canceledAt": "2026-06-22T18:00:00.000Z"
}

Estados declarados:

200 — factura cancelada (status=canceled)
409 — factura en estado terminal/unpaid (no permite la cancelación)

Página de factura hospedada (pública)

En lugar de enviar el slip de PIX/boleto por email (que expira), Z2Pay genera un enlace de factura hospedada con el formato /i/{token}. El pagador anónimo abre el enlace y el slip se genera en el momento. Estos endpoints no usan x-api-key — la credencial es la posesión del token (generado al emitir la factura, de alta entropía). Tienen rate limit para prevenir abusos.

El token es el public_access_token de la factura. La página hace polling en el GET para mostrar el slip y detectar el pago (la factura pasa de open a paid).

Obtener la factura para pago

Retorna los datos seguros de la factura (sin IDs internos ni companyId sensible) y el slip actual, si ya fue generado.

token

string

requerido

Token público de la factura.

curl https://billing-api.sandbox.z2pay.com/public/invoices/itk_Qx8mZ2pL9vRtKwYn

{
  "number": { "year": 2026, "sequence": 7 },
  "status": "open",
  "currency": "BRL",
  "total": 18990,
  "amountRemaining": 18990,
  "dueAt": "2026-06-25T00:00:00.000Z",
  "customerName": "Maria S.",
  "lineItems": [
    {
      "id": "line_2Wq8xZ4mTnRb",
      "description": "Plano Pro - mensal",
      "quantity": 1,
      "unitAmount": 18990,
      "amount": 18990
    }
  ],
  "slip": null,
  "allowedPaymentMethods": ["pix", "boleto"],
  "installmentsConfig": null,
  "companyId": "comp_4Tn7yWx2mKpQ"
}

slip

object | null

Slip del intento de cobro pendiente. null mientras aún no ha sido generado. Cuando está presente, contiene paymentMethod, status, pixUrl, pixCopyPaste, boletoUrl, boletoDigitableLine, boletoBarcode y expiresAt.

allowedPaymentMethods

string[] | null

Métodos permitidos para esta factura. null = sin restricción (la página decide por el método predeterminado de la suscripción).

installmentsConfig

object | null

Configuración de cuotas para tarjeta: { maxInstallments, freeInstallments?, interestRate? }. null = al contado.

companyId

string

Expuesto para inicializar el tokenizador de tarjeta en el front. Vea Tokenizer.

Estados declarados: 200 (vista de la factura), 404 (token inválido).

Generar el slip de PIX/boleto

Garantiza un slip válido para la factura. El cuerpo es opcional: el campo method fuerza PIX o boleto (entre los métodos permitidos). Sin method, usa el predeterminado de la suscripción.

token

string

requerido

Token público de la factura.

method

string

pix o boleto. Opcional.

curl -X POST https://billing-api.sandbox.z2pay.com/public/invoices/itk_Qx8mZ2pL9vRtKwYn/pay \
  -H "Content-Type: application/json" \
  -d '{ "method": "pix" }'

La respuesta tiene el mismo formato que el GET anterior. El slip puede tardar ~1-2s en aparecer (persistencia asíncrona) — la página debe continuar haciendo polling en el GET. Estados declarados: 200 (vista, el slip puede no estar poblado aún), 404 (token inválido), 409 (método no permitido por la factura).

Cobrar con tarjeta tokenizada

Cobra la factura con una tarjeta tokenizada por el Tokenizer en el front (puede ser tarjeta de tercero). Cobro eager — el resultado se refleja en el GET en el siguiente polling.

token

string

requerido

Token público de la factura.

cardToken

string

requerido

Token de la tarjeta emitido por el tokenizador.

installments

integer

Número de cuotas elegido por el pagador (1 a 12; 1 = al contado). Opcional.

curl -X POST https://billing-api.sandbox.z2pay.com/public/invoices/itk_Qx8mZ2pL9vRtKwYn/pay-card \
  -H "Content-Type: application/json" \
  -d '{
    "cardToken": "card_5Pm9xQ2wL8vTnRb",
    "installments": 3
  }'

La respuesta es la vista actualizada de la factura. Estados declarados: 200 (vista actualizada), 404 (token inválido), 409 (tarjeta no permitida o factura no pagable).

Para probar el flujo de pago en el sandbox, use las tarjetas de prueba y los datos de PIX/boleto, y simule el resultado mediante Simular.

Acciones disponibles en el panel

Algunas operaciones de factura — crear factura suelta, generar enlace de pago, reagendar y forzar nuevo cobro (retry) — son realizadas por el panel del comercio (sesión de usuario), y no están expuestas en la API pública por x-api-key. Los cuerpos a continuación documentan la forma de estos datos como referencia.

Crear factura suelta (manual)

Lanza un cobro ad-hoc vinculado a una suscripción, fuera del ciclo recurrente. Cuerpo:

subscriptionId (string, obligatorio)
description (string, 1-200, obligatorio)
amount (integer en centavos, positivo, obligatorio) — valor unitario
quantity (integer positivo, predeterminado 1)
dueAt (ISO 8601, obligatorio, estrictamente en el futuro)
reason (obligatorio): extra_service, adjustment, penalty, ad_hoc o other
reasonDetails (string, 1-500, obligatorio)
allowedPaymentMethods (array de card/pix/boleto, 1-3 ítems, opcional) — métodos ofrecidos en la página hospedada
installmentsConfig (objeto, opcional/nulo): { maxInstallments (1-12), freeInstallments? (1-12), interestRate? (0-100) }. freeInstallments no puede exceder maxInstallments.

La factura suelta nace con kind=manual, sin período de servicio (periodStart/periodEnd nulos).

Generar enlace de pago

Transiciona una factura scheduled a open antes del chargeAt y hace disponible el enlace de la página hospedada. No se ejecuta ningún cobro — el pagador elige el método al abrir el enlace. Cuerpo:

methods (array de card/pix/boleto, 1-3 ítems, obligatorio) — métodos ofrecidos en la página
installmentsConfig (objeto, opcional/nulo, misma forma que la factura suelta)

Reagendar factura

Modifica la fecha de cobro (chargeAt) de una factura scheduled. El dueAt se desplaza por el mismo intervalo. Cuerpo:

chargeAt (ISO 8601, obligatorio)

Forzar nuevo cobro (retry)

Dispara un nuevo cobro en una factura open/past_due sin esperar el ciclo de dunning. Sin cuerpo. Vea Ciclos.

Vea también

Suscripciones

Cree y gestione los contratos que generan las facturas.

Ciclos de cobro

Cómo cada ciclo emite una factura y el flujo de dunning.

Planes y precios

Defina los valores que componen los ítems de la factura.

Tokenizer

Tokenice tarjetas en el front para la página de factura hospedada.

​Endpoints

​Estados de la factura

​Listar facturas

​Detallar una factura

​Listar line items

​Reconciliar pago fuera del gateway

​Cancelar (void) una factura

​Página de factura hospedada (pública)

​Obtener la factura para pago

​Generar el slip de PIX/boleto

​Cobrar con tarjeta tokenizada

​Acciones disponibles en el panel

​Vea también

Suscripciones

Ciclos de cobro

Planes y precios

Tokenizer

Endpoints

Estados de la factura

Listar facturas

Detallar una factura

Listar line items

Reconciliar pago fuera del gateway

Cancelar (void) una factura

Página de factura hospedada (pública)

Obtener la factura para pago

Generar el slip de PIX/boleto

Cobrar con tarjeta tokenizada

Acciones disponibles en el panel

Vea también