POST /v1/refunds, informando a cobrança e o motivo. O estorno vale para cobranças Pix e de cartão de crédito (inclusive cartão salvo e Apple Pay) e é sempre do valor total da cobrança.
Para o negócio: use o estorno quando o pedido é cancelado, o produto não pode ser entregue ou o cliente desiste da compra. O cliente recebe o valor integral pelo mesmo meio de pagamento, a cobrança passa a
refunded e os sistemas conectados recebem o aviso charge.refunded. Do seu saldo sai o valor bruto da venda: as taxas da venda não são devolvidas.Quando usar
Como funciona
O desenho abaixo mostra o caminho de um pedido de estorno, da consulta da cobrança ao aviso por webhook.1
Confira a cobrança
A cobrança precisa estar
paid e não pode ter outro estorno. Consulte com GET /v1/charges/{id}.2
Peça o estorno
Seu servidor chama
POST /v1/refunds com chargeId e reason, usando a chave secreta da conta dona da cobrança.3
Leia a resposta
A resposta
201 traz status refunded: o estorno foi registrado na Finvia e o valor saiu do seu saldo.4
A Finvia devolve ao comprador
No Pix, sai uma devolução do pagamento original na hora. No cartão, o pedido vai à adquirente na hora e o crédito aparece na fatura do comprador conforme o prazo do banco emissor.
5
Os webhooks avisam
A cobrança passa a
refunded e o evento charge.refunded é enviado aos endpoints de webhook cadastrados e à postbackUrl da cobrança, se ela foi informada.Regras de negócio
Prazo para o comprador receber
O prazo depende do meio de pagamento, e não da API.A resposta
refunded significa que o estorno foi registrado na Finvia e o valor saiu do seu saldo. Se a adquirente ou o banco não concluir o estorno automaticamente, a API responde refunded mesmo assim e a equipe Finvia conclui o estorno manualmente. Nesse caso o comprador pode demorar mais para receber. Não reenvie o pedido: se o comprador não receber, acione o suporte com o chargeId.Quanto sai do seu saldo
Exemplo: uma venda de R$ 100,00 no Pix, com R$ 1,00 de taxa, já liquidada. Você recebeu R$ 99,00 no saldo disponível. No estorno, o comprador recebe R$ 100,00 e sai R$ 100,00 do seu saldo disponível (os R$ 99,00 recebidos mais a taxa de R$ 1,00, que não volta).
Estorno de venda com split
- O estorno é sempre da cobrança inteira. Não dá para estornar só a parte de um recebedor.
- O pedido é feito pela conta dona da cobrança (o originador). O recebedor do split não consegue estornar a venda.
- Partes do split já repassadas: cada recebedor devolve o que recebeu. O valor é debitado do saldo disponível dele (ou do bloqueado, se a conta estiver retida) e volta ao originador antes do débito total.
- Partes ainda não repassadas: são canceladas e ninguém recebe.
Estorno depois do saque
O estorno é permitido mesmo que o valor da venda já tenha sido sacado. A API não confere o saldo antes de estornar:- Se o valor já saiu da conta, o saldo disponível fica negativo. O mesmo vale para o recebedor do split.
- O negativo é compensado pelas próximas liquidações.
- Novos saques só passam quando o saldo disponível cobre o valor pedido. Antes disso, a API responde
422Insufficient balance.
Em validação (V-59): o time de produto ainda confirma o texto do prazo do cartão (“até duas faturas”), a regra das taxas e do saldo negativo e a resposta
refunded quando a adquirente recusa.Passo a passo
1. Peça o estorno
201 Created:
2. Trate o webhook charge.refunded
Quando o estorno é registrado, os endpoints e apostbackUrl recebem o evento no envelope padrão:
data. O payload completo está em Webhooks de cobrança. Quando o estorno é feito no tratamento de um alerta de pré-chargeback, o payload traz chargeback_alert_refunded: true.
Node.js
3. Estorno com proteção contra duplicidade
Cada cobrança comporta um único estorno, e a API recusa o segundo pedido com422. A rotina abaixo grava o resultado e trata as respostas de erro como finais.
Node.js
GET /v1/charges/{id} antes de repetir. Se ela estiver refunded, grave o resultado e não peça de novo.
Erros comuns
Os erros seguem o formato padrão (
statusCode, message, error). Trate pelo código HTTP: as mensagens podem mudar.
Perguntas frequentes
Posso devolver só parte do valor?
Posso devolver só parte do valor?
Não. O estorno é sempre do valor total da cobrança. A API não recebe um valor no pedido de estorno.
Posso pedir o estorno ao suporte da Finvia?
Posso pedir o estorno ao suporte da Finvia?
Não. O estorno é feito só pela rota
POST /v1/refunds. A Finvia só atua diretamente em caso de erro sistêmico.O comprador diz que não recebeu. O que faço?
O comprador diz que não recebeu. O que faço?
No Pix, a devolução costuma chegar em segundos. No cartão, o crédito depende do fechamento da fatura do emissor. Se o prazo passou, acione o suporte com o
chargeId: pode ser um caso em que a adquirente não concluiu o estorno automaticamente e a equipe Finvia está concluindo. Não peça outro estorno.As taxas da venda voltam para mim?
As taxas da venda voltam para mim?
Não. Do seu saldo sai o valor bruto da venda, e as taxas cobradas na venda não são devolvidas.
Já saquei o dinheiro da venda. Posso estornar?
Já saquei o dinheiro da venda. Posso estornar?
Pode. O saldo disponível fica negativo e é compensado pelas próximas liquidações. Enquanto isso, novos saques recebem
422 Insufficient balance.Estorno e chargeback são a mesma coisa?
Estorno e chargeback são a mesma coisa?
São processos diferentes. O estorno é pedido por você. O chargeback é uma contestação que o titular do cartão abre no banco emissor. Veja Bloqueio, chargeback e MED.
Como testar
No roteiro de homologação:- CHG-07: estorno total de uma cobrança paga, com status
refundede webhookcharge.refunded. No Modo Teste, crie um Pix com a chavesk_test_: ele virapaidsozinho em cerca de 5 segundos e já pode ser estornado. - AP-05: estorno de uma cobrança Apple Pay paga, se você usa Apple Pay.
POST /v1/charges/{id}/resend-webhook com {"status": "refunded"}. Ele dispara um evento simulado e não altera a cobrança.
Veja também
Estornar cobrança
Referência de
POST /v1/refunds.Webhooks de cobrança
Payload do
charge.refunded.Bloqueio, chargeback e MED
Contestações abertas pelo cliente.
Split
Como o repasse funciona antes do estorno.

