跳转到主要内容

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账户授权、商户自主决定何时扣款用户完成授权后，由商户按业务需要主动发起扣款
与一次性支付相比，订阅更关注长期状态管理。商户除完成下单与授权外，还需持续关注计划或授权范围、扣款结果、失败重试和订阅终止条件等。

​
标准接入流程

两类产品在主链路上一致：创建产品 → 创建订阅计划 → 创建订阅订单 → 引导用户授权；差异在授权成功之后： 
创建产品 -> 创建订阅计划 -> 创建订阅订单 -> 引导用户授权 -> [扣款阶段因 priceType 不同而分支] -> 查询与通知跟踪

​
扣款阶段分支说明

  • FIX_AMOUNT：授权成功后 → 周期扣款（按计划自动执行）→ 查询与通知跟踪
  • ACCOUNT_AUTH：授权成功后 → 商户按需发起扣款 → 查询与通知跟踪

​
最小可运行链路

首次接入建议先跑通最小链路，再补充试用期、首期优惠、终止条件等。 
创建产品 -> 创建计划 -> 创建订阅订单 -> 跳转 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 定义）：
  • subscriptionOrderNotifyWebhook：订阅订单状态更新通知
  • subscriptionOrderPaymentNotifyWebhook：支付扣款通知

​
接入建议

  • 订阅产品、计划和订单建议分别保存独立的业务标识，方便排查与对账。
  • 创建订单后，前端应尽快引导用户完成授权，降低授权前流失。
  • 首次接入建议把「订阅订单状态」与「扣款状态」作为两条独立业务线理解；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已扣款但资金存在风控风险

​
相关文档