Criar um reembolso

curl -X POST "https://api.chargefy.io/v1/refunds" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-8f4c2a" \
  -d '{
    "payment_intent": "pi_eJ7eDFMuARADw4M5",
    "reason": "requested_by_customer"
  }'

{
  "id": "re_oV73wzAJAwJCBjmC",
  "object": "refund",
  "amount": 5000,
  "balance_transaction": null,
  "charge": "ch_xZBMF4kE89iEyFek",
  "created_at": "2026-07-24T18:35:00Z",
  "currency": "brl",
  "customer": "cus_QB1ioGztNSbVU4M6",
  "description": null,
  "destination_details": null,
  "failure_balance_transaction": null,
  "failure_reason": null,
  "instructions_email": null,
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_intent": "pi_eJ7eDFMuARADw4M5",
  "pending_reason": "processing",
  "reason": "requested_by_customer",
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "pending",
  "transfer_reversal": null,
  "updated_at": "2026-07-24T18:35:00Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "Refund amount exceeds refundable amount",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "No such charge",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Charge has no refundable amount remaining",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "refund_in_progress",
    "message": "A refund is already in progress for this charge. Wait for it to reach a final status before creating another.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "refund_period_expired",
    "message": "The refund window for this transaction has expired; it can no longer be refunded.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "partial_refund_not_supported",
    "message": "This transaction does not support partial refunds; refund the full amount.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

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, em centavos.

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.

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:

curl "https://api.chargefy.io/v1/refunds?charge=ch_xZBMF4kE89iEyFek&status=pending" \
  -H "Authorization: Bearer {{API_KEY}}"

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, em centavos. Precisa ser um inteiro positivo e não pode superar o valor disponível da charge.Quando omitido, devolve todo o saldo disponível:

amount_captured − refunds em andamento ou concluídos

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.

Valor	Quando usar
`duplicate`	A mesma compra foi cobrada mais de uma vez.
`fraudulent`	A organização identificou suspeita de fraude e decidiu devolver voluntariamente.
`requested_by_customer`	O comprador solicitou cancelamento, troca ou devolução.

Disputa de cartão é um fluxo separado e não é um motivo de refund.

O que acontece depois da chamada

Etapa	Resultado
1. Resolver a origem	A Chargefy valida a `charge` enviada ou encontra a charge do `payment_intent`.
2. Reservar o valor	O valor fica comprometido com esse refund para impedir devoluções concorrentes acima do capturado.
3. Criar o objeto	Nasce um novo `refund`, normalmente em `pending` ou já no estado retornado pelo processamento.
4. Atualizar a charge	`amount_refunded`, `refunded` e `refunds` passam a refletir a devolução; `charge.status` continua `succeeded`.
5. Registrar a saída	Quando `refund.status = succeeded`, nasce uma transaction negativa com `type: "refund"` e `source` igual ao ID do refund.
6. Vincular o extrato	O `balance_transaction` do refund passa a apontar para esse movimento. Conclusão e movimento são gravados juntos, nunca um sem o outro.

As taxas da venda original não são devolvidas. Por isso a transaction do refund tem fee_amount: 0, enquanto o custo já registrado na transaction original permanece no extrato.

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:

Situação	Resultado
Repetir a mesma request com a mesma `Idempotency-Key`	Recupera o refund já criado. Não cria uma segunda devolução.
Criar outra devolução com outra chave, com uma em aberto	`409` com `code: "refund_in_progress"`. Aguarde a atual chegar ao fim.

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.

curl -X POST "https://api.chargefy.io/v1/refunds" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-8f4c2a" \
  -d '{
    "payment_intent": "pi_eJ7eDFMuARADw4M5",
    "reason": "requested_by_customer"
  }'

(b) Refund parcial pelo Payment Intent

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

curl -X POST "https://api.chargefy.io/v1/refunds" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-7b3d9e" \
  -d '{
    "amount": 5000,
    "payment_intent": "pi_eJ7eDFMuARADw4M5",
    "reason": "requested_by_customer"
  }'

(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 -X POST "https://api.chargefy.io/v1/refunds" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-6a2e8d" \
  -d '{
    "charge": "ch_xZBMF4kE89iEyFek",
    "reason": "duplicate"
  }'

(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 -X POST "https://api.chargefy.io/v1/refunds" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-5c1f7a" \
  -d '{
    "amount": 5000,
    "charge": "ch_xZBMF4kE89iEyFek",
    "metadata": {},
    "reason": "requested_by_customer"
  }'

Resposta

Retorna 200 OK com o objeto refund completo. Quando o processamento recebeu a tentativa mas ainda precisa confirmar ou repetir internamente o resultado, retorna 202 Accepted com o mesmo objeto em status: "pending". O status pode ser provisório: refund.created confirma que o objeto foi criado, mas somente status: "succeeded" confirma que a devolução terminou. 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:

