Skip to main content
POST
Esta rota devolve ao cliente o valor inteiro de uma cobrança paga. Ela atende cancelamento de pedido, desistência de compra, produto indisponível depois da venda e qualquer outro caso em que o dinheiro precisa voltar ao comprador. Funciona para cobranças pagas com Pix e com cartão de crédito (inclusive cartão salvo e Apple Pay).
Esta rota é o único caminho para pedir um estorno. A Finvia não faz estorno por chamado ou pelo suporte, exceto em caso de erro sistêmico. Integre esta chamada ao seu sistema ou ao seu processo de atendimento.

Quando usar

Antes de chamar

  • Tenha uma chave secreta do mesmo ambiente da cobrança (Credenciais e ambientes).
  • A cobrança precisa estar com status paid. Confira com GET /v1/charges/{id}. Uma cobrança bloqueada (isBlocked: true) continua paid e pode ser estornada.
  • O pedido precisa partir da conta dona da cobrança. Em venda com split, o recebedor não consegue estornar.
  • Cada cobrança aceita um único estorno.

Corpo da requisição

Os dois campos são obrigatórios.
string
required
ID da cobrança a ser estornada. A cobrança precisa estar com status paid. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.
string
required
Motivo do estorno, em texto livre. Fica registrado para auditoria. Ex.: Pedido ORD-123 cancelado pelo cliente.

Respostas

string
Resultado do estorno. Hoje a API devolve sempre refunded: o estorno foi registrado na Finvia e o valor saiu do seu saldo.
string | null
Texto informado pelo provedor de pagamento (PSP). Pode vir preenchido mesmo quando o estorno deu certo: decida pelo status, não por este campo.
string | null
Identificador do estorno no PSP, quando disponível. Ex.: ref_abc123.
Com o 201, a cobrança passa a refunded e o webhook charge.refunded é enviado aos endpoints do painel e à postbackUrl da cobrança. 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. Os erros seguem o formato padrão, com statusCode, message e error. Trate pelo código HTTP, não pelo texto.
Para o negócio: o comprador recebe o valor integral da cobrança. Do seu saldo sai o valor bruto da venda, e as taxas da venda não são devolvidas. Prazos para o comprador receber, efeito no split e estorno depois do saque estão no guia de estorno.

Evite estorno duplicado

A API não aceita o cabeçalho Idempotency-Key, mas recusa um segundo estorno da mesma cobrança. A proteção fica assim:
1

Grave o resultado

Ao receber o 201, grave o status e o pspRefundRefId junto com a cobrança. A resposta não traz um campo id do estorno.
2

Trate o 422 como final

422 Já existe um reembolso para esta cobrança indica que o estorno já foi feito. Não repita o pedido.
3

Depois de um timeout, consulte a cobrança

Chame GET /v1/charges/{id}. Se ela estiver refunded, grave o resultado e não envie outro pedido.
O guia de estorno traz uma rotina completa em Node.js.

Erros comuns

Como testar

No sandbox, com a chave sk_test_:
  • CHG-07: estorno total de uma cobrança paga. Resultado esperado: status refunded e webhook charge.refunded.
  • AP-05: estorno de uma cobrança Apple Pay paga, se você usa Apple Pay.
Detalhes e evidências em Roteiro de homologação.

Veja também

Guia de estorno

Prazos, saldo, split e estorno depois do saque.

Consultar cobrança

Confira o status antes e depois do estorno.

Webhooks de cobrança

Payload do evento charge.refunded.

Bloqueio, chargeback e MED

Quando o estorno vem de uma contestação.