All Lithic Financial Accounts have three types of balances:

available: funds that you can spend or transfer
pending: funds that are set aside for authorized card transactions or ACH transactions that have not yet been released. Funds from the pending balance cannot be accessed for spend or other use cases
total: the sum of available and pending balances

Balances can be either positive or negative. Positive balance indicates that the financial account has been pre-funded while a negative balance indicates that your financial account requires funding. Lithic currently only accepts settlement and funding in USD, so you would only see balances in USD currency.

Funds will move between available and pending balances as a financial transaction goes through its lifecycle. For example:

A card authorization for $10 would move $10 from the available balance to the pending balance. When that transaction settles, $10 would be deducted from the pending balance
An ACH payment for $100 would first appear in your pending balance. After a period of time per our ACH schedule, the $100 would be released from your pending balance and moved to your available balance for you to spend or transfer

During the card authorization flow, your available balance is checked against your “minimum balance” requirement to ensure there are enough funds to fulfill the transaction. Depending on your program's configuration, the check will be done on either the available balance of your program’s ISSUING financial account or an end-user account’s ISSUING financial account. Note that the available balance checked in the authorization flow is the same balance that will be provided to the network during a balance inquiry.

To learn more about how minimum balances can impact authorizations, check out Quick Start - Accounts & Money Movement.

Balance Schema

{
	"type": String,
	"token": String,
	"currency": String,
	"available_amount": Integer,
	"pending_amount": Integer,
	"total_amount": Integer,
	"created": String,
	"updated": String,
	"last_transaction_token": String,
	"last_transaction_event_token": String
}


type	`ISSUING`, `RESERVE`, `OPERATING`
token	Globally unique identifier for the financial account that holds this balance
currency	3-digit alphabetic ISO 4217 code for the currency of the balance
available_amount	Funds available for spend in the currency's smallest unit (e.g., cents for USD)
pending_amount	Funds not available for spend due to card authorizations or pending ACH release. Shown in the currency's smallest unit (e.g., cents for USD)
total_amount	The sum of available and pending balance in the currency's smallest unit (e.g., cents for USD)
created	Date and time for when the balance was first created
updated	Date and time for when the balance was last updated
last_transaction_token	Globally unique identifier for the last transaction that occurred on this financial account
last_transaction_event_token	Globally unique identifier for the last transaction event that occurred on this financial account

List Balances

Get the balances for a program or a given end-user account. This endpoint can only be used for financial accounts that are managed by the program associated with the calling API key. If an account_token is provided in the query parameter, the balances for that end-user’s financial accounts will be returned; otherwise, the endpoint will default return the balances for the program’s financial accounts.

The current balance is returned by default, unless a query date is provided in which case the historical balance at that time is returned.

GET https://api.lithic.com/v1/balances


account_token (optional, query parameter)	Globally unique identifier for the end-user account whose associated balances should be returned. String. Permitted values: 36-digit version 4 UUID (including hyphens).
balance_date (optional, query parameter)	UTC date of the balances to retrieve. String. Permitted values: Date string in the RFC 3339format: yyyy-MM-dd’T’hh:mm:ss.SSSZ.
financial_account_type (optional, query parameter)	Financial account type to be returned. String. Permitted values: ISSUING, RESERVE, OPERATING

Sample Request

curl https://api.lithic.com/v1/balances \
  -H 'Authorization: YOUR_API_KEY'

Sample Response

{
  "data": [
    {
      "financial_account_type": "ISSUING",
      "financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "currency": "USD",
      "available_amount": 10000,
      "pending_amount": 0,
      "total_amount": 10000,
      "created": "2022-07-18T22:36:40.045Z",
      "updated": "2022-07-18T22:36:40.045Z",
      "last_transaction_token": "3c3e4cda-e1e8-48ee-a039-677ec0550981",
      "last_transaction_event_token": "5c8e69bb-5de7-4667-9336-bf1cfa846687"
    },
    {
      "financial_account_type": "RESERVE",
      "financial_account_token": "f83j4ng0-5817-bf62-c3d0-4b963d76f09p",
      "currency": "USD",
      "available_amount": 0,
      "pending_amount": 0,
      "total_amount": 0,
      "created": "2022-07-18T22:36:40.045Z",
      "updated": "2022-07-18T22:36:40.045Z",
      "last_transaction_token": "b68790ad-769b-42e6-a92f-38ee44e52701",
      "last_transaction_event_token": "7f9d08ca-813f-4e39-9696-2e53cdb4e6ed"
    },
    {
      "financial_account_type": "OPERATING",
      "financial_account_token": "b03ging0-5gh7-9062-d8760-4bfu7593kndy",
      "currency": "USD",
      "available_amount": 0,
      "pending_amount": 0,
      "total_amount": 0,
      "created": "2022-07-18T22:36:40.045Z",
      "updated": "2022-07-18T22:36:40.045Z",
      "last_transaction_token": "b68790ad-769b-42e6-a92f-38ee44e52701",
      "last_transaction_event_token": "7f9d08ca-813f-4e39-9696-2e53cdb4e6ed"
    }
  ],
  "has_more": false,
}

