使用產品物品建立結帳工作階段

了解如何使用 Tokenz 產品目錄中的虛擬物品和組合包建立結帳工作階段。

概述

產品系統允許您透過 Tokenz Dashboard 管理虛擬物品和組合包。這些物品可以在建立結帳工作階段時直接引用，從而實現從產品管理到結帳完成的完全程式化流程。

前提條件

在使用虛擬物品和組合包建立結帳工作階段之前，請確保您已：

API 憑證：從 Tokenz Dashboard 取得您的金鑰
產品設定：在 Tokenz Dashboard 中建立虛擬物品和/或組合包
產品 ID：記下您要使用的物品 ID（格式：virtualitem_xxx 或 bundle_xxx） - 這些可以從 Product API 取得，允許完全程式化的結帳流程建立

使用產品物品建立結帳工作階段

使用虛擬物品

建立結帳工作階段時，您可以透過產品 ID 直接引用虛擬物品。定價和產品資訊將自動從您的產品設定中提取。

bash

curl --request POST \
  --url https://api.tokenz.one/v1/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemDetails": [
      {
        "virtualItem":{
          "id": "virtualitem_5xA9BnKfvH7",
          "quantity": 2
        }
      },
      {
        "virtualItem":{
          "id": "virtualitem_3yB8CmLgwI8",
          "quantity": 1
        }
      }
    ],
    "customerInfo": {},
    "successUrl": "https://yourdomain.com/success",
    "pendingUrl": "https://yourdomain.com/pending",
    "cancelUrl": "https://yourdomain.com/cancel",
    "locale": "zh_TW"
  }'

使用組合包

bash

curl --request POST \
  --url https://api.tokenz.one/v1/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemDetails": [
      {
        "bundle": {
          "id": "bundle_8mR5TnKfvH7",
          "quantity": 1
        }
      }
    ],
    "customerInfo": {},
    "successUrl": "https://yourdomain.com/success",
    "pendingUrl": "https://yourdomain.com/pending",
    "cancelUrl": "https://yourdomain.com/cancel",
    "locale": "zh_TW"
  }'

混合虛擬物品和組合包

您可以在單一結帳工作階段中同時使用虛擬物品和組合包：

bash

curl --request POST \
  --url https://api.tokenz.one/v1/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemDetails": [
      {
        "bundle": {
          "id": "bundle_8mR5TnKfvH7",
          "quantity": 1
        }
      },
      {
        "virtualItem": {
          "id": "virtualitem_5xA9BnKfvH7",
          "quantity": 3
        }
      }
    ],
    "customerInfo": {},
    "successUrl": "https://yourdomain.com/success",
    "pendingUrl": "https://yourdomain.com/pending",
    "cancelUrl": "https://yourdomain.com/cancel"
  }'

實作範例

javascript

import fetch from 'node-fetch';

async function createCheckoutSession() {
  const response = await fetch('https://api.tokenz.one/v1/checkoutsession', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TOKENZ_SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      itemDetails: [
        {
          virtualItem: {
            id: "virtualitem_5xA9BnKfvH7",
            quantity: 2
          }
        }
      ],
      successUrl: "https://yourdomain.com/success",
      pendingUrl: "https://yourdomain.com/pending",
      cancelUrl: "https://yourdomain.com/cancel",
      locale: "zh_TW"
    })
  });

  const session = await response.json();

  // 將使用者重新導向到結帳頁面
  return session.url;
}

回應

API 回傳一個結帳工作階段物件：

json

{
  "id": "checkoutsession_12345678QsZ",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/12345678QsZ",
  "cancelUrl": "https://yourdomain.com/cancel",
  "pendingUrl": "https://yourdomain.com/pending",
  "successUrl": "https://yourdomain.com/success",
  "order": {
    "id": "order_1xdzo1aZRGB",
    "object": "order",
    "status": "requiresPayment",
    "amount": {
      "amount": 900,
      "currency": "TWD"
    },
    "items": [
      {
        "id": "item_1xdzo1ZpRcT",
        "detail": {
          "product": {
            "price": {
              "amount": 450,
              "currency": "TWD"
            },
            "quantity": 2,
            "label": "魔力藥水",
            "description": "",
            "images": [
              "https://images.ctfassets.net/z82qbo7cv7ia/2JyshO1smpYQwi0my9Rtif/f7df805472f4a1a0bf4e295afe9378a7/mana-potion.png"
            ],
            "sku": "mana-potion-450",
            "taxCategory": "DIGITAL_GOODS_AND_SERVICES"
          }
        }
      }
    ],
    "test": true,
    "createdAt": "2025-09-22T04:32:04.696Z",
    "updatedAt": "2025-09-22T04:32:04.696Z"
  },
  "createdAt": "2025-09-22T04:32:04.374Z",
  "updatedAt": "2025-09-22T04:32:04.374Z",
  "test": true,
  "customerInfo": {},
  "locale": "zh_TW",
  "preferApplePay": false,
  "preferGooglePay": false
}

最佳實踐

驗證物品 ID：建立會話前始終驗證產品物品 ID 是否存在
錯誤處理：為無效或已停售的物品實作適當的錯誤處理
使用 Webhook：設定 webhook 以接收支付狀態的即時更新
充分測試：上線前使用測試模式驗證您的整合

後續步驟

設定 webhook 處理支付確認
使用測試模式測試您的整合
在 Tokenz Dashboard 監控交易