Request to create a new hold on a financial account

Parameters

financial_account_token

• Type: uuid
• Required: Yes
• Description: Globally unique identifier for the financial account.

amount

• Type: integer
• Required: Yes
• Constraints: ≥ 1
• Description: Amount to hold in cents.

memo

• Type: string | null
• Description: Reason for the hold.

token

• Type: uuid
• Description: Customer-provided token for idempotency. Becomes the hold token.

expiration_datetime

• Type: date-time
• Description: When the hold should auto-expire.

user_defined_id

• Type: string
• Description: User-provided identifier for the hold.

Response Codes

201 Created

• Type: object
• Description: Base class for all transaction types in the ledger service.

Properties

• status
  • Type: string
  • Enum: PENDING, SETTLED, EXPIRED, VOIDED
• token
  • Type: uuid
  • Required: Yes
  • Description: Unique identifier for the transaction.
• created
  • Type: date-time
  • Required: Yes
  • Description: ISO 8601 timestamp of when the transaction was created.
• updated
  • Type: date-time
  • Required: Yes
  • Description: ISO 8601 timestamp of when the transaction was last updated.
• family
  • Type: enum
  • Required: Yes
  • Const: HOLD - Hold Transaction
• result
  • Type: enum
  • Required: Yes
  • Enum: APPROVED, DECLINED
• financial_account_token
  • Type: uuid
  • Required: Yes
• pending_amount
  • Type: integer
  • Required: Yes
  • Description: Current pending amount (0 when resolved).
• currency
  • Type: string
  • Required: Yes
• events
  • Type: array of objects
  • Required: Yes

Events

• Type: object
• Description: Event representing a lifecycle change to a hold.

Properties

• token
  • Type: uuid
  • Required: Yes
• type
  • Type: string
  • Enum: HOLD_INITIATED, HOLD_VOIDED, HOLD_EXPIRED, HOLD_SETTLED
  • Required: Yes
• result
  • Type: string
  • Enum: APPROVED, DECLINED
  • Required: Yes
• detailed_results
  • Type: array of objects
  • Required: Yes
• amount
  • Type: integer
  • Required: Yes
  • Description: Amount in cents.
• created
  • Type: date-time
  • Required: Yes
• memo
  • Type: string | null
• settling_transaction_token
  • Type: uuid | null
• user_defined_id
  • Type: string | null
• expiration_datetime
  • Type: date-time | null

Example Request

curl --request POST \
     --url https://sandbox.lithic.com/v1/financial_accounts/financial_account_token/holds \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "amount": 0,
  "memo": "string",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "expiration_datetime": "2026-07-18T00:25:35.898Z",
  "user_defined_id": "string"
}'

Example Response

{
  "status": "PENDING",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created": "2026-07-18T00:25:35.898Z",
  "updated": "2026-07-18T00:25:35.898Z",
  "family": "string",
  "result": "APPROVED",
  "financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "pending_amount": 0,
  "currency": "string",
  "events": [
    {
      "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "HOLD_INITIATED",
      "result": "APPROVED",
      "detailed_results": [
        "APPROVED"
      ],
      "amount": 0,
      "created": "2026-07-18T00:25:35.898Z",
      "memo": "string",
      "settling_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "user_defined_id": "string",
  "expiration_datetime": "2026-07-18T00:25:35.898Z"
}