集成订阅

本指南将带您完成创建订阅、激活订阅，并让续订自动运行的全过程——涵盖无试用期和有试用期两种流程。

前提条件

您需要从 Tokenz 控制台获取 API 密钥。如果您尚未集成一次性付款，请参见结账——订阅构建在同一套 Checkout Session 流程之上。

1. 创建订阅结账会话

创建一个包含 subscription 字段块的 Checkout Session，用于指定周期性合约的详情。订阅结账只允许包含一个未打折的商品。

bash

curl --request POST \
  --url https://api.tokenz.one/v2/checkoutsession \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "itemDetails": [{
      "product": {
        "price": { "amount": 1000, "currency": "USD" },
        "quantity": 1,
        "label": "Pro Plan (Monthly)",
        "images": ["https://example.com/pro-plan.png"],
        "taxCategory": "SAAS"
      }
    }],
    "subscription": {
      "interval": { "unit": "MONTH", "count": 1 },
      "trialPeriodDays": 7,
      "dunningMode": "RETRY"
    },
    "successUrl": "https://example.com/success",
    "pendingUrl": "https://example.com/pending",
    "cancelUrl": "https://example.com/cancel",
    "customerInfo": {
      "emailAddress": "consumer@example.com"
    }
  }'

订阅参数

interval（必填）：计费间隔，为一个包含 unit（WEEK、MONTH 或 YEAR）和 count（不小于 1 的整数，表示两次续订之间的单位数）的对象。例如 { "unit": "MONTH", "count": 1 } 表示每月续订。
trialPeriodDays（可选，1–365）：首次扣款前的天数。若无试用期则省略此字段。
dunningMode（可选）：RETRY（默认）或 CANCEL_IMMEDIATELY。参见生命周期与计费。
dunningMaxAttempts（可选，默认 3）、dunningExpireAfterHours（可选，默认 24）：仅当 dunningMode 为 RETRY 时使用。

响应

json

{
  "id": "checkoutsession_1p4LPTRKB5Z",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/1p4LPTRKB5Z",
  "test": false,
  "subscription": {
    "id": "subscription_1p4LS47fB1h",
    "object": "subscription",
    "status": "created",
    "test": false,
    "items": [
      {
        "id": "item_1p4LS47fB1i",
        "detail": {
          "product": {
            "price": { "amount": 1000, "currency": "USD" },
            "quantity": 1,
            "label": "Pro Plan (Monthly)",
            "images": ["https://example.com/pro-plan.png"]
          }
        }
      }
    ],
    "interval": { "unit": "MONTH", "count": 1 },
    "createdAt": "2026-07-01T00:00:00Z",
    "updatedAt": "2026-07-01T00:00:00Z"
  }
}

注意： 当省略 trialPeriodDays 时，响应中还会包含一个用于首次扣款的 order 对象。

2. 将消费者重定向以完成设置

将消费者重定向到返回的 url。此后，Tokenz 托管的结账页面会负责处理其余的消费者端流程：

解析消费者所在地区、货币和适用税费
收集卡片信息，并完成发卡机构要求的任何 3D 验证
获取未来续订所需的周期性扣款授权（参见支付方式与授权）
无试用期：立即扣款首个订单并激活订阅
已配置试用期：开始试用而暂不扣款

消费者完成此步骤后，Tokenz 会根据结果将其重定向回您的 successUrl、pendingUrl 或 cancelUrl——与一次性 Checkout Session 使用相同的重定向机制。

3. 续订与激活会自动进行

您无需再进行任何调用：

如果没有试用期，一旦初始扣款成功，订阅立即变为 active。
如果配置了试用期，Tokenz 会在试用结束时自动创建并扣款首个订单，成功后激活订阅。
此后，只要订阅保持 active，Tokenz 就会在每个计费周期结束时自动创建并扣款新订单。

请监听 webhook 以保持您自己的记录同步——成功时为 subscription.trial_started、subscription.activated 和 subscription.renewed，扣款失败时为 subscription.unpaid。参见 Webhook。

流程图

查看订阅

使用 Tokenz 控制台查看和管理您账户下的所有订阅。对于您自己的系统，请依赖上述 webhook 事件来保持每个订阅状态的实时同步，而无需轮询。

测试

使用测试 API 密钥（以 test_ 为前缀）创建测试订阅；测试实体 ID 带有 _t 后缀（例如 subscription_1p4LS47fB1h_t）。
测试模式允许您在托管结账页面上模拟授权结果（通过、拒绝），从而无需真实卡组织即可测试正常流程以及催收/恢复流程。
Tokenz 控制台还允许您按需为测试订阅触发一次续订扣款，而无需等待常规的计费排程。