refund) devolve parte ou todo o valor de uma cobrança já
capturada. Ele é um objeto novo, ligado à charge de
origem, com valor, motivo e ciclo de vida próprios.
O reembolso não apaga nem desfaz o histórico do pagamento. A cobrança
aconteceu e continua registrada; o refund registra o fato seguinte: o dinheiro
foi devolvido.
Refund não é cancelamentoCancele quando o dinheiro ainda não foi capturado. Crie um refund quando a
charge já foi paga e capturada. Um Payment Intent em
requires_capture, por
exemplo, deve ser cancelado — ainda não há valor capturado para devolver.O que muda em cada objeto
Esta é a forma mais segura de entender o fluxo:Reembolso parcial e total na charge
A charge mantém o histórico agregado dos seus refunds:
Uma mesma charge pode ter vários refunds parciais, um de cada vez. Cada
devolução é um objeto independente; devolver R$ 50,00 e depois R$ 100,00 cria
dois refunds, não uma edição do primeiro.
Enquanto uma devolução ainda não terminou, a charge não aceita outra: a criação
responde
409 com code: "refund_in_progress". É isso que garante que a
confirmação de cada estorno seja atribuída à tentativa que a originou. Quando a
tentativa atual chega a succeeded, failed ou canceled, a próxima pode ser
criada sobre o saldo restante.
Uma charge com disputa aberta ou perdida também
não aceita refund: a criação responde 409 com code: "charge_disputed".
Nessas fases o valor contestado está retido ou já voltou ao comprador pela
disputa, e um refund o devolveria pela segunda vez.
O valor ainda disponível é:
failed ou canceled deixam de comprometer esse valor.
Como o reembolso aparece no extrato
O extrato é aditivo: cada movimento de dinheiro cria umatransaction. Entradas são positivas e
saídas são negativas, por isso o saldo pode ser calculado pela soma dos
lançamentos sem apagar ou reescrever o passado.
Considere uma venda de R$ 399,00 com R$ 8,74 de taxa, em que as taxas
são devolvidas integralmente:
O lançamento da venda continua com os valores originais. O refund cria o
lançamento de saída, com
source apontando para o re_* que o causou. O
lançamento original pode passar a status: "refunded" como uma anotação de
estado, mas amount, fee_amount e net_amount não são reescritos. O
lançamento de saída usa o valor efetivamente devolvido por cada participante.
Quando as taxas são devolvidas integralmente, uma venda totalmente reembolsada
fecha em zero, como os R$ 390,26 desse exemplo. Qualquer custo de processamento
não devolvido permanece com a organização que vendeu.
No objeto refund, balance_transaction aponta diretamente para esse novo
lançamento txn_* sempre que status é succeeded — a conclusão da devolução
e o movimento do extrato são gravados na mesma operação, então um nunca existe
sem o outro. Também é possível chegar ao movimento pelo refund que o causou:
Reembolso parcial no extrato
Um refund parcial distribui a devolução entre os participantes e confirma os valores efetivamente retirados, incluindo os arredondamentos. Numa venda de R$ 200,00 com R$ 5,98 de taxa devolvida proporcionalmente, um refund de R$ 100,00 tira do seu saldo metade do líquido que a venda tinha creditado:
O
amount do refund continua sendo R$ 100,00, o que o comprador recebe. O
movimento do extrato chega pelo webhook transaction.created, com source
apontando para o refund e status: "paid" desde o nascimento, porque o débito
acontece na conclusão da devolução:
-9701 de novo e a soma dos dois zera o líquido da venda, sem
centavo sobrando de arredondamento.
Anatomia do refund
Os campos centrais respondem a quatro perguntas:
Outros campos ajudam na conciliação:
Veja todos os campos em Objeto refund.
Criar um refund
UsePOST /v1/refunds com exatamente uma referência:
payment_intent: a Chargefy encontra a charge capturada correspondente;charge: você escolhe diretamente qual tentativa será reembolsada.
amount é opcional:
- sem
amount, devolve todo o valor ainda disponível; - com
amount, cria um refund parcial nesse valor, sempre na menor unidade da moeda (centavos embrl).
Ciclo de vida
A resposta doPOST /v1/refunds pode ser final ou provisória. O refund tem seu
próprio status:
Somente
succeeded confirma a devolução. refund.created confirma a criação do
objeto, não necessariamente a conclusão financeira.
Webhooks
Use webhooks para acompanhar mudanças sem fazer polling:
O
data.object dos eventos refund.* tem o mesmo formato retornado por
GET /v1/refunds/{id}.
Operações disponíveis
Refund é um recurso financeiro auditável. Você não remove nem altera seus valores depois da criação; apenas ametadata pode ser atualizada.
Próximos passos
Objeto refund
Campos, estados e referências do objeto completo.
Criar um refund
Payloads de criação, idempotência, resposta e erros.
Transactions
Como entradas, taxas e refunds aparecem no extrato.
Devolver um pagamento
Guia de implementação passo a passo.

