> ## 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. # 订阅订单状态更新消息通知 > Subscription order status update notification ## 概述 本页说明 `webhook subscriptionOrderNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。 订阅订单状态变更时，GatePay 向商户配置的 callback URL 发送异步通知（`bizType` 为 `SUBSCRIPTION_ORDER_STATUS`）。 ## 说明 * 建议基于 `bizId` 或 `data.subscriptionOrderNo` 做幂等处理。 * 验签、重试、`data` 解析与成功应答见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。 ## 触发情形 * 订阅订单状态发生变更（创建、授权、运行、取消、关闭等）时，GatePay 向商户注册时配置的 **callback URL** 发送通知 * 顶层 `bizStatus` 与解析 `data` 后的 `orderStatus` 取值一致 * 若通知投递失败，重试规则见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)。 ## 消息结构 | 字段名 | 类型 | 说明 | | ----------- | ------ | ----------------------------------------- | | `bizType` | string | 固定为 `SUBSCRIPTION_ORDER_STATUS` | | `bizId` | string | 订阅订单编号（通常与 `data.subscriptionOrderNo` 一致） | | `bizStatus` | string | 订阅订单状态，见下表 | | `data` | string | 订阅订单明细 JSON 字符串 | ### 消息结构示例 ```json theme={null} { "bizType": "SUBSCRIPTION_ORDER_STATUS", "bizId": "79544752854007999", "bizStatus": "CANCELLED", "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"CANCELLED\",\"paidCount\":0,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}" } ``` ## bizStatus / orderStatus 枚举值 | 值 | 说明 | | ------------ | --- | | `CREATED` | 已创建 | | `AUTHORIZED` | 已授权 | | `CONFIRMING` | 确认中 | | `TRIAL` | 试用中 | | `RUNNING` | 运行中 | | `UNPAID` | 未支付 | | `COMPLETED` | 已完成 | | `CANCELLED` | 已取消 | | `CLOSED` | 已关闭 | | `BLOCKED` | 已冻结 | ## data 字段说明 解析 `data` JSON 字符串后，常见字段如下： | 字段名 | 类型 | 说明 | | ----------------------------- | ------- | -------------------------------- | | `subscriptionOrderNo` | string | 订阅订单编号 | | `merchantSubscriptionOrderNo` | string | 商户订阅订单编号 | | `planNo` | string | 平台订阅计划编号 | | `planName` | string | 订阅计划名称 | | `planDesc` | string | 订阅计划描述 | | `merchantId` | string | 创建订阅计划的商户编号 | | `productNo` | string | 产品编号 | | `productName` | string | 产品名称 | | `cryptoCurrency` | string | 加密货币币种 | | `chain` | string | 加密货币网络（无链上授权时可能为空） | | `userAddress` | string | 用户授权地址 | | `authorizedAmount` | string | 授权额度 | | `cryptoAmount` | string | 单次扣款金额 | | `paidCount` | integer | 已扣款次数 | | `totalPaidAmount` | string | 已扣款总金额 | | `paymentChannel` | string | 支付渠道，常见取值：`GATEPAY`、`WEB3`（可能为空） | | `period` | string | 扣款周期，例如 `MONTH`、`NONE` | | `interval` | integer | 扣款间隔 | | `totalPayCount` | integer | 一共需要完成的扣款次数 | | `trialDays` | integer | 试用天数 | | `endTime` | int64 | 订阅自主结束时间（毫秒，未设置时为 `0`） | | `lastPayTime` | int64 | 最近一次扣款时间（毫秒，未扣款时为 `0`） | | `orderStatus` | string | 订阅订单状态，与顶层 `bizStatus` 一致 | | `createTime` | int64 | 订单创建时间（毫秒） | | `updateTime` | int64 | 订单更新时间（毫秒） | ## 回调示例 ### 运行中（`bizStatus=RUNNING`） ```json theme={null} { "bizType": "SUBSCRIPTION_ORDER_STATUS", "bizId": "79544752854007999", "bizStatus": "RUNNING", "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"RUNNING\",\"paidCount\":2,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0.2\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}" } ``` ### 订单取消（`bizStatus=CANCELLED`） ```json theme={null} { "bizType": "SUBSCRIPTION_ORDER_STATUS", "bizId": "79544752854007999", "bizStatus": "CANCELLED", "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"CANCELLED\",\"paidCount\":0,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}" } ``` ## OpenAPI ````yaml api-reference/version/100/cn/openapi/subscription/orderNotify-openapi.json webhook subscriptionOrderNotify openapi: 3.1.0 info: title: GatePay 订阅 API version: 1.0.0 description: 订阅业务相关 Webhook 定义。 servers: [] security: [] paths: {} ````