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

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

## 建议处理顺序

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

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

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

## 触发与重试机制

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

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

**签名验证**
处理前必须先验证所有回调签名。请参见 [认证与安全](/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` 判断支付金额。有关支付接入的更多详情，请参见 [支付](/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   | 非兑换 / 兑换 | 商户 订单号           |
| 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`，接入时建议按兼容方式解析。

### 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` （入账成功） 或 `PAY_BLOCK` （风险资金，未入账）

### data 字段

| 字段              | 类型  | 必填 | 说明                              |
| --------------- | --- | -- | ------------------------------- |
| channel\_id     | 字符串 | 是  | 渠道标识（蛇形命名；历史回调亦可能为 `channelId`） |
| currency        | 字符串 | 是  | 币种                              |
| orderAmount     | 字符串 | 否  | 订单金额                            |
| amount          | 字符串 | 是  | 实际入账金额                          |
| createTime      | 数字  | 是  | 创建时间 （毫秒）                       |
| transactionId   | 字符串 | 是  | 平台交易 ID                         |
| transactionTime | 数字  | 是  | 交易时间 （毫秒）                       |
| chain           | 字符串 | 是  | 链名称                             |
| address         | 字符串 | 是  | 收款地址                            |

**成功响应:**

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

***

## 提现 / 出款回调

有关提现和出金操作，请参见 [出金](/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`

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

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

***

## 相关文档

* [认证与安全](/essentials/version/100/cn/common/authentication) ： 签名验证与安全实践
* [支付](/essentials/version/100/cn/inflow/payment/payment) ： 支付回调详情
* [出款](/essentials/version/100/cn/outflow/payout) ： 出款回调详情
* [机构 API](/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`   | 闪兑地址支付延迟通知          | 否    | 继续结合订单模式与查询结果处理       |
| `TRANSFER_ADDRESS`  | `TRANSFERRED_ADDRESS_BLOCK`   | 风控阻断资金              | 是    | 标记异常并转人工处理            |
| `CHAIN_ADDRESS`     | `PAY_PASSED`                  | 链上交易合规验证通过          | 否    | 记录链上交易与验证过程中的状态       |
| `CHAIN_ADDRESS`     | `PAY_CONFIRMING`              | 链上交易开始同步            | 否    | 记录链上交易与验证过程中的状态       |
| `CHAIN_ADDRESS`     | `PAY_DONE`                    | 链上交易已确认             | 否    | 记录链上交易与验证过程中的状态       |
| `PAY_FIXED_ADDRESS` | `PAY_SUCCESS`                 | 静态地址收款成功            | 是    | 更新到账记录                |
| `PAY_FIXED_ADDRESS` | `PAY_BLOCK`                   | 静态地址风控资金            | 是    | 标记异常并人工复核             |
| `WITHDRAW`          | `WITHDRAW_SUCCESS`            | 出金批次全部成功            | 是    | 更新批次成功并完成台账确认         |
| `WITHDRAW`          | `WITHDRAW_PARTIAL`            | 出金批次部分成功            | 是    | 按子订单拆分处理成功与失败结果       |
| `WITHDRAW`          | `WITHDRAW_FAIL`               | 出金批次失败              | 是    | 标记失败并进入重试或人工处理        |
| `INSTITUTION`       | `INSTITUTION_ACCOUNT_SUCCESS` | 子账户创建成功             | 是    | 记录子账户开通成功             |
| `INSTITUTION`       | `INSTITUTION_ACCOUNT_FAIL`    | 子账户创建失败             | 是    | 记录失败原因并转人工排查          |

## 终态处理原则

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

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

## 相关文档

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