Saldo

GET /v1/balance te devolve o saldo agregado da sua conta — quanto entrou, quanto foi cobrado em taxas, quanto está disponível para saque e quanto está retido. Tudo em BRL, como string decimal.

Quando usar

Para mostrar saldo no seu painel

Se o seu produto tem uma área meu saldo, leia direto da API em vez de manter um espelho local.

Antes de fazer um saque

Confira availableAmount antes de pedir um saque pelo app ou pela API para garantir que o valor está disponível.

Como funciona

Faça uma chamada autenticada

GET https://api.troqpay.com/v1/balance com Authorization: Bearer trq_test_... ou trq_live_....

Leia os campos

A resposta traz oito valores, todos em BRL como string decimal.

Use availableAmount como referência de saque

availableAmount é o que está realmente liberado para você sacar agora.

Exemplo

curl https://api.troqpay.com/v1/balance \
  -H "Authorization: Bearer trq_test_xxx"

{
  "livemode": false,
  "currency": "BRL",
  "grossAmount": "5430.00",
  "feeAmount": "54.30",
  "pendingAmount": "129.90",
  "availableAmount": "5245.80",
  "reservedAmount": "0.00",
  "blockedAmount": "0.00"
}

Como ler cada campo

Campo	O que significa
`livemode`	`true` para chaves `trq_live_`, `false` para `trq_test_`
`currency`	Sempre `BRL`
`grossAmount`	Total bruto recebido (antes das taxas)
`feeAmount`	Total de taxas cobradas pela TroqPay. A taxa é 1% por checkout, com piso de R$0,99 — em valores baixos a taxa efetiva fica acima de 1%
`pendingAmount`	Valores ainda em liquidação
`availableAmount`	Disponível para saque agora
`reservedAmount`	Reservado para saques já solicitados
`blockedAmount`	Retido (por exemplo, valores em disputa ou bloqueio operacional)

Os valores são strings decimais, não números. Em JavaScript, evite Number(balance.availableAmount) — você pode perder precisão. Use uma biblioteca decimal (bignumber.js, decimal.js) ou BigInt em centavos.

O que esperar em cenários diferentes

Cenário	Comportamento
Conta em produção sem `APPROVED`	`403 forbidden`
Chave sem `BALANCE:READ`	`403 api_key_scope_forbidden`
Sem checkouts ainda	Todos os campos em `"0.00"`
Saque solicitado, ainda não pago	O valor sai de `availableAmount` e entra em `reservedAmount`
Saque concluído	O valor sai de `reservedAmount` e some do saldo

Próximos passos

Solicitar saque

Solicite saques (Pix ou carteira USDT) com o destino aprovado na conta.

Boas práticas

Veja o que vale a pena salvar em logs ao operar saldo e checkouts.

API Reference

Consulte o schema completo de GET /v1/balance na referência.

Precisa de ajuda para seguir?

Revisar autenticação

Confira chaves, ambiente e o gate de produção antes de chamar saldo em LIVE.

Revisar erros

Veja o que 403 forbidden ou 401 unauthorized querem dizer.

Abrir o app

Confira o saldo no app para comparar com o que a API devolve.

Fluxos do produto

Mais recursos

Saldo

Saldo

Quando usar

Para mostrar saldo no seu painel

Antes de fazer um saque

Como funciona

Exemplo

Como ler cada campo

O que esperar em cenários diferentes

Próximos passos

Solicitar saque

Boas práticas

API Reference

Precisa de ajuda para seguir?

Revisar autenticação

Revisar erros

Abrir o app

​Saldo

​Quando usar

Para mostrar saldo no seu painel

Antes de fazer um saque

​Como funciona

​Exemplo

​Como ler cada campo

​O que esperar em cenários diferentes

​Próximos passos

Solicitar saque

Boas práticas

API Reference

​Precisa de ajuda para seguir?

Revisar autenticação

Revisar erros

Abrir o app

Saldo

Quando usar

Como funciona

Exemplo

Como ler cada campo

O que esperar em cenários diferentes

Próximos passos

Precisa de ajuda para seguir?