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"
{
"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)
Tipos de Movimentação
| Tipo | Direção | Descrição |
|---|
payment | Entrada | Pagamento recebido de um cliente |
refund | Saída | Reembolso processado para um cliente |
payout | Saída | Saque realizado para conta bancária |
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 |
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"
{
"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.
