整合訂閱

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

前提條件

您需要從 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 後台還允許您按需為測試訂閱觸發一次續訂扣款，而無需等待常規的計費排程。