Consultar Saldo Disponível

Obtenha em tempo real o saldo líquido disponível da sua conta NomadsPay para saque.

GET/charges/balance

Descrição

Retorna o saldo disponível da empresa para saque. O valor é calculado em tempo real com a seguinte fórmula:

Saldo = Σ net_amount (cobranças PAID)
      + Ajustes financeiros do admin
      − Saques aprovados

Atenção: Cobranças com status PENDING, EXPIRED ou CANCELLED não são contabilizadas. Cobranças marcadas como reservadas pelo administrador também são excluídas do saldo disponível até liberação.

---

Autenticação

Header	Valor
Authorization	Bearer <SEU_CLIENT_SECRET>

---

Parâmetros

Nenhum parâmetro necessário. O saldo é calculado automaticamente com base na conta associada ao token.

---

Resposta de Sucesso

Campo	Tipo	Descrição
balance	number	Saldo disponível em reais (BRL)
currency	string	Sempre "BRL"
timestamp	string	Data/hora ISO 8601 da consulta

---

Códigos de Erro

Código	Motivo
401	Token inválido, expirado ou ausente
500	Erro interno ao calcular o saldo

Requisição

curl https://api.nomadspay.com/charges/balance \
  -H "Authorization: Bearer <SEU_CLIENT_SECRET>"

Resposta (200 OK)

{
  "balance": 97.50,
  "currency": "BRL",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Exemplo em JavaScript

const response = await fetch('https://api.nomadspay.com/charges/balance', {
  headers: {
    'Authorization': `Bearer ${process.env.NOMADS_SECRET}`
  }
});

if (!response.ok) {
  throw new Error(`Erro ${response.status}`);
}

const { balance, currency } = await response.json();
console.log(`Saldo disponível: ${currency} ${balance.toFixed(2)}`);
// Saldo disponível: BRL 97.50

Exemplo em Python

import os, requests

secret = os.getenv("NOMADS_SECRET")

resp = requests.get(
    "https://api.nomadspay.com/charges/balance",
    headers={"Authorization": f"Bearer {secret}"}
)

resp.raise_for_status()
data = resp.json()
print(f"Saldo disponível: BRL {data['balance']:.2f}")

---

Como o Saldo é Calculado

Componente	Efeito	Descrição
Cobranças PAID (net_amount)	➕ Credita	Valor líquido após desconto das taxas de cada cobrança confirmada
Ajustes financeiros	➕ / ➖	Créditos ou débitos aplicados manualmente pelo administrador
Saques aprovados	➖ Debita	Valores de saques com status PAID ou APPROVED

net_amount vs amount: O net_amount é o que você efetivamente recebe após a dedução das taxas. Em uma cobrança de R$ 100,00 com taxa de 4%, o net_amount será R$ 96,00 — e é esse valor que entra no saldo.

---

❓ Dúvidas frequentes — Consultar Saldo

O saldo retornado é o valor que posso sacar agora?

Sim. O valor em balance é o saldo líquido disponível para saque imediato. Ele já desconta:

• Taxas das cobranças pagas
• Saques pendentes ou em processamento
• Cobranças reservadas pelo administrador (que ainda não foram liberadas)

Se você solicitar um saque maior que esse valor, receberá erro 400 "Saldo insuficiente".

Por que meu saldo está zerado mesmo tendo cobranças pagas?

Verifique cada ponto:

1. As cobranças têm status PAID? Cobranças PENDING não entram no saldo
2. Há saques pendentes? Saques na fila reservam o valor antecipadamente
3. Há cobranças reservadas? O administrador pode reservar cobranças — elas ficam fora do saldo até liberação
4. A secret usada é da conta certa? Cada conta tem seu próprio saldo

Com que frequência devo consultar o saldo?

Não faça polling constante. O saldo só muda quando:

• Uma cobrança é paga (webhook charge.paid)
• Um saque é processado (webhook withdrawal.paid)
• O admin faz um ajuste manual

A prática correta é:

1. Receber o webhook charge.paid → então consultar o saldo atualizado
2. Antes de criar um saque → consultar o saldo para validar disponibilidade

Consultar a cada segundo desnecessariamente não traz benefício e consome requisições.

O saldo pode ser negativo?

Em circunstâncias normais, não. O sistema bloqueia saques que excederiam o saldo disponível. Em casos raros de condições de corrida (dois saques criados simultaneamente), o saldo pode momentaneamente ficar negativo — mas o administrador corrige via ajuste manual. Se isso acontecer, você receberá notificação.

Como construir um painel financeiro com o saldo em tempo real?

Combine a consulta de saldo com webhooks:

// 1. Consulta inicial ao carregar o painel
const { balance } = await fetch('/charges/balance', { headers }).then(r => r.json());

// 2. Atualiza o saldo quando receber webhook de pagamento
// No seu handler de webhook:
app.post('/webhook', async (req, res) => {
  const { event } = req.body;
  if (event === 'charge.paid' || event === 'withdrawal.paid') {
    const { balance } = await fetch('/charges/balance', { headers }).then(r => r.json());
    // Atualize seu estado/banco com o novo saldo
    updateBalance(balance);
  }
  res.status(200).json({ received: true });
});

Dessa forma, o saldo é sempre preciso sem polling desnecessário.

O timestamp retornado serve para alguma coisa?

Sim. O timestamp indica o exato momento em que o saldo foi calculado. Use-o para:

• Saber a "freshness" do saldo exibido no painel
• Registro de auditoria (quando o saldo foi consultado)
• Detectar se o dado está desatualizado em cache

O saldo inclui o valor de cobranças criadas há poucos segundos?

Somente se o status for PAID. Cobranças PENDING (recém-criadas e ainda não pagas) não entram no saldo. O valor só é creditado após a confirmação do pagamento pelo gateway — o que normalmente acontece em segundos após o pagamento real, via webhook.