> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```typescript theme={null}
const refund = await chargefy.sales.refund(saleId);
```

### Reembolso Parcial

Devolve apenas parte do valor:

```typescript theme={null}
const refund = await chargefy.sales.refund(saleId, {
  amount: 5000,  // R$ 50,00 (em centavos)
  reason: "Produto com defeito parcial"
});
```

> [!NOTE]
>
> 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) |

> [!NOTE]
>
> 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:

```typescript theme={null}
// 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:

```json theme={null}
{
  "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"
}
```

> [!NOTE]
>
> 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:

```typescript theme={null}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.