Hold Token

uuid

required
Globally unique identifier for the hold.

Response Structure

200 OK

object
Base class for all transaction types in the ledger service

• status

  • string
  • enum
  • required
  • Status of a hold transaction
  • Options: PENDING, SETTLED, EXPIRED, VOIDED

• token

  • uuid
  • required
  • Unique identifier for the transaction

• created

  • date-time
  • required
  • ISO 8601 timestamp of when the transaction was created

• updated

  • date-time
  • required
  • ISO 8601 timestamp of when the transaction was last updated

• family

  • const
  • enum
  • required
  • HOLD - Hold Transaction
  • Value: HOLD

• result

  • string
  • enum
  • required
  • Options: APPROVED, DECLINED

• financial_account_token

  • uuid
  • required

• pending_amount

  • integer
  • required
  • Current pending amount (0 when resolved)

• currency

  • string
  • required

• events

  • array of objects
  • required

Events Object

• events
  • object
  • Event representing a lifecycle change to a hold
  • Properties:
    • token
      • uuid
      • required
    • type
      • string
      • enum
      • required
      • Type of hold lifecycle event: HOLD_INITIATED, HOLD_VOIDED, HOLD_EXPIRED, HOLD_SETTLED
    • result
      • string
      • enum
      • required
      • Options: APPROVED, DECLINED
    • detailed_results
      • array of objects
      • required
      • Options: APPROVED, INSUFFICIENT_FUNDS
    • amount
      • integer
      • required
      • Amount in cents
    • created
      • date-time
      • required
    • memo
      • string | null
      • required
    • settling_transaction_token
      • uuid | null
      • required
      • Transaction token of the payment that settled this hold (only populated for HOLD_SETTLED events)
    • user_defined_id
      • string | null
      • required
    • expiration_datetime
      • date-time | null
      • required
      • When the hold will auto-expire if not resolved.

Error Handling

400 Bad Request

A parameter in the query given in the request does not match the valid queries for the endpoint.

401 Unauthorized

User has not been authenticated due to:

• Invalid or missing API key.
• API key is not active.
• Could not find API key associated with any user.
• Authorization header is not formatted properly.
• Insufficient privileges. Issuing API key required.

404 Not Found

The specified resource was not found.

429 Too Many Requests

Client has exceeded the number of allowed requests in a given time period.

• Rate limited, user has exceeded their per second or daily rate limit.

Example Request

curl --request GET \
     --url https://sandbox.lithic.com/v1/holds/hold_token \
     --header 'accept: application/json'

Example Response

{
  "status": "PENDING",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created": "2026-07-18T00:25:36.012Z",
  "updated": "2026-07-18T00:25:36.012Z",
  "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:36.012Z",
      "memo": "string",
      "settling_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "user_defined_id": "string",
  "expiration_datetime": "2026-07-18T00:25:36.012Z"
}