Consultar Saldo

Utilice este endpoint para consultar el saldo actual de la billetera.

Entornos Disponibles

Producción

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

Endpoint

• Método: GET
• Endpoint: /wallet/balance
• Autenticación: Bearer token

Ejemplo de Solicitud

cURL

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

JavaScript

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

Respuesta Exitosa

⚠️ Importante: Montos en Centavos

Todos los valores monetarios se devuelven en centavos. El saldo se calcula con cinco decimales, por la aplicación de las tarifas, así que en centavos puede venir con fracción: un saldo de R$ 8,488.15900 devuelve 848815.9.

Campo	Tipo	Obligatorio	Descripción
amount	number	Sí	Saldo disponible de la billetera. Obsoleto, se mantiene por compatibilidad; use balance
balance	number	Sí	Saldo disponible de la billetera
reserve	number	Sí	Monto retenido en reserva
pendingDebit	number	Sí	Débitos pendientes
frozen	number	Sí	Monto congelado

Ejemplo de Respuesta

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

Usar el saldo para retirar

El retiro solo acepta centavos enteros. Para retirar todo el saldo, descarte la fracción, no la redondee: redondear hacia arriba pide más de lo que hay en la billetera y la operación se rechaza por saldo insuficiente.

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

	Solicitud	Resultado
correcto	{ "amount": 848815 }	retiro realizado
incorrecto	{ "amount": 848816 }	saldo insuficiente
incorrecto	{ "amount": 848815.9 }	400, el campo exige un entero

En JavaScript, Math.floor(balance).

La fracción descartada permanece en la billetera y entra en el próximo retiro, en cuanto sume un centavo entero.

Errores Posibles

Código	Descripción	Solución
401	Credenciales inválidas	Verifique sus credenciales
403	Sin permiso/autorización	Contacte al soporte
404	Billetera no encontrada	Contacte al soporte
500	Error interno	Contacte al soporte