Forgedocs
Endpoints

Check Balance

Overview

The GET /accounts/balances endpoint returns the balance of the authenticated account in a format compatible with the Central Bank specification.

Endpoint

GET /accounts/balances

Authentication

stringobrigatorio

Bearer token obtained via /oauth/token.

Request

curl -X GET https://api.gateway.goforge.com.br/accounts/balances \
  -H "Authorization: Bearer <token>"
const response = await fetch('https://api.gateway.goforge.com.br/accounts/balances', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const balance = await response.json();
import requests

response = requests.get(
    'https://api.gateway.goforge.com.br/accounts/balances',
    headers={
        'Authorization': f'Bearer {token}',
    }
)

balance = response.json()

Response

{
  "data": [
    {
      "eventDate": "2025-01-15T10:30:00.000Z",
      "balanceAmount": {
        "available": 48734.90,
        "blocked": 1500.00,
        "overdraft": 0
      }
    }
  ]
}
{
  "statusCode": 401,
  "message": "Token não fornecido ou inválido",
  "error": "Unauthorized"
}

Response Fields

dataarray

List of balances. Currently returns only one item.

Balance Types

TypeDescription
availableBalance that can be used immediately for transfers
blockedAmounts reserved for operations being processed
overdraftAdditional credit limit (not implemented)

Total Balance Calculation

totalBalance = available + blocked

The available balance already deducts blocked amounts.

Comparison with Standard API

Standard API (GET /balance)BACEN API (GET /accounts/balances)
grossBalanceavailable + blocked
blockedBalanceblocked
netBalanceavailable
consultedAteventDate

Equivalence Example

// Standard API
{
  "grossBalance": 50234.90,
  "blockedBalance": 1500.00,
  "netBalance": 48734.90,
  "consultedAt": "2025-01-15T10:30:00.000Z"
}

// BACEN API (equivalent)
{
  "data": [{
    "eventDate": "2025-01-15T10:30:00.000Z",
    "balanceAmount": {
      "available": 48734.90,
      "blocked": 1500.00,
      "overdraft": 0
    }
  }]
}

Balance Flow in Operations

PIX Out (Transfer)

sequenceDiagram
    participant App
    participant API
    participant Bank

    Note over App,Bank: Initial state: available=1000, blocked=0

    App->>API: POST /dict/pix (R$ 100)
    API-->>App: { type: "PENDING" }

    Note over App,Bank: State: available=900, blocked=100

    Bank->>API: Confirmation
    API->>App: Webhook TRANSFER (LIQUIDATED)

    Note over App,Bank: Final state: available=900, blocked=0

PIX In (Receipt)

sequenceDiagram
    participant Payer
    participant API
    participant App

    Note over Payer,App: Initial state: available=1000

    Payer->>API: Pays QR Code
    API->>App: Webhook RECEIVE (LIQUIDATED)

    Note over Payer,App: Final state: available=1100

Best Practices

Common Errors

CodeErrorSolution
401Token not providedInclude the Authorization: Bearer <token> header
401Invalid tokenVerify that the token is correct
401Expired tokenObtain a new token via /oauth/token

Next Steps

Create Charge

Generate a QR Code to receive PIX

Transfer PIX

Send a PIX to another account

PIX Transfer

Initiate a PIX transfer to a DICT key

Overview

Understand the V2 webhook format used in the PIX Bacen API

On this page

OverviewEndpointAuthenticationRequestResponseResponse FieldsBalance TypesTotal Balance CalculationComparison with Standard APIEquivalence ExampleBalance Flow in OperationsPIX Out (Transfer)PIX In (Receipt)Best PracticesCommon ErrorsNext Steps