订阅支付

这一页讲周期性收费。订单、Session 和 Webhook 那套基础和一次性支付完全一样，先看过 Hosted Checkout 接入会顺很多。

先选路径

三种场景，走的接口不一样：

场景	走哪条	说明
新客户，或客户还没有可复用的支付工具	周期价格 + Checkout Session	推荐。客户在收银台里自己选支付方式并授权
已有 Clink Customer 和可用 Payment Instrument	`POST /subscription`	服务端直接建订阅并发起首笔付款
已有活跃订阅，客户要换卡、取消、升降级、看账单	`POST /billing/session`	优先交给客户门户；服务端自动化再用查询和更新 API

POST /checkout/session 和 POST /subscription 不是同一个接口的两种写法。前者给客户一个可交互的收银台，后者是服务端在已有客户和支付工具时直接下单。

一、准备周期性商品和价格

订阅必须用预先注册的 Product 和周期价格。priceDataList 那种临时商品建不了订阅。

{
  "productId": "prd_xxxxx",
  "currency": "USD",
  "unitAmount": 29.99,
  "priceType": "recurring",
  "recurringDetails": {
    "interval": "month",
    "intervalCount": 1,
    "trialPeriodDays": 7,
    "pricingModel": "flat_rate"
  },
  "isDefaultPrice": true
}

interval 支持 day、week、month、year、quarter、half_year、custom。

quarter 和 half_year 是平台自己算周期边界的，你不用把它换算成 3 个月或 6 个月再传。只有 interval 为 custom 时，intervalCount 才表示天数。

这一页的示例只用月付的 flat_rate 固定价。其他计费模式见创建价格的字段说明。

二、推荐路径：用 Checkout 创建首次订阅

结构和一次性支付一模一样——后端建 Session、前端打开收银台、Webhook 更新本地状态。只是把临时商品换成了周期价格。

{
  "customerEmail": "buyer@example.com",
  "merchantReferenceId": "membership_10001",
  "productId": "prd_xxxxx",
  "priceId": "price_xxxxx",
  "originalAmount": 29.99,
  "originalCurrency": "USD",
  "uiMode": "hostedPage",
  "successUrl": "https://merchant.example.com/subscription/success",
  "cancelUrl": "https://merchant.example.com/subscription/cancel"
}

金额和币种仍然要传，后端会校验它们和 Product/Price 一致。

创建 Session 的那一刻，订阅还不存在，钱也还没收到。客户提交支付后，收银台按周期价格走订阅流程，产生 Subscription、Invoice 和 Order 三个对象。浏览器跳回 successUrl 只表示交互结束——最终状态要查接口，并结合验签后的 Webhook 更新。

三、服务端路径：直接创建订阅

客户已经有 Clink Customer 和可用支付工具时用这条。

{
  "customerId": "cus_xxxxx",
  "merchantReferenceId": "membership_10002",
  "productId": "prd_xxxxx",
  "priceId": "price_xxxxx",
  "paymentInstrumentId": "pi_xxxxx",
  "paymentMethodType": "CARD",
  "paymentCurrency": "USD",
  "returnUrl": "https://merchant.example.com/subscription/return"
}

customerId、customerEmail、referenceCustomerId 至少给一个。周期价格必须属于当前商户，并且支持你传的 paymentCurrency。

某种支付方式能不能用于订阅，还受商户渠道配置和币种限制影响。上线前按你自己账户实际启用的方式逐一验证，别照抄一张通用清单。

返回里的 status 是数字，表示这一次付款的结果：

`status`	含义	你该做什么
`1`	本次支付成功	等对应的 Webhook 并幂等处理。不能只凭这个返回就开通权益
`2`	处理中	显示处理中并继续查询。不要当成失败去重新扣款
`3`	失败	记下失败结果，引导客户换支付方式或重试
`5`	需要客户再操作一步	按返回的 `action` 打开跳转、二维码或其他验证

响应还会带回 subscriptionId、sessionId、paymentInstrumentId、orderId 和 invoiceId。这五个都存进你自己的订阅记录——后面查询和对账时，只靠其中一个字段会不够用。

四、订阅状态怎么映射到权益

这是接订阅时最容易做错的地方。付款状态和权益状态是两件事。

