---
title: "集成订阅"
description: "本指南将带您完成创建订阅、激活订阅，并让续订自动运行的全过程——涵盖无试用期和有试用期两种流程。"
source: "https://docs.tokenz.one/zh-CN/v2/subscriptions/get-started"
api_version: "v2"
locale: "zh-CN"
version_status: "current"
docs_stage: "prod"
---

# 集成订阅

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

## 前提条件

您需要从 Tokenz 控制台获取 API 密钥。如果您尚未集成一次性付款，请参见[结账](https://docs.tokenz.one/zh-CN/v2/checkout)——订阅构建在同一套 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`。参见[生命周期与计费](https://docs.tokenz.one/zh-CN/v2/subscriptions/lifecycle#%E5%82%AC%E6%94%B6%EF%BC%88%E5%A4%B1%E8%B4%A5%E4%BB%98%E6%AC%BE%E6%81%A2%E5%A4%8D%EF%BC%89)。
- `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 验证
- 获取未来续订所需的周期性扣款授权（参见[支付方式与授权](https://docs.tokenz.one/zh-CN/v2/subscriptions/payment-methods)）
- **无试用期**：立即扣款首个订单并激活订阅
- **已配置试用期**：开始试用而暂不扣款

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

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

您无需再进行任何调用：

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

请监听 webhook 以保持您自己的记录同步——成功时为 `subscription.trial_started`、`subscription.activated` 和 `subscription.renewed`，扣款失败时为 `subscription.unpaid`。参见 [Webhook](https://docs.tokenz.one/zh-CN/v2/subscriptions/webhooks)。

```mermaid
sequenceDiagram;
autonumber;
participant C as 消费者;
participant M as 商户服务器;
participant T as Tokenz API;
participant TC as Tokenz 托管结账页面;
participant W as 商户 Webhook 处理程序;
M->>T: POST /v2/checkoutsession（包含 subscription 字段块）;
T-->>M: checkoutSession + subscription（created）;
M-->>TC: 将消费者重定向到结账会话 url;
TC->>TC: 收集卡片信息，解析地区/税费，获取授权;
alt 无试用期
TC->>TC: 扣款初始订单，订阅变为 active;
else 已配置试用期
TC->>TC: 订阅变为 trialing（尚未扣款）;
Note over T: 到达 trialEnd 时，Tokenz 自动创建并扣款首个订单;
T->>T: 订阅变为 active;
end
TC-->>C: 重定向回 successUrl / pendingUrl / cancelUrl;
T->>W: webhook: subscription.trial_started / subscription.activated;
loop 每个计费周期;
T->>T: 创建续订订单，自动向已保存的卡扣款;
T->>W: webhook: subscription.renewed（失败时为 subscription.unpaid）;
end
```

## 查看订阅

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

## 测试

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