通知概览 - Gate Pay DOCS

阅读路径

建议按以下顺序接入通知能力：

当订单状态发生变化时（如支付成功、超出支付时间、订单取消、关闭或异常等），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 等业务唯一标识做幂等处理。

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

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

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

bizType	说明
`PAY`	Gate 支付订单状态
`PAY_FIAT`	法币支付订单状态
`PAY_ADDRESS` / `TRANSFER_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：通知。

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`	是	标记异常，勿入账
`PAY_FIXED_ADDRESS`	`PAY_BLOCK`	是	风险资金，勿入账
`WITHDRAW`	`WITHDRAW_SUCCESS` / `WITHDRAW_PARTIAL` / `WITHDRAW_FAIL`	是	按批次与子单分别对账
`INSTITUTION`	`INSTITUTION_ACCOUNT_FAIL`	是	记录失败并人工跟进

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