Log In / Register

Listing the Balances for Accounts

This tutorial demonstrates the correct way to gather balance data from a list of accounts. Balance data for each account a customer is allowed to view could be displayed in a user interface or in a report.

This is done by first using an API operation to list accounts. The returned list of accounts does not include balance information. Instead, the the client must retrieve balance information for each account with a separate operation. This tutorial provides instructions on how to properly use both of the operations to gather all account and account balance information.

Note: You need to be authenticated to use the operations in this tutorial. For information on Authentication, please view the tutorial.

Gathering Balance Information

The listAccountBalances operation is used to gather account balance information. The operation requires a list of account IDs and returns the balance information for each individual account.

To gather a list of account IDs, follow the instructions for getting a list of accounts. After you have the customer’s full list of accounts, the IDs of those accounts can be passes to the listAccountBalances operation.

To use the listAccountBalances operation, perform GET request against:

/banking/accountBalances

The list of accounts can be passed to the listAccountBalances operation using the accounts query parameter. The accounts parameter takes a comma separated list of account IDs. The account IDs should be those accounts where allows.view is true.

In the following example, the operation will return the account balances for the three accounts with account IDs 05d00d7d-d630, b5a4f178-2baf, and 959908db-fd40 .

GET /banking/accountBalances?accounts=05d00d7d-d630,b5a4f178-2baf,959908db-fd40&retryCount=0

Note: All accounts must have a location property of internal . The listAccountBalances operation does not return balances for external accounts.

A 422 - Unprocessable Entity response likely indicates that one or more of the account IDs sent in the request is invalid. Every account ID in the request must be valid before the request can be accepted. Validate and fix all inaccurate account IDs and then resubmit the request. If all account IDs appear to be valid but the service still returns a 422 response, the error may be in another query parameter.

A 200 - OK response indicates the API has successfully gathered the balance information for all the accounts submitted. This is not alway possible in the time it takes to process a single request.

Sometimes the system cannot collect all of the balance information for accounts in a timely manner even though the submitted account IDs are valid. For example, the bank’s servers may be slow to respond due to high demand. When the balance information could not be retrieved for every account, the system responds with a detailed 202 - Accepted response.

A 202 - Accepted response includes the balance information for accounts where the information retrieval could be completed. It also includes the account IDs where the balance information retrieval could not be completed.

{
  "items": [
    {
      "id": "05d00d7d-d630",
      "available": "3208.20",
      "current": "3448.72",
      "currentWithPending": "3448.72",
      "updatedAt": "2022-05-02T06:51:19.375Z",
      "incomplete": false
    },
    {
      "id": "b5a4f178-2baf",
      "incomplete": true
    },
    {
      "id": "959908db-fd40",
      "incomplete": true
    },
  ],
  "incompleteAccounts": [
    "b5a4f178-2baf",
    "959908db-fd40"
  ],
  "retryCount": 1
}

The retryCount field includes an integer that increments with each attempt to collect balance data. The retryCount must be included with each resubmission of the incomplete account data.

The Retry-After response header indicates the time when the revised request can be resubmitted. Retry-After can be an integer or a date-time string, as shown below.

Retry-After: 120
Retry-After: Tue, 13 Sep 2022 23:59:59 GMT

An integer in the Retry-After header represents the number of seconds until the client can make the request again. A date-time string in the Retry-After header represents the earliest time the client can retry the operation. More information on the Retry-After response header, including the date-time string format, is available at RFC 9110 – HTTP Semantics.

If this Retry-After header is missing, the maximum number of retry attempts have been made and any further requests will receive a 429 (Too Many Requests) response.

To gather the rest of the account balance information, pass the incompleteAccounts from the response as the accounts query parameter and the retryCount query parameter as shown in the following example.

GET /banking/accountBalances?accounts=b5a4f178-2baf,959908db-fd40&retryCount=1

This operation may need to be performed several times until all the data is gathered. Once a 200 - OK response is received, all of the account balance information has been gathered.

A 429 - Too Many Attempts response indicates all attempts to gather account balances must be stopped. The service was unable to gather the information within a reasonable amount of attempts, and will not process further requests.

Code Example

This section includes a pseudocode example of looping through each page’s internal account IDs to gather the account balance data. This example is not in any specific programming language.

const accountsService = new AccountsService(httpClient, basePath, config);
// GET /banking/accounts 
var accounts_page = accountsService.listAccounts();
var end = false;
while (!end){
  var retryCount = 0;
  var accountID_list = extractInternalAccountIdsFrom(accounts_page);
  var gettingBalances = accountID_list.length > 0;
  while (gettingBalances) {
    // GET /banking/accountBalances?accounts=list&retryCount=n
    const account_balances = accountsService.listAccountBalances( accountID_list, retryCount);
    if (account_balances.response_code == 422){
		error(‘Invalid Account IDs. Manually Review.’);
		gettingBalances = false;
    } else {
      if (account_balances.response_code == 429){
        error(“Too Many Attempts to Gather Balances. Restart Later.”);
        gettingBalances = false;
      } else if (account_balances.response_code == 200) {
        displayBalances(account_balances.items);
      //Processing done
      }  else if (account_balances.response_code == 202) {
        displayBalances(account_balances.items);
        //get remaining account balances for remaining accounts using the incompleteAccounts field
        accountID_list = account_balances.incompleteAccounts;
        retryCount = account_balances.retryCount;
      }
      //else do other error handling, such as for 500 errors.
    } //end of balance gathering loop
  if (is_defined(all_accounts.nextPage_url)){
    httpClient.get(accounts_page.nextPage_url)
  } else { 
    //There are no more pages of accounts
    end = true;
  }
} //end of pagination loop