---
title: "整合訂閱"
description: "本指南將帶您完成建立訂閱、啟用訂閱，並讓續訂自動執行的全過程——涵蓋無試用期和有試用期兩種流程。"
source: "https://docs.tokenz.one/zh-TW/v2/subscriptions/get-started"
api_version: "v2"
locale: "zh-TW"
version_status: "current"
docs_stage: "prod"
---

# 整合訂閱

本指南將帶您完成建立訂閱、啟用訂閱，並讓續訂自動執行的全過程——涵蓋無試用期和有試用期兩種流程。

## 前提條件

您需要從 Tokenz 後台取得 API 金鑰。如果您尚未整合單次付款，請參見[結帳](https://docs.tokenz.one/zh-TW/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-TW/v2/subscriptions/lifecycle#%E5%82%AC%E6%94%B6%EF%BC%88%E4%BB%98%E6%AC%BE%E5%A4%B1%E6%95%97%E5%BE%A9%E5%8E%9F%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-TW/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-TW/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 後台還允許您按需為測試訂閱觸發一次續訂扣款，而無需等待常規的計費排程。