Devolver uma cobrança
Devolva ao pagador o valor de uma cobrança paga, inteiro ou em parte, com a tarifa de devolução debitada da sua conta além do valor.
Peça a devolução
- Tudo o que resta: chame a rota sem corpo ou com
{}. - Uma parte: envie só
amount, em centavos, até orefundableAmountda consulta da cobrança. Idempotency-Key: mande uma nova por devolução.- Cota: a devolução conta na cota do saque, de 5 por minuto por credencial e 10 por conta.
Um corpo com outro campo, ou que não é JSON, é recusado com 400 e nada é devolvido.
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/payment/P20261005113205K7Q2M9XB4TC127431/refund' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Idempotency-Key: 5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f' \
--header 'Content-Type: application/json' \
--data '{ "amount": 1000 }'{
"id": "P20261005113205K7Q2M9XB4TC127431",
"status": "PAID",
"amount": 1500,
"refundedAmount": 0,
"refundFee": 0,
"refundInProgressAmount": 1000,
"refundableAmount": 0,
"refunds": [
{
"id": "cmu7r2f9k000301s6abcd5678",
"status": "PROCESSING",
"amount": 1000,
"serviceFee": 100,
"totalDebited": 1100,
"endToEndId": null,
"rejectedReason": null,
"requestedAt": "2026-10-06T09:15:00.000Z",
"settledAt": null,
"releasedAt": null
}
]
}Referência: Solicitar a devolução de uma cobrança
A resposta é a cobrança inteira; o exemplo mostra só o que muda. O que sai da sua conta é o totalDebited da tentativa em refunds, com a tarifa de devolução somada.
Se receber 502, repita com a mesma Idempotency-Key e o mesmo amount.
A resposta traz a devolução já pedida, no estado em que estiver, sem enviar outro Pix. Isso vale também para uma devolução recusada: para tentar de novo, use outra chave. Sem a chave, repetir depois que a primeira concluiu faz uma segunda devolução.
Confirme a devolução
| Desfecho | Aviso | Tentativa em refunds |
|---|---|---|
| O valor voltou ao pagador. | REFUND_COMPLETED | SETTLED |
| O banco recusou e o valor voltou ao seu saldo. | REFUND_FAILED | RELEASED, com o motivo em rejectedReason |
| Ainda em andamento. | - | PROCESSING |
Os dois avisos trazem refundId e paymentId, e o corpo deles está em Devolução concluída e Devolução recusada. Para conferir, consulte a cobrança e olhe a tentativa mais recente.
Quando a devolução total conclui, a cobrança passa a REFUNDED e refundedAt é preenchido. O comprovante da cobrança continua disponível.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
REFUND_DISABLED | 403 | Estorno desabilitado para esta conta. |
PAYMENT_NOT_FOUND | 404 | Pagamento não encontrado. |
REFUND_ABOVE_REMAINING | 422 | O valor do estorno é maior do que o que resta a devolver deste pagamento. |
REFUND_ABOVE_TICKET_MAX | 422 | O valor do estorno está acima do limite por operação desta conta. |
REFUND_ALREADY_REFUNDED | 422 | Este pagamento já foi estornado integralmente. |
REFUND_INFRACTION_OPEN | 422 | Esta cobrança tem uma contestação MED em andamento; o estorno fica indisponível até o desfecho. |
REFUND_INSUFFICIENT_BALANCE | 422 | Saldo insuficiente para estornar este pagamento. |
REFUND_IN_FLIGHT | 422 | Já existe um estorno em andamento para este pagamento. Aguarde o desfecho antes de pedir outro. |
REFUND_NOT_PAID | 422 | Só é possível estornar um pagamento que foi pago. |
Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.