PayZu GatewayEstornos e contestações

Estornar uma fatura


Nesta páginaPeça o estornoAcompanhe a devolução do PixAssinatura da faturaPagamento em duplicidadeQuando o estorno não saiErros desta operação

Estorne 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

bash
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 }'
Trecho da resposta no cartão
{
  "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 paid pode 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, com Idempotent-Replayed: true, sem estornar de novo; com outro corpo, 409.
  • Corpo: é opcional e só aceita cancel_subscription, descrito em Assinatura da fatura. Outro campo responde 400.
  • Resposta no cartão: o 201 traz a fatura inteira, já refunded, com o estorno confirmed em refunds, billing.refunded_at e o total somado a amounts.refunded, que também conta um pagamento em duplicidade já devolvido. Sai o evento invoice.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.

EtapaFaturaTentativaEstorno em refundsEvento
Devolução pedidapaidrefund_requestedrequestedinvoice.refund_requested
Devolução confirmadarefundedrefundedconfirmedinvoice.refunded
Devolução recusada pelo bancopaidpaidfailedinvoice.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_subscriptionO que acontece com a assinatura
trueÉ cancelada, se estiver active.
falseContinua como está.
Sem o campoVale refund_cancels_subscription da conta, que nasce true e está em Alterar a carência.
Corpo para estornar sem cancelar a assinatura
{ "cancel_subscription": false }

Quando o estorno cancela a assinatura:

  • Assinatura: passa a canceled, com cancellation.reason igual a invoice_refund, e sai subscription.canceled.
  • Outras faturas em aberto dela: as que não têm pagamento confirmado passam a canceled, com cancellation.reason igual a subscription_cancellation. No estorno pedido por esta rota, sai um invoice.canceled por fatura, antes de subscription.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_requested e, com a devolução confirmada, a refunded. O estorno entra em refunds.
  • Fatura: o status não muda. amounts.paid soma os dois pagamentos e amounts.refunded traz 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çãoResposta
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ódigoHTTPMensagem
PZ031403Esta conta só tem acesso de consulta.
PZ032403Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix.
PZ033403Pix não habilitado para esta conta. Fale com o suporte para habilitar.
-404Fatura não encontrada para o id informado.
PZ400409Só uma fatura paga pode ser estornada.
PZ402409O estorno desta fatura já está em andamento.
PZ401422Esta fatura já foi estornada.
PZ403422Não foi possível estornar esta fatura agora. Tente de novo mais tarde.
PZ404422Saldo 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.