Reembolsos
Criar um reembolso
Cria um refund total ou parcial para uma charge capturada.
Cria um novo
refund para devolver parte ou todo o valor capturado de uma
charge.
Envie exatamente um destes campos:
payment_intent: a Chargefy localiza a charge capturada correspondente;charge: você escolhe diretamente qual tentativa deve ser reembolsada.
amount, o endpoint devolve todo o valor ainda disponível. Com amount,
cria um refund parcial nesse valor, na menor unidade da moeda (centavos em brl).
O refund não muda o Payment Intent de
succeeded para outro status. Ele cria
um objeto com ciclo próprio. Quando a devolução termina em succeeded, o
extrato recebe uma nova transaction negativa.Pré-requisitos
A charge resolvida precisa:- ter
status: "succeeded"; - estar paga e capturada;
- ter
amount_captured > 0; - ainda ter valor disponível para devolver;
- não ter outra devolução em andamento;
- não ter disputa aberta nem perdida.
Uma devolução em andamento por vez
Cada charge aceita apenas um refund não concluído por vez. Enquanto existir um refund empending ou requires_action para aquela charge, uma nova criação
responde 409 com code: "refund_in_progress".
Isso garante que a confirmação da devolução seja atribuída à tentativa certa:
com duas devoluções parciais abertas ao mesmo tempo, a confirmação que chega
depois seria indistinguível entre elas. Assim que a tentativa atual termina em
succeeded, failed ou canceled, a charge volta a aceitar um novo refund
parcial sobre o saldo restante.
Para localizar a devolução em andamento, liste os refunds da charge:
Venda em disputa
Enquanto a disputa da charge espera resposta (needs_response) ou está em
análise (under_review), e depois de perdida (lost), a criação responde
409 com code: "charge_disputed". Nessas fases o valor contestado está
retido ou já voltou ao comprador pela própria disputa, e um refund o devolveria
pela segunda vez. Para devolver o dinheiro a um comprador que contestou, aceite
a disputa com POST /v1/disputes/{id}/close.
Consulta prévia (warning_needs_response, warning_under_review,
warning_closed) e disputa ganha (won) aceitam refund. O campo
is_charge_refundable da disputa diz isso de
antemão.
Devolução automática por meio de pagamento
Nesses casos nada foi devolvido. Se quiser devolver, faça o estorno do
pagamento direto ao comprador, fora da Chargefy.
Um comprador que paga a mesma compra duas vezes (por exemplo, o Pix e depois o
boleto antigo) fica com as duas charges em
succeeded no mesmo Payment Intent.
Nada é devolvido por conta própria: para devolver a segunda, crie o refund com
charge e reason: "duplicate".
Um Payment Intent em requires_capture só foi autorizado. Cancele-o com
POST /v1/payment-intents/{id}/cancel
em vez de criar um refund.
Valor a devolver, na menor unidade da moeda (centavos em O teto depende da moeda. Em
brl). Precisa ser um inteiro positivo e não pode
superar o valor disponível da charge.Quando omitido, devolve todo o saldo disponível:brl, o máximo é 999999999 na menor unidade. Acima do teto, a API retorna 400 amount_too_large com param e maximum_amount. Quando o valor já está associado a uma moeda, a resposta inclui currency.ID do Payment Intent (
pi_*). A Chargefy localiza a charge capturada mais
recente que ainda pode ser reembolsada.Envie payment_intent ou charge, nunca os dois.Motivo da devolução. Padrão:
null.Disputa de cartão é um fluxo separado e não é um motivo de refund.
O que acontece depois da chamada
O processamento distribui a devolução entre os participantes. A transaction do
refund tem
fee_amount: 0 e amount igual ao valor efetivamente retirado da
conta daquele participante, que pode diferir do valor devolvido ao comprador.
A conclusão confere os valores de cada conta antes de registrar a saída.
Quando todas as taxas são devolvidas, o reembolso total fecha o extrato em zero;
qualquer custo de processamento não devolvido permanece com quem vendeu.
Formas de criar
Use umaIdempotency-Key única por devolução lógica. Se a resposta não chegar,
consulte o refund associado antes de qualquer nova operação.
A chave e o limite de uma devolução em andamento resolvem problemas diferentes,
e os dois continuam valendo:
Nunca use outra chave para contornar um estado
pending: isso não acelera a
confirmação e a criação será recusada.
(a) Refund total pelo Payment Intent
Use quando o seu sistema acompanha o pagamento pelopi_*. A Chargefy encontra
a charge capturada, e a ausência de amount devolve todo o saldo disponível.
(b) Refund parcial pelo Payment Intent
Envieamount quando apenas parte do valor deve voltar ao comprador.
cURL
(c) Refund total por uma charge específica
Usecharge quando você precisa escolher a tentativa exata, por exemplo ao
conciliar uma cobrança duplicada.
cURL
(d) Refund parcial por uma charge específica
Esta forma combina a escolha da tentativa com um valor parcial.metadata
pode guardar a referência livre do seu pedido ou atendimento.
cURL
Resposta
Retorna200 OK com o objeto refund completo. Quando a resposta do
processamento não confirma o resultado (por exemplo, por tempo esgotado),
retorna 202 Accepted com o mesmo objeto em status: "pending". A Chargefy
confere o resultado em alguns minutos e encerra o refund: succeeded se a
devolução aconteceu, failed se não aconteceu. Nada é reenviado por conta
própria; depois de um failed, crie um novo refund se ainda quiser devolver.
refund.created confirma que o objeto foi criado, mas somente
status: "succeeded" confirma que a devolução terminou.
Venda que ainda não pode ser estornada
Logo depois do pagamento, a venda pode ainda não estar liberada para estorno na rede do cartão. Nesse caso a criação responde503 com
code: "try_again_later" e a tentativa termina em failed (com
refund.failed): nada foi devolvido e nada fica pendente. Crie o refund de
novo em algumas horas, com uma nova Idempotency-Key. A Chargefy não repete o
pedido por você.
Em status: "succeeded", o campo balance_transaction já vem preenchido com o
movimento negativo do extrato. Um refund concluído nunca é retornado sem esse
vínculo.
Neste exemplo, a devolução ainda está sendo processada:
Erros comuns
Acompanhar a conclusão
Persista orefund.id e trate os eventos:
refund.createdpara registrar o estado inicial;refund.updatedpara acompanhar mudanças, inclusivepending→succeeded;refund.failedpara tratar uma falha;charge.refundedpara reconciliar a charge;transaction.createdpara registrar o movimento negativo do extrato.
GET /v1/refunds/{id}. Para a integração normal,
prefira webhooks a polling.
Veja Objeto refund para o significado de cada
campo e Reembolsos para o modelo conceitual completo.

