Faturas - Z2Pay Developers

A fatura (invoice) é o documento de cobrança gerado a cada ciclo de uma assinatura. Ela acumula os line items (itens cobrados), tem um total em centavos e percorre um ciclo de vida de estados (scheduled → open → paid, com desvios para past_due, unpaid, canceled e refunded). Esta API expõe a leitura das faturas, ações administrativas de reconciliação (pagamento fora do gateway e cancelamento) e a página de fatura hospedada — o link público que o pagador anônimo abre para pagar via PIX, boleto ou cartão.

Todos os endpoints autenticados usam o header x-api-key (veja Autenticação). Os endpoints sob /public/invoices/* são públicos — a credencial é a posse do token de alta entropia gerado na emissão da fatura. Valores monetários são sempre inteiros em centavos (ex: 18990 = R$ 189,90).

Endpoints

Método	Rota	Descrição
`GET`	`/invoices`	Lista faturas com filtros e paginação
`GET`	`/invoices/:id`	Detalha uma fatura
`GET`	`/invoices/:id/line-items`	Lista os itens (line items) de uma fatura
`POST`	`/admin/invoices/:id/mark-paid-out-of-band`	Reconcilia um pagamento feito fora do gateway
`POST`	`/admin/invoices/:id/void`	Cancela (void) uma fatura antes do pagamento
`GET`	`/public/invoices/:token`	(Público) Obtém a fatura para a página hospedada
`POST`	`/public/invoices/:token/pay`	(Público) Gera a slip de PIX/boleto
`POST`	`/public/invoices/:token/pay-card`	(Público) Cobra a fatura com cartão tokenizado

Estados da fatura

O campo status da fatura segue este ciclo de vida:

Estado	Significado
`scheduled`	Criada com antecedência; ativa quando o `chargeAt` chega (emissão da slip adiada)
`suspended`	Congelada por pausa da assinatura — fora dos ciclos de cobrança
`open`	Ativa, aguardando pagamento (slip de PIX/boleto já existe quando aplicável)
`paid`	Totalmente paga
`past_due`	Cobrança falhou; em processo de retentativa (dunning)
`unpaid`	Retentativas esgotadas — cobrança abandonada
`canceled`	Cancelada (void) pelo lojista antes do pagamento
`refunded`	Reembolsada após o pagamento

Estados terminais (paid, canceled, refunded, unpaid) rejeitam ações de cancelamento. A reconciliação fora do gateway só aceita faturas em open, past_due ou unpaid.

Listar faturas

status

string[]

Filtra por um ou mais estados. Aceita CSV (status=open,past_due) ou repetido (status=open&status=past_due). Valores: scheduled, suspended, open, paid, past_due, unpaid, canceled, refunded.

subscriptionId

string

Filtra pelas faturas de uma assinatura específica.

customerId

string

Filtra pelas faturas de um cliente específico.

paymentMethods

string[]

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

string

Busca livre por nome/email/documento do cliente ou pelo código da fatura (prefixo).

code

string

Busca parcial pelo número formatado da fatura (ex: 2026-0007, 2026-, 42). Máx. 20 caracteres.

customer

string

Busca parcial por nome, email ou documento do cliente. Máx. 255 caracteres.

totalMin

integer

Valor total mínimo da fatura, em centavos.

totalMax

integer

Valor total máximo da fatura, em centavos.

dateField

string

Campo de data ao qual aplicar dateFrom/dateTo. Valores: issued, due, paid, created, charge.

dateFrom

string

Início do intervalo de datas. ISO 8601 com timezone (ex: 2026-06-01T00:00:00-03:00) ou data simples (2026-06-01).

dateTo

string

Fim do intervalo de datas. Mesmo formato de dateFrom.

orderBy

string

Campo de ordenação. Valores: createdAt (padrão), dueAt, code, customer, paidAt, value.

order

string

Direção da ordenação: asc ou desc (padrão).

page

integer

Página da paginação.

limit

integer

Itens 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
}

O formato exato do envelope de paginação segue a convenção da API — consulte Convenções.

Detalhar uma fatura

string

obrigatório

ID da fatura (prefixo inv_).

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

A resposta é o objeto da fatura. Campos principais:

string

ID da fatura (inv_).

number

object

Número da fatura: { year, sequence }. Único e sequencial por empresa/ano.

status

string

Estado atual (veja a tabela de estados).

kind

string

Natureza da fatura: enrollment (adesão), recurring (ciclo regular) ou manual (avulsa). Imutável.

customerId

string

ID do cliente (cust_).

customerName

string | null

Nome do cliente (snapshot).

customerEmail

string | null

Email do cliente (snapshot).

customerDocument

string | null

Documento do cliente (snapshot).

currency

string

Moeda ISO de 3 letras (ex: BRL).

subscriptionId

string | null

Assinatura de origem (sub_), quando aplicável.

chargeAt

string

Quando a fatura deixa de ser scheduled e fica pagável. ISO 8601.

dueAt

string | null

Data de vencimento. ISO 8601.

issuedAt

string | null

Data de emissão. ISO 8601.

paidAt

string | null

Data do pagamento. ISO 8601.

canceledAt

string | null

Data do cancelamento. ISO 8601.

subtotal

integer

Soma dos itens, em centavos.

taxTotal

integer

Total de impostos, em centavos.

total

integer

Valor total da fatura, em centavos.

amountPaid

integer

Valor já pago, em centavos.

amountRemaining

integer

Valor restante a pagar, em centavos.

amountRefunded

integer

Valor acumulado reembolsado, em centavos.

installments

integer

Parcelas no cartão para a cobrança (1-12; 1 = à vista).

periodStart

string | null

Início do período de serviço. Nulo para kind=manual. ISO 8601.

periodEnd

string | null

Fim do período de serviço. Nulo para kind=manual. ISO 8601.

createdAt

string

Data de criação. ISO 8601.

updatedAt

string

Data da última atualização. ISO 8601.

O controller declara os seguintes status para este endpoint:

200 — fatura encontrada
404 — fatura não encontrada

Veja Erros para o formato do corpo de erro.

Listar line items

Retorna os itens (linhas de cobrança) de uma fatura.

string

obrigatório

ID da fatura (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 do item: subscription, proration, one_time ou metered_usage.

quantity

integer

Quantidade.

unitAmount

integer

Valor unitário, em centavos.

amount

integer

Valor total do item, em centavos.

Reconciliar pagamento fora do gateway

Marca a fatura como paid quando o pagamento foi recebido por fora (transferência bancária, dinheiro, cheque). Não passa pelo gateway. Aceita faturas em open, past_due ou unpaid.

Este endpoint vive sob o prefixo /admin. Use-o apenas para reconciliação real — ele transiciona o estado da fatura sem cobrança eletrônica.

Este endpoint é idempotente: envie o header Idempotency-Key para evitar reprocessamento em retries. Veja Convenções.

string

obrigatório

ID da fatura (inv_).

amount

integer

obrigatório

Valor recebido, em centavos. Inteiro positivo.

method

string

padrão:"other"

Forma do pagamento off-channel: bank_transfer, cash, check ou other.

paidAt

string

Data/hora do recebimento, ISO 8601 em UTC (com sufixo Z, ex: 2026-06-22T17:30:00.000Z). Opcional.

note

string

Observação livre (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"
}

Status declarados:

200 — fatura atualizada (status=paid)
409 — fatura em estado terminal (não permite a reconciliação)

Cancelar (void) fatura

Cancela uma fatura antes do pagamento. Aceita scheduled, open ou past_due. Estados terminais e unpaid são rejeitados. reason e reasonDetails são obrigatórios. Este endpoint é idempotente: envie o header Idempotency-Key.

string

obrigatório

ID da fatura (inv_).

reason

string

obrigatório

Motivo do cancelamento: duplicate, wrong_amount, customer_agreement, issued_by_mistake ou other.

reasonDetails

string

obrigatório

Detalhes do 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"
}

Status declarados:

200 — fatura cancelada (status=canceled)
409 — fatura em estado terminal/unpaid (não permite cancelamento)

Página de fatura hospedada (pública)

Em vez de enviar a slip de PIX/boleto por email (que expira), a Z2Pay gera um link de fatura hospedada no formato /i/{token}. O pagador anônimo abre o link e a slip é gerada na hora. Estes endpoints não usam x-api-key — a credencial é a posse do token (gerado na emissão, de alta entropia). Eles têm rate limit contra abuso.

O token é o public_access_token da fatura. A página faz polling no GET para exibir a slip e detectar o pagamento (a fatura passa de open para paid).

Obter a fatura para pagamento

Retorna os dados seguros da fatura (sem IDs internos nem companyId sensível) e a slip atual, se já gerada.

token

string

obrigatório

Token público da fatura.

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 da tentativa de cobrança pendente. null enquanto ainda não gerada. Quando presente, contém paymentMethod, status, pixUrl, pixCopyPaste, boletoUrl, boletoDigitableLine, boletoBarcode e expiresAt.

allowedPaymentMethods

string[] | null

Métodos permitidos para esta fatura. null = sem restrição (a página decide pelo método padrão da assinatura).

installmentsConfig

object | null

Config de parcelamento para cartão: { maxInstallments, freeInstallments?, interestRate? }. null = à vista.

companyId

string

Exposto para inicializar o tokenizador de cartão no front. Veja Tokenizer.

Status declarados: 200 (view da fatura), 404 (token inválido).

Gerar a slip de PIX/boleto

Garante uma slip válida para a fatura. O corpo é opcional: o campo method força PIX ou boleto (entre os métodos permitidos). Sem method, usa o padrão da assinatura.

token

string

obrigatório

Token público da fatura.

method

string

pix ou boleto. Opcional.

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

A resposta tem o mesmo formato do GET acima. A slip pode levar ~1-2s para aparecer (persistência assíncrona) — a página deve continuar fazendo polling no GET. Status declarados: 200 (view, slip pode ainda não estar populada), 404 (token inválido), 409 (método não permitido pela fatura).

Cobrar com cartão tokenizado

Cobra a fatura com um cartão tokenizado pelo Tokenizer no front (pode ser cartão de terceiro). Cobrança eager — o resultado reflete no GET no próximo polling.

token

string

obrigatório

Token público da fatura.

cardToken

string

obrigatório

Token do cartão emitido pelo tokenizador.

installments

integer

Número de parcelas escolhido pelo pagador (1 a 12; 1 = à vista). 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
  }'

A resposta é a view atualizada da fatura. Status declarados: 200 (view atualizada), 404 (token inválido), 409 (cartão não permitido ou fatura não pagável).

Para testar o fluxo de pagamento no sandbox, use os cartões de teste e os dados de PIX/boleto, e simule o desfecho via Simular.

Ações disponíveis no painel

Algumas operações de fatura — criar fatura avulsa, gerar link de pagamento, reagendar e forçar nova cobrança (retry) — são realizadas pelo painel do lojista (sessão de usuário), e não estão expostas na API pública por x-api-key. Os corpos abaixo documentam a forma desses dados para referência.

Criar fatura avulsa (manual)

Lança uma cobrança ad-hoc atrelada a uma assinatura, fora do ciclo recorrente. Corpo:

subscriptionId (string, obrigatório)
description (string, 1-200, obrigatório)
amount (integer em centavos, positivo, obrigatório) — valor unitário
quantity (integer positivo, padrão 1)
dueAt (ISO 8601, obrigatório, estritamente no futuro)
reason (obrigatório): extra_service, adjustment, penalty, ad_hoc ou other
reasonDetails (string, 1-500, obrigatório)
allowedPaymentMethods (array de card/pix/boleto, 1-3 itens, opcional) — métodos oferecidos na página hospedada
installmentsConfig (objeto, opcional/nulo): { maxInstallments (1-12), freeInstallments? (1-12), interestRate? (0-100) }. freeInstallments não pode exceder maxInstallments.

A fatura avulsa nasce com kind=manual, sem período de serviço (periodStart/periodEnd nulos).

Gerar link de pagamento

Transiciona uma fatura scheduled para open antes do chargeAt e disponibiliza o link da página hospedada. Nenhuma cobrança é executada — o pagador escolhe o método ao abrir o link. Corpo:

methods (array de card/pix/boleto, 1-3 itens, obrigatório) — métodos oferecidos na página
installmentsConfig (objeto, opcional/nulo, mesma forma da fatura avulsa)

Reagendar fatura

Altera a data de cobrança (chargeAt) de uma fatura scheduled. O dueAt desloca pelo mesmo intervalo. Corpo:

chargeAt (ISO 8601, obrigatório)

Forçar nova cobrança (retry)

Dispara uma nova cobrança em fatura open/past_due sem esperar o ciclo de dunning. Sem corpo. Veja Ciclos.

Veja também

Assinaturas

Crie e gerencie os contratos que geram as faturas.

Ciclos de cobrança

Como cada ciclo emite uma fatura e o fluxo de dunning.

Planos e preços

Defina os valores que compõem os itens da fatura.

Tokenizer

Tokenize cartões no front para a página de fatura hospedada.

​Endpoints

​Estados da fatura

​Listar faturas

​Detalhar uma fatura

​Listar line items

​Reconciliar pagamento fora do gateway

​Cancelar (void) fatura

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

​Obter a fatura para pagamento

​Gerar a slip de PIX/boleto

​Cobrar com cartão tokenizado

​Ações disponíveis no painel

​Veja também

Assinaturas

Ciclos de cobrança

Planos e preços

Tokenizer

Endpoints

Estados da fatura

Listar faturas

Detalhar uma fatura

Listar line items

Reconciliar pagamento fora do gateway

Cancelar (void) fatura

Página de fatura hospedada (pública)

Obter a fatura para pagamento

Gerar a slip de PIX/boleto

Cobrar com cartão tokenizado

Ações disponíveis no painel

Veja também