# Account Balance
source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md

The Account Balance service provides real-time or cached bank account balance information from your customer's Financial Institution (FI). The information returned includes:

* Available balance---the amount of money that the account holder can spend or withdraw immediately. This value reflects some pending transactions (for example, a pending debit card transaction).
* Cleared balance---the amount of money currently in the account. This may vary from the available balance as it does not account for pending transactions.

<br />

The available and cleared balance will be the same if there are no pending transactions or funds to clear. However, if there is, for example, a pending debit card transaction of $50, the available balance will be $50 lower than the cleared balance.

For both fraud prevention and managing insufficient funds (NSF), we recommend you rely on the available balance. This value provides a more accurate view of funds by factoring in pending debit transactions or holds, which the cleared balance does not include.
Tip: To leverage the **Get Available Balance** solution, enrollment to this service is required. Please contact your account manager to learn more. Note: The **Get Available Balance** endpoint is a premium service, and is billable for each successful API call.

## Use Cases {#use-cases}

* **Payments** - Evaluate a customer's ability to make a payment.
* **Financial Aggregation Tools** - Provides up-to-date account balance information that can be consolidated and displayed to the customer.

## How It Works {#how-it-works}

1. Generate the required credentials to call the API. See [Generate Your Credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) in the Quick Start Guide.
2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) in the Quick Start Guide.
3. Create [a customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) and link them to at least one account via [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). You can use any of the [Bank Account Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#bank-account-profiles) to test.
4. Call [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetAvailableBalanceLive).

<br />

You can use the optional `balance_cache_interval` query parameter to control balance caching. The value specifies the maximum age in minutes of the cached balance that you will receive. The value must be from 0 to 1440 (1440 minutes is 24 hours) and defaults to 30 if not specified.

For example, if you specify 15 minutes, cached data is returned only if the data was cached in the last 15 minutes.

If no suitable cached balance exists, the Financial Institution is called to return a live balance.

Specify a `balance_cache_interval` of `0` to force retrieval of a live balance.
Tip: Using a balance cache interval improves performance by avoiding making too many requests to the FI to obtain a live balance. We recommend using the default 30-minute interval, but you can adjust this based on your specific needs.

### Get Available Balance {#get-available-balance}

Retrieve the available and cleared account balances for a single account in real-time from an FI, using `customerId` and `accountId` in the request parameters. You can use this endpoint to retrieve either a live or cached balance from an FI.

API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/availableBalance/live`

Note: The default caching behavior of this endpoint changed on **30 June 2026**.

* **Previously** : if `balance_cache_interval` was not specified, it defaulted to 0 (a live balance was always retrieved).

* **From 30 June 2026** : if `balance_cache_interval` is not specified, it defaults to 30 minutes
  (a cached balance is returned if available).

Diagram account-balance

## Testing {#testing}

See [Balance Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#balance-profiles) for details of banking profiles that are provided for testing purposes. These profiles are designed to return different account balances for testing purposes.