跳转到主要内容
WEBHOOK
subscriptionOrderNotify
{
  "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\":\"\"}"
}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

​
概述

本页说明 webhook subscriptionOrderNotify。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。 订阅订单状态变更时，GatePay 向商户配置的 callback URL 发送异步通知（bizType 为 SUBSCRIPTION_ORDER_STATUS）。

​
说明

  • 建议基于 bizId 或 data.subscriptionOrderNo 做幂等处理。
  • 验签、重试、data 解析与成功应答见 通知概览；签名规则见 安全与签名。

​
触发情形

  • 订阅订单状态发生变更（创建、授权、运行、取消、关闭等）时，GatePay 向商户注册时配置的 callback URL 发送通知
  • 顶层 bizStatus 与解析 data 后的 orderStatus 取值一致
  • 若通知投递失败，重试规则见 通知概览。

​
消息结构

字段名类型说明
bizTypestring固定为 SUBSCRIPTION_ORDER_STATUS
bizIdstring订阅订单编号（通常与 data.subscriptionOrderNo 一致）
bizStatusstring订阅订单状态，见下表
datastring订阅订单明细 JSON 字符串

​
消息结构示例

{
  "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 字符串后，常见字段如下：
字段名类型说明
subscriptionOrderNostring订阅订单编号
merchantSubscriptionOrderNostring商户订阅订单编号
planNostring平台订阅计划编号
planNamestring订阅计划名称
planDescstring订阅计划描述
merchantIdstring创建订阅计划的商户编号
productNostring产品编号
productNamestring产品名称
cryptoCurrencystring加密货币币种
chainstring加密货币网络（无链上授权时可能为空）
userAddressstring用户授权地址
authorizedAmountstring授权额度
cryptoAmountstring单次扣款金额
paidCountinteger已扣款次数
totalPaidAmountstring已扣款总金额
paymentChannelstring支付渠道，常见取值：GATEPAY、WEB3（可能为空）
periodstring扣款周期，例如 MONTH、NONE
intervalinteger扣款间隔
totalPayCountinteger一共需要完成的扣款次数
trialDaysinteger试用天数
endTimeint64订阅自主结束时间（毫秒，未设置时为 0）
lastPayTimeint64最近一次扣款时间（毫秒，未扣款时为 0）
orderStatusstring订阅订单状态，与顶层 bizStatus 一致
createTimeint64订单创建时间（毫秒）
updateTimeint64订单更新时间（毫秒）

​
回调示例

​
运行中（bizStatus=RUNNING）

{
  "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）

{
  "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\":\"\"}"
}

请求体

application/json

订阅订单状态更新通知入参 POST方式

​
bizType
string

业务类型：SUBSCRIPTION_ORDER_STATUS

​
bizStatus
enum<string>

业务状态：订阅订单状态码，与 data.orderStatus 取值一致。

可用选项:
CREATED,
AUTHORIZED,
CONFIRMING,
TRIAL,
RUNNING,
UNPAID,
COMPLETED,
CANCELLED,
CLOSED,
BLOCKED
​
data
string

订阅订单明细 JSON 字符串。

​
bizId
string

订阅订单编号（通常与 data.subscriptionOrderNo 一致）。

响应

200 - application/json

返回 HTTP 200 表示已收到回调通知。

​
returnCode
string

响应码，SUCCESS表示成功 FAIL标识失败

​
returnMessage
string

响应描述，成功时为空