Skip to main content
Uma fatura é um pedido de pagamento emitido para um cliente, com itens baseados em preços. Nasce como rascunho (draft), é aberta (open) para poder ser paga e fecha como paid, void ou uncollectible. Assinaturas e checkouts geram faturas automaticamente. Todos os endpoints exigem chave secreta (sk_…).
Sandbox: https://api.upag.dev/v1 com sk_test_…. Produção: https://api.upag.io/v1 com sk_live_….

​
Estrutura

​
Atributos

​
string
UUID da fatura.
​
string
UUID do cliente.
​
string | null
Campo reservado; hoje vem sempre null. Para saber como uma fatura foi paga, consulte payments.
​
string | null
UUID da assinatura que gerou a fatura. null em faturas avulsas.
​
string
draft, open, paid, void ou uncollectible. Veja Status.
​
string
Moeda dos preços da fatura (brl ou usd). Só faturas em brl podem ser pagas.
​
string | null
Descrição informada na criação.
​
integer
Valor a pagar em centavos: soma dos itens menos os descontos. Recalculado a cada mudança nos itens.
​
integer
Valor pago em centavos. 0 até a fatura ser paga; depois, igual a amountDue.
​
integer
Tentativas de pagamento que falharam (cartão recusado ou Pix vencido).
​
string | null
Vencimento informado na criação (ISO 8601).
​
string | null
ISO 8601 do pagamento. null até a fatura ser paga.
​
array
Linhas da fatura.
  • id: UUID do item.
  • product: UUID do produto.
  • price: UUID do preço.
  • name: nome do preço, copiado na hora em que o item entrou.
  • amount: valor unitário em centavos, copiado do preço na hora em que o item entrou.
  • quantity: quantidade.
  • totalAmount: amount × quantity, em centavos.
​
array
Descontos aplicados (hoje só de cupom, vindos de um checkout).
  • id: UUID do desconto.
  • item: UUID do item descontado.
  • coupon: UUID do cupom.
  • type: coupon.
  • amount: desconto em centavos.
​
array
Tentativas de pagamento, uma por cobrança criada para a fatura. Só vem em respostas da API; nos webhooks de fatura não aparece.
  • charge: UUID da cobrança.
  • type: pix ou card.
  • status: status da cobrança (pending, paid, expired, failed, in_review, refunded, partially_refunded ou chargeback).
  • settledAt: ISO 8601 do momento em que o resultado foi aplicado à fatura. null enquanto a cobrança está pendente.
  • createdAt: ISO 8601.
​
string
ISO 8601.
​
string
ISO 8601.

​
Status

Não há endpoint para anular uma fatura nem para marcá-la como uncollectible. Um cartão recusado não muda o status: a fatura continua open, attemptCount sobe e você pode pagar de novo. Acompanhe as mudanças por webhooks de fatura: invoice.created, invoice.opened, invoice.paid, invoice.voided, invoice.uncollectible e invoice.payment_failed.