Como consultar saldos, lançamentos e gerar extratos financeiros
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.
| Tipo | Descrição |
|---|---|
available | Saldo disponível para saque |
reserved | Saldo reservado (aguardando liquidação de recebíveis) |
As carteiras são por moeda. Cada owner (merchant ou plataforma) possui um par de carteiras available + reserved para cada moeda ativa (BRL, USD, EUR). Cada carteira carrega sua própria moeda, e saldos, lançamentos e extratos são sempre de uma única moeda.
curl -X GET "https://api.worldfypayments.com/v1/wallets?wallet_type=available¤cy_code=BRL" \
-H "Authorization: Basic {credentials}"| Parâmetro | Tipo | Descrição |
|---|---|---|
wallet_type | string | available ou reserved |
currency_code | string | Filtra por moeda (ex: BRL, USD, EUR) |
is_active | boolean | Filtra por carteiras ativas/inativas |
curl -X GET https://api.worldfypayments.com/v1/wallets/{id} \
-H "Authorization: Basic {credentials}"{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"owner_type": "merchant",
"owner_id": "m1e2r3c4-h5a6-7890-ntid-000000000001",
"wallet_type": "available",
"currency_id": "c1u2r3r4-...",
"is_active": true,
"balance": "1250000",
"last_entry_at": "2026-02-10T14:30:00.000Z",
"currency": {
"id": "c1u2r3r4-...",
"code": "BRL",
"name": "Real Brasileiro",
"symbol": "R$",
"decimal_places": 2,
"is_active": true
}
}
}O campo balance é uma string que representa o saldo atual em centavos. No exemplo acima, R$ 12.500,00. Os dados da moeda da carteira ficam no objeto aninhado currency.
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.
curl -X GET "https://api.worldfypayments.com/v1/wallets/{id}/entries?direction=credit&page=1&limit=20" \
-H "Authorization: Basic {credentials}"| 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) |
| 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 |
{
"id": "770e8400-e29b-41d4-a716-446655440000",
"wallet_id": "550e8400-e29b-41d4-a716-446655440000",
"amount": "9650",
"direction": "credit",
"balance_after": "1259650",
"reference_type": "receivable_settlement",
"reference_id": "880e8400-e29b-41d4-a716-446655440000",
"counter_entry_id": null,
"description": "Liquidação de recebível",
"metadata": null,
"idempotency_key": "receivable-settlement-880e8400",
"created_at": "2026-02-10T14:30:00.000Z"
}amount e balance_after são retornados como strings em centavos.
O extrato fornece uma visão consolidada dos lançamentos de uma carteira em um período, incluindo os dados da carteira e um resumo financeiro. Como cada carteira é de uma única moeda, o extrato é sempre monomoeda.
curl -X GET "https://api.worldfypayments.com/v1/wallets/{id}/statement?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Basic {credentials}"{
"data": {
"wallet": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"wallet_type": "available",
"balance": "1250000",
"currency": { "code": "BRL", "symbol": "R$", "decimal_places": 2 }
},
"entries": [
{
"id": "770e8400-e29b-41d4-a716-446655440000",
"date": "2026-01-02T10:00:00.000Z",
"description": "Liquidação de recebível",
"reference_type": "receivable_settlement",
"reference_id": "880e8400-e29b-41d4-a716-446655440000",
"direction": "credit",
"amount": "9650",
"balance_after": "509650"
}
],
"period": {
"start": "2026-01-01T03:00:00.000Z",
"end": "2026-02-01T02:59:59.999Z"
},
"summary": {
"total_credits": "850000",
"total_debits": "100000",
"opening_balance": "500000",
"closing_balance": "1250000"
}
}
}| Campo | Descrição |
|---|---|
opening_balance | Saldo no início do período (string, centavos) |
closing_balance | Saldo no fim do período (string, centavos) |
total_credits | Total de entradas no período (string, centavos) |
total_debits | Total de saídas no período (string, centavos) |
Os parâmetros start_date e end_date são obrigatórios para gerar o extrato.