設定商城

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

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

開始之前

主控台右上角的開關用來在測試與正式之間切換。測試與正式各自有獨立的產品、商城和 Webhook 端點，所以你在測試中的設定不會改變正式商城。測試購買使用測試卡，不會向任何人收費。

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

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

在伺服器做好這兩件事之前，你也可以先試用商店。請參閱還沒有伺服器？。

1. 新增產品

切換到測試模式，開啟 商店 > 產品。逐一建立物品，或從檔案匯入商品目錄。請參閱匯入產品。

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

2. 建置商城

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

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

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

3. 設定發貨

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

1. 在 訂單傳送到哪裡 中輸入伺服器上接收訂單的 HTTPS 網址，然後選擇 儲存端點。
2. 複製簽名密鑰。Tokenz 只在儲存端點時顯示一次。伺服器用它確認每筆訂單來自 Tokenz。請參閱保護你的 Webhook 端點。
3. 選擇 傳送測試事件。Tokenz 會傳送一筆已付款的範例訂單，你的伺服器應在 5 秒內回應。

端點會收到所有訂單、退款和爭議事件。每筆已付款的訂單以 order.succeeded 事件送達，playerId 中是玩家，物品清單中帶有 SKU。把物品發放給該玩家，並在收到 refund.created 時收回。事件說明請見 Webhook。

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

還沒有伺服器？

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

4. 驗證玩家 ID

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

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

之後玩家輸入 ID 時，Tokenz 會在付款前向這個 URL 傳送一個 user.validation 請求，其中包含玩家輸入的 ID。你的正式 URL 回應 true 後，Tokenz 可能在幾分鐘內重複使用這個回應，不再呼叫你的伺服器，所以不要依靠這項驗證來立即封鎖帳號。請參閱 回應的重複使用。在設定測試 URL 之前，測試預覽接受任何玩家 ID，所以等你的伺服器能夠回應時再設定。

{
  "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 回應，並說明玩家是否存在：

{ "valid": true }

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

完整的請求和回應說明請參閱 玩家 ID 驗證。

5. 進行測試購買

在 商店 > 商城編輯器 中選擇 開啟預覽。它會開啟你在測試中最後發布的商城。用測試卡購買一件物品，然後確認伺服器已發放該物品。主控台處於測試模式時，訂單也會顯示在 訂單 中。

6. 正式上線

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

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

需要協助？

聯絡 Tokenz 支援，並附上你的商城網址。