PayZu GatewayCobranças
Cancelar uma fatura
Feche uma fatura em aberto que não deve mais ser paga, como um pedido desfeito antes do pagamento.
Cancele a fatura
bash
curl -X POST https://api.sandbox.payzu.dev/v1/invoices/in_5Hn9WqZc2LmXv6BtYr1dKe/cancel \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-d '{ "note": "Cliente desistiu da compra" }'Trecho da resposta
{
"id": "in_5Hn9WqZc2LmXv6BtYr1dKe",
"status": "canceled",
"billing": {
"cycle_number": null,
"due_at": "2026-11-11T15:20:59.344Z",
"expires_at": "2026-11-26T15:20:59.344Z",
"paid_at": null,
"canceled_at": "2026-11-11T15:31:04.118Z",
"refunded_at": null,
"chargedback_at": null
},
"payments": [
{
"id": "pay_EHbu1cBNxmis3c7Ftz2Dg7",
"status": "pending",
"method": "pix",
"amount": 5990
}
],
"cancellation": {
"reason": "merchant_request",
"note": "Cliente desistiu da compra"
}
}Referência: Cancelar uma fatura
A resposta é 200, com a fatura inteira, e sai o evento invoice.canceled.
| Campo | Regra |
|---|---|
note | Opcional, de 1 a 255 caracteres. Volta em cancellation.note. O corpo também é opcional. |
Idempotency-Key | Opcional. Com ela, repetir o cancelamento retorna a resposta guardada; sem ela, o segundo cancelamento é recusado porque a fatura já não está em aberto. |
O que pode ser cancelado
- Status: só a fatura
pending. A fatura paga se desfaz pelo estorno. - Fatura de assinatura: não é cancelada sozinha. Cancele a assinatura, como em Cancelar uma assinatura: as faturas em aberto dela sem pagamento confirmado passam a
canceledjunto, comcancellation.reasonigual asubscription_cancellation, e sai uminvoice.canceledpor fatura. - Tentativa já paga: se a fatura em aberto já tem uma tentativa paga, ela passa a
paid, saiinvoice.paid, e o cancelamento é recusado.
O cancelamento não desfaz o Pix já emitido.
O QR Code de uma tentativa pending vale até pix.expires_at. Se o cliente pagar nesse prazo, ou se uma tentativa de cartão em andamento for aprovada, a fatura volta a paid, com cancellation e billing.canceled_at nulos, e sai invoice.paid.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
| - | 404 | Fatura não encontrada para o id informado. |
PZ111 | 409 | Só uma fatura em aberto pode ser paga ou cancelada. |
PZ120 | 409 | Fatura de assinatura não é cancelada sozinha. Cancele a assinatura. |
Os erros de autenticação, de idempotência e de validação estão no Catálogo de erros.