Overview

The Real-Time Data APIs enable you to request up-to-date balance information for a liability or retrieve the latest Payoff Summary as of the COMPLETED call. This functionality refreshes information to ensure you see the most current financial data available.

Real-time data retrieval is not always supported for every liability or lender. Therefore, an eligibility check is required before initiating a refresh.

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 realTimeBalanceor payOffSummary support.

The following two samples are examples of what could be seen on two different credit cards or auto loans for a user, where one card/loan is supported for real-time balance, but another is not as the card/loan is closed with no outstanding balance.

Supported Example:

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

Unsupported Example:

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

If availability is NOT_SUPPORTED, do not attempt a refresh as as refresh would be unsuccessful.

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. Or to find payoffSummary data: data.autoLoans.balanceDetails.

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"
}