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

The following two samples are examples of 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, you will first have to initiate the refresh request and then listen for webhook updates to determine if the balance is available for retrieval from /v1/users endpoint.

Refresh Liability - This endpoint will initiate 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
Check Balance Refresh Status - Since the refresh can take some time, we recommend using this webhook to be notified as soon as this process is completed. The three statuses are IN_PROGRESS, FAILED, COMPLETED
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.

Refresh balance request statuses

Below are the statuses you can receive from the balance refresh webhook:

Status	Description
`IN_PROGRESS`	The request to update this liability's balance is underway, please continue to check in on the status.
`COMPLETED`	The request to update this liability's balance is completed and is available from the /v1/users endpoint.
`FAILED`	We were 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

Unsupported liabilities

If we are unable to support real time balances for a liability, you will see one of the following objects in the capabilities matrix for that liability. This will provide you with further details on why we do not support that capability.

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

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

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

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

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

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