> ## 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.

# Release Escrow Funds

> Release previously held escrow funds to a recipient wallet, deducting any configured escrow fee.

Releases funds held by an escrow [hold](/api-reference/escrow/hold) to a recipient wallet. You can release the full held amount or a partial amount. If your application has an escrow fee configured, it is deducted from the released amount and routed to your fee wallet; the recipient receives the net.

### Path Parameters

<ParamField path="transaction_id" type="string" required>
  The ID of the escrow transaction (returned by the hold endpoint) to release from. Must be in `held` status.
</ParamField>

### 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 releasing the funds twice.
</ParamField>

### Request Body

<ParamField body="recipient_wallet_id" type="string" required>
  The unique identifier of the wallet to release the funds to.
</ParamField>

<ParamField body="amount" type="number">
  The amount to release. Defaults to the full held amount if omitted. Must be greater than 0 and not exceed the held amount.
</ParamField>

### Response

<ResponseField name="id" type="string">
  The unique identifier of the release transaction.
</ResponseField>

<ResponseField name="recipient_wallet_id" type="string">
  The ID of the wallet the funds were released to.
</ResponseField>

<ResponseField name="amount" type="number">
  The net amount credited to the recipient (after any escrow fee).
</ResponseField>

<ResponseField name="application_fee" type="number">
  The escrow fee collected on the release, if any.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the release transaction (e.g., `completed`).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of the release.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "c2d3e4f5-...",
    "wallet_id": "9a8b7c6d-...",
    "escrow_wallet_id": "5e4f3a2b-...",
    "recipient_wallet_id": "7c6d5e4f-...",
    "application_wallet_id": "3a2b1c0d-...",
    "amount": 198.0,
    "escrow_amount": 0.0,
    "application_fee": 2.0,
    "transaction_type": "escrow_release",
    "status": "completed",
    "description": "Escrow released",
    "created_at": "2025-01-16T12:00:00Z",
    "updated_at": "2025-01-16T12:00:00Z"
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "Transaction is not in 'held' status"
  }
  ```

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

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

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://hpay-api.host-sl.com/api/v1/escrow/b1f2c3d4-.../release \
    --header 'api-key: YOUR_API_KEY' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Idempotency-Key: order-1234-release' \
    --header 'Content-Type: application/json' \
    --data '{
      "recipient_wallet_id": "7c6d5e4f-...",
      "amount": 200.00
    }'
  ```

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

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

  release = client.escrow.release(
      "b1f2c3d4-...",                      # escrow hold transaction id
      recipient_wallet_id="7c6d5e4f-...",
      amount=200.00,                       # omit to release the full held amount
  ,
      idempotency_key="order-1234-release",
  )
  print(release["status"])
  ```

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

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

  const release = await client.escrow.release("b1f2c3d4-...", {
    recipientWalletId: "7c6d5e4f-...",
    amount: 200.0, // omit to release the full held amount
    idempotencyKey: "order-1234-release",
  });
  console.log(release.status);
  ```
</RequestExample>