> ## 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` 解析与成功应答见 [通知概览](/global/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/global/api-reference/version/100/cn/common/securityAndSignature)。

## 触发情形

* 订阅订单状态发生变更（授权、运行、取消、关闭等）时，GatePay 向商户注册时配置的 **callback URL** 发送通知
* 顶层 `bizStatus` 与解析 `data` 后的 `orderStatus` 取值一致
* `bizStatus=CREATED` 时不会发送通知
* 若通知投递失败，重试规则见 [通知概览](/global/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 枚举值

| 值 | 说明 |
| - | - |
| `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 global/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: {}

````

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