Overview

Lithic has added a new Holds API to our Ledger Solutions offering. Holds can be used to reserve funds which will be used for a specific purpose, before that use actually happens. Holds are considered a new family of transaction.

Details

Holds reduce available_balance and increasing pending_balance without affecting the total. Holds can be resolved in three ways:

Settlement — linked to a payment (wire, ACH, or book transfer)
Manual void — explicitly voided via API
Expiration — automatically expired after the expiration_datetime

Status Lifecycle

PENDING ──► SETTLED   (via HOLD_SETTLED — linked to payment)
        ──► VOIDED    (via HOLD_VOIDED — manually voided)
        └──► EXPIRED   (via HOLD_EXPIRED — expiration_datetime passed)

Status	Description	`pending_amount`	Can Void?
`PENDING`	Hold is active and reserving funds	Hold amount	✅ Yes
`SETTLED`	Hold was consumed by a payment	`0`	❌ No
`VOIDED`	Hold was manually cancelled	`0`	❌ No
`EXPIRED`	Hold automatically expired	`0`	❌ No

API Endpoints

Method	Description	Endpoint
`POST`	Create a hold	`/financial_accounts/{financial_account_token}/holds`
`POST`	Void an active hold	`/holds/{token}/void`
`GET`	Get a single hold	`/holds/{token}`
`GET`	List holds for an account	`/financial_accounts/{financial_account_token}/holds`

Request & Response Examples

Create a Hold

Request: POST /v1/financial_accounts/{financial_account_token}/holds

{
  "amount": 1000,
  "memo": "Reserve for upcoming payment",
  "user_defined_id": "my-hold-123",
  "expiration_datetime": "2026-03-09T12:00:00Z"
}

Field	Type	Required	Notes
`amount`	integer	✅ Yes	Amount in cents
`memo`	string	No	Optional description
`user_defined_id`	string	No	User-supplied identifier
`expiration_datetime`	ISO 8601 datetime	No	Must be ≥ 2 hours in the future

Response (200 OK):

{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "family": "HOLD",
  "status": "PENDING",
  "result": "APPROVED",
  "financial_account_token": "fa-uuid-here",
  "pending_amount": 1000,
  "currency": "USD",
  "user_defined_id": "my-hold-123",
  "expiration_datetime": "2026-03-09T12:00:00Z",
  "created": "2026-03-02T10:00:00Z",
  "updated": "2026-03-02T10:00:00Z",
  "events": [
    {
      "token": "event-uuid",
      "type": "HOLD_INITIATED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "amount": 1000,
      "created": "2026-03-02T10:00:00Z",
      "memo": "Reserve for upcoming payment",
      "settling_transaction_token": null
    }
  ]
}

Insufficient balance: If the account lacks sufficient funds, the hold is still created but returned with "result": "DECLINED" and "pending_amount": 0.

Void a Hold

Request: POST /v1/holds/{token}/void

{
  "memo": "Canceling hold"
}

Response (200 OK): Returns the hold object with "status": "VOIDED" and "pending_amount": 0, plus a HOLD_VOIDED event appended to the events array.

Event Types

Event Type	Description	When It Occurs
`HOLD_INITIATED`	Hold was created	On successful hold creation
`HOLD_VOIDED`	Hold was manually cancelled	When void API is called
`HOLD_EXPIRED`	Hold automatically expired	When `expiration_datetime` passes (via cron job)
`HOLD_SETTLED`	Hold was consumed by payment	When linked payment settles

Balance Impact

State	Available	Pending	Total
Before Hold	$1000	$0	$1000
After $300 Hold	$700	$300	$1000
After Resolution	$1000	$0	$1000

Placing a hold reduces available balance and increases pending balance. The total balance is always unchanged. On void, settlement, or expiration, the pending amount is released back to available.

Payment Integration (Linked Holds)

Holds can be optionally linked to payments (book transfers, outbound wires, outbound ACH) using the hold_token parameter. This enables atomic fund reservation during payment processing.

Supported Payment Types

Payment Type	Endpoint	`hold_token` Support
Book Transfers	`/v1/book_transfers`	✅ Yes
Outbound Wires	`/v1/internal/wires/outbound`	✅ Yes
Outbound ACH	`/v1/internal/ach/transfers`	✅ Yes

Flow

Create a hold → receive hold_token
Create payment with "hold_token": "<hold_token>" in the request body
System validates: hold exists, status is PENDING, not expired, amount is sufficient
On payment success → hold transitions to SETTLED; settling_transaction_token is populated
On payment failure → hold remains PENDING and can be reused or voided

Release Timeline

Available now: March 3, 2026.

User Impact

This change is additive only. Learn more about Ledger APIs via our API Reference

If you have any questions or concerns, please contact us via the HELP link in your Lithic Dashboard.

The Lithic changelog has an RSS feed! To monitor for new update announcements, subscribe with your preferred RSS reader.