> ## 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.

# 订阅

> 介绍订阅支付产品配置、计划管理、授权流程、扣款方式、周期或单次扣款查询与状态说明。

## 概述

订阅支付适用于会员、SaaS、周期性服务和其他需要持续授权与扣款的业务。订阅支付产品在能力上分为两类，通过产品价格上的 `priceType` 区分：

| `priceType`    | 产品能力            | 扣款方式                          |
| -------------- | --------------- | ----------------------------- |
| `FIX_AMOUNT`   | 固定金额、按订阅计划周期扣款  | 用户完成授权后，由系统按商户创建的订阅计划自动执行周期扣款 |
| `ACCOUNT_AUTH` | 账户授权、商户自主决定何时扣款 | 用户完成授权后，由商户按业务需要主动发起扣款        |

与一次性支付相比，订阅更关注长期状态管理。商户除完成下单与授权外，还需持续关注计划或授权范围、扣款结果、失败重试和订阅终止条件等。

## 标准接入流程

两类产品在主链路上一致：创建产品 → 创建订阅计划 → 创建订阅订单 → 引导用户授权；差异在授权成功之后：

```text theme={null} theme={null}
创建产品 -> 创建订阅计划 -> 创建订阅订单 -> 引导用户授权 -> [扣款阶段因 priceType 不同而分支] -> 查询与通知跟踪
```

### 扣款阶段分支说明

* **FIX\_AMOUNT**：授权成功后 → 周期扣款（按计划自动执行）→ 查询与通知跟踪
* **ACCOUNT\_AUTH**：授权成功后 → 商户按需发起扣款 → 查询与通知跟踪

## 最小可运行链路

首次接入建议先跑通最小链路，再补充试用期、首期优惠、终止条件等。

```text theme={null} theme={null}
创建产品 -> 创建计划 -> 创建订阅订单 -> 跳转 subscriptionLink 完成授权 -> 接收扣款通知 -> 查询订单与扣款详情确认结果
```

* **FIX\_AMOUNT**：完成上述链路后，重点观察计划周期内的自动扣款与失败重试。
* **ACCOUNT\_AUTH**：完成授权后，需在业务侧主动触发扣款并同样通过通知 + 查询确认结果。

### 第一步：创建产品

商户先创建订阅产品及其价格信息，用于定义订阅对象、计费币种和展示信息；选择价格时请指定 `priceType`，以确定后续是固定周期扣款还是授权后商户自主扣款。

核心接口：

* `POST /merchant/open/v1/pay/merchant/product/create`
* `GET /merchant/open/v1/pay/merchant/product/pageQuery`
* `GET /merchant/open/v1/pay/merchant/product/queryOne`

### 第二步：创建订阅计划

订阅计划用于定义与订阅相关的规则（如扣款周期、试用期、结束条件、优惠方式等）。创建计划时需关联前一步创建的产品或价格信息。

核心接口：

* `POST /open/v1/plan/save`
* `GET /open/v1/plan/list`
* `GET /open/v1/plan/detail`

### 第三步：创建订阅订单

用户确认购买后，由商户服务端创建订阅订单。接口返回的 `subscriptionLink` 用于引导用户进入授权页面。

核心接口：

* `POST /open/v1/order/create`
* `GET /open/v1/order/list`
* `GET /open/v1/order/detail`

### 第四步：引导用户完成授权

商户前端将用户重定向到 `subscriptionLink`，由用户完成授权。

* **FIX\_AMOUNT**：授权完成后，订阅进入计划约定的周期扣款阶段。
* **ACCOUNT\_AUTH**：授权完成后，获得账户扣款授权；后续由商户在服务端调用接口 `POST /open/v1/order/deduct` 触发扣款。

### 第五步：跟踪订单与扣款状态

订阅订单状态与每次扣款状态应优先通过通知获取，再用查询接口兜底确认。

核心接口：

* `GET /open/v1/deduction/order/list`
* `GET /open/v1/deduction/order/detail`
* `POST /open/v1/order/deduct`（`ACCOUNT_AUTH` 场景下商户主动扣款）

回调说明（详见 API Reference 中 Webhook 定义）：

* `subscriptionOrderNotify`：订阅订单状态更新通知
* `subscriptionOrderPaymentNotify`：支付扣款通知

## 接入建议

* 订阅产品、计划和订单建议分别保存独立的业务标识，方便排查与对账。
* 创建订单后，前端应尽快引导用户完成授权，降低授权前流失。
* 首次接入建议把「订阅订单状态」与「扣款状态」作为两条独立业务线理解；`ACCOUNT_AUTH` 还需区分「授权额度」与「已扣款总金额」。
* **FIX\_AMOUNT**：周期扣款是持续流程，不要仅凭单次 API 响应判断订阅长期是否正常。
* **ACCOUNT\_AUTH**：需在服务端建立授权有效期、扣款幂等与重试策略，避免重复或遗漏扣款。
* 若内部有用户中心或会员系统，建议将订阅状态与会员权益做显式映射，避免把单次支付结果直接等同于权益状态。

## 常见问题

### 订阅支付支持的币种和支付方式有哪些？

支持使用所有主流 Web3 钱包，或通过 Gate App 授权账户中的 USDT/USDC 进行订阅；如您已开通 Stripe 收款，我们也支持关联账户实现法币订阅支付。

### 订阅订单的有效期是多久？

订阅订单本身没有统一的有效期表述，它会根据配置的 `totalPayCount` 或 `endTime` 等终止条件结束；若均未配置，通常可视为长期订阅。

### 如何设置试用期？

创建订阅计划时可通过 `trialDays` 设置试用天数。试用期内不执行正式扣款，试用期结束后按产品与计划规则进入后续的扣款流程。

### 如何设置首期优惠？

针对订阅支付场景，在创建产品价格时可通过 `promoConfigType` 配置首期优惠：

* `FIX_AMOUNT`：设置 `promoAmount` 作为首期优惠金额
* `RATE`：设置 `promoRate` 作为首期折扣比例，例如 `0.1` 表示一折价格

### 订阅开始后如何手动结束？

商户可调用 `POST /open/v1/order/complete`，并设置 `operationType=FINISH` 结束订阅，结束后系统不再执行后续的扣款。

### ACCOUNT\_AUTH 模式下扣款由谁发起？

由商户根据业务需求在服务端主动触发，可调用 `POST /open/v1/order/deduct`，输入金额和币种发起扣款，并与通知、扣款查询接口校验状态。

## 订单状态说明

| 状态           | 说明                    |
| ------------ | --------------------- |
| `CREATED`    | 订阅订单已创建，等待用户授权        |
| `AUTHORIZED` | 已完成授权，等待首次扣款或等待商户发起扣款 |
| `CONFIRMING` | 确认中，首次确认订阅时等待扣款结果     |
| `TRIAL`      | 处于试用期内，尚未开始扣款         |
| `RUNNING`    | 订阅正常运行中，等待系统或由商户发起扣款  |
| `UNPAID`     | 当前扣款失败，但尚未达到关闭条件      |
| `COMPLETED`  | 已达到结束条件，或由商户手动完成      |
| `CANCELLED`  | 已被商户取消                |
| `CLOSED`     | 因异常情况关闭，例如扣款失败次数超限    |
| `BLOCKED`    | 已扣款但资金存在风控风险          |

## 相关文档

* [支付](/essentials/version/100/cn/inflow/payment/payment)
* [通知](/essentials/version/100/cn/common/notification)
* [认证](/essentials/version/100/cn/common/authentication)
* [错误](/essentials/version/100/cn/common/error)
* [API Reference](/api-reference/version/100/cn/introduction)