{
  "id": "re_oV73wzAJAwJCBjmC",
  "object": "refund",
  "amount": 5000,
  "balance_transaction": null,
  "charge": "ch_xZBMF4kE89iEyFek",
  "created_at": "2026-07-24T18:35:00Z",
  "currency": "brl",
  "customer": "cus_QB1ioGztNSbVU4M6",
  "description": null,
  "destination_details": null,
  "failure_balance_transaction": null,
  "failure_reason": null,
  "instructions_email": null,
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_intent": "pi_eJ7eDFMuARADw4M5",
  "pending_reason": "processing",
  "reason": "requested_by_customer",
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "pending",
  "transfer_reversal": null,
  "updated_at": "2026-07-24T18:35:00Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "Refund amount exceeds refundable amount",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "No such charge",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Charge has no refundable amount remaining",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "refund_in_progress",
    "message": "A refund is already in progress for this charge. Wait for it to reach a final status before creating another.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "refund_period_expired",
    "message": "The refund window for this transaction has expired; it can no longer be refunded.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "partial_refund_not_supported",
    "message": "This transaction does not support partial refunds; refund the full amount.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

Erros comuns

HTTP	Situação	Como corrigir
`400`	`charge` e `payment_intent` foram enviados juntos ou ambos foram omitidos.	Envie exatamente uma referência.
`400`	`amount` não é inteiro positivo ou supera o valor disponível.	Envie o valor em centavos dentro do saldo reembolsável.
`400`	O Payment Intent está em `requires_capture`.	Cancele a autorização em vez de criar um refund.
`404`	A charge ou o Payment Intent não existe no escopo da organização.	Confira o ID, a organização e o modo da API key.
`409`	A charge não está paga/capturada ou não tem saldo disponível.	Consulte a charge e os refunds já criados.
`409 refund_in_progress`	A charge já tem uma devolução em `pending` ou `requires_action`.	Aguarde a tentativa atual encerrar; liste os refunds da charge para acompanhá-la.
`422`	A charge não pode ser reembolsada automaticamente.	Não repita sem alterar o contexto; trate o caso operacionalmente.
`202`	O refund foi criado, mas o resultado ainda está em confirmação ou aguarda tratamento interno.	Persista o `refund.id`; aguarde `refund.updated` ou consulte o recurso. Não crie outro refund.
`409 refund_period_expired`	O prazo de estorno terminou.	Não repita; trate a devolução por outro fluxo operacional.
`409 charge_already_refunded`	O pagamento já foi estornado.	Consulte os refunds existentes; não crie outra devolução.
`409 partial_refund_not_supported`	A operação aceita apenas estorno total.	Corrija `amount` para o saldo total reembolsável.
`502 refund_state_mismatch`	O estado local e o financeiro não puderam ser conciliados.	Não repita cegamente; envie o `X-Request-Id` ao suporte.

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.

curl -X POST "https://api.chargefy.io/v1/refunds" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-8f4c2a" \
  -d '{
    "payment_intent": "pi_eJ7eDFMuARADw4M5",
    "reason": "requested_by_customer"
  }'

{
  "id": "re_oV73wzAJAwJCBjmC",
  "object": "refund",
  "amount": 5000,
  "balance_transaction": null,
  "charge": "ch_xZBMF4kE89iEyFek",
  "created_at": "2026-07-24T18:35:00Z",
  "currency": "brl",
  "customer": "cus_QB1ioGztNSbVU4M6",
  "description": null,
  "destination_details": null,
  "failure_balance_transaction": null,
  "failure_reason": null,
  "instructions_email": null,
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_intent": "pi_eJ7eDFMuARADw4M5",
  "pending_reason": "processing",
  "reason": "requested_by_customer",
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "pending",
  "transfer_reversal": null,
  "updated_at": "2026-07-24T18:35:00Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "Refund amount exceeds refundable amount",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "No such charge",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Charge has no refundable amount remaining",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "refund_in_progress",
    "message": "A refund is already in progress for this charge. Wait for it to reach a final status before creating another.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "refund_period_expired",
    "message": "The refund window for this transaction has expired; it can no longer be refunded.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "partial_refund_not_supported",
    "message": "This transaction does not support partial refunds; refund the full amount.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Criar um reembolso

Pré-requisitos

Uma devolução em andamento por vez

O que acontece depois da chamada

Formas de criar

(a) Refund total pelo Payment Intent

(b) Refund parcial pelo Payment Intent

(c) Refund total por uma charge específica

(d) Refund parcial por uma charge específica

Resposta

Erros comuns

Acompanhar a conclusão

​Pré-requisitos

​Uma devolução em andamento por vez

​O que acontece depois da chamada

​Formas de criar

​(a) Refund total pelo Payment Intent

​(b) Refund parcial pelo Payment Intent

​(c) Refund total por uma charge específica

​(d) Refund parcial por uma charge específica

​Resposta

​Erros comuns

​Acompanhar a conclusão

Pré-requisitos

Uma devolução em andamento por vez

O que acontece depois da chamada

Formas de criar

(a) Refund total pelo Payment Intent

(b) Refund parcial pelo Payment Intent

(c) Refund total por uma charge específica

(d) Refund parcial por uma charge específica

Resposta

Erros comuns

Acompanhar a conclusão