> ## Documentation Index
> Fetch the complete documentation index at: https://doc.hpay.host-sl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hold Funds in Escrow

> Move funds from a user wallet into the application's escrow wallet, where they are held until released or refunded.

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](/api-reference/escrow/release) them to a recipient or [refund](/api-reference/escrow/refund) them to the sender.

<Note>
  Escrow must be enabled for your application. If it isn't, this endpoint returns `403`. Contact HostPay or enable escrow from your dashboard.
</Note>

### Headers

<ParamField header="Idempotency-Key" type="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.
</ParamField>

### Request Body

<ParamField body="wallet_id" type="string" required>
  The unique identifier of the user wallet to hold funds from.
</ParamField>

<ParamField body="amount" type="number" required>
  The amount to hold in escrow, in the application's base currency. Must be greater than 0.
</ParamField>

<ParamField body="description" type="string">
  An optional description for the hold (default: "Funds held in escrow").
</ParamField>

### Response

<ResponseField name="id" type="string">
  The unique identifier of the escrow transaction. Use this ID to release or refund the hold.
</ResponseField>

<ResponseField name="wallet_id" type="string">
  The ID of the sender wallet the funds were held from.
</ResponseField>

<ResponseField name="escrow_wallet_id" type="string">
  The ID of the application escrow wallet now holding the funds.
</ResponseField>

<ResponseField name="amount" type="number">
  The transaction amount.
</ResponseField>

<ResponseField name="escrow_amount" type="number">
  The amount currently held in escrow for this transaction.
</ResponseField>

<ResponseField name="transaction_type" type="string">
  The transaction type (`escrow_hold`).
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the escrow transaction (`held`).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the hold was created.
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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"
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "Insufficient funds to hold in escrow"
  }
  ```

  ```json 401 theme={null}
  {
    "detail": "Invalid credentials"
  }
  ```

  ```json 403 theme={null}
  {
    "detail": "Escrow feature is not enabled for this application"
  }
  ```

  ```json 404 theme={null}
  {
    "detail": "Sender wallet not found"
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  from hostpay import HostPay

  client = HostPay(api_key="YOUR_API_KEY", secret_key="YOUR_SECRET_KEY")

  hold = client.escrow.hold(
      wallet_id="9a8b7c6d-...",
      amount=200.00,
      description="Order #1234 held pending delivery",
      idempotency_key="order-1234-hold",
  )
  print(hold["id"], hold["status"])
  ```

  ```typescript TypeScript theme={null}
  import { HostPay } from "@hostpay/sdk";

  const client = new HostPay({ apiKey: "YOUR_API_KEY", secretKey: "YOUR_SECRET_KEY" });

  const hold = await client.escrow.hold({
    walletId: "9a8b7c6d-...",
    amount: 200.0,
    description: "Order #1234 held pending delivery",
    idempotencyKey: "order-1234-hold",
  });
  console.log(hold.id, hold.status);
  ```
</RequestExample>