Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.treasuryprime.com/llms.txt

Use this file to discover all available pages before exploring further.

Manual holds let you place temporary restrictions on specific amounts in an account, reducing the available balance while keeping the current balance unchanged. This guide covers how to create, manage, and release manual holds through the Treasury Prime API.
Manual holds require the manual_hold entitlement. Contact your Treasury Prime Account Manager to enable this feature for your organization.

​
What are manual holds?

Manual holds temporarily reserve a specific amount of funds in an account, preventing those funds from being used for payments, transfers, or withdrawals. The account’s current balance remains unchanged, but the available balance decreases by the hold amount. Unlike automatic holds created by the system during payment processing (such as card authorizations or pending ACH transfers), manual holds are explicitly created and managed through the API. You control when to create them, how long they last, and when to release them. Manual holds are particularly useful when you need to prevent funds from being accessed while investigating potential fraud, resolving disputes, meeting compliance requirements, or verifying account holder information. They provide a middle ground between allowing full account access and completely locking an account. Treasury Prime supports manual holds on both Treasury Prime ledger accounts and select partner bank core systems. The feature operates similarly across both platforms, with some differences in maximum expiration periods and processing logic.

​
Key benefits

  1. Fraud prevention without account disruption: Place holds on suspicious amounts while allowing legitimate transactions to continue, avoiding the need to completely lock an account.
  2. Flexible dispute resolution: Reserve disputed transaction amounts during investigation without permanently removing funds, maintaining customer trust while protecting your program.
  3. Compliance control: Meet regulatory requirements by temporarily restricting access to specific amounts during anti-money laundering (AML) reviews, sanctions screening, or other compliance processes.
  4. Temporary fund restrictions: Hold funds pending document verification, identity confirmation, or other operational requirements without the permanence of a withdrawal.
  5. Automatic expiration: Holds automatically release after a specified timeframe, reducing manual overhead and ensuring funds are not held indefinitely.

​
How manual holds work

Creating a manual hold involves calling the POST /hold endpoint with the account ID and hold amount. Treasury Prime immediately reserves the specified amount from the account’s available balance and creates a hold transaction in the transaction history. The hold remains active until you explicitly release it via the PATCH /hold/{id} endpoint, or until it reaches its expiration timestamp. During this time, the account holder cannot access the held funds for payments, transfers, or withdrawals. When you create a hold, you specify an optional expiration timestamp. If you don’t provide one, Treasury Prime automatically sets the expiration to the maximum allowed period based on the account type. For Treasury Prime ledger accounts, this is 10 days from creation. For partner bank core accounts, this is the next processing day at 11:00 PM Pacific Time. Treasury Prime runs an automated job every 5 minutes to check for expired holds. When a hold expires, the system automatically releases it, restores the funds to the available balance, and triggers a hold_expiration.create webhook event.

​
Creating a hold

When you create a manual hold:
  1. Treasury Prime validates the request: The system checks that the account is open, not locked, and has sufficient available balance to cover the hold amount.
  2. Treasury Prime creates the hold transaction: A hold transaction appears in the account’s transaction history with a negative amount, reducing the available balance. The current balance remains unchanged.
  3. Hold record is stored: Treasury Prime creates a manual hold object with status active, storing the hold amount, description, expiration timestamp, and associated transaction ID.
  4. Webhook event fires: Treasury Prime sends a manual_hold.create webhook event to your configured webhook endpoints.
Example request to create a manual hold
curl -X POST \
  -u $API_KEY_ID:$API_SECRET_KEY \
  https://api.treasuryprime.com/hold \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "acct_1234567890",
    "amount": "10.00",
    "expires_at": "2023-11-09T22:39:48Z",
    "hold_description": "Fraud investigation hold",
    "hold_release_description": "Investigation complete"
  }'
Example response
{
  "id": "hold_1234567890",
  "account_id": "acct_1234567890",
  "amount": "10.00",
  "status": "active",
  "bank_id": "bank_treasuryprime",
  "expires_at": "2023-11-09T22:39:48Z",
  "hold_description": "Fraud investigation hold",
  "hold_release_description": "Investigation complete",
  "hold_transaction_id": "ttx_1234567890",
  "org_id": "org_1234567890",
  "release_transaction_id": null
}

​
Releasing a hold

