Estornos
Estorno é a devolução de um Pix que você recebeu. Vale só para transação de entrada (type: DEPOSIT) já liquidada (status: COMPLETED).
Como funciona
Informe amount para devolver parte do valor, ou omita o campo para devolver o valor cheio. A resposta volta na hora com o estorno pendente: a confirmação não é síncrona.
A resposta 200 significa que o estorno foi aceito, não que o dinheiro voltou. Espere o webhook com status: REFUNDED antes de dar baixa no seu lado.
Sempre mande clientReference
clientReference é a chave de idempotência do estorno. Sem ela, um retry por timeout ou erro de rede devolve o dinheiro duas vezes.
| Situação | O que acontece |
|---|---|
Mesma chave, mesmo amount | Devolve o estorno já criado, não cria outro |
Mesma chave, amount diferente | Recusa com PZC210 |
| Sem chave | Cada chamada cria um estorno novo |
Gere a chave a partir do seu próprio pedido (estorno-pedido-2026-001) e reuse o mesmo valor no retry. Em estorno parcial, use uma chave por parcela.
Exemplos
Acompanhar o resultado
Os campos de estorno voltam no callback e na consulta da transação: refundStatus, refundAmount, refundEndToEndId, refundReason e refundedAt. A referência completa está em Webhooks.