Financeiro
Carteiras e Extratos
Como consultar saldos, lançamentos e gerar extratos financeiros
O que são Carteiras?
Carteiras são contas financeiras internas que registram todos os movimentos de dinheiro. Cada merchant possui carteiras que controlam saldo disponível e saldo reservado.
Tipos de Carteira
| Tipo | Descrição |
|---|---|
available | Saldo disponível para saque |
reserved | Saldo reservado (aguardando liquidação de recebíveis) |
Consultando Carteiras
Listar carteiras
curl -X GET "https://api.payhubrasil.com.br/v1/wallets?wallet_type=available" \
-H "Authorization: Basic {credentials}"Buscar carteira com saldo
curl -X GET https://api.payhubrasil.com.br/v1/wallets/{id} \
-H "Authorization: Basic {credentials}"{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"wallet_type": "available",
"currency_code": "BRL",
"balance": 1250000,
"is_active": true
}
}O campo balance representa o saldo atual em centavos. No exemplo acima, R$ 12.500,00.
Lançamentos
Lançamentos são registros individuais de entrada (crédito) ou saída (débito) em uma carteira. Cada transação que movimenta dinheiro gera um lançamento.
Listando lançamentos
curl -X GET "https://api.payhubrasil.com.br/v1/wallets/{id}/entries?direction=credit&page=1&limit=20" \
-H "Authorization: Basic {credentials}"Filtros disponíveis
| Parâmetro | Tipo | Descrição |
|---|---|---|
reference_type | string | Tipo de operação que gerou o lançamento |
direction | string | credit (entrada) ou debit (saída) |
start_date | string | Data inicial (ISO 8601) |
end_date | string | Data final (ISO 8601) |
Tipos de Referência
| Tipo | Direção | Descrição |
|---|---|---|
charge | crédito | Cobrança capturada |
refund | débito | Estorno de cobrança |
chargeback | débito | Contestação de pagamento |
chargeback_reversal | crédito | Reversão de contestação |
withdrawal | débito | Saque realizado |
fee | débito | Taxa cobrada |
adjustment | ambos | Ajuste manual |
transfer | ambos | Transferência entre carteiras |
receivable_settlement | crédito | Liquidação de recebível |
anticipation | crédito | Antecipação de recebível |
anticipation_fee | débito | Taxa de antecipação |
reserve_release | crédito | Liberação de saldo reservado |
Resposta de um lançamento
{
"id": "770e8400-e29b-41d4-a716-446655440000",
"wallet_id": "550e8400-e29b-41d4-a716-446655440000",
"direction": "credit",
"amount": 9650,
"balance_after": 1259650,
"reference_type": "receivable_settlement",
"reference_id": "880e8400-e29b-41d4-a716-446655440000",
"description": "Liquidação de recebível"
Extratos
O extrato fornece uma visão consolidada dos lançamentos em um período, incluindo um resumo financeiro.
Gerando um extrato
curl -X GET "https://api.payhubrasil.com.br/v1/wallets/{id}/statement?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Basic {credentials}"Resposta
{
"data": {
"summary": {
"opening_balance": 500000,
"closing_balance": 1250000,
"total_credits": 850000,
"total_debits": 100000
},
"entries": [
{
"direction": "credit",
"amount": 9650,
Campos do Resumo
| Campo | Descrição |
|---|---|
opening_balance | Saldo no início do período (centavos) |
closing_balance | Saldo no fim do período (centavos) |
total_credits | Total de entradas no período (centavos) |
total_debits | Total de saídas no período (centavos) |
Os parâmetros start_date e end_date são obrigatórios para gerar o extrato.