通知 - Gate Pay DOCS

处理要求

对于每一笔收到的回调，你都必须：

先验证签名 ：见认证与安全了解签名验证详情
解析业务数据 并进行幂等处理
返回约定的成功响应

由于同一业务事件可能被重复投递，因此你必须基于业务唯一标识实现幂等处理。

建议处理顺序

为了降低误更新、重复入账或过早判定终态的风险，建议按以下顺序处理回调：

校验请求头与签名
解析 bizType、bizId、bizStatus
对业务唯一标识做幂等检查
更新本地业务状态
返回成功响应
对关键资金事件结合查询接口做最终确认

对于支付、OTC、出金等资金相关场景，回调通常应被视为主要事件来源，但关键结果仍建议结合查询接口做最终核验。

触发与重试机制

触发条件 当订单状态发生变化（如支付成功、超时、取消、关闭或异常）时，GatePay 会向你配置的回调地址发送通知。重试如果你未返回约定的成功响应，或请求超时，GatePay 会按规则重试回调。 签名验证 处理前必须先验证所有回调签名。请参见认证与安全了解详情。

回调消息结构

所有回调都包含以下顶层字段:

字段	类型	说明
bizType	字符串	通知类别（见 bizType 枚举）
bizId	字符串	订单 ID 或业务 ID
bizStatus	字符串	业务状态 (因 bizType 而异)
client_id	字符串	商户 client_id
data	字符串	以 JSON 字符串表示的业务载荷；须 `JSON.parse` 后使用。`WITHDRAW` 回调不使用本字段。结构因 `bizType` 而异，见各通知子页 `data` 字段说明。

回调示例:

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

建议使用 HTTP 200 状态码表示已成功接收.

bizType 枚举

取值	说明
PAY	非地址支付订单的状态变更
PAY_REFUND	退款订单的状态变更
PAY_BATCH	批量奖励订单的状态变更
PAY_GIFT_BATCH	批量礼品卡支付的状态变更
PAY_ADDRESS	地址支付订单的状态变更
TRANSFER_ADDRESS	地址支付资金流水通知
CHAIN_ADDRESS	地址支付链上交易生命周期通知
PAY_FIXED_ADDRESS	静态地址收款通知
WITHDRAW	提现 / 出款状态变更
INSTITUTION	机构 API 账户相关通知

总体说明

通知章节用于说明所有支付、退款、地址收款、静态地址收款、出金与机构相关回调的共性规则。
每类业务的详细回调字段解释，仍应以对应产品章节中的接入说明与 API Reference 共同理解。
如果你的业务同时接入多种支付方式，请务必按照 bizType 分流处理，不要假设所有订单都共用同一回调字段集合。
不建议仅依据单次回调立即完成财务终态确认；对于关键资金动作，建议结合查单或详情查询接口完成最终核验。

支付产品与 bizType 对应关系

如果你的业务同时接入多种支付产品，建议先按“产品类型 -> bizType”建立内部映射：

产品或场景	主要 bizType	说明
托管收银台、Web 拉起、普通非地址支付	`PAY`	用于非地址类支付订单状态通知
退款	`PAY_REFUND`	用于退款状态推进
地址支付	`PAY_ADDRESS`	用于地址支付订单状态变化
地址支付资金到账	`TRANSFER_ADDRESS`	用于地址支付资金入账、延迟到账或风控状态
地址支付链上交易生命周期	`CHAIN_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	非兑换 / 兑换	商户订单号
originalMerchantTradeNo	非兑换 / 兑换	关联的原始商户订单号（补单场景有值）
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	仅兑换延迟支付通知，不入账

TRANSFER_ADDRESS data 字段

字段	说明
merchantTradeNo	商户订单号
originalMerchantTradeNo	关联的原始商户订单号（补单场景有值）
originalOrderId	关联的原始订单 ID（补单场景有值）
currency	币种
orderAmount	订单金额
createTime	创建时间
transactionId	平台交易 ID
transferAmount	链上转账金额
txHash	区块链交易哈希
chain	链名称
address	地址
channelId	渠道标识

说明：历史或不同业务流中，交易哈希字段可能表现为 txHash、tx_hash 或 hash，接入时建议按兼容方式解析。

CHAIN_ADDRESS 状态枚举

状态	说明
PAY_PASSED	链上交易合规验证通过
PAY_CONFIRMING	链上交易开始同步
PAY_DONE	链上交易已确认

CHAIN_ADDRESS data 字段

字段	类型	说明
merchantTradeNo	string	商户订单号
productType	string	创建订单时的 `goodsType`
productName	string	创建订单时的 `goodsName`
clientId	string	商户 `client_id`
tradeType	string	创建订单时的 `terminalType`
goodsName	string	商品名称
terminalType	string	终端类型
currency	string	订单币种
orderAmount	number	订单金额
payerId	int64	支付用户 UID
createTime	int64	订单创建时间（毫秒）
transferAmount	number	链上到账金额
txHash	string	链上交易 Hash
channelId	string	客户名称
chain	string	网络
address	string	收款地址
fromAddress	string	付款方地址
passedTime	int64	链上交易合规验证通过时间（毫秒）；`bizStatus=PAY_PASSED` 时返回
confirmingTime	int64	链上交易开始同步时间（毫秒）；`bizStatus=PAY_CONFIRMING` 时返回
doneTime	int64	链上交易已确认时间（毫秒）；`bizStatus=PAY_DONE` 时返回

静态地址收款通知

bizType: PAY_FIXED_ADDRESS bizStatus: PAY_SUCCESS （入账成功）

data 字段

字段	类型	必填	说明
channel_id	字符串	是	渠道标识（蛇形命名；历史回调亦可能为 `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 字符串，需要进行二次解析
重复处理	使用幂等处理支持重复通知