Get Balances

Get the balance for a given financial account. The current balance is returned by default, unless a query date is provided in which case the historical balance at that time is returned.

Users can also retrieve the balance after a given transaction event by providing a last_transaction_event_token. A balance will be returned only if this transaction event has been approved and has a balance impact. A declined event does not trigger any update to the balance, so no balance is returned.

GET https://api.lithic.com/v1/financial_accounts/{financial_account_token}/balances


financial_account_token (required, path parameter)	Globally unique identifier for the financial account whose associated balance should be returned. String. Permitted values: 36-digit version 4 UUID (including hyphens).
balance_date (optional, query parameter)	UTC date of the balance to retrieve String. Permitted values: Date string in the RFC 3339 format: yyyy-MM-dd’T’hh:mm:ss.SSSZ
last_transaction_event_token (optional, query parameter)	Globally unique identifier for the transaction event whose associated balance should be returned. String. Permitted values: 36-digit version 4 UUID (including hyphens).

Sample Request

curl https://api.lithic.com/v1/financial_accounts/3e548dd6-a9d4-4319-8c7f-2bf0905898b2/balances \
  -H 'Authorization: YOUR_API_KEY'

Sample Response

{
  "data": [
    {
      "financial_account_type": "ISSUING",
      "financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "currency": "USD",
      "available_amount": 10000,
      "pending_amount": 0,
      "total_amount": 10000,
      "created": "2022-07-18T22:36:40.045Z",
      "updated": "2022-07-18T22:36:40.045Z",
      "last_transaction_token": "3c3e4cda-e1e8-48ee-a039-677ec0550981",
      "last_transaction_event_token": "5c8e69bb-5de7-4667-9336-bf1cfa846687"
    }
  ]
}

List Aggregate Balances

GET https://api.lithic.com/v1/aggregate_balances


financial_account_type (optional, query parameter)	Financial account type to be returned. String. Permitted values: ISSUING, RESERVE

Sample Request

curl https://api.lithic.com/v1/aggregate_balances \
  -H 'Authorization: YOUR_API_KEY'

Sample Response

{
  "data": [
    {
      "financial_account_type": "ISSUING",
      "currency": "USD",
      "available_amount": 20000,
      "pending_amount": 0,
      "total_amount": 20000,
      "created": "2022-07-18T22:36:40.045Z",
      "updated": "2022-07-18T22:36:40.045Z",
      "last_transaction_token": "3c3e4cda-e1e8-48ee-a039-677ec0550981",
      "last_transaction_event_token": "5c8e69bb-5de7-4667-9336-bf1cfa846687",
      "last_financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    {
      "financial_account_type": "RESERVE",
      "currency": "USD",
      "available_amount": 0,
      "pending_amount": 0,
      "total_amount": 0,
      "created": "2022-07-18T22:36:40.045Z",
      "updated": "2022-07-18T22:36:40.045Z",
      "last_transaction_token": "b68790ad-769b-42e6-a92f-38ee44e52701",
      "last_transaction_event_token": "7f9d08ca-813f-4e39-9696-2e53cdb4e6ed",
      "last_financial_account_token": "f83j4ng0-5817-bf62-c3d0-4b963d76f09p"
    },
    {
      "financial_account_type": "OPERATING",
      "financial_account_token": "b03ging0-5gh7-9062-d8760-4bfu7593kndy",
      "currency": "USD",
      "available_amount": 0,
      "pending_amount": 0,
      "total_amount": 0,
      "created": "2022-07-18T22:36:40.045Z",
      "updated": "2022-07-18T22:36:40.045Z",
      "last_transaction_token": "b68790ad-769b-42e6-a92f-38ee44e52701",
      "last_transaction_event_token": "7f9d08ca-813f-4e39-9696-2e53cdb4e6ed"
    }
  ],
  "has_more": false
}

Events API and Webhooks

You can receive notification of External Bank Account events by subscribing to the following event types in the Events API:

balance.updated: Notification that the balance for an ISSUING, OPERATING, or RESERVE financial account has been updated