Consulta de Saldo
Nesta seção, você aprenderá como consultar os saldos da sua conta PixToPay, incluindo saldos atuais e histórico.
Endpoint Disponível
- Produção:
https://api.pixtopay.com.br/v2/balance
⚠️ Atenção: Este endpoint está disponível apenas em produção.
Consultar saldos atuais
Consulte os saldos atuais da sua conta, divididos por tipo e instituição bancária.
Route
GET /v2/balance
Headers
{
"Authorization": "YOUR_API_KEY"
}Exemplo de requisição:
curl --location 'https://api.pixtopay.com.br/v2/balance' \
--header 'Authorization: API_KEY'Resposta 200 - Sucesso:
{
"transactional": {
"balance": 2222222.21,
"balances": [
{
"bank": "STARKBANK",
"amount": 1234567.89
},
{
"bank": "GENIAL",
"amount": 0
},
{
"bank": "EFIPAY",
"amount": 987654.32
}
]
},
"operational": {
"balance": 2222222.21,
"balances": [
{
"bank": "STARKBANK",
"amount": 1234567.89
},
{
"bank": "GENIAL",
"amount": 0
},
{
"bank": "EFIPAY",
"amount": 987654.32
}
]
}
}Campos da Resposta
| Parâmetro | Tipo | Descrição |
|---|---|---|
transactional | object | Saldo transacional (disponível para transações) |
transactional.balance | number | Saldo total transacional em reais |
transactional.balances | array | Detalhamento por instituição bancária |
transactional.balances[].bank | string | Nome da instituição bancária |
transactional.balances[].amount | number | Saldo na instituição específica |
operational | object | Saldo operacional (uso interno) |
operational.balance | number | Saldo total operacional em reais |
operational.balances | array | Detalhamento por instituição bancária |
Consultar histórico de saldo
Consulte o saldo de abertura e fechamento de uma data específica.
Route
GET /v2/balance/history
Headers
{
"Authorization": "YOUR_API_KEY"
}Query Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
date | string | Sim | Data para consulta no formato "YYYY-MM-DD" (ex: "2025-08-11") |
Exemplo de requisição:
curl --location 'https://api.pixtopay.com.br/v2/balance/history?date=2025-08-11' \
--header 'Authorization: API_KEY'Resposta 200 - Sucesso:
{
"transactional": {
"date": "2025-08-11",
"balance": {
"opening": 246.9,
"closing": 1357.82
},
"balances": [
{
"bank": "STARKBANK",
"opening_balance": 123.45,
"closing_balance": 678.91
},
{
"bank": "EFIPAY",
"opening_balance": 123.45,
"closing_balance": 678.91
},
{
"bank": "GENIAL",
"opening_balance": 0,
"closing_balance": 0
}
]
},
"operational": {
"date": "2025-08-11",
"balance": {
"opening": 246.9,
"closing": 1357.82
},
"balances": [
{
"bank": "STARKBANK",
"opening_balance": 123.45,
"closing_balance": 678.91
},
{
"bank": "EFIPAY",
"opening_balance": 123.45,
"closing_balance": 678.91
},
{
"bank": "GENIAL",
"opening_balance": 0,
"closing_balance": 0
}
]
}
}Campos da Resposta
| Parâmetro | Tipo | Descrição |
|---|---|---|
transactional.date | string | Data da consulta |
transactional.balance | object | Saldo consolidado do dia |
transactional.balance.opening | number | Saldo de abertura (início do dia) |
transactional.balance.closing | number | Saldo de fechamento (fim do dia) |
transactional.balances | array | Detalhamento por instituição bancária |
transactional.balances[].bank | string | Nome da instituição bancária |
transactional.balances[].opening_balance | number | Saldo de abertura na instituição |
transactional.balances[].closing_balance | number | Saldo de fechamento na instituição |
operational | object | Dados do saldo operacional (mesmo formato) |
Resposta 400 - Data inválida:
{
"type": "ValidationError",
"message": "date must be in YYYY-MM-DD format"
}Entendendo os Tipos de Saldo
Saldo Transacional
- Definição: Saldo disponível para realizar transações (cobranças PIX, pagamentos, etc.)
- Uso: Este é o saldo que você pode utilizar para criar pagamentos e cobranças
- Atualização: Atualizado em tempo real a cada transação
Saldo Operacional
- Definição: Saldo operacional da conta, usado para fins de controle interno
- Uso: Geralmente utilizado para reconciliação e controle financeiro
- Diferença: Pode diferir do saldo transacional devido a reservas e bloqueios
Instituições Bancárias
A PixToPay trabalha com múltiplas instituições bancárias para garantir redundância e disponibilidade:
- STARKBANK
- EFIPAY
- GENIAL
- Outras instituições: Consultar time comercial para validação de disponibilidade de demais instituições de pagamento.
O saldo total é distribuído entre essas instituições para otimizar processamento e disponibilidade.
Casos de Uso
1. Verificação antes de criar pagamento
async function canMakePayout(amount) {
const response = await fetch("https://api.pixtopay.com.br/v2/balance", {
headers: { Authorization: "YOUR_API_KEY" },
});
const data = await response.json();
return data.transactional.balance >= amount;
}2. Reconciliação diária
async function getDailyBalance(date) {
const response = await fetch(
`https://api.pixtopay.com.br/v2/balance/history?date=${date}`,
{ headers: { Authorization: "YOUR_API_KEY" } }
);
return await response.json();
}3. Dashboard de saldos
async function getBalanceSummary() {
const response = await fetch("https://api.pixtopay.com.br/v2/balance", {
headers: { Authorization: "YOUR_API_KEY" },
});
const data = await response.json();
return {
total: data.transactional.balance,
byBank: data.transactional.balances.map((b) => ({
bank: b.bank,
amount: b.amount,
percentage: ((b.amount / data.transactional.balance) * 100).toFixed(2),
})),
};
}Observações Importantes
- 🔒 Segurança: Endpoint disponível apenas em produção para proteger informações sensíveis
- 🕐 Atualização: Saldos são atualizados em tempo real
- 📊 Histórico: Histórico disponível para qualquer data a partir da criação da conta
- 💰 Moeda: Todos os valores são em BRL (Real Brasileiro)
- 📅 Fechamento: O fechamento diário ocorre à meia-noite (UTC-3)
Alertas de Saldo
Recomendamos implementar alertas quando:
- ✅ Saldo abaixo de um valor mínimo de operação
- ✅ Grande variação de saldo em curto período
- ✅ Discrepância entre saldo transacional e operacional
- ✅ Saldo negativo em alguma instituição