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

O saldo total da conta é a soma de available + pending + blocked. Apenas o saldo available pode ser sacado.

​

Consultar Saldo

​

Via SDK

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

curl -X GET https://api.chargefy.io/v1/balance \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"

Resposta:

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

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

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:

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

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

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:

{
  "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

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

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

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