Devolver um depósito
Devolva ao pagador um Pix recebido numa chave da conta, inteiro ou em parte, com a tarifa de devolução debitada 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 do depósito. Idempotency-Key: mande uma nova por devolução.
Um corpo com outro campo, ou que não é JSON, é recusado sem devolver nada. A TED recebida, com method igual a TED, não aceita devolução, nem depois de liberada: liberar o depósito e pedir de novo vale só para o Pix.
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765/refund' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Idempotency-Key: 9b2e4c6a-1d3f-4a5b-8c7d-0e9f1a2b3c4d'{
"id": "cmu4a1b2c000001s6xyz98765",
"amount": 5000,
"refundedAmount": 0,
"refundInProgressAmount": 5000,
"refundableAmount": 0,
"openInfractionProtocol": null,
"refunds": [
{
"id": "cmu7r2f9k000501s6ijkl9012",
"status": "PROCESSING",
"amount": 5000,
"serviceFee": 100,
"totalDebited": 5100,
"endToEndId": null,
"rejectedReason": null,
"requestedAt": "2026-10-06T10:05:00.000Z",
"settledAt": null,
"releasedAt": null
}
]
}Referência: Solicitar a devolução de um depósito
A resposta é o depósito inteiro; o exemplo mostra só o que muda. O débito na sua conta é o totalDebited da tentativa em refunds, com a tarifa de devolução somada.
O depósito aceita uma devolução de cada vez.
Nenhuma é aceita enquanto ele estiver retido ou houver infração MED aberta. Se receber 502, repita com a mesma Idempotency-Key e o mesmo amount, que retornam a devolução já pedida sem enviar outro Pix, ou confira refunds na consulta do depósito antes de pedir de novo.
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 |
Os dois avisos trazem depositId e refundId e vão só aos webhooks cadastrados. O corpo deles está em Devolução concluída e Devolução recusada. Para conciliar, consulte o depósito.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
REFUND_DISABLED | 403 | Estorno desabilitado para esta conta. |
DEPOSIT_NOT_FOUND | 404 | Depósito não encontrado. |
DEPOSIT_BLOCKED | 422 | O depósito está retido. Libere-o antes de solicitar a devolução. |
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_TED_NOT_SUPPORTED | 422 | TED recebida não aceita devolução: a devolução é uma operação do Pix e depende do identificador end-to-end, que a TED não tem. |
Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.