订阅状态	含义	本地权益怎么处理
`incomplete`	订阅建了，首次付款还没完成	不要开通付费权益
`free_trial`	在免费试用期内	按你的试用规则开通，记下 `trialEnd`
`active`	订阅有效，当前没有未结账单	保持权益开启
`past_due`	续费失败，系统还可能重试	按你的宽限期策略处理。不是已支付，也不要立刻再发起一笔扣款
`incomplete_expired`	首次订阅没完成，超时关闭了	关掉这条没生效的订阅流程
`cancelled`	订阅已终止	到实际终止时间再回收权益

不要拿 subscription.created 当作开通付费权益的信号。 它只说明订阅记录建出来了。免费试用由 subscription.trialing 驱动；首笔付款和续费要结合 subscription.activated、invoice.paid 和查询结果做幂等流转。权益变化要落到你自己的订阅和账单记录上，不能只更新一个订单状态——订阅是持续关系，一个订单号装不下。

五、要订阅哪些事件

一次性支付那套 order.* 仍然有效，订阅再加下面这些。 生命周期 subscription.created、subscription.trialing、subscription.activated、subscription.past_due、subscription.incomplete_expired、subscription.cancelled 套餐变更 subscription.updated.plan_changed、subscription.updated.plan_change_canceled、subscription.updated.renewed、subscription.updated.cancel_at_period_end_set、subscription.updated.cancel_at_period_end_revoked 账单 invoice.open、invoice.paid、invoice.void

订阅时必须写完整的事件名。subscription.* 和 invoice.* 这类通配符不是能提交给 API 的值。

事件会重试，也不保证顺序。处理器至少要做到：

按 event.id 原子去重
乱序到达时按订阅状态优先级处理，别让旧事件覆盖新状态
同一个 invoiceId 的履约动作只执行一次

验签、去重和订单匹配的写法见 Hosted Checkout 接入。

六、取消

{
  "reason": "客户主动取消",
  "cancelReasonCode": "no_longer_needed",
  "cancelImmediately": false
}

reason 必填，1 到 255 个字符。cancelReasonCode 可选，取值为 too_expensive、need_more_features、found_alternative、no_longer_needed、poor_customer_service、poor_usability、poor_quality、other_reasons。 cancelImmediately 省略或传 false 时，订阅在当前周期结束时取消；传 true 立即取消。

取消不等于退款。 立即取消不会自动退还本期已收的钱。要退款得单独调退款接口。

七、升降级

必须先预览再确认，两步都要传 quantity。 第一步：预览

{
  "priceId": "price_yyyyy",
  "quantity": 1,
  "promotionCode": "WELCOME20"
}

第二步：用预览返回的 priceSnapshotId 确认

{
  "priceSnapshotId": "snap_xxxxx",
  "quantity": 1,
  "promotionCode": "WELCOME20"
}

用了优惠码的话，预览和确认要传同一个码，否则金额对不上。 immediate: true 的变更可能产生补差价付款并返回 action；false 表示预约到下一个账期边界生效。待生效的变更可以调 POST /subscription/{id}/update/cancel 撤销。

当前 API Reference 里 preview 和 confirm 的请求体示例漏了 quantity，但服务端把它列为必填。以这一页为准，两个请求都要传。

八、计划阶段

scheduledPhases 可以让订阅在未来的续费边界自动切套餐，最多 10 个阶段，sequence 和 effectiveCycle 都从 1 开始且严格递增。这是进阶能力，首次接入用不上。字段说明见结账会话。

开始使用

接入

配置与上线

介绍

财务信息

先选路径

一、准备周期性商品和价格

二、推荐路径：用 Checkout 创建首次订阅

三、服务端路径：直接创建订阅

四、订阅状态怎么映射到权益

五、要订阅哪些事件

六、取消

七、升降级

八、计划阶段

接下来

优惠与促销码

上线检查

​先选路径

​一、准备周期性商品和价格

​二、推荐路径：用 Checkout 创建首次订阅

​三、服务端路径：直接创建订阅

​四、订阅状态怎么映射到权益

​五、要订阅哪些事件

​六、取消

​七、升降级

​八、计划阶段

​接下来

优惠与促销码

上线检查

先选路径

一、准备周期性商品和价格

二、推荐路径：用 Checkout 创建首次订阅

三、服务端路径：直接创建订阅

四、订阅状态怎么映射到权益

五、要订阅哪些事件

六、取消

七、升降级

八、计划阶段

接下来