Consultar faturas
Confira o status e as tentativas de uma fatura, ou liste as faturas para conciliar as vendas e os ciclos de assinatura.
Consulte a fatura
curl "https://api.sandbox.payzu.dev/v1/invoices/in_7Kd2QmXvB9LtYc4WnRz8Hs" \
-H "Authorization: Bearer SUA_CHAVE_DE_API"{
"id": "in_7Kd2QmXvB9LtYc4WnRz8Hs",
"status": "paid",
"url": "https://invoice.payzu.com.br/pay/in_7Kd2QmXvB9LtYc4WnRz8Hs",
"description": "Pedido 1234",
"external_reference": "pedido-1234",
"created_at": "2026-11-11T15:20:59.333Z",
"updated_at": "2026-11-11T15:20:59.336Z",
"amounts": {
"subtotal": 15990,
"discount": 0,
"total": 15990,
"paid": 15990,
"refunded": 0
},
"billing": {
"cycle_number": null,
"due_at": "2026-11-11T15:20:59.333Z",
"expires_at": "2026-11-26T15:20:59.333Z",
"paid_at": "2026-11-11T15:20:59.335Z",
"canceled_at": null,
"refunded_at": null,
"chargedback_at": null
},
"items": [
{ "name": "Curso de fotografia", "sku": "CURSO-01", "quantity": 1, "unit_price": 15990 }
],
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 12 }
},
"checkout": {
"redirect_url": null,
"cancel_url": null
},
"customer": {
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"document": "52998224725",
"document_type": "cpf"
},
"subscription": null,
"payment_link": null,
"payments": [
{
"id": "pay_Nfa3VKU4p0ojE3jMQeunRD",
"status": "paid",
"method": "credit_card",
"amount": 15990,
"created_at": "2026-11-11T15:20:59.333Z",
"paid_at": "2026-11-11T15:20:59.335Z",
"failed_at": null,
"failure": null,
"credit_card": {
"installments": 1,
"authorization_code": "123456",
"card": {
"id": "card_GL2pIWf5pznF4qwg2KKd5v",
"brand": "visa",
"last_digits": "1111",
"holder_name": "MARIA SOUZA"
}
}
}
],
"refunds": [],
"cancellation": null,
"chargeback": null,
"metadata": {
"internal_id": "1234"
}
}Referência: Consultar uma fatura
| Campo | O que traz |
|---|---|
url | A página de pagamento da fatura. Vem em toda fatura e não muda nem vence. |
amounts | subtotal é o valor cheio, discount o desconto e total o valor a pagar. paid soma tudo o que entrou e refunded tudo o que foi devolvido, em centavos. |
billing | O vencimento (due_at), o limite para pagar (expires_at) e a data de cada mudança de status. cycle_number é o ciclo da assinatura, com a adesão no ciclo 0. |
customer | O cliente da fatura. Vem null na fatura criada sem cliente, até a primeira tentativa na página. |
subscription, payment_link | De onde a fatura veio: a assinatura ou a compra pelo link de pagamento. |
payments | As tentativas de pagamento, da mais nova para a mais antiga. payments[0] é a última. |
refunds | Os estornos, com status requested, confirmed ou failed. |
cancellation | Na fatura canceled, o motivo em reason (merchant_request ou subscription_cancellation) e a sua note. |
chargeback | Na fatura contestada, o id e o status da contestação, como em Consultar uma contestação. |
Status da tentativa
| Status | O que significa |
|---|---|
pending | Pix aguardando pagamento, com o QR Code em pix. |
processing | Cartão ou Pix sem resposta da adquirente. No Pix, passa a pending, com o QR Code, quando a cobrança aparece. |
paid | Paga. |
failed | Recusada, com o motivo em failure. |
expired | O QR Code do Pix venceu sem pagamento. |
refund_requested | Estorno pedido e ainda não confirmado. |
refunded | Estornada. |
chargedback | Contestada. |
Um pagamento confirmado numa fatura que já estava paga é devolvido sozinho: a tentativa passa a refunded, o estorno entra em refunds, e o status da fatura não muda. Veja Pagamento em duplicidade. Os status da fatura estão em Cobranças.
Liste as faturas
curl "https://api.sandbox.payzu.dev/v1/invoices?customer_id=cus_bdQT0ls1QMIXVuhngvhbwC&status=paid" \
-H "Authorization: Bearer SUA_CHAVE_DE_API"Referência: Listar as faturas
A lista traz items e next_cursor, da fatura mais nova para a mais antiga, com cada item igual à consulta, inclusive payments e refunds. A paginação é por cursor, como em Paginação.
| Filtro | O que traz |
|---|---|
status | As faturas nesse status. |
payment_method | As faturas cuja última tentativa foi nesse meio. |
customer_id, subscription_id, payment_link_id | As faturas do cliente, da assinatura ou do link de pagamento. |
external_reference | As faturas com essa referência. |
search | Busca na descrição, na referência, no código da assinatura e no nome, no e-mail ou no documento do cliente. |
due_from, due_to | O dia do vencimento. |
paid_from, paid_to | O dia do pagamento. |
created_from, created_to | O dia da criação. |
updated_from | As faturas alteradas a partir desse dia. |
Os dias vão no formato AAAA-MM-DD, no fuso de São Paulo. Na fatura em aberto, updated_at muda a cada tentativa, por isso updated_from serve para sincronizar o seu sistema.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
| - | 404 | Fatura não encontrada para o id informado. |
Os erros de autenticação e de validação estão no Catálogo de erros.