---
title: "設定商城"
description: "Tokenz 商城是由 Tokenz 代管的遊戲商店。玩家在商店購買物品，Tokenz 負責收款，你的遊戲伺服器發放物品。你在主控台中建置商店，不需要自己開發店面。"
source: "https://docs.tokenz.one/zh-TW/v2/checkout/webshop"
api_version: "v2"
locale: "zh-TW"
version_status: "current"
docs_stage: "prod"
---

# 設定商城

Tokenz 商城是由 Tokenz 代管的遊戲商店。玩家在商店購買物品，Tokenz 負責收款，你的遊戲伺服器發放物品。你在主控台中建置商店，不需要自己開發店面。

先在測試模式中完成所有設定並進行一次測試購買，再透過一份清單正式上線：商城和訂單端點可從測試複製，產品和玩家 ID 驗證需在正式環境中重新設定。

## 開始之前

主控台右上角的開關用來在測試與正式之間切換。測試與正式各自有獨立的產品、商城和 Webhook 端點，所以你在測試中的設定不會改變正式商城。測試購買使用[測試卡](https://docs.tokenz.one/zh-TW/v2/checkout/testing#%E5%AE%8C%E6%88%90%E4%B8%80%E6%AC%A1%E6%88%90%E5%8A%9F%E7%9A%84%E6%B8%AC%E8%A9%A6%E6%94%AF%E4%BB%98)，不會向任何人收費。

你的遊戲伺服器要為商店做兩件事：

- **交付訂單。** Tokenz 把每筆已付款的訂單傳送到你伺服器上的端點，由伺服器發放物品。
- **驗證玩家 ID。** 玩家付款前，Tokenz 會詢問你的伺服器，玩家輸入的 ID 是否存在，確保物品發到真實的帳號。

在伺服器做好這兩件事之前，你也可以先試用商店。請參閱[還沒有伺服器？](https://docs.tokenz.one/zh-TW/v2/checkout/webshop#no-server-yet)。

## 1. 新增產品

切換到測試模式，開啟 **商店** > **產品**。逐一建立物品，或從檔案匯入商品目錄。請參閱[匯入產品](https://docs.tokenz.one/zh-TW/v2/product/import)。

已發布的產品會在商店中販售，草稿不會顯示。

## 2. 建置商城

開啟 **商店** > **商城編輯器**，選擇 **編輯商城**。選定商城網址，再為每種販售語言加入標誌、顏色和文字。編輯器旁的預覽會顯示玩家看到的商城。

玩家在付款前輸入玩家 ID。在 **玩家 ID 說明** 中寫出遊戲裡在哪裡顯示 ID，一兩句話即可，附上截圖會更清楚。玩家會從玩家 ID 欄位中的說明圖示開啟這段說明。

商城準備好後，選擇 **發布**。在測試中發布不會讓商城公開，只是讓它可以進行測試購買。

## 3. 設定發貨

在 **商店** > **商城編輯器** 中選擇 **設定發貨**。在 **發貨** 頁面設定訂單如何送到你的遊戲伺服器。

1. 在 **訂單傳送到哪裡** 中輸入伺服器上接收訂單的 HTTPS 網址，然後選擇 **儲存端點**。
2. 複製簽名密鑰。Tokenz 只在儲存端點時顯示一次。伺服器用它確認每筆訂單來自 Tokenz。請參閱[保護你的 Webhook 端點](https://docs.tokenz.one/zh-TW/v2/checkout/webhooks-get-started#3.-%E4%BF%9D%E8%AD%B7%E4%BD%A0%E7%9A%84-webhook-%E7%AB%AF%E9%BB%9E)。
3. 選擇 **傳送測試事件**。Tokenz 會傳送一筆已付款的範例訂單，你的伺服器應在 5 秒內回應。

端點會收到所有訂單、退款和爭議事件。每筆已付款的訂單以 `order.succeeded` 事件送達，`playerId` 中是玩家，物品清單中帶有 SKU。把物品發放給該玩家，並在收到 `refund.created` 時收回。事件說明請見 [Webhook](https://docs.tokenz.one/zh-TW/v2/checkout/webhooks#%E4%BA%8B%E4%BB%B6%E7%9A%84%E7%A8%AE%E9%A1%9E)。

由別人來開發端點？在 **交給開發人員** 中選擇 **複製設定說明**。說明會列出端點、它接收的事件和你的產品，並附上一筆範例訂單。說明中不含簽名密鑰，請另外傳送。

### 還沒有伺服器？

在測試模式中，**發貨** 頁面提供 **使用 Tokenz 測試伺服器**。它接受所有測試訂單，不會向遊戲發放任何東西。在你設定測試驗證 URL 之前，測試預覽也會不經驗證直接接受輸入的玩家 ID。所以你可以在撰寫伺服器程式之前進行測試購買。伺服器準備好後，改為輸入它的網址。

## 4. 驗證玩家 ID

Tokenz 透過你伺服器上的驗證 URL 驗證玩家 ID，它與接收訂單的端點是分開的。開啟 **設定** > **開發者** > **使用者驗證**，或在 **發貨** 頁面選擇 **開啟使用者驗證**。測試和正式環境各有自己的 URL 和簽名密鑰，所以先在測試模式中設定：

1. 選擇 **設定驗證**，輸入你伺服器上的 HTTPS 網址並儲存。
2. 複製簽名密鑰。它只會在產生時顯示一次。
3. 輸入一個真實的玩家 ID，選擇 **傳送測試驗證**，確認你的伺服器能夠回應。

之後玩家輸入 ID 時，Tokenz 會在付款前向這個 URL 傳送一個 `user.validation` 請求，其中包含玩家輸入的 ID。你的正式 URL 回應 `true` 後，Tokenz 可能在幾分鐘內重複使用這個回應，不再呼叫你的伺服器，所以不要依靠這項驗證來立即封鎖帳號。請參閱 [回應的重複使用](https://docs.tokenz.one/zh-TW/v2/checkout/webhooks#player-id-check-reuse)。在設定測試 URL 之前，測試預覽接受任何玩家 ID，所以等你的伺服器能夠回應時再設定。

```json
{
  "id": "9f8d3c2b-1a4e-4f6d-8b0c-2e5a7d9f1c34",
  "object": "user.validation",
  "createdAt": "2026-07-22T09:15:00Z",
  "test": true,
  "credentials": { "type": "playerId", "playerId": "player-42931" }
}
```

以 HTTP `200` 回應，並說明玩家是否存在：

```json
{ "valid": true }
```

- 無論玩家是否存在，都回傳 `200`。Tokenz 會把其他狀態碼視為服務中斷，玩家將無法購買。
- 在 3 秒內回應。否則玩家無法付款，並會被提示重試。
- 只回傳 `valid`。輸入 ID 的任何人都能讀到你的回應，所以不要傳送關於玩家的其他資訊。
- 當 `test` 為 `true` 時，用你的測試玩家來核對 ID。
- 像處理訂單一樣驗證 `Tokenz-Signature` 標頭，但要使用驗證 URL 的簽名密鑰。

完整的請求和回應說明請參閱 [玩家 ID 驗證](https://docs.tokenz.one/zh-TW/v2/checkout/webhooks#player-id-checks)。

## 5. 進行測試購買

在 **商店** > **商城編輯器** 中選擇 **開啟預覽**。它會開啟你在測試中最後發布的商城。用[測試卡](https://docs.tokenz.one/zh-TW/v2/checkout/testing#%E5%AE%8C%E6%88%90%E4%B8%80%E6%AC%A1%E6%88%90%E5%8A%9F%E7%9A%84%E6%B8%AC%E8%A9%A6%E6%94%AF%E4%BB%98)購買一件物品，然後確認伺服器已發放該物品。主控台處於測試模式時，訂單也會顯示在 **訂單** 中。

## 6. 正式上線

把主控台切換到正式，開啟 **商店** > **商城編輯器**。**正式上線** 清單列出正式環境還需要的項目，每項旁邊都有一個按鈕：

| 項目 | 要做的事 |
| --- | --- |
| 合約 | 透過頁面上方的 **啟用帳戶** 簽署。正式收款開始前，Tokenz 會審核合約。專案由所屬組織的合約涵蓋。 |
| 正式環境販售中的商品 | 正式環境有自己的產品。選擇 **新增商品**，在正式環境中重新建立或匯入。 |
| 商城 | 選擇 **從測試複製**，用測試中已發布的商城取代正式環境的草稿。 |
| 訂單端點 | 如果測試訂單傳送到你自己的伺服器，選擇 **用於正式環境**，把正式訂單也傳送到那裡。正式環境有自己的簽名密鑰，只顯示一次。否則選擇 **設定** 並輸入伺服器網址。 |
| 玩家 ID 驗證 | 正式環境有自己的驗證 URL。選擇 **設定** 開啟正式環境的 **使用者驗證**，輸入你伺服器的網址，並複製正式環境的簽名密鑰。 |

所有項目準備好後，就能使用 **啟用商城**。啟用後，正式商城會發布，玩家可以透過商城網址進入。

## 需要協助？

[聯絡 Tokenz 支援](https://tokenz.one/zh-tw/support)，並附上你的商城網址。