> ## 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 会向你配置的回调地址发送异步通知。本文档介绍通知结构、回调类型以及接入最佳实践。

## 处理要求

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

1. **先验证签名** ： 见 [认证与安全](/global/essentials/version/100/cn/common/authentication) 了解签名验证详情
2. **解析业务数据** 并进行幂等处理
3. **返回约定的成功响应**

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

## 建议处理顺序

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

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

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

## 触发与重试机制

**触发条件**
当订单状态发生变化（如支付成功、超时、取消、关闭或异常）时，GatePay 会向你配置的回调地址发送通知。

**重试**
如果你未返回约定的成功响应，或请求超时，GatePay 会按规则重试回调。

**签名验证**
处理前必须先验证所有回调签名。请参见 [认证与安全](/global/essentials/version/100/cn/common/authentication) 了解详情。

## 回调消息结构

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

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

**回调示例:**

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "6948484859590",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "cdhu-fgrfg44-5ggd-cdvsa",
  "data": "{\"merchantTradeNo\":\"M202603120001\",\"orderAmount\":\"100.00\"}"
}
```

## 回调确认响应

请以 HTTP 200 返回以下 JSON 响应:

```json theme={null}
{
  "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` 判断支付金额。有关支付接入的更多详情，请参见 [支付](/global/essentials/version/100/cn/inflow/payment/payment)。

***

## 退款通知

退款订单使用 `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 | 字符串 | 是 | 收款地址 |

**成功响应:**

```json theme={null}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}
```

***

## 提现 / 出款回调

有关提现和出金操作，请参见 [出金](/global/essentials/version/100/cn/outflow/payout) 了解详细回调结构和字段说明。

**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`

有关机构账户相关通知，请参见 [机构](/global/essentials/version/100/cn/internalflow/institution)。

### 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 字符串，需要进行二次解析 |
| **重复处理** | 使用幂等处理支持重复通知 |

### 推荐处理流程

1. **接收** 回调请求
2. **验证** 使用商户密钥验证签名，具体规则可参考 [认证与安全](/global/essentials/version/100/cn/common/authentication)
3. **提取** 并解析 `data` 字段 (JSON 字符串 → 对象)
4. **检查** 幂等键 （例如 transactionId 或 merchantTradeNo）
5. **存储** 处理前持久化存储通知
6. **处理** 异步处理业务逻辑
7. **返回** `{"returnCode": "SUCCESS", "returnMessage": ""}` 并使用 HTTP 200

该设计可提高可靠性并避免重复处理.

***

## 相关文档

* [认证与安全](/global/essentials/version/100/cn/common/authentication) ： 签名验证与安全实践
* [支付](/global/essentials/version/100/cn/inflow/payment/payment) ： 支付回调详情
* [出款](/global/essentials/version/100/cn/outflow/payout) ： 出款回调详情
* [机构 API](/global/essentials/version/100/cn/internalflow/institution) ： 机构回调详情

## 常见事件目录

## 事件处理建议

* 优先按 `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` | 子账户创建失败 | 是 | 记录失败原因并转人工排查 |

## 终态处理原则

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

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

## 相关文档

* [通知](/global/essentials/version/100/cn/common/notification)
* [快速开始](/global/essentials/version/100/cn/common/quickstart)
* [支付](/global/essentials/version/100/cn/inflow/payment/payment)
* [出金](/global/essentials/version/100/cn/outflow/payout)
* [OTC](/global/essentials/version/100/cn/otc)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.