Get Balance

Use this endpoint to get the current wallet balance.

Available Environments

Production

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

Endpoint

• Method: GET
• Endpoint: /wallet/balance
• Authentication: Bearer token

Request Example

cURL

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

JavaScript

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

Success Response

⚠️ Important: Amounts in Cents

Every monetary amount is returned in cents. The balance is calculated with five decimal places, because of how fees are applied, so in cents it can come with a fraction: a balance of R$ 8,488.15900 returns 848815.9.

Field	Type	Required	Description
amount	number	Yes	Available wallet balance. Deprecated, kept for compatibility; use balance
balance	number	Yes	Available wallet balance
reserve	number	Yes	Amount held in reserve
pendingDebit	number	Yes	Pending debits
frozen	number	Yes	Frozen amount

Response Example

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

Using the balance to withdraw

A withdrawal only accepts whole cents. To withdraw the entire balance, drop the fraction, do not round it: rounding up asks for more than the wallet holds and the operation is refused for insufficient balance.

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

	Request	Result
correct	{ "amount": 848815 }	withdrawal completed
wrong	{ "amount": 848816 }	insufficient balance
wrong	{ "amount": 848815.9 }	400, the field requires an integer

In JavaScript, Math.floor(balance).

The dropped fraction stays in the wallet and goes into the next withdrawal, as soon as it adds up to a whole cent.

Possible Errors

Code	Description	Solution
401	Invalid credentials	Check your credentials
403	No permission/authorization	Contact support
404	Wallet not found	Contact support
500	Internal error	Contact support