常见事件目录

事件处理建议

优先按 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`	闪兑地址支付延迟通知	否	继续结合订单模式与查询结果处理
`CHAIN_ADDRESS`	`PAY_PASSED`	链上交易合规验证通过	否	记录链上交易与验证过程中的状态
`CHAIN_ADDRESS`	`PAY_CONFIRMING`	链上交易开始同步	否	记录链上交易与验证过程中的状态
`CHAIN_ADDRESS`	`PAY_DONE`	链上交易已确认	否	记录链上交易与验证过程中的状态
`PAY_FIXED_ADDRESS`	`PAY_SUCCESS`	静态地址收款成功	是	更新到账记录
`WITHDRAW`	`WITHDRAW_SUCCESS`	出金批次全部成功	是	更新批次成功并完成台账确认
`WITHDRAW`	`WITHDRAW_PARTIAL`	出金批次部分成功	是	按子订单拆分处理成功与失败结果
`WITHDRAW`	`WITHDRAW_FAIL`	出金批次失败	是	标记失败并进入重试或人工处理
`INSTITUTION`	`INSTITUTION_ACCOUNT_SUCCESS`	子账户创建成功	是	记录子账户开通成功
`INSTITUTION`	`INSTITUTION_ACCOUNT_FAIL`	子账户创建失败	是	记录失败原因并转人工排查

终态处理原则

对于终态事件，推荐同时满足以下条件后再推进后续业务：

签名验证通过
幂等校验通过
事件已经持久化
业务状态已经与本地订单、退款单或批次单一致

通知

处理要求

建议处理顺序

触发与重试机制

回调消息结构

回调确认响应

bizType 枚举

总体说明

支付产品与 bizType 对应关系

托管收银台支付通知

退款通知

地址支付通知

PAY_ADDRESS 状态枚举

PAY_ADDRESS data 字段

TRANSFER_ADDRESS 状态枚举

TRANSFER_ADDRESS data 字段

CHAIN_ADDRESS 状态枚举

CHAIN_ADDRESS data 字段

静态地址收款通知

data 字段

提现 / 出款回调

主单字段

子订单字段

机构 API 回调

data 字段（JSON 字符串）

回调接入指南

接入要求

推荐处理流程

相关文档

常见事件目录

事件处理建议

事件目录

终态处理原则

相关文档

​处理要求

​建议处理顺序

​触发与重试机制

​回调消息结构

​回调确认响应

​bizType 枚举

​总体说明

​支付产品与 bizType 对应关系

​托管收银台支付通知

​退款通知

​地址支付通知

​PAY_ADDRESS 状态枚举

​PAY_ADDRESS data 字段

​TRANSFER_ADDRESS 状态枚举

​TRANSFER_ADDRESS data 字段

​CHAIN_ADDRESS 状态枚举

​CHAIN_ADDRESS data 字段

​静态地址收款通知

​data 字段

​提现 / 出款回调

​主单字段

​子订单字段

​机构 API 回调

​data 字段（JSON 字符串）

​回调接入指南

​接入要求

​推荐处理流程

​相关文档

​常见事件目录

​事件处理建议

​事件目录

​终态处理原则

​相关文档

处理要求

建议处理顺序

触发与重试机制

回调消息结构

回调确认响应

bizType 枚举

总体说明

支付产品与 bizType 对应关系

托管收银台支付通知

退款通知

地址支付通知

PAY_ADDRESS 状态枚举

PAY_ADDRESS data 字段

TRANSFER_ADDRESS 状态枚举

TRANSFER_ADDRESS data 字段

CHAIN_ADDRESS 状态枚举

CHAIN_ADDRESS data 字段

静态地址收款通知

data 字段

提现 / 出款回调

主单字段

子订单字段

机构 API 回调

data 字段（JSON 字符串）

回调接入指南

接入要求

推荐处理流程

相关文档

常见事件目录

事件处理建议

事件目录

终态处理原则

相关文档