Estornar uma fatura
Nesta página
Peça o estornoAcompanhe a devolução do PixAssinatura da faturaPagamento em duplicidadeQuando o estorno não saiErros desta operaçãoEstorne o valor total de uma fatura paga, no cartão ou no Pix, seja ela uma venda, um ciclo de assinatura ou uma compra pelo link de pagamento.
Peça o estorno
curl -X POST https://api.sandbox.payzu.dev/v1/invoices/in_2WcN6xQmLb9TzYv4KdRh8E/refunds \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: a3f1c9e2-7b4d-4e8a-9c6f-1d2e3f4a5b6c" \
-H "Content-Type: application/json" \
-d '{ "cancel_subscription": true }'{
"id": "in_2WcN6xQmLb9TzYv4KdRh8E",
"status": "refunded",
"amounts": {
"subtotal": 49900,
"discount": 0,
"total": 49900,
"paid": 49900,
"refunded": 49900
},
"billing": {
"paid_at": "2026-11-11T15:32:07.930Z",
"refunded_at": "2026-11-13T14:10:26.380Z"
},
"refunds": [
{
"id": "rfd_8WqL5nXcVb2TzYm7KdRh4E",
"status": "confirmed",
"amount": 49900,
"requested_at": "2026-11-13T14:10:25.978Z",
"confirmed_at": "2026-11-13T14:10:26.380Z",
"failed_at": null,
"failure": null
}
]
}Referência: Estornar uma fatura
- Fatura: só a
paidpode ser estornada. O estorno é da tentativa que quitou a fatura, sempre pelo valor total. Idempotency-Key: é obrigatória nesta chamada. Repetir a chamada com a mesma chave e o mesmo corpo retorna a resposta guardada, comIdempotent-Replayed: true, sem estornar de novo; com outro corpo,409.- Corpo: é opcional e só aceita
cancel_subscription, descrito em Assinatura da fatura. Outro campo responde400. - Resposta no cartão: o
201traz a fatura inteira, járefunded, com o estornoconfirmedemrefunds,billing.refunded_ate o total somado aamounts.refunded, que também conta um pagamento em duplicidade já devolvido. Sai o eventoinvoice.refunded.
Uma venda no cartão com contestação não pode ser estornada.
Antes de estornar, a PayZu confere a cobrança na adquirente e, se houver contestação, recusa o pedido sem estornar. Responda a contestação, como em Contestações.
Acompanhe a devolução do Pix
No Pix, a devolução é pedida na hora e confirmada depois.
| Etapa | Fatura | Tentativa | Estorno em refunds | Evento |
|---|---|---|---|---|
| Devolução pedida | paid | refund_requested | requested | invoice.refund_requested |
| Devolução confirmada | refunded | refunded | confirmed | invoice.refunded |
| Devolução recusada pelo banco | paid | paid | failed | invoice.refund_failed |
A resposta 201 traz a fatura ainda paid, com o estorno requested. Enquanto a devolução está pedida, um novo pedido é recusado; depois de uma recusa, a devolução pode ser pedida outra vez. Acompanhe pela consulta da fatura ou pelos eventos.
Assinatura da fatura
Quando a fatura é de uma assinatura, o estorno pode cancelar a assinatura. Em fatura fora de assinatura, o campo não tem efeito.
cancel_subscription | O que acontece com a assinatura |
|---|---|
true | É cancelada, se estiver active. |
false | Continua como está. |
| Sem o campo | Vale refund_cancels_subscription da conta, que nasce true e está em Alterar a carência. |
{ "cancel_subscription": false }Quando o estorno cancela a assinatura:
- Assinatura: passa a
canceled, comcancellation.reasonigual ainvoice_refund, e saisubscription.canceled. - Outras faturas em aberto dela: as que não têm pagamento confirmado passam a
canceled, comcancellation.reasonigual asubscription_cancellation. No estorno pedido por esta rota, sai uminvoice.canceledpor fatura, antes desubscription.canceled. - Estorno que chega pela adquirente, fora desta rota: segue a configuração da conta e fecha as faturas sem
invoice.canceled.
A contestação que leva a fatura a chargedback também cancela a assinatura, como explica Contestações.
A assinatura cancelada por estorno não pode ser reativada.
A reativação é recusada, como explica Reativar uma assinatura. Para cobrar o cliente de novo, crie outra assinatura.
Pagamento em duplicidade
Um pagamento confirmado numa fatura que já está paid, refunded ou chargedback, como um Pix pago depois do cartão, é devolvido sozinho, sem chamada sua.
- Tentativa: passa a
refund_requestede, com a devolução confirmada, arefunded. O estorno entra emrefunds. - Fatura: o status não muda.
amounts.paidsoma os dois pagamentos eamounts.refundedtraz o valor devolvido. - Evento: sai
invoice.payment_refunded. - Assinatura: não muda nem é cancelada.
O estorno pedido por esta rota é sempre da tentativa que quitou a fatura, nunca do pagamento em duplicidade.
Quando o estorno não sai
| Situação | Resposta |
|---|---|
| A adquirente não respondeu a tempo, e a PayZu encontra o estorno ao reler a cobrança. | 201, com a fatura estornada. |
| A adquirente não respondeu a tempo, e o estorno não aparece na releitura. | 422, com o estorno failed em refunds e o evento invoice.refund_failed. A fatura segue paid. |
| O saldo disponível da conta é menor que o valor do estorno. | 422, com o estorno failed em refunds e o evento invoice.refund_failed. A fatura segue paid. |
refunds[].failure vem sempre null: o motivo da recusa está no erro da resposta. A mesma fatura nunca é estornada duas vezes.
Depois de uma recusa, tente de novo com outra Idempotency-Key.
As duas recusas saem depois do envio à adquirente, e a resposta fica guardada na chave por 24 horas: a mesma chave repete o erro, com Idempotent-Replayed: true.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ031 | 403 | Esta conta só tem acesso de consulta. |
PZ032 | 403 | Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix. |
PZ033 | 403 | Pix não habilitado para esta conta. Fale com o suporte para habilitar. |
| - | 404 | Fatura não encontrada para o id informado. |
PZ400 | 409 | Só uma fatura paga pode ser estornada. |
PZ402 | 409 | O estorno desta fatura já está em andamento. |
PZ401 | 422 | Esta fatura já foi estornada. |
PZ403 | 422 | Não foi possível estornar esta fatura agora. Tente de novo mais tarde. |
PZ404 | 422 | Saldo disponível menor que o valor do estorno. Tente de novo quando houver saldo. |
Os erros de autenticação e de idempotência estão no Catálogo de erros.