Estornar uma cobrança
Cancele uma venda confirmada estornando o valor total da cobrança, uma única vez, com o valor debitado do saldo da sua conta.
Estorne a cobrança
- Cobrança:
chargeIdé oidda cobrança, que precisa estar comcreditCardPayment.statusigual a2ereversedAmountvazio. - Corpo: a rota não recebe corpo.
- Valor: não envie
amountna query. O estorno parcial não está disponível.
curl --request PUT \
--url 'https://api.sandbox.payzu.dev/v1/charges/e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90/reverse' \
--header "Authorization: Bearer $PAYZU_TOKEN" \
--cert "$PAYZU_CLIENT_CERT" --key "$PAYZU_CLIENT_KEY"{
"id": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90",
"creditCardPayment": {
"status": 2,
"reversedAmount": 10000,
"reversedDate": "2026-06-13T09:12:45.000Z"
}
}Referência: Estornar ou devolver uma cobrança
A resposta traz a cobrança inteira; o exemplo mostra só os campos que mudam.
Um estorno não se desfaz.
Antes de chamar a rota, confira se o id é o da cobrança certa.
Uma segunda chamada para a mesma cobrança espera de 3 a 5 segundos pela primeira. Se a primeira terminar o estorno nesse intervalo, a segunda retorna 422; se a primeira ainda estiver em andamento, a segunda retorna 409.
Confirme o estorno
| Momento | O que a cobrança mostra |
|---|---|
Logo depois do PUT | reversedAmount com o valor da cobrança e reversedDate preenchidos. creditCardPayment.status pode continuar 2. |
| Cancelamento confirmado | creditCardPayment.status muda para 10 ou 11, e a PayZu envia o aviso charge.update para a postbackUrl da cobrança. |
O aviso é o canal recomendado para refletir a mudança no seu sistema; veja Webhooks. A consulta por GET /charges/{chargeId} mostra os mesmos campos a qualquer momento.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ404 | 400 | Valor do estorno excede o saldo disponível |
PZ403 | 403 | Estorno parcial não disponível |
PZ100 | 404 | Cobrança não encontrada |
PZ402 | 409 | Já existe um estorno em andamento para esta cobrança |
PZ406 | 409 | Estorno desta cobrança já está em processamento |
PZ104 | 422 | Conta sem provedor de pagamento configurado |
PZ108 | 422 | Configuração de pagamento da conta incompleta |
PZ400 | 422 | Cobrança não disponível para estorno |
PZ401 | 422 | Cobrança já estornada |
PZ800 | 422 | Conta sem carteira configurada |
PZ900 | 422 | O provedor de pagamento recusou a operação |
PZ901 | 503 | Não foi possível estabelecer comunicação com o provedor de pagamento. Tente novamente em instantes. |
Os erros de autenticação e de validação e os demais códigos estão no Catálogo de erros.