Skip to main content
POST
/
api
/
v1
/
escrow
/
hold
curl --request POST \
  --url https://hpay-api.host-sl.com/api/v1/escrow/hold \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Idempotency-Key: order-1234-hold' \
  --header 'Content-Type: application/json' \
  --data '{
    "wallet_id": "9a8b7c6d-...",
    "amount": 200.00,
    "description": "Order #1234 held pending delivery"
  }'

{
  "id": "b1f2c3d4-...",
  "wallet_id": "9a8b7c6d-...",
  "escrow_wallet_id": "5e4f3a2b-...",
  "recipient_wallet_id": null,
  "application_wallet_id": null,
  "amount": 200.0,
  "escrow_amount": 200.0,
  "application_fee": null,
  "transaction_type": "escrow_hold",
  "status": "held",
  "description": "Funds held in escrow",
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z"
}
Holds a specified amount from a user’s wallet in your application’s escrow wallet. The funds are debited from the sender immediately and held (status held) until you release them to a recipient or refund them to the sender.
Escrow must be enabled for your application. If it isn’t, this endpoint returns 403. Contact HostPay or enable escrow from your dashboard.

​
Headers

​
Idempotency-Key
string
Optional but recommended for this money-moving call. Retries with the same key within 24 hours return the original result instead of creating a duplicate hold.

​
Request Body

​
wallet_id
string
required
The unique identifier of the user wallet to hold funds from.
​
amount
number
required
The amount to hold in escrow, in the application’s base currency. Must be greater than 0.
​
description
string
An optional description for the hold (default: “Funds held in escrow”).

​
Response

​
id
string
The unique identifier of the escrow transaction. Use this ID to release or refund the hold.
​
wallet_id
string
The ID of the sender wallet the funds were held from.
​
escrow_wallet_id
string
The ID of the application escrow wallet now holding the funds.
​
amount
number
The transaction amount.
​
escrow_amount
number
The amount currently held in escrow for this transaction.
​
transaction_type
string
The transaction type (escrow_hold).
​
status
string
The current status of the escrow transaction (held).
​
created_at
string
ISO 8601 timestamp of when the hold was created.
{
  "id": "b1f2c3d4-...",
  "wallet_id": "9a8b7c6d-...",
  "escrow_wallet_id": "5e4f3a2b-...",
  "recipient_wallet_id": null,
  "application_wallet_id": null,
  "amount": 200.0,
  "escrow_amount": 200.0,
  "application_fee": null,
  "transaction_type": "escrow_hold",
  "status": "held",
  "description": "Funds held in escrow",
  "created_at": "2025-01-16T10:30:00Z",
  "updated_at": "2025-01-16T10:30:00Z"
}

curl --request POST \
  --url https://hpay-api.host-sl.com/api/v1/escrow/hold \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Idempotency-Key: order-1234-hold' \
  --header 'Content-Type: application/json' \
  --data '{
    "wallet_id": "9a8b7c6d-...",
    "amount": 200.00,
    "description": "Order #1234 held pending delivery"
  }'