通知概览

​

阅读路径

1. 本页（通知概览） — 公共信封、重试、验签与 bizType 说明
2. 各业务通知子页 — 字段表与代码示例（本菜单「支付 / OTC / 提现 / 订阅 / 机构」分组）
3. Guide：通知 — 事件目录、终态处理与产品到 bizType 映射
4. 最佳实践 — 支付查单兜底、退款 10s 规则与安全建议

​

概述

• 投递方式：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，验签规则见 安全与签名。
2. 解析 data：凡使用标准信封的回调，data 均为 JSON 字符串，须 JSON.parse 后再读字段；提现（WITHDRAW） 无 data 字段，采用 main_order + suborders 专用结构（见 提现通知）。顶层 client_id / clientId 可能缺失或混用，以实际回调为准。
3. 应答：处理成功后返回 HTTP 200 及 JSON：{"returnCode":"SUCCESS","returnMessage":""}。返回 FAIL 或超时将触发重试。

​

消息结构

​

消息结构示例

{
  "bizType": "PAY",
  "bizId": "xxx",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "xxx",
  "data": "{...}"
}

​

bizType

​

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

​

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