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 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.
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 8,74 de taxa:
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. Como a taxa
da venda original não é devolvida, ela continua sendo um custo de R$ 8,74 nesse
exemplo.
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:
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 em centavos.
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.