Skip to main content
Um reembolso (refund) devolve dinheiro que já foi capturado em uma charge: ele reverte parte ou todo o valor cobrado e aponta sempre para a charge de origem. É o objeto que responde “essa cobrança foi devolvida, deu certo, e quanto voltou?”.
Refund ≠ cancelamentoCancelar interrompe uma cobrança que ainda não capturou dinheiro (um payment_intent ou uma charge em andamento). Um refund atua sobre valor que já entrou: ele devolve o que foi capturado. Por isso o refund só existe para uma charge succeeded, paga e capturada.

​
Modelo conceitual

Cada refund nasce de uma charge e carrega de volta as referências que aquela charge tinha: o payment_intent que a originou e, quando existem, a invoice, o customer e o payment_method.
ObjetoPapelQuem cria
chargeA cobrança capturada que será revertida.O sistema, ao confirmar o intent.
refundA devolução de parte ou todo o valor da charge.Você (POST /v1/refunds).
Uma mesma charge pode ter vários refunds parciais. O valor disponível para reembolsar é o valor capturado menos os refunds já pending, requires_action ou succeeded.

​
Anatomia do refund

CampoTipoDescrição
amountintegerValor reembolsado, em centavos.
chargestringCharge de origem (ch_*). Sempre presente.
currencystringMoeda em 3 letras minúsculas (brl).
customerstring | nullCustomer relacionado (cus_*).
failure_reasonstring | nullMotivo normalizado da falha quando status = failed; null nos demais estados.
invoicestring | nullInvoice relacionada (inv_*).
payment_intentstring | nullIntent que originou a charge (pi_*).
payment_methodstring | nullMétodo usado na charge (pm_*).
reasonstring | nullMotivo informado na criação; null quando não foi enviado.
statusstringpending, requires_action, succeeded, failed ou canceled.
metadataobjectPares chave→valor livres, controlados por você. {} quando vazio.
O schema público completo, com cada campo retornado, está em Objeto refund.

​
Exemplo reduzido

{
  "id": "re_123",
  "object": "refund",
  "amount": 5000,
  "charge": "ch_456",
  "currency": "brl",
  "payment_intent": "pi_789",
  "reason": "requested_by_customer",
  "status": "succeeded"
}

​
Criar um refund

Refund é uma ação que materializa um recurso próprio: você o cria com POST /v1/refunds apontando para uma charge capturada ou para um payment_intent que já tenha uma charge reembolsável. Sem amount, o refund usa todo o valor ainda disponível da charge resolvida.
CampoTipoRegra
chargestringCharge a reembolsar (ch_*). Envie charge ou payment_intent, não ambos.
payment_intentstringPayment Intent a reembolsar (pi_*). A Chargefy resolve internamente a charge capturada.
amountintegerValor em centavos, inteiro > 0. Omitido = valor disponível inteiro (refund total).
reasonstringMotivo público do refund: duplicate, fraudulent ou requested_by_customer.
metadataobjectPares chave→valor livres para correlacionar com o seu sistema.
curl -X POST https://api.chargefy.io/v1/refunds \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "charge": "ch_456"
  }'
Use o header Idempotency-Key (ou idempotency_key no body) para criar o refund com segurança em caso de retry. Repetir a mesma chave devolve o refund já criado em vez de gerar uma cobrança em duplicidade.
Chargeback/dispute não é reason de refund. Use fraudulent quando você estiver fazendo uma devolução voluntária por fraude; disputa de cartão é outro fluxo financeiro.

​
Quando uma charge é reembolsável

O refund só prossegue se a charge estiver de fato capturada. A charge precisa estar succeeded, paga, capturada e com valor capturado > 0. Fora disso, a criação falha:
SituaçãoHTTPmessage
Charge não encontrada na organização404No such charge.
Charge não está capturada/paga409Charge is not refundable.
Charge sem valor disponível (já totalmente reembolsada)409Charge has no refundable amount remaining.
amount maior que o valor disponível400Refund amount exceeds refundable amount.
amount não inteiro ou ≤ 0400amount must be a positive integer.
Charge não pode ser reembolsada automaticamente422Charge cannot be refunded automatically.
Quando o payment_intent ainda está em requires_capture, ele não tem valor capturado para refund. Cancele o intent com POST /v1/payment-intents/{id}/cancel em vez de criar um refund.
Reembolso é irreversível. Não há endpoint para “desfazer” um refund: uma vez que ele liquida, o dinheiro voltou. Para devolver mais valor da mesma charge, crie um novo refund parcial enquanto houver valor disponível.

​
Ciclo de vida e liquidação

A criação devolve o refund já com o estado retornado pela liquidação — que pode ser imediato ou assíncrono, dependendo do meio. Quando ainda não há confirmação final, o refund nasce pending ou requires_action e migra de estado depois, comunicado por webhook.
StatusSignificado
pendingRefund registrado, aguardando a confirmação da devolução.
requires_actionRefund aguardando ação para continuar.
succeededValor devolvido com sucesso.
failedNão foi possível concluir a devolução. Veja failure_reason.
canceledA reversão foi cancelada antes de concluir.
Como a liquidação pode ser assíncrona, não faça polling: trate o status retornado na criação como provisório e reaja aos webhooks refund.created, refund.updated e refund.failed para acompanhar a transição até succeeded, failed ou canceled.

​
Consultar e listar

Refund é recurso financeiro auditável: você cria, consulta, lista e atualiza apenas a metadata.
OperaçãoVerboURL
Criar refundPOST/v1/refunds
Consultar um refundGET/v1/refunds/{id}
Listar refundsGET/v1/refunds
Atualizar metadataPOST/v1/refunds/{id}
A listagem é por cursor (starting_after, ending_before, limit de 1 a 100), em ordem decrescente de criação. Filtros disponíveis:
FiltroCasa com
chargeRefunds de uma charge (ch_*).
customerRefunds de um customer (cus_*).
invoiceRefunds de uma invoice (inv_*).
payment_intentRefunds de um intent (pi_*).
statuspending, requires_action, succeeded, failed ou canceled.
created[gte], created[gt], created[lte], created[lt]Data de criação por ISO-8601 ou Unix seconds.
curl -G https://api.chargefy.io/v1/refunds \
  -H "Authorization: Bearer {{API_KEY}}" \
  -d charge=ch_456 \
  -d limit=10

​
Webhooks

Mudanças no refund disparam eventos cujo data.object carrega o objeto refund completo, no mesmo shape do GET /v1/refunds/{id}.
EventoQuando dispara
refund.createdO refund foi criado.
refund.failedO refund chegou ao estado failed.
refund.updatedAlgum campo público do refund mudou (tipicamente status).
charge.refundedA charge recebeu um refund parcial ou total.
O evento refund.updated também traz data.previous_attributes com os valores anteriores dos campos alterados — por exemplo, status saindo de pending para succeeded.
Reaja aos webhooks em vez de fazer polling. Ao receber refund.created, refund.updated ou refund.failed, consulte o refund pelo id do payload para conciliar com o seu pedido — metadata é o caminho para correlacionar com o seu sistema.

​
Próximos passos

Objeto refund

Schema público completo e cada campo retornado.

Criar refund (API)

Contrato do POST /v1/refunds, com amount, reason e idempotência.

Charges

A cobrança capturada que um refund reverte.

Payment Intents

O processo que materializa a charge a ser reembolsada.