Pular para o conteúdo principal
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.
Sem 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 em pending 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.
integer
Valor a devolver, na menor unidade da moeda (centavos 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:
O teto depende da moeda. Em 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.
string
ID da charge que será reembolsada (ch_*). Envie charge ou payment_intent, nunca os dois.
object
Pares chave-valor livres para correlacionar o refund com o seu sistema. Padrão: {}.
string
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.
string
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 uma Idempotency-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 pelo pi_*. A Chargefy encontra a charge capturada, e a ausência de amount devolve todo o saldo disponível.

(b) Refund parcial pelo Payment Intent

Envie amount quando apenas parte do valor deve voltar ao comprador.
cURL

(c) Refund total por uma charge específica

Use charge 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

Retorna 200 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 responde 503 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 o refund.id e trate os eventos:
  • refund.created para registrar o estado inicial;
  • refund.updated para acompanhar mudanças, inclusive pending → succeeded;
  • refund.failed para tratar uma falha;
  • charge.refunded para reconciliar a charge;
  • transaction.created para registrar o movimento negativo do extrato.
Também é possível consultar 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.