Endpoint

GET /v2/finance/get-balance

Headers

Query Parameters

Request Examples

Get account balance:

GET /v2/finance/get-balance?account_branch_identifier=0001&account_number=12345678-9
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...

Another account example:

GET /v2/finance/get-balance?account_branch_identifier=1234&account_number=98765432-1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...

Response Details

{
  "worked": true,
  "amount": 14501.25,
  "amount_available": 14501.25,
  "amount_total": 15000.50,
  "amount_blocked": 499.25,
  "amount_schedule": 0.00,
  "last_update": "2026-06-02T10:30:00Z",
  "account_branch": "0001",
  "account_number": "12345678-9"
}

Balance Calculation:

amount_available = amount_total - amount_blocked

Important Notes:

• All amounts are returned in BRL (Brazilian Real)
• Values include 2 decimal places
• If amount_available calculation results in a negative number, it is automatically set to 0.00
• amount_total can be negative (overdraft scenarios), but amount_available is always >= 0.00
• amount_schedule is informational only and does not affect amount_available

Error Responses

Business Rules

Account Validation:

• Account must exist in the system
• Account must not be in closed status
• User must have permission to access this specific account
• Both branch identifier and account number are required

Blocked Amount:

• Blocked amounts represent funds that are reserved for pending transactions
• Common scenarios for blocked funds:
  • PIX transactions awaiting confirmation
  • Scheduled payments pending execution
  • Pre-authorizations for future debits
  • Temporary holds for security reasons
• Blocked amounts are not available for new transactions

Scheduled Amount:

• Scheduled amounts represent future transactions already scheduled
• Does not reduce the available balance until executed
• Informational field for planning purposes
• Helps prevent scheduling conflicts

Response Times:

• Balance queries may take 1-3 seconds for real-time data
• Last update timestamp indicates data freshness
• Consider caching balance information in your application for frequently accessed accounts

Use Cases

1. Display Account Balance:
Show the current account balance to users in dashboards or account summary pages.

2. Pre-Transaction Validation:
Check available balance before initiating a transaction to prevent insufficient funds errors.

3. Balance Monitoring:
Regularly poll this endpoint to monitor account balances for alerts or reporting.

4. Multi-Account Overview:
Query balances for multiple accounts to provide a consolidated view of financial position.

5. Transaction Limits:
Compare available balance against transaction amounts to calculate maximum possible transaction values.

Best Practices

Balance Display:

• Show all relevant values (total, blocked, available) for complete transparency
• Highlight when blocked amount is significant
• Format currency values properly (e.g., R$ 15.000,50)
• Handle negative total balances appropriately in your UI
• Display last update timestamp to show data freshness

Error Handling:

• Always handle the "Account is closed" error gracefully
• Implement retry logic for temporary failures (e.g., network timeouts)
• Cache the last known balance as a fallback during service interruptions
• Provide clear error messages to end users

Security:

• Never expose balance information in URLs or logs
• Use HTTPS for all balance queries
• Implement proper access controls in your application layer
• Mask or redact balance information in non-secure environments
• Do not store balance information longer than necessary

Performance:

• Consider caching balance responses for frequently accessed accounts
• Recommended polling frequency: once per minute maximum
• Use webhooks or real-time notifications when available for balance changes
• Implement request throttling to avoid rate limits