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

# 提现回调通知

> 当批量提现/出款订单状态发生变化时，GatePay 发送 `bizType` 为 `WITHDRAW` 的 webhook 通知（专用报文结构，非标准 `data` 封装）。

回调报文包含 `main_order` 主订单对象和 `suborders` 子订单数组；批次状态见 `main_order.status`（`INIT` / `PROCESSING` / `PARTIAL` / `FAIL` / `SUCCESS`）。商户须校验签名，处理成功后返回 `{"returnCode":"SUCCESS","returnMessage":""}`。以 `batch_id` + `merchant_withdraw_id` 作为幂等键。通知失败时按 [通知概览](/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试。

## 概述

本页说明 `webhook withdrawNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。

批量提现/出款订单状态变更时，GatePay 向商户配置的 callback URL 发送通知（对应 `bizType=WITHDRAW` 专用报文，**无** `data` 字段）。

## 说明

* 建议以 `batch_id` + `merchant_withdraw_id` 作为幂等键。
* 验签、重试与成功应答见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)；签名见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。
* 长时间未收到回调时可调用 [提现查询](/api-reference/version/100/cn/endpoint/withdraw/withdrawQuery) 补偿。

## 触发情形

* 批量提现/出款订单状态发生改变时（例如全部成功、全部失败或部分成功），GatePay 向商户注册时配置的 **callback URL** 发送通知
* 若通知投递失败，重试规则见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)。

**适用范围**：提现/出款批次及子订单状态变更，对应通用回调体系中的 **`bizType=WITHDRAW`**。接入说明见 [出金](/essentials/version/100/cn/outflow/payout)。

## bizType 说明

在 [通知概览](/api-reference/version/100/cn/common/asyncNotification) 的 `bizType` 枚举中，提现类通知的取值为 **`WITHDRAW`**，表示提现/出款状态变更。

与支付、退款等使用 `bizType`、`bizId`、`bizStatus`、`client_id`、`data` 标准封装的回调不同，**`WITHDRAW` 回调采用专用报文结构**：请求体直接包含 `main_order`（批次主单）与 `suborders`（子订单数组），批次状态体现在 `main_order.status` 字段中。

## bizStatus 枚举值

终态通知的业务语义与下列 `bizStatus` 一致；批次处理进度另见 `main_order.status`（含 `INIT`、`PROCESSING` 等中间态）。

| 值                  | 说明                                                  |
| ------------------ | --------------------------------------------------- |
| `WITHDRAW_SUCCESS` | 批次全部成功，所有子订单均为终态（对应 `main_order.status=SUCCESS`）    |
| `WITHDRAW_PARTIAL` | 批次部分成功，部分子订单成功、部分失败（对应 `main_order.status=PARTIAL`） |
| `WITHDRAW_FAIL`    | 批次全部失败（对应 `main_order.status=FAIL`）                 |

## 消息结构

| 字段名          | 类型     | 说明         |
| ------------ | ------ | ---------- |
| `main_order` | object | 批次主单信息，见下表 |
| `suborders`  | array  | 子订单列表，见下表  |

### 消息结构示例

```json theme={null}
{
  "main_order": {
    "accountId": 10002,
    "batch_id": "831618381568",
    "merchant_id": 17329983,
    "status": "SUCCESS",
    "client_id": "igasgasdbub",
    "pay_back_status": "NO",
    "channel_id": ""
  },
  "suborders": [
    {
      "accountId": 10002,
      "suborder_id": "30969031299072",
      "status": "DONE",
      "merchant_withdraw_id": "1839295815",
      "currency": "USDT",
      "amount": 2362.1
    }
  ]
}
```

## 批次状态（`main_order.status`）

| 值            | 是否终态 | 说明               |
| ------------ | ---- | ---------------- |
| `INIT`       | 否    | 批次已创建，正在进行初始校验   |
| `PROCESSING` | 否    | 批次处理中，资金正在转移     |
| `PARTIAL`    | 是    | 部分子订单成功，部分失败     |
| `FAIL`       | 是    | 整个批次失败           |
| `SUCCESS`    | 是    | 整个批次成功，所有子订单均已完成 |

**回调顺序通常如下**：`INIT` → `PROCESSING` → 终态（`SUCCESS` / `PARTIAL` / `FAIL`）。

## main\_order 字段说明

| 字段名               | 类型     | 说明                                         |
| ----------------- | ------ | ------------------------------------------ |
| `batch_id`        | string | 批次 ID                                      |
| `merchant_id`     | int64  | 商户 ID                                      |
| `status`          | string | 批次状态，见上表                                   |
| `client_id`       | string | 创建批次时使用的 `client_id`                       |
| `pay_back_status` | string | 回退状态                                       |
| `channel_id`      | string | 客户名称 / 渠道标识                                |
| `accountId`       | int64  | 订单所属的账户ID（商户或机构发起返回其账户ID，机构代子账户发起则返回子账户ID） |

## suborders 子项字段

| 字段名                     | 类型     | 说明                                         |
| ----------------------- | ------ | ------------------------------------------ |
| `suborder_id`           | string | 子订单 ID                                     |
| `merchant_id`           | int64  | 商户 ID                                      |
| `channel_id`            | string | 客户名称 / 渠道标识                                |
| `chain`                 | string | 区块链网络                                      |
| `from_address`          | string | 出款方链上地址                                    |
| `address`               | string | 收款地址                                       |
| `currency`              | string | 币种                                         |
| `amount`                | number | 转账金额                                       |
| `fee`                   | number | 手续费                                        |
| `tx_id`                 | string | 交易哈希                                       |
| `memo`                  | string | 备注                                         |
| `status`                | string | 子订单状态：`DONE`（成功）或 `FAIL`（失败）               |
| `merchant_withdraw_id`  | string | 商户提现 ID，建议作为幂等键                            |
| `fee_type`              | int    | 手续费类型：`0` 内扣，`1` 外扣                        |
| `batch_withdraw_id`     | string | 批量提现 ID                                    |
| `desc`                  | string | 描述                                         |
| `reconciliation_status` | int    | 对账状态                                       |
| `is_placed`             | int    | 是否已提交：`0` 未提交，`1` 已提交                      |
| `finish_time`           | int64  | 完成时间（毫秒）                                   |
| `sub_amount`            | number | 子订单总金额                                     |
| `done_amount`           | number | 实际完成金额                                     |
| `accountId`             | int64  | 订单所属的账户ID（商户或机构发起返回其账户ID，机构代子账户发起则返回子账户ID） |

## 回调示例

### 批量提现全部成功（`main_order.status=SUCCESS`）

```json theme={null}
{
  "main_order": {
    "accountId": 10002,
    "batch_id": "1526052914503263472",
    "merchant_id": 48177363,
    "status": "SUCCESS",
    "client_id": "DlaHYwkeGDjSGRVr",
    "pay_back_status": "NO",
    "channel_id": ""
  },
  "suborders": [
    {
      "accountId": 10002,
      "fee": "0.0499",
      "desc": "",
      "chain": "BASEEVM",
      "tx_id": "0x2546829d95b7614acebde9dcc92d5b880ae82fa9791c2f80faa7ca668fc5cd3b",
      "amount": "0.1",
      "status": "DONE",
      "address": "0x524287c1e5a312a12c76380a3227611d3cb20ddf",
      "currency": "USDC",
      "fee_type": 0,
      "channel_id": "",
      "sub_amount": "0.1",
      "done_amount": "0.0501",
      "finish_time": 1780037579000,
      "merchant_id": 48177363,
      "suborder_id": "79553574716833917",
      "from_address": "0x0D0707963952f2fBA59dD06f2b425ace40b492Fe",
      "batch_withdraw_id": "1526052914503263472",
      "merchant_withdraw_id": "1526052914503263472",
      "reconciliation_status": 0
    }
  ]
}
```

### 部分成功（`main_order.status=PARTIAL`）

```json theme={null}
{
  "main_order": {
    "accountId": 10002,
    "batch_id": "1526052914503263472",
    "merchant_id": 48177363,
    "status": "PARTIAL",
    "client_id": "DlaHYwkeGDjSGRVr",
    "pay_back_status": "NO",
    "channel_id": ""
  },
  "suborders": [
    {
      "accountId": 10002,
      "fee": "0.0499",
      "desc": "",
      "chain": "BASEEVM",
      "tx_id": "0x2546829d95b7614acebde9dcc92d5b880ae82fa9791c2f80faa7ca668fc5cd3b",
      "amount": "0.1",
      "status": "DONE",
      "address": "0x524287c1e5a312a12c76380a3227611d3cb20ddf",
      "currency": "USDC",
      "fee_type": 0,
      "channel_id": "",
      "sub_amount": "0.1",
      "done_amount": "0.0501",
      "finish_time": 1780037579000,
      "merchant_id": 48177363,
      "suborder_id": "79553574716833917",
      "from_address": "0x0D0707963952f2fBA59dD06f2b425ace40b492Fe",
      "batch_withdraw_id": "1526052914503263472",
      "merchant_withdraw_id": "1526052914503263472",
      "reconciliation_status": 0
    },
    {
      "accountId": 10002,
      "fee": "0.0499",
      "desc": "",
      "chain": "BASEEVM",
      "tx_id": "",
      "amount": "0.1",
      "status": "FAIL",
      "address": "0x524287c1e5a312a12c76380a3227611d3cb20ddf",
      "currency": "USDC",
      "fee_type": 0,
      "channel_id": "",
      "sub_amount": "0.1",
      "done_amount": "0.0501",
      "finish_time": 1780037579000,
      "merchant_id": 48177363,
      "suborder_id": "79553574716833918",
      "from_address": "0x0D0707963952f2fBA59dD06f2b425ace40b492Fe",
      "batch_withdraw_id": "1526052914503263472",
      "merchant_withdraw_id": "1526052914503263473",
      "reconciliation_status": 0
    }
  ]
}
```

### 全部失败（`main_order.status=FAIL`）

```json theme={null}
{
  "main_order": {
    "accountId": 10002,
    "batch_id": "1526052914503263472",
    "merchant_id": 48177363,
    "status": "FAIL",
    "client_id": "DlaHYwkeGDjSGRVr",
    "pay_back_status": "NO",
    "channel_id": ""
  },
  "suborders": [
    {
      "accountId": 10002,
      "fee": "0.0499",
      "desc": "",
      "chain": "BASEEVM",
      "tx_id": "",
      "amount": "0.1",
      "status": "FAIL",
      "address": "0x524287c1e5a312a12c76380a3227611d3cb20ddf",
      "currency": "USDC",
      "fee_type": 0,
      "channel_id": "",
      "sub_amount": "0.1",
      "done_amount": "0.0501",
      "finish_time": 1780037579000,
      "merchant_id": 48177363,
      "suborder_id": "79553574716833917",
      "from_address": "0x0D0707963952f2fBA59dD06f2b425ace40b492Fe",
      "batch_withdraw_id": "1526052914503263472",
      "merchant_withdraw_id": "1526052914503263472",
      "reconciliation_status": 0
    }
  ]
}
```


## OpenAPI

````yaml api-reference/version/100/cn/openapi/withdraw-callback-openapi.json webhook withdrawNotify
openapi: 3.1.0
info:
  title: GatePay 提现与钱包 API
  version: 1.0.0
  description: >-
    基于 GatePay 提现与钱包相关文档整理的 OpenAPI 3.1
    规范。涵盖批量提现下单、提现订单查询、币种链查询、账户总额查询以及提现手续费查询等接口。
servers: []
security: []
paths: {}

````