> ## 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：通知](/global/essentials/version/100/cn/common/notification)** — 事件目录、终态处理与产品到 `bizType` 映射
4. **[最佳实践](/global/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`，验签规则见 [安全与签名](/global/api-reference/version/100/cn/common/securityAndSignature)。
2. **解析 `data`**：标准信封回调的 `data` 为 **JSON 字符串**，须 `JSON.parse` 后再读字段。**例外：** **提现（`WITHDRAW`）** 无 `data` 字段，采用 `main_order` + `suborders` 专用结构（见 [提现通知](/global/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：通知](/global/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` | 否 | 勿过早终态，继续链上确认 |
| `CHAIN_ADDRESS` | `PAY_PASSED` / `PAY_CONFIRMING` / `PAY_DONE` | 否 | 记录链上交易与验证过程中的状态 |
| `WITHDRAW` | `WITHDRAW_SUCCESS` / `WITHDRAW_PARTIAL` / `WITHDRAW_FAIL` | 是 | 按批次与子单分别对账 |
| `INSTITUTION` | `INSTITUTION_ACCOUNT_FAIL` | 是 | 记录失败并人工跟进 |

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

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

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


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