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

# Saldo e Movimentações

> Consulte o saldo disponível, saldo a liberar e acompanhe todas as movimentações financeiras da sua conta.

## Visão Geral

A Chargefy oferece controle completo sobre o saldo da sua conta. O saldo é dividido em duas categorias: **disponível** (pronto para saque) e **a liberar** (aguardando prazo de liquidação do método de pagamento).

## Tipos de Saldo

| Tipo | Descrição |
| - | - |
| `available` | Saldo disponível para saque imediato |
| `pending` | Saldo a liberar — aguardando prazo de liquidação |
| `blocked` | Saldo bloqueado por disputa, chargeback ou análise |

> [!NOTE]
>
> O saldo total da conta é a soma de `available + pending + blocked`. Apenas o saldo `available` pode ser sacado.

## Consultar Saldo

### Via SDK

```typescript theme={null}
import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const balance = await chargefy.balance.get();

console.log(`Disponível: R$ ${(balance.available / 100).toFixed(2)}`);
// "Disponível: R$ 1.250,00"

console.log(`A liberar: R$ ${(balance.pending / 100).toFixed(2)}`);
// "A liberar: R$ 3.400,00"

console.log(`Bloqueado: R$ ${(balance.blocked / 100).toFixed(2)}`);
// "Bloqueado: R$ 0,00"
```

### Via API

```bash theme={null}
curl -X GET https://api.chargefy.io/v1/balance \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"
```

**Resposta:**

```json theme={null}
{
  "available": 125000,
  "pending": 340000,
  "blocked": 0,
  "currency": "BRL",
  "updated_at": "2026-03-12T08:00:00Z"
}
```

> [!NOTE]
>
> Todos os valores monetários são representados em **centavos**. R\$ 1.250,00 = `125000`.

## Timeline de Liberação

O prazo para que o saldo passe de `pending` para `available` depende do método de pagamento utilizado na transação:

| Método de Pagamento | Prazo de Liberação | Descrição |
| - | - | - |
| **PIX** | Imediato (D+0) | O valor é liberado assim que o pagamento é confirmado |
| **Boleto Bancário** | D+2 | Liberado 2 dias úteis após a compensação do boleto |
| **Cartão de Crédito** | D+30 | Liberado 30 dias após a captura da transação |
| **Cartão de Débito** | D+1 | Liberado 1 dia útil após a transação |

> [!WARNING]
>
> Os prazos acima são contados em **dias úteis**. Finais de semana e feriados nacionais não são contabilizados.

## Consultar Saldo Futuro

Você pode consultar a projeção do saldo que será liberado nos próximos dias:

```typescript theme={null}
const forecast = await chargefy.balance.forecast();

for (const entry of forecast.items) {
  const date = new Date(entry.date).toLocaleDateString("pt-BR");
  const amount = (entry.amount / 100).toFixed(2);
  console.log(`${date}: R$ ${amount}`);
}
// "13/03/2026: R$ 500,00"
// "14/03/2026: R$ 1.200,00"
// "15/03/2026: R$ 0,00"
// "11/04/2026: R$ 1.700,00"  (cartão de crédito D+30)
```

## Movimentações (Extrato)

O extrato contém todas as movimentações financeiras da conta, incluindo entradas, saídas e taxas.

### Tipos de Movimentação

| Tipo | Direção | Descrição |
| - | - | - |
| `payment` | Entrada | Pagamento recebido de um cliente |
| `refund` | Saída | Reembolso processado para um cliente |
| `fee` | Saída | Taxa de processamento da Chargefy |
| `chargeback` | Saída | Estorno por disputa do portador do cartão |
| `adjustment` | Entrada/Saída | Ajuste manual realizado pela equipe |

### Consultar Extrato via SDK

```typescript theme={null}
import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

// Listar movimentações com filtros
const transactions = await chargefy.balance.listTransactions({
  start_date: "2026-03-01",
  end_date: "2026-03-12",
  type: "payment",       // Filtrar por tipo (opcional)
  page: 1,
  limit: 20,
});

for (const tx of transactions.items) {
  const amount = (tx.amount / 100).toFixed(2);
  const date = new Date(tx.created_at).toLocaleDateString("pt-BR");
  console.log(`[${tx.type}] R$ ${amount} - ${date} - ${tx.description}`);
}
// "[payment] R$ 150,00 - 10/03/2026 - Pagamento PIX - Venda #sale_abc123"
// "[payment] R$ 299,90 - 11/03/2026 - Pagamento Cartão - Venda #sale_def456"
```

### Via API

```bash theme={null}
curl -X GET "https://api.chargefy.io/v1/balance/transactions?start_date=2026-03-01&end_date=2026-03-12&limit=20" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"
```

**Resposta:**

```json theme={null}
{
  "items": [
    {
      "id": "txn_abc123",
      "type": "payment",
      "amount": 15000,
      "net_amount": 14250,
      "fee": 750,
      "currency": "BRL",
      "description": "Pagamento PIX - Venda #sale_abc123",
      "sale_id": "sale_abc123",
      "status": "completed",
      "created_at": "2026-03-10T14:30:00Z"
    },
    {
      "id": "txn_def456",
      "type": "fee",
      "amount": -750,
      "currency": "BRL",
      "description": "Taxa de processamento - PIX",
      "related_transaction_id": "txn_abc123",
      "status": "completed",
      "created_at": "2026-03-10T14:30:00Z"
    }
  ],
  "pagination": {
    "total_count": 47,
    "page": 1,
    "limit": 20
  }
}
```

## Detalhes de uma Movimentação

```typescript theme={null}
const transaction = await chargefy.balance.getTransaction("txn_abc123");

console.log(transaction.id);          // "txn_abc123"
console.log(transaction.type);        // "payment"
console.log(transaction.amount);      // 15000 (R$ 150,00)
console.log(transaction.net_amount);  // 14250 (R$ 142,50)
console.log(transaction.fee);         // 750 (R$ 7,50)
console.log(transaction.sale_id);     // "sale_abc123"
```

## Taxas de Processamento

As taxas são descontadas automaticamente de cada transação:

| Método | Taxa |
| - | - |
| PIX | 0,99% por transação |
| Cartão de Crédito | 4,49% + R\$ 0,39 por transação |
| Cartão de Débito | 2,49% + R\$ 0,39 por transação |
| Boleto Bancário | R\$ 3,49 por boleto compensado |

> [!NOTE]
>
> As taxas podem variar conforme o plano contratado. Consulte a seção **Configurações > Plano** no dashboard para verificar as taxas aplicadas à sua conta.

## Dashboard

No painel da Chargefy, a seção **Finanças > Saldo** exibe:

* **Resumo de saldo**: Cards com saldo disponível, a liberar e bloqueado
* **Gráfico de evolução**: Gráfico de linha mostrando a evolução do saldo nos últimos 30 dias
* **Projeção de liberação**: Calendário com os valores que serão liberados nos próximos dias
* **Extrato completo**: Tabela com todas as movimentações, com filtros por tipo, data e valor
* **Exportação**: Botão para exportar o extrato em CSV ou PDF para conciliação contábil

> [!TIP]
>
> Use o filtro de datas no extrato para gerar relatórios mensais e facilitar a conciliação com sua contabilidade.


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