> ## 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. **本页（通知概览）** — 公共信封、重试、验签与 `bizType` 说明
2. **各业务通知子页** — 字段表与代码示例（本菜单「支付 / OTC / 提现 / 订阅 / 机构」分组）
3. **[Guide：通知](/essentials/version/100/cn/common/notification)** — 事件目录、终态处理与产品到 `bizType` 映射
4. **[最佳实践](/api-reference/version/100/cn/common/bestPractices)** — 支付查单兜底、退款 10s 规则与安全建议

## 概述

当订单状态发生变化时（如支付成功、超出支付时间、订单取消、关闭或异常等），GatePay 会向商户注册时配置的 **callback URL** 发送异步 POST 通知。

* **投递方式**：GatePay 以 POST 方式向 callback URL 发送 JSON 格式通知。
* **重试机制**：若因网络或其他原因导致通知失败，GatePay 将在 **15 秒（2 次）/ 30 秒 / 3 分钟 / 10 分钟 / 20 分钟 / 30 分钟（3 次）/ 60 分钟 / 3 小时（3 次）/ 6 小时（2 次）** 后重试。若重试仍失败，商户可通过相应查询接口获取最新状态。
* **幂等要求**：同一业务事件可能被多次投递，须基于 `bizId`、`merchantTradeNo` 等业务唯一标识做幂等处理。

## 处理要求

1. **验签**：收到通知后必须先校验签名，再处理业务。请求头包含 `X-GatePay-Timestamp`、`X-GatePay-Nonce`、`X-GatePay-Signature`，验签规则见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。
2. **解析 `data`**：凡使用标准信封的回调，`data` 均为 **JSON 字符串**，须 `JSON.parse` 后再读字段；**提现（`WITHDRAW`）** 无 `data` 字段，采用 `main_order` + `suborders` 专用结构（见 [提现通知](/api-reference/version/100/cn/endpoint/withdraw/callback)）。顶层 `client_id` / `clientId` 可能缺失或混用，以实际回调为准。
3. **应答**：处理成功后返回 HTTP 200 及 JSON：`{"returnCode":"SUCCESS","returnMessage":""}`。返回 `FAIL` 或超时将触发重试。

## 消息结构

| 字段                    | 说明                                  |
| --------------------- | ----------------------------------- |
| bizType               | 业务类型                                |
| bizId                 | 业务 ID                               |
| bizStatus             | 业务状态                                |
| client\_id / clientId | 应用 ClientId（字段名以实际为准，可能缺失）          |
| data                  | 业务数据 JSON 字符串（`WITHDRAW` 除外，见提现通知页） |

### 消息结构示例

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "xxx",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "xxx",
  "data": "{...}"
}
```

## bizType

| bizType                                           | 说明           |
| ------------------------------------------------- | ------------ |
| `PAY`                                             | Gate 支付订单状态  |
| `PAY_FIAT`                                        | 法币支付订单状态     |
| `PAY_ADDRESS`                                     | 地址支付订单状态     |
| `TRANSFER_ADDRESS`                                | 地址支付资金到账     |
| `CHAIN_ADDRESS`                                   | 地址支付链上交易生命周期 |
| `PAY_FIXED_ADDRESS`                               | 静态地址收款       |
| `FIXED_ADDRESS_RISK`                              | 静态地址风险       |
| `PAY_REFUND`                                      | 退款状态         |
| `PAY_BATCH`                                       | 批量转账 / 奖励    |
| `PAY_GIFT_BATCH`                                  | 礼品卡批量支付      |
| `PAY_UNRESOLVED`                                  | 异常支付         |
| `INSTITUTION`                                     | 机构子账户创建结果    |
| `OTC`                                             | OTC 入金 / 出金  |
| `WITHDRAW`                                        | 提现 / 出金批次    |
| `SUBSCRIPTION_ORDER_STATUS`                       | 订阅订单状态       |
| `SUBSCRIPTION_PAYMENT` / `ACCOUNT_AUTH_DEDUCTION` | 订阅扣款 / 授权扣款  |

## 常见终态与建议动作（摘要）

完整事件目录见 [Guide：通知](/essentials/version/100/cn/common/notification#事件目录)。

| bizType             | bizStatus（示例）                                             | 是否终态 | 建议动作            |
| ------------------- | --------------------------------------------------------- | ---- | --------------- |
| `PAY` / `PAY_FIAT`  | `PAY_SUCCESS`                                             | 是    | 标记支付成功并履约       |
| `PAY` / `PAY_FIAT`  | `PAY_ERROR` / `PAY_CLOSE`                                 | 是    | 标记失败或关闭，停止轮询    |
| `PAY_REFUND`        | `REFUND_PROCESS`                                          | 否    | 标记处理中，等待后续通知或查单 |
| `PAY_REFUND`        | `REFUND_SUCCESS` / `REFUND_REJECTED`                      | 是    | 完成退款或对账 / 人工处理  |
| `PAY_ADDRESS`       | `PAY_EXPIRED_IN_PROCESS`                                  | 否    | 勿过早终态，继续链上确认    |
| `TRANSFER_ADDRESS`  | `TRANSFERRED_ADDRESS_BLOCK`                               | 是    | 标记异常，勿入账        |
| `CHAIN_ADDRESS`     | `PAY_PASSED` / `PAY_CONFIRMING` / `PAY_DONE`              | 否    | 记录链上交易与验证过程中的状态 |
| `PAY_FIXED_ADDRESS` | `PAY_BLOCK`                                               | 是    | 风险资金，勿入账        |
| `WITHDRAW`          | `WITHDRAW_SUCCESS` / `WITHDRAW_PARTIAL` / `WITHDRAW_FAIL` | 是    | 按批次与子单分别对账      |
| `INSTITUTION`       | `INSTITUTION_ACCOUNT_FAIL`                                | 是    | 记录失败并人工跟进       |

## bizStatus 枚举值（支付 / 地址类）

| 值                              | 说明                          |
| ------------------------------ | --------------------------- |
| PAY\_SUCCESS                   | 支付成功                        |
| PAY\_ERROR                     | 支付异常                        |
| PAY\_CLOSE                     | 支付关闭                        |
| PAY\_BLOCK                     | 固定地址收款审核 / 风险阻塞             |
| REFUND\_SUCCESS                | 退款成功                        |
| REFUND\_PROCESS                | 退款处理中                       |
| REFUND\_REJECTED               | 退款拒绝                        |
| PAY\_EXPIRED\_IN\_PROCESS      | 有效期内已达金额但存在未确认链上记录          |
| TRANSFERRED\_ADDRESS\_IN\_TERM | 有效期内地址划转入账                  |
| TRANSFERRED\_ADDRESS\_DELAY    | 延迟地址划转入账                    |
| CONVERT\_ADDRESS\_PAY\_DELAY   | 换币地址支付延迟                    |
| TRANSFERRED\_ADDRESS\_BLOCK    | 地址划转阻塞                      |
| PAY\_PASSED                    | 链上交易合规验证通过（`CHAIN_ADDRESS`） |
| PAY\_CONFIRMING                | 链上交易开始同步（`CHAIN_ADDRESS`）   |
| PAY\_DONE                      | 链上交易已确认（`CHAIN_ADDRESS`）    |
| PAID                           | 批量订单已支付                     |
| RISK\_ADDRESS                  | 固定地址风险                      |

订阅、OTC、机构、异常支付等专用 `bizStatus` 见对应子页。