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

# 加密货币提现事件

> 商户钱包的加密货币提现成功、失败或被取消时，VelaFi 发送的 CRYPTO_WITHDRAW_WEBHOOK 推送内容参考。

当您某个商户钱包的加密货币提现进入最终状态时，VelaFi 会向您的 `CRYPTO_WITHDRAW_WEBHOOK` 端点发送一个已签名的 HTTP POST 请求。请验证 `signature` 请求头，并以 `{"callbackStatus": "SUCCESS"}` 响应以确认接收。

此事件涵盖：

* 通过[创建加密货币提现](https://docs.velafi.com/cn/api-reference/crypto-wallet/create-crypto-withdrawal.md)或在 VelaFi 后台发起的、提现到外部地址的提现。
* 批量付款中付往外部地址的每一笔付款。
* 入金订单向订单目标地址的自动提现。此类提现成功时还会触发 [`ON_RAMP_WITHDRAW_WEBHOOK`](https://docs.velafi.com/cn/api-reference/webhooks/on-ramp-withdraw-message-push)，因此如果您同时订阅了这两种事件类型，同一笔转账会收到两次通知。

以下情况不会发送此事件：

* 通过创建加密货币提现或在后台发起的、提现到 VelaFi 钱包地址的提现。此类提现记为内部划转，显示在[加密货币划转历史](https://docs.velafi.com/cn/api-reference/merchant/query-crypto-transfers.md)中。
* 稳定币支付退款，即使它们会显示在[加密货币提现记录](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)中。
* 仍在处理中、等待审批或正在审核的提现。只推送最终状态。

> [!NOTE]
>
> 请通过[创建 Webhook](https://docs.velafi.com/cn/api-reference/webhooks/create-webhook-endpoints.md) 注册此事件类型，并传入 `"eventType": "CRYPTO_WITHDRAW_WEBHOOK"`。与其他事件类型一样，一个 Webhook 会接收您账户下所有商户的此事件，且沙盒环境不会触发 Webhook。

## 请求头

| 请求头 | 描述 |
| - | - |
| `signature` | 原始请求体的 RSA-SHA256 签名，采用十六进制编码。使用您 Webhook 的 `publicKey` 进行验证。请参阅 [Webhook 设置](https://docs.velafi.com/cn/api-reference/webhooks/webhook-setup.md)。 |
| `Content-Type` | `application/json` |

## 负载字段

所有值均以 JSON 字符串形式发送。

**webhookId** `string`

该事件所排队推送的 Webhook ID。

**eventType** `string`

对于此事件类型，始终为 `CRYPTO_WITHDRAW_WEBHOOK`。

**withdrawId** `string`

提现记录 ID。与[创建加密货币提现](https://docs.velafi.com/cn/api-reference/crypto-wallet/create-crypto-withdrawal.md)和[加密货币提现记录](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)返回的 `orderId` 一致。

**clientId** `string`

该提现的 `clientId`：您在创建加密货币提现时传入的值；入金自动提现则为入金订单的 `orderId`。同一批量付款中的所有付款共用同一个值，格式为 `masspayout:<id>`。如果提现没有 `clientId`，则为空。

**userId** `string`

您的 VelaFi 账户（用户）ID。

**merchantId** `string`

被扣款钱包所属的商户。

**crypto** `string`

代币符号，例如 `USDT`。

**network** `string`

提现所用的网络，例如 `TRC20`。与[提现额度](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-withdrawal-quota.md)中的 `chainType` 值相同。

**address** `string`

目标地址。

**amount** `string`

提现数量（与加密货币提现记录中的 `cryptoAmount` 值相同）。

**fee** `string`

网络手续费，币种与 `crypto` 相同。入金自动提现始终为 `0`。

**netAmount** `string`

`amount` 减去 `fee`（与加密货币提现记录中的 `arriveCryptoAmount` 值相同）。

**status** `string`

提现的最终结果：

* `SUCCESS` — 提现已在链上完成。
* `FAILED` — 提现失败或被 VelaFi 拒绝，提现数量已退回钱包余额。
* `REFUNDED` — 资金已从 VelaFi 钱包转出，随后被退回，并已退回钱包余额。请按与 `FAILED` 相同的方式处理。
* `CANCELLED` — 提现在发出前于 VelaFi 后台被取消，提现数量已退回钱包余额。Open API 不提供取消提现的端点。

**statusCode** `string`

[加密货币提现记录](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)中对应的 `status` 代码：`SUCCESS` 为 `6`，`FAILED` 和 `REFUNDED` 为 `7`，`CANCELLED` 为 `9`。

**txHash** `string`

链上交易哈希。仅在 `status` 为 `SUCCESS` 时包含。

**createTime** `string`

提现的创建时间（Unix 时间戳，毫秒）。

**completeTime** `string`

提现进入最终状态的时间（Unix 时间戳，毫秒）。

**timestamp** `string`

本次推送尝试签名时的 Unix 时间戳（毫秒）。

## 负载示例

> [tab] SUCCESS
>
> ```json Incoming POST body theme={null}
> {
>   "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
>   "eventType": "CRYPTO_WITHDRAW_WEBHOOK",
>   "withdrawId": "512345678901234567",
>   "clientId": "withdraw-0001",
>   "userId": "455472",
>   "merchantId": "100001",
>   "crypto": "USDT",
>   "network": "TRC20",
>   "address": "YOUR_DESTINATION_ADDRESS",
>   "amount": "100",
>   "fee": "1",
>   "netAmount": "99",
>   "status": "SUCCESS",
>   "statusCode": "6",
>   "txHash": "4a7f0c3e2b1d9f8e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f",
>   "createTime": "1735279907000",
>   "completeTime": "1735280100000",
>   "timestamp": "1735280101000"
> }
> ```

> [tab] FAILED
>
> ```json Incoming POST body theme={null}
> {
>   "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
>   "eventType": "CRYPTO_WITHDRAW_WEBHOOK",
>   "withdrawId": "512345678901234568",
>   "clientId": "withdraw-0002",
>   "userId": "455472",
>   "merchantId": "100001",
>   "crypto": "USDT",
>   "network": "TRC20",
>   "address": "YOUR_DESTINATION_ADDRESS",
>   "amount": "100",
>   "fee": "1",
>   "netAmount": "99",
>   "status": "FAILED",
>   "statusCode": "7",
>   "createTime": "1735279907000",
>   "completeTime": "1735283507000",
>   "timestamp": "1735283508000"
> }
> ```

## 必需的响应

返回 HTTP `2xx` 状态（例如 `200`）及以下 JSON 响应体以确认接收：

```json Your response theme={null}
{
  "callbackStatus": "SUCCESS"
}
```

## 处理说明

* **每笔提现推送一次最终事件。** VelaFi 在提现进入最终状态时发送此事件，不推送审批、审核等中间状态。如需在提现进入最终状态前查看其状态，请使用[加密货币提现记录](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)。
* **重复推送。** 同一事件可能会多次送达，因此请按 `withdrawId` 和 `status` 去重。请参阅[推送与重试](https://docs.velafi.com/cn/api-reference/webhooks/webhook-setup.md#delivery-and-retries)。
* **核对错过的事件。** 如果您的端点错过了所有推送尝试，该事件不会被重新推送。请通过加密货币提现记录核对处理中的提现：按 `clientId` 匹配；批量付款中的付款请按 `withdrawId`（即提现记录中的 `orderId`）匹配。不要在您的系统中无限期锁定用户余额。
* **更换 Webhook。** 与其他事件类型不同，待推送的事件只会推送到其排队时所属的 Webhook。如果您在删除或停用旧 Webhook 后新建一个 `CRYPTO_WITHDRAW_WEBHOOK` 的 Webhook，仍在旧 Webhook 队列中的事件将不会推送。如需更改推送地址，请改用[更新 Webhook](https://docs.velafi.com/cn/api-reference/webhooks/update-a-webhook.md) 修改现有 Webhook 的 URL。停用的 Webhook 在未新建其他 Webhook 的情况下重新启用后，其待推送的事件仍会推送。


## Related topics

- [获取加密货币提现记录](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)
- [创建加密货币提现](https://docs.velafi.com/cn/api-reference/crypto-wallet/create-crypto-withdrawal.md)
- [资金记录事件](https://docs.velafi.com/cn/api-reference/webhooks/funding-records-message-push.md)
- [更新日志](https://docs.velafi.com/cn/docs/changelog.md)
- [入金提现事件](https://docs.velafi.com/cn/api-reference/webhooks/on-ramp-withdraw-message-push.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.