---
title: "使用产品物品创建结账会话"
description: "了解如何使用 Tokenz 产品目录中的虚拟物品和组合包创建结账会话。"
source: "https://docs.tokenz.one/zh-CN/v1/product/session"
api_version: "v1"
locale: "zh-CN"
version_status: "legacy"
docs_stage: "prod"
---

# 使用产品物品创建结账会话

了解如何使用 Tokenz 产品目录中的虚拟物品和组合包创建结账会话。

## 概述

产品系统允许您通过仪表板管理虚拟物品和组合包。这些产品物品可以在创建结账会话时直接引用，从而实现从产品管理到结账完成的完全程序化流程。

## 前提条件

在使用产品物品创建结账会话之前，请确保您已：

1. **API 凭证**：从 Tokenz 仪表板获取您的密钥
2. **产品设置**：在仪表板中创建虚拟物品和/或组合包
3. **产品 ID**：记下您要使用的物品 ID（格式：`virtualitem_xxx` 或 `bundle_xxx`） - 这些可以从产品 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_CN"
  }'
```

### 使用组合包

```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_CN"
  }'
```

### 混合物品和组合包

您可以在单个结账会话中同时使用虚拟物品和组合包：

```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"
  }'
```

## 实现示例

#### NodeJS

```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_CN"
    })
  });

  const session = await response.json();

  // 将用户重定向到结账页面
  return session.url;
}
```

#### Python

```python
import requests
import os

def create_checkout_session():
    url = "https://api.tokenz.one/v1/checkoutsession"

    headers = {
        "Authorization": f"Bearer {os.environ['TOKENZ_SECRET_KEY']}",
        "Content-Type": "application/json"
    }

    payload = {
        "itemDetails": [
            {
              "virtualItem": {
                "id": "virtualitem_5xA9BnKfvH7",
                "quantity": 2
              }
            }
        ],
        "successUrl": "https://yourdomain.com/success",
        "pendingUrl": "https://yourdomain.com/pending",
        "cancelUrl": "https://yourdomain.com/cancel",
        "locale": "zh_CN"
    }

    response = requests.post(url, json=payload, headers=headers)
    session = 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": "CNY"
    },
    "items": [
      {
        "id": "item_1xdzo1ZpRcT",
        "detail": {
          "product": {
            "price": {
              "amount": 450,
              "currency": "CNY"
            },
            "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_CN",
  "preferApplePay": false,
  "preferGooglePay": false
}
```

## 最佳实践

1. **验证物品 ID**：创建会话前始终验证产品物品 ID 是否存在
2. **错误处理**：为无效或已停售的物品实现适当的错误处理
3. **使用 Webhook**：设置 webhook 以接收支付状态的实时更新
4. **充分测试**：上线前使用测试模式验证您的集成

## 后续步骤

- [设置 webhook](https://docs.tokenz.one/zh-CN/v1/checkout/webhooks) 处理支付确认
- 使用测试模式[测试您的集成](https://docs.tokenz.one/zh-CN/v1/checkout/testing)
- 在[仪表板](https://dashboard.tokenz.one/)监控交易