Skip to main content

​
Visão Geral

A Chargefy permite processar reembolsos para transações já concluídas. Os reembolsos são processados automaticamente, garantindo que o valor seja devolvido ao comprador pelo mesmo método de pagamento utilizado na compra.

​
Tipos de Reembolso

​
Reembolso Total

Devolve o valor integral da transação: 
const refund = await chargefy.sales.refund(saleId);

​
Reembolso Parcial

Devolve apenas parte do valor: 
const refund = await chargefy.sales.refund(saleId, {
  amount: 5000,  // R$ 50,00 (em centavos)
  reason: "Produto com defeito parcial"
});
O valor de reembolso parcial não pode exceder o valor reembolsável (valor original menos reembolsos já processados).

​
Regras de Reembolso

Para que uma transação seja elegível a reembolso, ela precisa atender a todas as condições:
CondiçãoDescrição
Status succeededA transação deve ter sido concluída com sucesso
Prazo de 30 diasReembolsos só podem ser feitos dentro de 30 dias da transação
Valor disponívelO valor solicitado não pode exceder o valor reembolsável
Não é reembolsoNão é possível reembolsar uma transação que já é um reembolso

​
Fluxo de Processamento

1

Solicitação

Você solicita o reembolso via API informando o ID da venda e, opcionalmente, o valor e motivo.
2

Validação

A Chargefy valida a elegibilidade: status da transação, prazo, valor disponível.
3

Processamento

A Chargefy processa a requisição de void/cancelamento junto ao processador de pagamentos.
4

Atualização

O status da venda original é atualizado para refunded (total) ou partially_refunded (parcial).
5

Registro

Um registro de reembolso é criado com os detalhes da operação.

​
Prazos por Método de Pagamento

O tempo para o cliente receber o reembolso varia conforme o método de pagamento:
MétodoPrazo Estimado
PIXInstantâneo a 1 dia útil
Cartão de Crédito5 a 10 dias úteis (depende da bandeira e banco emissor)
Boleto5 a 15 dias úteis (depósito em conta)
Para reembolsos de Boleto, o valor é devolvido via transferência bancária para a conta do comprador. É necessário que a Chargefy tenha os dados bancários do comprador.

​
Reembolsos Múltiplos

Uma mesma transação pode ter múltiplos reembolsos parciais, desde que o total não exceda o valor original: 
// Transação original: R$ 100,00

// Primeiro reembolso parcial: R$ 30,00
await chargefy.sales.refund(saleId, { amount: 3000 });
// Valor reembolsável restante: R$ 70,00

// Segundo reembolso parcial: R$ 20,00
await chargefy.sales.refund(saleId, { amount: 2000 });
// Valor reembolsável restante: R$ 50,00

// Terceiro reembolso: R$ 50,00 (completa o reembolso total)
await chargefy.sales.refund(saleId, { amount: 5000 });
// Status atualizado para "refunded"

​
Status do Reembolso

StatusDescrição
pendingReembolso solicitado, aguardando processamento
succeededReembolso processado com sucesso

​
Dados do Reembolso

Cada reembolso retorna os seguintes dados: 
{
  "id": "sale_xxx",
  "is_refund": true,
  "refund_parent_id": "sale_original_xxx",
  "amount": -5000,
  "status": "succeeded",
  "payment_method": "credit_card",
  "created_at": "2026-03-12T10:30:00Z"
}
O amount de um reembolso é sempre negativo, representando a saída de valor. O refund_parent_id referencia a transação original.

​
Verificar Elegibilidade

Antes de processar um reembolso, verifique se a transação é elegível: 
const sale = await chargefy.sales.get(saleId);

if (sale.can_refund) {
  const refundable = sale.amount - sale.refunded_amount;
  console.log(`Valor reembolsável: R$ ${(refundable / 100).toFixed(2)}`);
}
CampoDescrição
can_refundSe a transação pode ser reembolsada
refunded_amountTotal já reembolsado (em centavos)
amountValor original da transação (em centavos)

​
Webhooks

Eventos disparados para reembolsos:
EventoDescrição
refund.createdReembolso criado
refund.updatedStatus do reembolso atualizado

​
Escopos de API

EscopoPermissão
sales:readVisualizar transações e reembolsos
sales:writeProcessar reembolsos