Fetch Real Time Balance Data
This guide is for Platform API v2011101. For guidance on the newest version, see Connectivity Integration Guides.
The Platform API's balance check feature enables you to get real-time account balance information. This means the up-to-date balance information as it would appear on digital banking website, for instance. This can be critical to the success of any number of use cases including payments and account origination. Balance checks differ from standard aggregation because no transaction data is gathered, only account information.
This guide will take you through the balance check process using API endpoints. After reading this guide, you'll be able to:
- Gather balance information.
- Read balance information.
API Workflow
For most use cases, balance checks are performed for already existing users and members as part of a larger process such as moving money or originating a new held account. To avoid confusion and unnecessary work, the steps in this guide assume these already exist. If your test or use case requires it, you may need to first create a user and a member.
The workflow for performing a balance check is as follows:
- Start the balance check process.
- Poll the member's connection status.
- Answer multifactor authentication, if necessary.
- Poll the member's connection status again until it reaches an end state.
- A successful end state is when the connection_status is CONNECTED and the is_aggregating field changes from true to false.
- List the member's account information or read a particular account's information.
Call the Check Balance Endpoint
To make this request, you'll need an existing user_guid and member_guid as stated above.
Make a POST request to /users/{user_guid}/members/{member_guid}/check_balance. This request only starts the balance aggregation process; actually reading the aggregated data comes late. The response will be a member object with information about the state of the balance check process that just started.
Check the Connection Status
Check the connection status of the member to get information on the state of the balance aggregation. Important fields include connection_status, is_being_aggregated, and successfully_aggregated_at. The is_being_aggregated field will tell you whether the balance aggregation is ongoing or complete.
When you see "connection_status": "CONNECTED" and "is_being_aggregated": false at the same time, the balance aggregation is done and you can move on to the next step. The successfully_aggregated_at field will give the exact time the aggregate successfully completed, but won't update if the balance aggregation fails.
You may need to check the connection status several times until an end state is reached.
Make a request to the Read Member Status endpoint (GET /users/{user_guid}/members/{member_guid}/status). The response in the example shows a successful end state.
Deal with Multifactor Authentication
Aggregation-type jobs such as balance checks may trigger multifactor authentication (MFA) from the institution associated with the member. This is indicated by connection_status: CHALLENGED.
Please see the detailed section on answering MFA challenges for more information. For this part of the guide, we'll assume there was no MFA and move on to the next step.
Read the account's balance
The balance job was successful and you can now read balance information. This is given by the balance and available_balance fields on the account object.
Make a GET request to the /users/{user_guid}/members/{member_guid}/accounts/{account_guid} endpoint. The response will include all the attributes of the specified account.
There is another endpoint for reading an account provided for code convenience: GET /users/{user_guid}/accounts/{account_guid}.
You may also consider listing the details for all accounts associated with a user or a member:
GET /users/{user_guid}/accounts
GET /users/{user_guid}/members/{member_guid}/accounts