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.
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
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.