Balances
Learn more about balances
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. If you are on a prepay program, the available balance of your program’s ISSUING
financial account will be checked. If you are on Lithic Send, the check will be done on an end-user account’s ISSUING
financial account.
To learn more about how minimum balances can impact authorizations, check out Quick Start - Lithic Send.
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 |
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 ISO 8601 format: 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 |
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"
},
],
"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
.
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 ISO 8601 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"
},
],
"has_more": false
}
Updated about 2 months ago