Balances and holds
An account reports what is posted in the ledger and what can be spent. The gap between the two is made of holds, and every hold has a kind, an owner and an end.
Balances
GET /accounts/{id} returns the account with its balances. Amounts are integers in minor units of currency_code.
ledger_amountintegerAlwaysWhat is posted in the ledger.
available_amountintegerAlwaysThe ledger amount less every active hold. Payments and card authorizations are decided against it.
pending_amountintegerAlwaysDeposited and not yet available: the reg_cc_availability holds.
holding_amountintegerAlwaysReserved for payments in flight and card authorizations: the pending_debit and card_authorization holds.
locked_amountintegerAlwaysThe legal holds. On a frozen account everything that would be available is reported here, and available_amount is 0.
last_activity_datestring · dateSometimesThe customer's last movement. Dormancy counts from it.
The ledger's own view is GET /ledger/accounts/{id}/balances with the account's ledger_account_id: posted_amount, available_amount, holds_amount and the active holds summed by kind.
Holds
A hold reserves part of a ledger account's posted balance without moving money. It has a kind, an amount, a source_ref naming what it is for, the source_service that placed it, an optional expires_at and a status: active, released or expired. Deposit products do not allow a negative balance, so a hold larger than the available amount answers ledger.insufficient_available. Only the service that placed a hold may release it. Another caller is answered forbidden, and a hold that is no longer active answers ledger.hold_not_active.
kind | Placed | Ends |
|---|---|---|
pending_debit | By payments, when an outgoing ACH credit, wire or instant payment is created. An ACH transfer shows it as hold_id. | The settlement journal posts the debit and releases the hold together, through its release_hold_id. A payment that is rejected or fails releases the hold and posts nothing. |
reg_cc_availability | With a deposit, one hold for each part of the availability schedule. expires_at is the day that part becomes available. | The ledger's end-of-day close expires it, so the funds are available when that day starts. |
card_authorization | By cards, for an approved authorization. It expires after 7 days. Airlines, lodging, vehicle rental and cruise lines get 30 days, and fuel merchants 3. | The clearing posts and releases it, or it expires. |
legal | By accounts, for the amount a garnishment reaches. | The garnishment is released or remitted. |
Deposit availability
POST /accounts/{id}/credits takes an availability kind and places the Regulation CC schedule for it. With none, the credit is available at once. ach_credit and wire are available the next business day. A check or mobile_check makes the first $275 available the next business day and the rest on the second. The part of a day's check deposits over $6,725 waits until the seventh business day, or the ninth on an account opened within 30 days. These are the figures in force since 1 July 2025. A check deposit through payments follows the same schedule, and an incoming ACH credit is held to the next business day. Incoming wires and instant payments post with no hold.
Deposit servicing staff, or a service identity, can hold a check credit longer with POST /accounts/{id}/exception-holds: a credit_id and a reason of new_account, large_deposit, redeposited, repeated_overdraft, doubtful_collectability or emergency. The answer carries the notice owed to the customer: the amount held, the citation and the day the funds become available.
Overdrafts
When an item would overdraw an account, the rail asks the accounts service to decide first. The terms are set with PUT /accounts/{id}/overdraft-protection: a source of none, line (a facility_id) or linked_account (a linked_account_id), and pay_into_overdraft with its limit_amount, fee_amount, daily_fee_cap and de_minimis_amount. Each overdraft decision records one outcome:
not_needed: the available balance covers the item.line_advance: the line of credit is drawn for the shortfall, rounded up todraw_increment_amount.sweep: the shortfall moves from the linked account.paid_into_overdraft: the bank advances the shortfall within the limit and charges the fee when one applies.returned: nothing covers it, and the item is refused or returned.
No fee is charged within the de minimis amount, past the daily cap, on an item presented again within 30 days, or on a returned deposit charged back. A card or ATM item carries a fee only while the account owner's opt-in is active with its confirmation delivered, and the fee is assessed after the clearing posts. Advances stay outstanding until POST /accounts/overdraft-repayments repays them from available deposits, and an account with one cannot close.