--- title: "設定商城" description: "本指南帶您建置由 Tokenz 代管的商城,完成測試購買、串接遊戲伺服器,再正式上線。您不需要開發商城前端,也不必為本例呼叫 Checkout Session API;玩家購買時,代管商城會開啟結帳頁面。" source: "https://docs.tokenz.one/zh-TW/v3/checkout/webshop" api_version: "v3" locale: "zh-TW" version_status: "current" docs_stage: "prod" --- # 設定商城 本指南帶您建置由 Tokenz 代管的商城,完成測試購買、串接遊戲伺服器,再正式上線。您不需要開發商城前端,也不必為本例呼叫 Checkout Session API;玩家購買時,代管商城會開啟結帳頁面。 我們以售價 **480 日圓** 的 **500 Gems** 為例,商品 SKU 為 `gem-pack-500`,測試玩家為 `player-42931`。購買一份後,該玩家的測試帳號應增加 500 顆寶石。商品與玩家皆為範例;上線前請改用實際販售的內容,並以真實的測試帳號完成驗證。 ## 開始之前 1. 登入 [Tokenz 主控台](https://dashboard.tokenz.one/zh-TW/home)。若尚無存取權限,請聯絡組織管理員或 [Tokenz 支援](https://tokenz.one/zh-tw/support)協助開通。 2. 開啟組織/專案切換選單,選取遊戲所屬專案。如果專案尚不存在,而且您有權限,選擇 **新增專案**。填寫專案名稱、必填的片假名名稱(例如 **Example Game** 與 **サンプルゲーム**)、聯絡信箱與唯一的網址識別名稱。只有專案確實符合頁面中的法律實體聲明時,才勾選確認;否則請聯絡 Tokenz。建立專案不代表已可正式收款。 3. 將主控台切換到 **測試**。確認可以開啟 **商店** > **產品**、**商店** > **商城編輯器**與開發者設定。若頁面不可見或無法編輯,請管理員確認對應權限與商城功能是否已啟用。 4. 視需要準備標誌或圖片。後續伺服器串接需要一位開發人員,提供兩個 HTTPS 處理端點:玩家驗證與訂單事件。第一次購買可先使用 Tokenz 測試伺服器,不需要這兩個端點。 **預期結果:** 已選取正確的遊戲專案與測試模式,並可編輯商品與商城。此時不會實際扣款,也尚未發布正式商城。 **遇到問題:** 先確認目前的組織與專案,再調整權限。如果找不到專案、無法建立專案或仍無法存取,請管理員或 Tokenz 支援協助完成帳戶/專案設定。 測試與正式模式分別管理商品、商城內容和 Webhook 端點。商城網址由兩種模式共用:在任一模式修改網址,都會同時更新另一模式的網址與結帳返回網址。每次修改商品目錄或端點前,都要確認目前模式。 ## 1. 新增商品 為方便重現第一個商品,請將下列內容存為 UTF-8 編碼的 `products.csv`。在測試模式開啟 **商店** > **產品**,選擇 **匯入商品**並上傳檔案: ```csv sku,name,description,price,currency,taxCategory,publish gem-pack-500,500 Gems,Adds 500 gems to your game account.,480,JPY,virtualCurrency,true ``` 檢查匯入預覽、修正錯誤後,選擇 **匯入**。SKU 用來識別商品,名稱會顯示給玩家。價格為 480 日圓;稅務類別對應遊戲內貨幣,`publish` 表示發布商品而非存為草稿。圖片、其他幣別與大量商品的處理方式請見[匯入商品](https://docs.tokenz.one/zh-TW/v3/product/import)。 若選擇用表單建立,請填入相同資料。在 **新增方案** 中加入 **一次性** 價格方案,將預設價格設為 **480 JPY**,儲存商品後再發布。確認價格方案已上架:商品即使已發布,沒有已上架的價格方案仍無法購買。 **預期結果:** 商品清單中有一件已發布的 **500 Gems**,SKU 為 `gem-pack-500`,且有顯示 **480 日圓** 的已上架一次性價格方案。它屬於測試目錄,正式目錄沒有變更。 **遇到問題:** 匯入預覽有錯誤時不會寫入資料,請修正指定列後重新上傳。實際匯入也可能回報個別失敗,請檢查最後結果。同一 SKU 已存在時,匯入會更新該商品,不要不斷換用新 SKU 重試。若無法新增/上架價格方案或發布商品,請管理員補齊權限。第一次購買先不設定販售期間、庫存或購買上限。 日後啟用這些限制時,也要逐一測試。每日、每週、每月與每年重設的購買上限均以 `UTC` 為準,每週從星期一開始,每年從 1 月 1 日開始。未設定重設週期時,每位玩家的購買上限不會自動重設。 ## 2. 建置商城 1. 開啟 **商店** > **商城編輯器** > **編輯商城**。專案尚無商城網址時,設定唯一網址。使用主控台顯示的網址,不要自行加上 `test-` 前綴。 2. 檢查英文的商店/品牌名稱與遊戲名稱。本測試範例分別填入 **Example Game Store** 和 **Example Game**。英文一律提供;某種語言的翻譯留白時,會使用英文內容。 3. 加入標誌、顏色與要顯示的商城文字。舊商城若仍顯示 **Fantasy Studio** 或其他語言的範例公司名稱,請改為實際發行商名稱,或關閉 **覆蓋公司名稱**。範例公司名稱可能導致商城無法啟用。主視覺圖片、專案簡介與「關於」文字皆為選填;上線前請確認準備顯示的支援與政策連結。 4. 在 **玩家 ID 說明** 中說明玩家可在遊戲的哪個位置找到 ID,例如「開啟設定 > 帳號,複製玩家 ID」。請改成您遊戲中的實際路徑。加入玩家需要的語言,並檢查各語言文字。 5. 依序選擇 **儲存變更**、**發布**。 **預期結果:** 測試商城已有儲存並發布的版本,編輯器預覽顯示所填名稱與樣式。在測試模式發布不會啟用公開的正式商城。發布後再次儲存的變更仍是草稿,必須再次發布才會顯示給玩家。 **遇到問題:** 依檢查訊息修正對應欄位,優先確認英文名稱與範例公司名稱。網址已被使用或屬於保留名稱時,需改用其他識別名稱。玩家預覽若比編輯器內容舊,請儲存、發布,再重新開啟預覽;玩家預覽讀取的是已發布版本。 ## 3. 設定發貨 ### 還沒有伺服器? **操作:** 在 **商店** > **商城編輯器** 中選擇 **設定發貨**。在測試模式選擇 **使用 Tokenz 測試伺服器**,暫不設定測試驗證 URL,再前往[進行測試購買](https://docs.tokenz.one/zh-TW/v3/checkout/webshop#make-a-test-purchase)。開發人員準備好端點後,再回到這裡串接。 **預期結果:** 發貨頁面顯示 Tokenz 測試伺服器。它接收測試訂單事件,但不發放遊戲物品。未設定測試驗證 URL 時,測試預覽會接受輸入的接收者 ID,不進行驗證。 **遇到問題:** 此選項僅供測試。如果已設定測試驗證 URL,該伺服器仍須正常回應;訂單測試伺服器不會略過既有驗證。請修正驗證錯誤,或由開發人員移除該測試設定後,再體驗不需自建伺服器的流程。 ### 串接遊戲伺服器 1. 請開發人員提供接收訂單事件的 HTTPS POST 端點,並實作[簽章驗證](https://docs.tokenz.one/zh-TW/v3/checkout/webhooks-get-started#3.-%E4%BF%9D%E8%AD%B7%E4%BD%A0%E7%9A%84-webhook-%E7%AB%AF%E9%BB%9E)。本例中,將 SKU `gem-pack-500` 對應到測試遊戲中的 500 顆寶石。 2. 在測試模式的 **發貨** 頁面,將端點 URL 填入 **訂單傳送到哪裡**,選擇 **儲存端點**。準備改用自己的伺服器時,這一步也會取代 Tokenz 測試伺服器。 3. 選擇 **複製設定說明**,將說明交給開發人員。複製僅顯示一次的簽章金鑰,並另外分享。請將金鑰安全存放在伺服器端。 4. 選擇 **傳送測試事件**並檢查結果。探測請求要求在 5 秒內回應。這是範例事件,不是真實購買:其中的 ID 不對應真實訂單,也可能沒有 `recipientId`。它只用來確認接收、驗章與回應,不代表遊戲已發放物品。 **預期結果:** 已設定自己的測試 URL,帶有簽章的範例請求取得 2xx 回應。開發人員可以在伺服器紀錄中找到它。實際發貨仍須透過第 5 步的測試購買確認。 **遇到問題:** 確認 URL 可從外部透過 HTTPS 存取、端點接受 POST,並使用本端點的測試金鑰,對未經修改的原始請求內文驗章。查看探測結果中的 HTTP 回應或逾時資訊。請參閱 [Webhook 疑難排解](https://docs.tokenz.one/zh-TW/v3/checkout/webhooks#%E7%96%91%E9%9B%A3%E6%8E%92%E8%A7%A3%EF%BC%9A%E6%88%91%E7%9A%84%E7%AB%AF%E9%BB%9E%E6%B2%92%E6%9C%89%E6%94%B6%E5%88%B0%E4%BA%8B%E4%BB%B6)。 新建的發貨端點預設訂閱: - 訂單:`order.succeeded`、`order.canceled`、`order.expired`、`order.failed`。 - 退款:`refund.created`、`refund.failed`。 - 爭議:`dispute.created`、`dispute.closed`。 預設不包含 `order.created`。若使用現有端點,請在開發者設定中確認事件訂閱;實際只會投遞設定中的事件。 ### 讀取訂單並發放物品 以下為本例需要讀取的欄位節錄,並非完整 Webhook。讀取前應先對完整的原始請求驗章。實際事件 ID 與訂單 ID 由 Tokenz 產生,請勿將範例 ID 寫死在程式中。 ```json { "id": "2d8419f0-81fa-4e04-bb39-5cf95efa829a", "object": "order.succeeded", "test": true, "eventData": { "type": "order", "version": "v3", "data": { "order": { "id": "order_example_t", "recipientId": "player-42931", "items": [ { "detail": { "product": { "sku": "gem-pack-500", "quantity": 1 } } } ] } } } } ``` | 讀取欄位 | 用途 | | --- | --- | | 最外層的 `id` | 避免重複處理事件投遞。先持久儲存事件,再回傳 2xx,並以非同步方式處理工作。 | | `eventData.data.order.id` | 將訂單與遊戲發放紀錄、交付紀錄對應。 | | `eventData.data.order.recipientId` | 玩家輸入的接收者 ID。找到測試玩家 `player-42931`,不要根據事件 ID 或 SKU 猜測玩家。 | | 每個物品的 `detail.product.sku` 與 `detail.product.quantity` | 每份 `gem-pack-500` 發放 500 顆寶石:數量 1 發放 500,數量 2 發放 1,000。 | 同一事件重試時不得重複發放。遊戲發放操作與完成紀錄應保持一致,避免背景工作重試造成重複發貨。遇到未知 SKU 或缺少 `recipientId` 時應排查,不可猜測接收帳號。請參閱[重試與冪等性](https://docs.tokenz.one/zh-TW/v3/checkout/webhooks#%E9%87%8D%E8%A9%A6%E8%88%87%E5%86%AA%E7%AD%89%E6%80%A7)。開發人員也可以[登錄交付紀錄](https://docs.tokenz.one/zh-TW/v3/order),作為已完成發貨的證據。 `refund.created` 表示退款申請已建立,不代表退款已成功。請決定全額/部分退款分別應收回哪些物品或權益。若收到申請就收回,請處理 `refund.failed`,在退款失敗時恢復已收回的內容。請參閱[退款](https://docs.tokenz.one/zh-TW/v3/refunds)。 ## 4. 驗證接收者 ID 如果第一次購買使用了 Tokenz 測試伺服器,請先串接自己的遊戲伺服器,再繼續。設定玩家驗證後,使用自己的伺服器完成第 5 步。玩家驗證 URL 與訂單事件 URL 是兩項獨立串接,各有自己的簽章金鑰;即使兩個端點部署在同一個應用程式中,也須分別設定。 1. 在測試遊戲中建立玩家 `player-42931`,或統一改用一個已存在的測試帳號。購買前記下該帳號的寶石餘額。 2. 請開發人員提供 HTTPS POST 驗證端點。端點使用驗證金鑰檢查 `Tokenz-Signature`,在測試遊戲的玩家資料中查詢提交的 ID,並於 3 秒內回傳 JSON 判定結果。 3. 在測試模式開啟 **設定** > **開發者** > **使用者驗證**,或發貨頁面的 **開啟使用者驗證**。選擇 **設定驗證**,填入 URL 並儲存,複製僅顯示一次的簽章金鑰。 4. 使用 **傳送測試驗證**,分別提交 `player-42931` 與測試遊戲中不存在的 ID,例如 `player-missing`。 驗證請求範例: ```json { "id": "9f8d3c2b-1a4e-4f6d-8b0c-2e5a7d9f1c34", "object": "user.validation", "createdAt": "2026-07-22T09:15:00Z", "test": true, "credentials": { "type": "recipientId", "recipientId": "player-42931" } } ``` 以 HTTP `200` 回傳對應結果: ```json { "valid": true } ``` ```json { "valid": false } ``` **預期結果:** 已存在的測試玩家回傳 `valid: true`,不存在的玩家回傳 `valid: false`。否定結果也應透過正常的 HTTP 回應傳回,而不是 HTTP 錯誤。主控台中的探測不會建立結帳,也不代表物品能成功發放。 **遇到問題:** 非 2xx 回應、JSON 格式錯誤或非布林值的 `valid` 都屬於服務故障;逾時也會阻擋結帳。確認驗證 URL 自己的金鑰與原始請求內文驗章邏輯。`test` 為 true 時,應查詢測試玩家資料。不要回傳玩家詳情:Tokenz 不會轉送原始回應,但玩家可以得知判定結果。 正式環境中,同一商家專案下同一接收者 ID 的驗證成功結果可能被重複使用,預設有效期為 5 分鐘,可用 `validUntil` 指定截止時間。因此,帳號封鎖狀態不一定立即反映到商城。否定結果不會被重複使用;測試模式每次都會呼叫您的伺服器。請參閱[接收者 ID 驗證](https://docs.tokenz.one/zh-TW/v3/checkout/webhooks#player-id-checks)。 ## 5. 進行測試購買 1. 在測試模式開啟 **商店** > **商城編輯器** > **開啟預覽**,查看最後發布的測試商城。瀏覽器阻擋彈出視窗時,請使用 **複製預覽連結**,再開啟複製的連結。不要自行組合測試網址,預覽連結會提供存取憑證。 2. 輸入 `player-42931`,選擇 **500 Gems**,購買一份。尚未設定驗證時,該 ID 會被直接接受;設定驗證後,必須通過測試遊戲的玩家查詢。 3. 選擇信用卡,填入測試卡 **4242 4242 4242 4242**、任意 3 碼 CVC 與未來的到期日。頁面若有測試結果選項,請選擇成功。測試時不要使用真實卡片。[測試卡參考](https://docs.tokenz.one/zh-TW/v3/checkout/testing#%E6%B8%AC%E8%A9%A6%E5%8D%A1%E8%99%9F)列有其他卡號;請略過該頁透過 API 建立結帳的步驟,因為商城已經會開啟結帳頁面。 4. 完成付款後,維持測試模式,在 **訂單** 中找到新訂單,並記下訂單 ID。 **預期結果:** 測試付款成功,訂單出現在測試訂單清單中。使用 Tokenz 測試伺服器時,只能確認結帳流程已跑通,遊戲餘額不會改變。使用自己的伺服器時,應找到帶簽章的 `order.succeeded` 事件與該訂單的發放紀錄。測試玩家餘額必須只增加一次,增加 500 顆寶石。 **遇到問題:** **開啟預覽**無法使用時,先發布測試商城。找不到商品或無法購買時,確認測試模式、發布狀態、已上架價格方案、販售期間與庫存/購買上限。玩家驗證失敗時,請檢查第 4 步。付款成功卻未收到物品時,以訂單 ID 核對事件投遞結果與遊戲發放紀錄。2xx 只代表事件已接收,不代表物品已發放。 不能根據成功頁面或重新導向直接發貨。付款處理中,應等待 `order.succeeded` 事件,或查詢並確認訂單已成功;取消/失敗返回頁面不能觸發發放。請參閱[訂單](https://docs.tokenz.one/zh-TW/v3/order)。 付款後,結帳會將玩家帶回您的商店,而不是遊戲。網路商店的返回 URL 依循商店位址。如果您的遊戲透過 API 自行建立 Checkout Session,請參閱[返回您的應用程式](https://docs.tokenz.one/zh-TW/v3/checkout/get-started#return-to-your-app)。 上線前,使用自己的伺服器確認以下結果: - 不存在的接收者 ID 回傳 `{ "valid": false }`,並阻擋購買。 - 驗證請求逾時或回傳 HTTP `500` 時,購買會被阻擋,玩家可以重試。 - 未發布的商品、未上架的價格方案、販售期間外的商品,以及庫存耗盡或已達購買上限的商品均無法購買。 - 投遞失敗的事件會重試。重複投遞同一事件不會重複發放物品;請同時核對訂單紀錄與遊戲餘額。 修正與上述預期不符的行為。即使先前已透過 Tokenz 測試伺服器完成購買,也要使用自己的伺服器完成第 5 步。 ## 6. 正式上線 **操作:** 將主控台切換到正式模式,開啟 **商店** > **商城編輯器**,完成 **正式上線** 清單中的各項: | 項目 | 操作與預期結果 | 受阻時確認 | | --- | --- | --- | | 合約 | 必要時透過 **啟用帳戶** 簽署。專案適用所屬組織的合約。正式收款需要 Tokenz 核准。 | 等待審核或聯絡支援;簽署完成不等於審核通過。 | | 正式環境販售中的商品 | 建立/匯入實際販售的正式目錄,發布商品並確認價格方案已上架,核對幣別與金額。 | 測試商品與正式商品分開。只有範例確實對應您打算販售的真實商品時,才匯入正式環境。 | | 商城 | **從測試複製**會以已發布的測試商城取代正式草稿。檢查名稱、文字、網址、支援/政策連結與樣式。 | 修正提示的欄位,上線前替換所有範例內容。 | | 訂單端點 | 只有自己的測試伺服器也能處理正式訂單時,才選擇 **用於正式環境**;否則 **設定**正式 URL。複製新的正式簽章金鑰。 | Tokenz 測試伺服器不能交付正式訂單。共用 URL 也須依模式使用不同金鑰與資料。 | | 接收者 ID 驗證 | 設定正式驗證 URL,複製正式金鑰,並以獲授權的正式玩家測試。 | 測試驗證 URL 不會自動沿用;正式伺服器必須查詢正式玩家資料。 | 各項準備好後,選擇 **啟用商城**,發布正式商城。開啟主控台顯示的公開網址,核對正式商品、價格、語言、玩家 ID 說明與連結。不能以測試預覽證明公開商城已可使用。 **預期結果:** 獲授權的玩家能開啟公開商城,購買預期的正式商品。如果團隊要執行正式驗證購買,請先取得授權,使用支援的真實付款方式,並預期實際扣款。測試卡僅供測試模式使用。像測試時一樣,核對正式訂單、正式事件與遊戲內發放結果。 **遇到問題:** 公開商城、商品目錄或伺服器不正確時,先停止上線驗證,修正正式設定並重新發布。需要停止販售時,在商城編輯器中停用商城;修改尚未發布的草稿不會改變玩家正在看到的內容。 ## 需要協助? 聯絡 [Tokenz 支援](https://tokenz.one/zh-tw/support)時,請提供專案/商城網址、模式、訂單 ID(若已產生)、大致時間與錯誤或 HTTP 狀態。不要提供簽章金鑰或玩家詳情。保留伺服器的事件與發放紀錄,方便開發人員區分付款、投遞與遊戲處理環節的問題。