Overview

To support the most up to date information on a liability, we provide an ability to refresh the balance of a liability with the real time balance as of the COMPLETED call. There are a few items to take into consideration as it relates to real time balances, which you will find below.

Determining Eligibility

Each liability is provided back via the /v1/users endpointwith a capabilities matrix for what functionality we support specific to that user's liability. For real time balance, liability types that are eligible for this capability are marked with a section of the capabilities matrix specific to the realTimeBalancesupport.

As an example, the following two samples are what could be seen on two different credit cards for a user, where one card is supported for real time balance, but another is not as the card is closed with no outstanding balance.

Card that is supported for Real Time Balance:

"capabilities": {
                    "payments": {
                        "billPayment": {
                            "availability": "SUPPORTED"
                        }
                    },
                    "data": {
                        "realtimeBalance": {
                            "availability": "SUPPORTED"
                        }
                    }
                }

Card that is not supported for Real Time Balance:

"capabilities": {
                    "payments": {
                        "billPayment": {
                            "availability": "SUPPORTED"
                        }
                    },
                    "data": {
                        "realtimeBalance": {
                            "availability": "NOT_SUPPORTED",
                            "description": "CLOSED_ACCOUNT_NO_BALANCE"
                        }
                    }
                }

Requesting Real Time Balance Updates

To request a real time balance update, there are two endpoints that you should be aware to both kick the request off, as well as be aware of when the updated balance is then available for retrieval from /v1/users endpoint.

1. Refresh Liability - This endpoint will kick off the refresh functionality for the supplied liabilityId to the API endpoint. As noted above, please only request liabilities that are marked as SUPPORTED for real time balance
2. Check Balance Refresh Status - Once the refresh request has been kicked off, you will want to monitor the status of the refresh transaction using this status webhook. Since the refresh can take a little bit of time, we recommend using the webhook to be notified as soon as this process is completed. The three statuses are IN_PROGRESS, FAILED, COMPLETED
3. Retrieve User - Following aCOMPLETED status for all of the refresh balance requests for an individual user, you will call the retrieve user endpoint and will find the specific update, with an updatedOn timestamp within the data.creditCards.balanceDetails object.

Statuses

Refresh balance request statuses:

1. IN_PROGRESS - The request to update this liability's balance is underway, please continue to check in on the status.
2. COMPLETED - The request to update this liability's balance is completed and is available from the /v1/users endpoint.
3. FAILED - If a request is unable to retrieve the liability's balance, the status will be marked as failed and the last balance retrieved for this liability will remain displayed on the /v1/users endpoint.

Not Supported Eligibility Statuses:

"realtimeBalance": {
                            "availability": "NOT_SUPPORTED",
                            "description": "CLOSED_ACCOUNT_NO_BALANCE"
                        }

"realtimeBalance": {
                            "availability": "FIELD_ERROR",
                            "fieldErrors": [
                                {
                                    "field": "CREDIT_CARD_NUMBER",
                                    "error": "NOT_PRESENT"
                                }
                            ]
                        }

"data": {
                        "realtimeBalance": {
                            "availability": "NOT_SUPPORTED",
                            "description": "REFRESH_EXHAUSTED",
                            "nextEligibleRefreshOn": 1709960400000
                        }
                    }

"data": {
                        "realtimeBalance": {
                            "availability": "NOT_SUPPORTED",
                            "description": "NOT_PRIMARY_ACCOUNT_HOLDER"
                        }
                    }

"data": {
                        "realtimeBalance": {
                            "availability": "NOT_SUPPORTED",
                            "description": "ACCOUNT_TERMINATED"
                        }
                    }

"data": {
                        "realtimeBalance": {
                            "availability": "NOT_SUPPORTED",
                            "description": "INSTITUTION_NOT_SUPPORTED"
                        }
                    }