O que é o ledger
O ledger (livro-razão) da ClearPago registra todos os movimentos financeiros confirmados da sua conta. Cada operação Pix que alcança um estado terminal de sucesso gera um lançamento com tipo, valor em centavos, referência à transação de origem e timestamp.
O ledger é a fonte primária para:
- Cálculo de saldo disponível.
- Reconciliação financeira com o seu ERP ou planilha.
- Auditoria de movimentações por período.
- Suporte a devoluções (verificação do teto disponível).
Quando lançamentos são criados
| Operação | Evento que dispara | Tipo de lançamento |
|---|
| Cash-in pago | Cash-in atinge PAID | Crédito |
| Cash-out confirmado | Cash-out atinge CONFIRMED | Débito |
| Refund-in confirmado | Refund-in atinge CONFIRMED | Débito |
| Cash-out revertido | Cash-out atinge REVERSED | Crédito |
Operações em estados não terminais (PENDING, DISPATCHED, PROVIDER_RESULT_UNKNOWN) ainda não geram lançamentos. O ledger só reflete resultados definitivos.
Consultar o ledger
Listar lançamentos
# Todos os créditos de abril
curl "https://api.clearpago.com.br/api/pix/ledger?operation=credit&start_date=2026-04-01&end_date=2026-04-30" \
-H "Authorization: Bearer <seu_api_token>"
# Todos os débitos, paginação por cursor
curl "https://api.clearpago.com.br/api/pix/ledger?operation=debit&limit=100&cursor=<cursor>" \
-H "Authorization: Bearer <seu_api_token>"
Detalhe de uma entrada
curl "https://api.clearpago.com.br/api/pix/ledger/e5f6a7b8-c9d0-1234-efab-345678901234" \
-H "Authorization: Bearer <seu_api_token>"
Parâmetros de consulta
| Parâmetro | Tipo | Descrição |
|---|
operation | string | credit ou debit |
entry_type | string | Ex.: pix_cash_in_credit, pix_cash_out_debit, pix_cash_in_reversal_debit, pix_cash_out_reversal_credit |
start_date | YYYY-MM-DD | Data inicial inclusiva |
end_date | YYYY-MM-DD | Data final inclusiva |
limit | integer | Tamanho da página (máx. 100) |
cursor | string | Paginação por cursor (preferida para grandes volumes) |
Como interpretar uma entrada
{
"id": "e5f6a7b8-c9d0-1234-efab-345678901234",
"operation": "credit",
"entry_type": "pix_cash_in_credit",
"amount_cents": 15075,
"created_at": "2026-04-01T12:10:00.000Z"
}
| Campo | Interpretação |
|---|
operation: credit | Entrada de valor na conta (recebimento ou reversão de envio). |
operation: debit | Saída de valor da conta (envio ou devolução de recebimento). |
amount_cents: 15075 | R$ 150,75 em centavos. |
entry_type | Tipo específico do lançamento. |
- Use
entry_type para identificar o tipo de operação.
TODO: campo de referência ao cash-in/cash-out id na entrada do ledger — confirmar se existe campo transaction_id ou resource_id na resposta.- Compare
amount_cents com value_cents dos webhooks recebidos.
- Caso encontre divergência, use
GET /api/pix/cash-in/{id} ou GET /api/pix/cash-out/{id} para consultar o estado atual.
Saldo disponível
O saldo disponível é a diferença acumulada entre créditos e débitos no ledger. A plataforma é a fonte autoritativa.
TODO: endpoint de saldo consolidado (GET /balance ou similar) — verificar existência com a equipe.
Boas práticas de fechamento
- Exporte o ledger por período fechado (ex.: por dia) usando
start_date e end_date.
- Use paginação por cursor para volumes grandes.
- Não modifique entradas do ledger no seu sistema — elas são imutáveis.
- Reconcilie diariamente com seu sistema financeiro interno para identificar divergências cedo.
Referências
