Reembolsos

Processe reembolsos totais ou parciais para transações via PIX, Cartão de Crédito e Boleto.

​

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ção	Descrição
Status succeeded	A transação deve ter sido concluída com sucesso
Prazo de 30 dias	Reembolsos só podem ser feitos dentro de 30 dias da transação
Valor disponível	O valor solicitado não pode exceder o valor reembolsável
Não é reembolso	Nã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étodo	Prazo Estimado
PIX	Instantâneo a 1 dia útil
Cartão de Crédito	5 a 10 dias úteis (depende da bandeira e banco emissor)
Boleto	5 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

Status	Descrição
pending	Reembolso solicitado, aguardando processamento
succeeded	Reembolso 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)}`);
}

Campo	Descrição
can_refund	Se a transação pode ser reembolsada
refunded_amount	Total já reembolsado (em centavos)
amount	Valor original da transação (em centavos)

​

Webhooks

Eventos disparados para reembolsos:

Evento	Descrição
refund.created	Reembolso criado
refund.updated	Status do reembolso atualizado

​

Escopos de API

Escopo	Permissão
sales:read	Visualizar transações e reembolsos
sales:write	Processar reembolsos