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.
处理要求
对于每一笔收到的回调，你都必须：
- 先验证签名 ： 见 认证与安全 了解签名验证详情
- 解析业务数据 并进行幂等处理
- 返回约定的成功响应
由于同一业务事件可能被重复投递，因此你必须基于业务唯一标识实现幂等处理。
建议处理顺序
为了降低误更新、重复入账或过早判定终态的风险，建议按以下顺序处理回调：
- 校验请求头与签名
- 解析
bizType、bizId、bizStatus
- 对业务唯一标识做幂等检查
- 更新本地业务状态
- 返回成功响应
- 对关键资金事件结合查询接口做最终确认
对于支付、OTC、出金等资金相关场景，回调通常应被视为主要事件来源，但关键结果仍建议结合查询接口做最终核验。
触发与重试机制
触发条件
当订单状态发生变化（如支付成功、超时、取消、关闭或异常）时，GatePay 会向你配置的回调地址发送通知。
重试
如果你未返回约定的成功响应，或请求超时，GatePay 会按规则重试回调。
签名验证
处理前必须先验证所有回调签名。请参见 认证与安全 了解详情。
回调消息结构
所有回调都包含以下顶层字段:
| 字段 | 类型 | 说明 |
|---|
| bizType | 字符串 | 通知类别 （见 bizType 枚举） |
| bizId | 字符串 | 订单 ID 或业务 ID |
| bizStatus | 字符串 | 业务状态 (因 bizType 而异) |
| client_id | 字符串 | 商户 client_id |
| data | 字符串 | 以 JSON 字符串表示的业务载荷；结构因 bizType 而异 |
{
"bizType": "PAY",
"bizId": "6948484859590",
"bizStatus": "PAY_SUCCESS",
"client_id": "cdhu-fgrfg44-5ggd-cdvsa",
"data": "{\"merchantTradeNo\":\"M202603120001\",\"orderAmount\":\"100.00\"}"
}
回调确认响应
请以 HTTP 200 返回以下 JSON 响应:
{
"returnCode": "SUCCESS",
"returnMessage": ""
}
bizType 枚举
| 取值 | 说明 |
|---|
| PAY | 非地址支付订单的状态变更 |
| PAY_REFUND | 退款订单的状态变更 |
| PAY_BATCH | 批量奖励订单的状态变更 |
| PAY_GIFT_BATCH | 批量礼品卡支付的状态变更 |
| PAY_ADDRESS | 地址支付订单的状态变更 |
| TRANSFER_ADDRESS | 地址支付资金流水通知 |
| PAY_FIXED_ADDRESS | 静态地址收款通知 |
| WITHDRAW | 提现 / 出款状态变更 |
| INSTITUTION | 机构 API 账户相关通知 |
总体说明
- 通知章节用于说明所有支付、退款、地址收款、静态地址收款、出金与机构相关回调的共性规则。
- 每类业务的详细回调字段解释，仍应以对应产品章节中的接入说明与 API Reference 共同理解。
- 如果你的业务同时接入多种支付方式，请务必按照
bizType 分流处理，不要假设所有订单都共用同一回调字段集合。
- 不建议仅依据单次回调立即完成财务终态确认；对于关键资金动作，建议结合查单或详情查询接口完成最终核验。
支付产品与 bizType 对应关系
如果你的业务同时接入多种支付产品，建议先按“产品类型 -> bizType”建立内部映射：
| 产品或场景 | 主要 bizType | 说明 |
|---|
| 托管收银台、Web 拉起、普通非地址支付 | PAY | 用于非地址类支付订单状态通知 |
| 退款 | PAY_REFUND | 用于退款状态推进 |
| 地址支付 | PAY_ADDRESS | 用于地址支付订单状态变化 |
| 地址支付资金到账 | TRANSFER_ADDRESS | 用于地址支付资金入账、延迟到账或风控状态 |
| 静态地址收款 | PAY_FIXED_ADDRESS | 用于静态地址到账结果 |
| 出金 / 提现 | WITHDRAW | 用于批次及子订单状态变化 |
| 机构子账户相关 | INSTITUTION | 用于机构子账户开通结果通知 |
托管收银台支付通知
托管收银台支付遵循通用的 PAY 回调模型。对于非地址支付，请使用 orderAmount 判断支付金额。有关支付接入的更多详情，请参见 支付。
退款通知
退款订单使用 PAY_REFUND 回调类型。
- 退款查询与对账时，请优先使用商户侧唯一标识
refundRequestId。
- API 发起的退款与商户后台手工退款是两个不同操作入口，文档中的回调说明仅覆盖 API 集成场景。
- 退款状态推进建议同时结合回调与退款查询接口完成。
地址支付通知
PAY_ADDRESS 状态枚举
| 状态 | 适用模式 | 说明 |
|---|
| PAY_SUCCESS | 非兑换 / 兑换 | 支付成功 |
| PAY_ERROR | 非兑换 / 兑换 | 支付失败 |
| PAY_CLOSE | 非兑换 / 兑换 | 订单已关闭 |
| PAY_EXPIRED_IN_PROCESS | 非兑换 / 兑换 | 有效期内已达到目标金额，但仍存在链上未最终确认记录 |
| PENDING | 兑换 | 待处理 |
| PROCESS | 兑换 | 处理中 |
| PAID | 兑换 | 已支付 |
| EXPIRED | 兑换 | 已过期 |
PAY_ADDRESS data 字段
| 字段 | 适用模式 | 说明 |
|---|
| merchantTradeNo | 非兑换 / 兑换 | 商户 订单号 |
| productType | 非兑换 / 兑换 | 产品类型 |
| productName | 非兑换 / 兑换 | 产品名称 |
| goodsName | 非兑换 / 兑换 | 商品名称 |
| tradeType | 非兑换 / 兑换 | 交易类型 |
| terminalType | 非兑换 / 兑换 | 终端类型 |
| currency | 非兑换 / 兑换 | 计价币种 |
| orderAmount | 非兑换 / 兑换 | 订单金额 |
| payerId | 非兑换 / 兑换 | 付款方标识 |
| createTime | 非兑换 / 兑换 | 创建时间 |
| transactionId | 非兑换 / 兑换 | 平台交易 ID |
| waitAmountOnChain | 非兑换 / 兑换 | 已检测到但尚未最终入账的链上金额 |
| doneAmountOnChain | 非兑换 / 兑换 | 已确认并入账的链上金额 |
| channelId | 非兑换 / 兑换 | 渠道标识 |
| chain | 非兑换 / 兑换 | 链名称 |
| address | 非兑换 / 兑换 | 收款地址 |
| fromAddress | 非兑换 / 兑换 | 付款方地址 |
| payCurrency | 兑换 | 用于兑换的支付币种 |
| payAmount | 兑换 | 用于兑换的支付金额 |
| rate | 兑换 | 汇率 |
| overPay | 兑换 | 超付金额 |
TRANSFER_ADDRESS 状态枚举
| 状态 | 说明 |
|---|
| TRANSFERRED_ADDRESS_IN_TERM | 有效期内入账 |
| TRANSFERRED_ADDRESS_DELAY | 有效期后入账 |
| CONVERT_ADDRESS_PAY_DELAY | 仅兑换延迟支付通知，不入账 |
| TRANSFERRED_ADDRESS_BLOCK | 风控资金，未入账 |
TRANSFER_ADDRESS data 字段
| 字段 | 说明 |
|---|
| merchantTradeNo | 商户 订单号 |
| currency | 币种 |
| orderAmount | 订单金额 |
| createTime | 创建时间 |
| transactionId | 平台交易 ID |
| transferAmount | 链上转账金额 |
| txHash | 区块链交易哈希 |
| chain | 链名称 |
| address | 地址 |
| channelId | 渠道标识 |
txHash、tx_hash 或 hash，接入时建议按兼容方式解析。
静态地址收款通知
bizType: PAY_FIXED_ADDRESS
bizStatus: PAY_SUCCESS （入账成功） 或 PAY_BLOCK （风险资金，未入账）
data 字段
| 字段 | 类型 | 必填 | 说明 |
|---|
| channelId | 字符串 | 是 | 渠道标识 |
| currency | 字符串 | 是 | 币种 |
| orderAmount | 字符串 | 否 | 订单金额 |
| amount | 字符串 | 是 | 实际入账金额 |
| createTime | 数字 | 是 | 创建时间 （毫秒） |
| transactionId | 字符串 | 是 | 平台交易 ID |
| transactionTime | 数字 | 是 | 交易时间 （毫秒） |
| chain | 字符串 | 是 | 链名称 |
| address | 字符串 | 是 | 收款地址 |
{
"returnCode": "SUCCESS",
"returnMessage": ""
}
提现 / 出款回调
有关提现和出金操作，请参见 出金 了解详细回调结构和字段说明。
bizType: WITHDRAW
主单字段
| 字段 | 必填 | 说明 |
|---|
| batch_id | 是 | 批次 ID |
| merchant_id | 是 | 商户 ID |
| status | 是 | INIT / PROCESSING / PARTIAL / FAIL / SUCCESS |
| client_id | 是 | 创建批次时使用的 client_id |
| pay_back_status | 是 | 回退状态 |
| channel_id | 是 | 渠道标识 |
子订单字段
| 字段 | 必填 | 说明 |
|---|
| suborder_id | 是 | 子订单 ID |
| chain | 是 | 链 |
| address | 是 | 地址 |
| currency | 是 | 币种 |
| amount | 是 | 金额 |
| fee | 是 | 手续费 |
| txHash | 是 | 交易哈希 |
| status | 是 | DONE / FAIL |
| merchant_withdraw_id | 是 | 商户 提现 ID |
| fee_type | 是 | 0=内扣；1=外扣 |
| finish_time | 是 | 完成时间 |
| sub_amount | 是 | 子订单总金额 |
| done_amount | 是 | 实际完成金额 |
机构 API 回调
bizType: INSTITUTION
bizStatus: INSTITUTION_ACCOUNT_SUCCESS 或 INSTITUTION_ACCOUNT_FAIL
有关机构账户相关通知，请参见 机构。
data 字段（JSON 字符串）
| 字段 | 说明 |
|---|
| request_id | 请求标识 |
| account_id | 账户 ID |
| customer_id | 客户 ID |
| display_name | 账户显示名称 |
| status | ACTIVE 或 FAIL |
| created | 毫秒时间戳 |
回调接入指南
接入要求
| 项目 | 建议 |
|---|
| 接口 | 使用专用路径，例如 /webhook/gatepay |
| 协议 | HTTPS 与 TLS 1.2+ |
| 处理策略 | 验证签名 → 幂等存储 → 异步处理业务 → 返回 SUCCESS |
| 签名验证 | 签名验证失败时绝不返回 SUCCESS |
| data 解析 | data 字段是 JSON 字符串，需要进行二次解析 |
| 重复处理 | 使用幂等处理支持重复通知 |
推荐处理流程
- 接收 回调请求
- 验证 使用商户密钥验证签名，具体规则可参考 认证与安全
- 提取 并解析
data 字段 (JSON 字符串 → 对象)
- 检查 幂等键 （例如 transactionId 或 merchantTradeNo）
- 存储 处理前持久化存储通知
- 处理 异步处理业务逻辑
- 返回
{"returnCode": "SUCCESS", "returnMessage": ""} 并使用 HTTP 200
该设计可提高可靠性并避免重复处理.
相关文档
常见事件目录
事件处理建议
- 优先按
bizType 分流，不要假设所有回调都共享同一套字段
- 再按
bizStatus 判断当前状态是否为中间态或终态
- 最后结合
merchantTradeNo、refundRequestId、batch_id 等业务键做幂等更新
事件目录
| bizType | bizStatus | 业务含义 | 是否终态 | 推荐动作 |
|---|
PAY | PAY_SUCCESS | 非地址支付成功 | 是 | 更新订单为成功，触发发货或入账 |
PAY | PAY_ERROR | 非地址支付失败 | 是 | 标记失败，允许人工或系统重试 |
PAY | PAY_CLOSE | 订单关闭 | 是 | 结束业务流，停止继续轮询 |
PAY_REFUND | REFUND_PROCESS | 退款处理中 | 否 | 更新退款处理中状态，继续等待回调或查询 |
PAY_REFUND | REFUND_SUCCESS | 退款成功 | 是 | 更新退款完成状态并做资金对账 |
PAY_REFUND | REFUND_REJECTED | 退款拒绝 | 是 | 标记退款失败，进入人工排查 |
PAY_ADDRESS | PAY_SUCCESS | 地址支付成功 | 是 | 更新订单成功并记录链上支付信息 |
PAY_ADDRESS | PAY_EXPIRED_IN_PROCESS | 有效期内达到金额，但仍有未确认链上记录 | 否 | 持续等待确认，不应过早判定终态 |
TRANSFER_ADDRESS | TRANSFERRED_ADDRESS_IN_TERM | 有效期内完成入账 | 是 | 更新到账完成状态 |
TRANSFER_ADDRESS | TRANSFERRED_ADDRESS_DELAY | 延迟到账 | 是 | 更新延迟到账结果，并结合业务判断是否可接受 |
TRANSFER_ADDRESS | CONVERT_ADDRESS_PAY_DELAY | 闪兑地址支付延迟通知 | 否 | 继续结合订单模式与查询结果处理 |
TRANSFER_ADDRESS | TRANSFERRED_ADDRESS_BLOCK | 风控阻断资金 | 是 | 标记异常并转人工处理 |
PAY_FIXED_ADDRESS | PAY_SUCCESS | 静态地址收款成功 | 是 | 更新到账记录 |
PAY_FIXED_ADDRESS | PAY_BLOCK | 静态地址风控资金 | 是 | 标记异常并人工复核 |
WITHDRAW | INIT / PROCESSING | 出金批次处理中 | 否 | 更新处理中状态，等待后续回调 |
WITHDRAW | SUCCESS | 出金批次全部成功 | 是 | 更新批次成功并完成台账确认 |
WITHDRAW | PARTIAL | 出金批次部分成功 | 是 | 按子订单拆分处理成功与失败结果 |
WITHDRAW | FAIL | 出金批次失败 | 是 | 标记失败并进入重试或人工处理 |
INSTITUTION | INSTITUTION_ACCOUNT_SUCCESS | 子账户创建成功 | 是 | 记录子账户开通成功 |
INSTITUTION | INSTITUTION_ACCOUNT_FAIL | 子账户创建失败 | 是 | 记录失败原因并转人工排查 |
终态处理原则
对于终态事件，推荐同时满足以下条件后再推进后续业务：
- 签名验证通过
- 幂等校验通过
- 事件已经持久化
- 业务状态已经与本地订单、退款单或批次单一致
相关文档
