出金
提现回调通知
当批量提现/出款订单状态发生变化时，GatePay 发送 bizType 为 WITHDRAW 的 webhook 通知（专用报文结构，非标准 data 封装）。
回调报文包含 main_order 主订单对象和 suborders 子订单数组；批次状态见 main_order.status（INIT / PROCESSING / PARTIAL / FAIL / SUCCESS）。商户须校验签名，处理成功后返回 {"returnCode":"SUCCESS","returnMessage":""}。以 batch_id + merchant_withdraw_id 作为幂等键。通知失败时按 通知概览 中的间隔重试。
WEBHOOK
概述
本页说明webhook withdrawNotify。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。
批量提现/出款订单状态变更时，GatePay 向商户配置的 callback URL 发送通知（对应 bizType=WITHDRAW 专用报文，无 data 字段）。
说明
触发情形
- 批量提现/出款订单状态发生改变时（例如全部成功、全部失败或部分成功），GatePay 向商户注册时配置的 callback URL 发送通知
- 若通知投递失败，重试规则见 通知概览。
bizType=WITHDRAW。接入说明见 出金。
bizType 说明
在 通知概览 的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 | 子订单列表，见下表 |
消息结构示例
批次状态（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 | 客户名称 / 渠道标识 |
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 | 实际完成金额 |