When you release a manual hold:
  1. Treasury Prime validates the hold status: The system checks that the hold is in active status and has not already been released or expired.
  2. Release transaction is created: A hold release transaction appears in the transaction history with a positive amount, restoring the funds to the available balance.
  3. Hold status updates: The hold object’s status changes from active to released, and Treasury Prime records the release transaction ID.
  4. Webhook event fires: Treasury Prime sends a manual_hold.update webhook event to your configured webhook endpoints.
Example request to release a manual hold
curl -X PATCH \
  -u $API_KEY_ID:$API_SECRET_KEY \
  https://api.treasuryprime.com/hold/hold_1234567890 \
  -H 'Content-Type: application/json' \
  -d '{"status": "released"}'
Example response
{
  "id": "hold_1234567890",
  "account_id": "acct_1234567890",
  "amount": "10.00",
  "status": "released",
  "bank_id": "bank_treasuryprime",
  "expires_at": "2023-11-09T22:39:48Z",
  "hold_description": "Fraud investigation hold",
  "hold_release_description": "Investigation complete",
  "hold_transaction_id": "ttx_1234567890",
  "org_id": "org_1234567890",
  "release_transaction_id": "ttx_0987654321"
}

​
Manual hold vs. account lock

Manual holds and account locks serve different purposes and have different scopes of impact:
FeatureManual HoldAccount Lock
PurposeReserve specific amount of fundsBlock all account activity
ScopeAffects available balance onlyBlocks payments, cards, transfers
FlexibilityCan hold any amount up to available balanceAll-or-nothing restriction
DurationTemporary (max 10 days for ledger accounts)Can be indefinite
Use caseFraud investigation on specific transactions, disputesSevere fraud, compliance issues, account closure
ImpactAccount holder can still use remaining available balanceAccount holder cannot perform any transactions
Use manual holds when you need to restrict access to a specific amount while allowing other account activity to continue. Use account locks when you need to completely prevent all activity on an account.

​
Key considerations

​
Account and balance requirements

  • Account must be open and unlocked: You can only create manual holds on accounts that are open and not locked. Attempting to create a hold on a closed or locked account returns an error.
  • Sufficient available balance required: The hold amount cannot exceed the account’s available balance. Treasury Prime validates this before creating the hold and returns an error if insufficient funds are available.
  • Balance impact: Manual holds reduce the available balance but do not change the current balance. The account holder sees the hold amount as unavailable for use.
  • Pending network transfers block hold creation: If an account has a pending incoming network transfer, you cannot create a hold until the transfer completes. This prevents holds from interfering with expected incoming funds.

​
Hold lifecycle and expiration

  • Expiration timestamps must be in the future: The expires_at value must be greater than the current timestamp. Treasury Prime rejects holds with expiration dates in the past.
  • Maximum expiration periods vary by account type: Treasury Prime ledger accounts support holds up to 10 days. Partner bank core accounts support holds until the next processing day at 11:00 PM Pacific Time, based on the bank’s processing calendar.
  • Automatic expiration runs every 5 minutes: Treasury Prime checks for expired holds every 5 minutes and automatically releases them. This means a hold may remain active for up to 5 minutes past its expiration timestamp, triggering a hold_expiration.create webhook event.
  • Holds cannot be modified after creation: You cannot change the hold amount or extend the expiration time. Release the existing hold and create a new one if you need to adjust these values.
  • Released or expired holds cannot be reactivated: Once a hold reaches released or expired status, it cannot return to active status. Create a new hold if needed.

​
Hold statuses and transactions

  • Hold statuses: Manual holds have five possible statuses: active (currently in effect), released (manually released), expired (automatically expired), pending (creation in progress), and error (creation failed).
  • Transaction history: Manual holds create two types of transactions in the account history: a hold transaction (negative amount) when created, and a hold release transaction (positive amount) when released. Both transactions use the hold ID as their trace_id, making it easy to find all transactions related to a specific hold.
  • Release descriptions: You can provide a hold_release_description when creating the hold, and update it later before releasing. This description appears on the release transaction.

​
Webhook events

  • Webhook events: Manual holds trigger three webhook events: manual_hold.create when created, manual_hold.update when released or updated, and hold_expiration.create when expired. Subscribe to these events to receive real-time notifications about hold lifecycle changes.
For detailed API endpoint documentation, parameter specifications, and response schemas, see the Manual Hold API Reference.