Consultar saldo

O endpoint de saldo retorna a fotografia financeira atual de uma conta: quanto já está disponível para saque, quanto ainda está pendente de liquidação, quanto está bloqueado e qual plano de taxas está em vigor. Use-o para planejar saques, conciliar caixa e exibir o saldo nos seus painéis.

GET /v1/finance/balance

Como funciona

Quando uma venda é aprovada, o dinheiro não cai imediatamente como "disponível". Ele segue um ciclo até liquidar:

1. Pendente (pending) — a transação foi aprovada, mas o valor ainda está dentro do prazo de liquidação do seu plano (feePlan.availabilityDays). Ainda não pode ser sacado.
2. Disponível (available) — o prazo de liquidação venceu e o valor já está livre para saque.
3. Bloqueado (blocked) — valores retidos temporariamente por disputas, chargebacks, garantia (warranty) ou processos administrativos. Não entram no disponível enquanto o bloqueio existir.

O endpoint é somente leitura (não altera nada) e reflete o estado em tempo real conforme as transações são processadas. A resposta é um único objeto de saldo no nível raiz, acompanhado de um bloco merchant (identificação da conta) e de _links (navegação HATEOAS — veja Convenções).

Todos os valores monetários são inteiros em centavos (150000 = R$ 1.500,00) e os timestamps são ISO 8601 em UTC (2026-04-12T17:56:33.000Z). Veja Convenções.

Os campos do feePlan

O feePlan é o plano de taxas vigente da conta. Ele explica quanto você paga por operação e quando o dinheiro fica disponível — por isso costuma ser usado junto com o saldo para projetar caixa. Os principais campos:

• availabilityDays — dias até um recebível pendente virar disponível.
• cashoutFee / minCashoutAmount — taxa por saque e valor mínimo de saque (centavos).
• transactionFixedFee e taxas por método (pixFee, nupayFee, billetFee, creditFee) — custos por transação (centavos).
• antecipationFee / antecipationDays — taxa e prazo de antecipação.
• transactionAmountLimit — teto por transação (centavos).
• warrantyEnabled / warrantyPercentage — se há retenção de garantia e seu percentual.

Quando usar

• Antes de solicitar um saque, para confirmar que há saldo disponível suficiente.
• Para exibir o saldo em painéis e dashboards do lojador.
• Para conciliação contábil e planejamento de fluxo de caixa.
• Para consultar o plano de taxas ativo e estimar custos.

Quando NÃO usar: este endpoint dá o agregado atual. Para ver os recebíveis individuais (cada parcela a receber, sua data prevista e status), use Listar Recebíveis. Não fique em polling contínuo aqui para detectar mudanças de saldo — prefira reagir a eventos por webhook (veja Proibição de Polling) e consultar o saldo sob demanda.

Requisição

Headers

Por ser uma requisição GET sem corpo, não há Content-Type. Nunca use Authorization: Bearer ou Basic — a autenticação é sempre pelo header SelectKey.

Parâmetros de query

Exemplo curl

curl -G https://api.selectwin.io/v1/finance/balance \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "companyId=bus_1234567890"

Resposta

200 OK — o corpo é o objeto de saldo no nível raiz.

{
  "id": "bal_01hqzvabc",
  "available": 150000,
  "pending": 25000,
  "blocked": 0,
  "debit": 0,
  "refunded": 12000,
  "warranty": 5000,
  "feePlan": {
    "id": "fee_01hqzvabc",
    "cashoutFee": 367,
    "transactionFixedFee": 49,
    "antecipationFee": 0,
    "antecipationDays": 30,
    "transactionAmountLimit": 5000000,
    "minCashoutAmount": 1000,
    "availabilityDays": 30,
    "warrantyPercentage": 0,
    "warrantyEnabled": false,
    "pixFee": 99,
    "nupayFee": 199,
    "billetFee": 349,
    "creditFee": 399,
    "chargeMonthlyFee": 0,
    "premium": true,
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-01-26T20:18:05.000Z"
  },
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/finance/balance",
      "method": "GET"
    }
  }
}

Campos da resposta

Campos do feePlan

Erros

Em caso de erro, a resposta segue o envelope padrão com um error.code estável — sempre trate pelo code, nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

{
  "error": {
    "code": "balanceNotFound",
    "statusCode": 404,
    "category": "client",
    "message": "Your balance not found"
  }
}

Boas práticas

• Confirme o disponível antes de sacar. Cheque available (não pending) antes de solicitar um saque e compare com feePlan.minCashoutAmount.
• Some cashoutFee ao planejar saques. O líquido que sai do available inclui a taxa de saque; projete o valor já descontando cashoutFee.
• Use availabilityDays para projetar caixa. Combinado com a data prevista de cada recebível (Listar Recebíveis), ele indica quando o pending virará available.
• Trate blocked e warranty separadamente. Esses valores não são sacáveis; não os some ao disponível ao exibir "saldo livre".
• Não fique em polling. Consulte o saldo sob demanda e reaja a mudanças por webhooks, não em laços contínuos (Proibição de Polling).
• Trate todos os valores como centavos. Divida por 100 apenas na exibição; nunca faça contas de dinheiro com ponto flutuante.
• Trate IDs como opacos. Armazene id, feePlan.id e merchant.merchantId como strings inteiras, sem fazer parsing.

Veja também

• Visão Geral de Finanças — o recurso e suas operações.
• Listar Recebíveis — os valores a receber que compõem o pending.
• Convenções da API — centavos, datas, IDs e camelCase.
• Autenticação — o header SelectKey.
• Catálogo de Códigos de Erro — todos os error.code.