Buscar Saldo

Utilize este endpoint para buscar o saldo atual da carteira.

Ambientes Disponíveis

Produção

https://api.gateway.com.br/core

Endpoint

• Método: GET
• Endpoint: /wallet/balance
• Autenticação: Bearer token

Exemplo de Requisição

cURL

curl --request GET \
--url https://api.gateway.com.br/core/wallet/balance \
--header 'Authorization: Bearer seu-token-jwt'

JavaScript

const response = await fetch('https://api.gateway.com.br/core/wallet/balance', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer seu-token-jwt'
  }
});
const data = await response.json();

Resposta de Sucesso

⚠️ Importante: Valores em Centavos

Todos os valores monetários retornam em centavos. O saldo é calculado com cinco casas decimais, por causa da aplicação de taxas, então em centavos ele pode vir com fração: um saldo de R$ 8.488,15900 retorna 848815.9.

Campo	Tipo	Obrigatório	Descrição
amount	number	Sim	Saldo disponível da carteira. Depreciado, mantido por compatibilidade; use balance
balance	number	Sim	Saldo disponível da carteira
reserve	number	Sim	Valor em reserva
pendingDebit	number	Sim	Débitos pendentes
frozen	number	Sim	Valor congelado

Exemplo de Resposta

{
  "amount": 10000,
  "balance": 10000,
  "reserve": 2500,
  "pendingDebit": 800,
  "frozen": 1200
}

Usando o saldo para sacar

O saque aceita apenas centavo inteiro. Para sacar o saldo todo, descarte a fração, não arredonde: arredondar para cima pede mais do que existe na carteira e a operação é recusada por saldo insuficiente.

GET /wallet/balance
{ "balance": 848815.9 }

	Requisição	Resultado
correto	{ "amount": 848815 }	saque realizado
errado	{ "amount": 848816 }	saldo insuficiente
errado	{ "amount": 848815.9 }	400, o campo exige um inteiro

Em JavaScript, Math.floor(balance).

A fração descartada continua na carteira e entra no próximo saque, assim que somar um centavo inteiro.

Possíveis Erros

Código	Descrição	Solução
401	Credenciais inválidas	Verifique suas credenciais
403	Sem permissão/autorização	Contate o suporte
404	Carteira não encontrada	Contate o suporte
500	Erro interno	Contate o suporte