GET /accounts/{account_id}/balance

To access the user's account balance information, the TPP can now make a GET request to the /accounts/{account_id}/balance endpoint, where {account_id} is an id (shown above in yellow) returned in the response.

Here's an example of the response to the GET /accounts{account-id}/balance call:

{

    "balance": {

        "accountId": "a:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",

        "current": {

            "currency": "USD",

            "value": "12009.1000"

        },

        "available": {

            "currency": "USD",

            "value": "12009.1000"

        }

    },

    "status": "SUCCESSFUL_REQUEST"

}

Key bank-dependent fields in the balance object and their corresponding descriptions are listed in the following table.

Key Fields in the Bank's Account Balance Response
Field Subfield Description
accountId System-generated account ID
available currency ISO currency code for the available balance
value Available balance valued in the designated currency; typical precision rounding to 4 decimal places (HALF-EVEN), although this is entirely up to the bank. The Token Platform strictly serves as the pipeline between the TPP and the bank, imposing no precision restrictions.
current currency ISO currency code for the current balance
value Current balance valued in the designated currency.
otherBalances amount currency and value for other balances associated with the account, when applicable
type Bank-defined string indicating the type of balance

The status returned will be one of the following: INVALID_REQUEST, SUCCESSFUL_REQUEST, or MORE_SIGNATURES_NEEDED.

Note: The response status value MORE_SIGNATURES_NEEDED applies only to a scenario in which the bank requires the user to explicitly consent to a specific balance retrieval even though a valid access token exists. This is not a current requirement of any Token-connected bank and can therefore be disregarded until future notice.

An INVALID_REQUEST status in a response is the default setting that is always overridden when the API is invoked.

You can also retrieve balances for multiple accounts with a single call. Simply make the GET request to /account-balance?account_id={{ACCOUNT_ID_1}}&account_id={{ACCOUNT_ID_2}}&etc...

Tip: Use a GET /account-balance call to retrieve the associated balances for multiple accounts if the user holds more than one account at the bank. This call returns an array of accountIds, along with each respective account's balance, in contrast to the more targeted GET /accounts/{account-id}/balance call, which returns the balances (current and available) for the specified account only, as discussed above.

Based on the responses to these respective account balance queries, you can display the requested account information to the user.

Please refer to the API's Swagger Object and Field Definitions and Swagger Specification for additional details on all of the above.