{
  "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
    }
  ]
}

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

出金

提现回调通知

当批量提现/出款订单状态发生变化时，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

withdrawNotify

{
  "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
    }
  ]
}

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

概述

本页说明 webhook withdrawNotify。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。批量提现/出款订单状态变更时，GatePay 向商户配置的 callback URL 发送通知（对应 bizType=WITHDRAW 专用报文，无 data 字段）。

说明

建议以 batch_id + merchant_withdraw_id 作为幂等键。
验签、重试与成功应答见通知概览；签名见安全与签名。
长时间未收到回调时可调用提现查询补偿。

触发情形

批量提现/出款订单状态发生改变时（例如全部成功、全部失败或部分成功），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": {
    "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`）

{
  "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`）

{
  "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`）

{
  "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
    }
  ]
}

请求体

application/json

GatePay 在批量提现订单状态变化时向商户回调的数据结构，包含主订单对象和子订单数组。

main_order

object

必填

回调通知中的主提现单信息。

Show child attributes

suborders

object[]

必填

子订单回调详情数组。

Show child attributes

响应

200 - application/json

返回 HTTP 200 表示商户已成功接收通知。

商户接收通知后的响应体。

returnCode

string

必填

返回状态码，SUCCESS 表示成功。

returnMessage

string | null

返回说明，成功时可为空。

⌘I

公共

余额

机构

支付

OTC

闪兑

出金

礼品卡

订阅

对账

通知

提现回调通知

概述

说明

触发情形

bizType 说明

bizStatus 枚举值

消息结构

消息结构示例

批次状态（`main_order.status`）

main_order 字段说明

suborders 子项字段

回调示例

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

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

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

请求体

响应

​概述

​说明

​触发情形

​bizType 说明

​bizStatus 枚举值

​消息结构

​消息结构示例

​批次状态（main_order.status）

​main_order 字段说明

​suborders 子项字段

​回调示例

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

​部分成功（main_order.status=PARTIAL）

​全部失败（main_order.status=FAIL）

请求体

响应

概述

说明

触发情形

bizType 说明

bizStatus 枚举值

消息结构

消息结构示例

批次状态（`main_order.status`）

main_order 字段说明

suborders 子项字段

回调示例

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

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

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