Skip to main content
O estorno devolve ao cliente o valor de uma cobrança paga. Você pede o estorno com uma única chamada, 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.
O estorno é feito somente pela API. A Finvia não faz estorno por chamado ou pelo suporte, exceto em caso de erro sistêmico. Se a sua equipe de atendimento precisa estornar, dê a ela uma tela no seu sistema que chame POST /v1/refunds.

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 422 Insufficient balance.
O desenho abaixo resume o efeito do estorno no split e no seu saldo, inclusive quando o valor já foi sacado. O saldo negativo vale também para o recebedor do split que já sacou a parte dele.
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

Resposta 201 Created:
Para o desenvolvedor: guarde o pspRefundRefId junto com o pedido. Ele é a referência do estorno no processador e ajuda no atendimento ao cliente e na conciliação.

2. Trate o webhook charge.refunded

Quando o estorno é registrado, os endpoints e a postbackUrl recebem o evento no envelope padrão:
O exemplo mostra parte do objeto 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 com 422. A rotina abaixo grava o resultado e trata as respostas de erro como finais.
Node.js
Depois de um timeout no pedido de estorno, consulte a cobrança com 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

Não. O estorno é sempre do valor total da cobrança. A API não recebe um valor no pedido de estorno.
Não. O estorno é feito só pela rota POST /v1/refunds. A Finvia só atua diretamente em caso de erro sistêmico.
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.
Não. Do seu saldo sai o valor bruto da venda, e as taxas cobradas na venda não são devolvidas.
Pode. O saldo disponível fica negativo e é compensado pelas próximas liquidações. Enquanto isso, novos saques recebem 422 Insufficient balance.
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 refunded e webhook charge.refunded. No Modo Teste, crie um Pix com a chave sk_test_: ele vira paid sozinho 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.
Para testar só o tratamento do evento, use 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.