> For the complete documentation index, see [llms.txt](https://docs.ezeebit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ezeebit.com/wallets-and-withdrawal/submit-withdrawal.md).

# Submit Withdrawal

Submit a crypto withdrawal with optional fee lock and status webhook.

**Live:**

<mark style="color:green;">`POST`</mark> [<mark style="color:blue;">https://api.ezeebit.com/open/api/v1/merchant/crypto/withdrawal/submit</mark>](https://api.ezeebit.com/open/api/v1/merchant/crypto/withdrawal/submit)

**UAT:**

<mark style="color:green;">`POST`</mark> [<mark style="color:blue;">https://uat-api.ezeebit.com/open/api/v1/merchant/crypto/withdrawal/submit</mark>](https://uat-api.ezeebit.com/open/api/v1/merchant/crypto/withdrawal/submit)

## Headers

| Name                   | Type   | Required | Value                          |
| ---------------------- | ------ | -------- | ------------------------------ |
| Content-Type           | string | Y        | application/json               |
| Ezeebit-Timestamp      | long   | Y        | Unix timestamp in milliseconds |
| Ezeebit-Nonce          | string | Y        | 32 characters                  |
| Ezeebit-Certificate-SN | string | Y        | API key issued by Ezeebit Pay  |
| Ezeebit-Signature      | string | Y        | Uppercase SHA512 signature     |

## Request Body

{% tabs %}
{% tab title="Your wallet" %}

```json
{
  "currencyUnit": "USDT",
  "whitelistAddressId": 4821,
  "currencyAmount": "101.50",
  "feeQuoteId": 48291,
  "counterpartyVaspId": "66fd0195bef6e83b3ececc1b",
  "webhookUrl": "https://hooks.your-domain.com/withdrawals",
  "idempotencyKey": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}
```

{% endtab %}

{% tab title="Customer account" %}

```json
{
  "currencyUnit": "USDT",
  "whitelistAddressId": 4821,
  "currencyAmount": "101.50",
  "feeQuoteId": 48291,
  "customerAccountId": "cust-1001",
  "counterpartyVaspId": "66fd0195bef6e83b3ececc1b",
  "webhookUrl": "https://hooks.your-domain.com/withdrawals",
  "idempotencyKey": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
}
```

{% endtab %}
{% endtabs %}

## Form data

| Parameter          | Required | Description                                                                                                                                                                                                                             |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| currencyUnit       | Yes      | `USDT`. USDT on Ethereum is the only asset and network available for withdrawal today.                                                                                                                                                  |
| whitelistAddressId | Yes      | The Id of the Active destination address to use to send the funds to                                                                                                                                                                    |
| currencyAmount     | Yes      | Gross amount to be debited from the account. Must be greater than `0`.                                                                                                                                                                  |
| feeQuoteId         | No       | Locked withdrawal fee. Omit it and the fee is calculated live at submission.                                                                                                                                                            |
| customerAccountId  | No       | Withdraw from one of your customer accounts instead of your own wallet. Use the same value you quoted with.                                                                                                                             |
| counterpartyVaspId | No       | VASP directory ID.                                                                                                                                                                                                                      |
| webhookUrl         | No       | Where we post the [withdrawal status](https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md#withdrawal-status) events for this withdrawal. Optional: without it, they go to the Payouts webhook set in the merchant portal. |
| idempotencyKey     | No       | Retry key, at most **128 characters**. Retrying with the same key returns the original order instead of creating a second withdrawal.                                                                                                   |

Quote `currencyAmount` is net. Submission `currencyAmount` is gross. When reusing a quote, submit its `settleCurrencyAmount`.

With `customerAccountId`, the customer account's balance is debited instead of yours, and the response returns its `customerAccountId`.

## Response

<table><thead><tr><th width="190">Status</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td>Withdrawal submitted</td></tr><tr><td>301</td><td>Permission denied — this API key is not permitted to submit withdrawals</td></tr><tr><td>10069</td><td>Withdrawals are temporarily disabled for this account</td></tr><tr><td>10070</td><td>Merchant not found</td></tr><tr><td>10071</td><td>Invalid argument or destination</td></tr><tr><td>10072</td><td>Service error; safe to retry</td></tr><tr><td>10073</td><td>Insufficient balance</td></tr><tr><td>10074</td><td>Quote expired, used, or mismatched</td></tr><tr><td>10091</td><td>Amount exceeds the maximum per-transaction withdrawal amount</td></tr><tr><td>10092</td><td>Amount would exceed your daily withdrawal limit</td></tr><tr><td>10093</td><td>Amount exceeds the default per-transaction withdrawal limit. Please contact support.</td></tr><tr><td>10094</td><td>Amount would exceed the default daily withdrawal limit. Please contact support.</td></tr><tr><td>10095</td><td>Amount is below the minimum per-transaction withdrawal amount</td></tr><tr><td>10096</td><td>Amount is below the default minimum per-transaction withdrawal amount. Please contact support.</td></tr><tr><td>10097</td><td>Number of withdrawals today would exceed the daily count limit</td></tr><tr><td>10098</td><td>Number of withdrawals today would exceed the default daily count limit. Please contact support.</td></tr><tr><td>10104</td><td><code>webhookUrl</code> is not a valid URL — send a full URL with a host. There is no allowlist to register it on</td></tr><tr><td>10108</td><td>Customer account is frozen</td></tr><tr><td>10119</td><td>This withdrawal cannot be processed to the selected destination address. Nothing was debited</td></tr><tr><td>10120</td><td>Service temporarily unavailable. Nothing was created or debited, so it is safe to retry</td></tr><tr><td>10121</td><td>Customer account not found</td></tr></tbody></table>

### Response fields

<table><thead><tr><th width="200">Field</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>orderNo</td><td>string</td><td>Withdrawal order number. Use it to correlate the status webhook</td></tr><tr><td>status</td><td>string</td><td>Status the withdrawal was accepted into</td></tr><tr><td>kytTxnId</td><td>string</td><td>Travel Rule / KYT screening transaction id</td></tr><tr><td>feeAmount</td><td>decimal</td><td>Fee actually charged for this withdrawal</td></tr><tr><td>feeQuoteId</td><td>long</td><td>The fee quote that funded this withdrawal — the one you supplied, or one generated automatically if you omitted <code>feeQuoteId</code></td></tr><tr><td>customerAccountId</td><td>string</td><td>The customer account debited, or <code>null</code> for your own wallet</td></tr></tbody></table>

{% tabs %}
{% tab title="200" %}

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "orderNo": "WD2026082012345",
    "status": "PENDING_APPROVAL",
    "kytTxnId": "TR2026082012345a1b2c3d4",
    "feeAmount": "1.50",
    "feeQuoteId": 48291,
    "customerAccountId": null
  }
}
```

{% endtab %}

{% tab title="10073" %}

```json
{
  "code": 10073,
  "msg": "Insufficient balance",
  "data": null
}
```

{% endtab %}
{% endtabs %}

Possible statuses include `PENDING_APPROVAL`, `SUBMITTED`, `CONFIRMING`, `COMPLETED`, `REVERTED`, and `CANCELLED`.
