設定商城
本指南帶您建置由 Tokenz 代管的商城,完成測試購買、串接遊戲伺服器,再正式上線。您不需要開發商城前端,也不必為本例呼叫 Checkout Session API;玩家購買時,代管商城會開啟結帳頁面。
我們以售價 480 日圓 的 500 Gems 為例,商品 SKU 為 gem-pack-500,測試玩家為 player-42931。購買一份後,該玩家的測試帳號應增加 500 顆寶石。商品與玩家皆為範例;上線前請改用實際販售的內容,並以真實的測試帳號完成驗證。
開始之前
- 登入 Tokenz 主控台。若尚無存取權限,請聯絡組織管理員或 Tokenz 支援協助開通。
- 開啟組織/專案切換選單,選取遊戲所屬專案。如果專案尚不存在,而且您有權限,選擇 新增專案。填寫專案名稱、必填的片假名名稱(例如 Example Game 與 サンプルゲーム)、聯絡信箱與唯一的網址識別名稱。只有專案確實符合頁面中的法律實體聲明時,才勾選確認;否則請聯絡 Tokenz。建立專案不代表已可正式收款。
- 將主控台切換到 測試。確認可以開啟 商店 > 產品、商店 > 商城編輯器與開發者設定。若頁面不可見或無法編輯,請管理員確認對應權限與商城功能是否已啟用。
- 視需要準備標誌或圖片。後續伺服器串接需要一位開發人員,提供兩個 HTTPS 處理端點:玩家驗證與訂單事件。第一次購買可先使用 Tokenz 測試伺服器,不需要這兩個端點。
預期結果: 已選取正確的遊戲專案與測試模式,並可編輯商品與商城。此時不會實際扣款,也尚未發布正式商城。
遇到問題: 先確認目前的組織與專案,再調整權限。如果找不到專案、無法建立專案或仍無法存取,請管理員或 Tokenz 支援協助完成帳戶/專案設定。
測試與正式模式分別管理商品、商城內容和 Webhook 端點。商城網址由兩種模式共用:在任一模式修改網址,都會同時更新另一模式的網址與結帳返回網址。每次修改商品目錄或端點前,都要確認目前模式。
1. 新增商品
為方便重現第一個商品,請將下列內容存為 UTF-8 編碼的 products.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 表示發布商品而非存為草稿。圖片、其他幣別與大量商品的處理方式請見匯入商品。
若選擇用表單建立,請填入相同資料。在 新增方案 中加入 一次性 價格方案,將預設價格設為 480 JPY,儲存商品後再發布。確認價格方案已上架:商品即使已發布,沒有已上架的價格方案仍無法購買。
預期結果: 商品清單中有一件已發布的 500 Gems,SKU 為 gem-pack-500,且有顯示 480 日圓 的已上架一次性價格方案。它屬於測試目錄,正式目錄沒有變更。
遇到問題: 匯入預覽有錯誤時不會寫入資料,請修正指定列後重新上傳。實際匯入也可能回報個別失敗,請檢查最後結果。同一 SKU 已存在時,匯入會更新該商品,不要不斷換用新 SKU 重試。若無法新增/上架價格方案或發布商品,請管理員補齊權限。第一次購買先不設定販售期間、庫存或購買上限。
日後啟用這些限制時,也要逐一測試。每日、每週、每月與每年重設的購買上限均以 UTC 為準,每週從星期一開始,每年從 1 月 1 日開始。未設定重設週期時,每位玩家的購買上限不會自動重設。
2. 建置商城
- 開啟 商店 > 商城編輯器 > 編輯商城。專案尚無商城網址時,設定唯一網址。使用主控台顯示的網址,不要自行加上
test-前綴。 - 檢查英文的商店/品牌名稱與遊戲名稱。本測試範例分別填入 Example Game Store 和 Example Game。英文一律提供;某種語言的翻譯留白時,會使用英文內容。
- 加入標誌、顏色與要顯示的商城文字。舊商城若仍顯示 Fantasy Studio 或其他語言的範例公司名稱,請改為實際發行商名稱,或關閉 覆蓋公司名稱。範例公司名稱可能導致商城無法啟用。主視覺圖片、專案簡介與「關於」文字皆為選填;上線前請確認準備顯示的支援與政策連結。
- 在 玩家 ID 說明 中說明玩家可在遊戲的哪個位置找到 ID,例如「開啟設定 > 帳號,複製玩家 ID」。請改成您遊戲中的實際路徑。加入玩家需要的語言,並檢查各語言文字。
- 依序選擇 儲存變更、發布。
預期結果: 測試商城已有儲存並發布的版本,編輯器預覽顯示所填名稱與樣式。在測試模式發布不會啟用公開的正式商城。發布後再次儲存的變更仍是草稿,必須再次發布才會顯示給玩家。
遇到問題: 依檢查訊息修正對應欄位,優先確認英文名稱與範例公司名稱。網址已被使用或屬於保留名稱時,需改用其他識別名稱。玩家預覽若比編輯器內容舊,請儲存、發布,再重新開啟預覽;玩家預覽讀取的是已發布版本。
3. 設定發貨
還沒有伺服器?
操作: 在 商店 > 商城編輯器 中選擇 設定發貨。在測試模式選擇 使用 Tokenz 測試伺服器,暫不設定測試驗證 URL,再前往進行測試購買。開發人員準備好端點後,再回到這裡串接。
預期結果: 發貨頁面顯示 Tokenz 測試伺服器。它接收測試訂單事件,但不發放遊戲物品。未設定測試驗證 URL 時,測試預覽會接受輸入的接收者 ID,不進行驗證。
遇到問題: 此選項僅供測試。如果已設定測試驗證 URL,該伺服器仍須正常回應;訂單測試伺服器不會略過既有驗證。請修正驗證錯誤,或由開發人員移除該測試設定後,再體驗不需自建伺服器的流程。
串接遊戲伺服器
- 請開發人員提供接收訂單事件的 HTTPS POST 端點,並實作簽章驗證。本例中,將 SKU
gem-pack-500對應到測試遊戲中的 500 顆寶石。 - 在測試模式的 發貨 頁面,將端點 URL 填入 訂單傳送到哪裡,選擇 儲存端點。準備改用自己的伺服器時,這一步也會取代 Tokenz 測試伺服器。
- 選擇 複製設定說明,將說明交給開發人員。複製僅顯示一次的簽章金鑰,並另外分享。請將金鑰安全存放在伺服器端。
- 選擇 傳送測試事件並檢查結果。探測請求要求在 5 秒內回應。這是範例事件,不是真實購買:其中的 ID 不對應真實訂單,也可能沒有
recipientId。它只用來確認接收、驗章與回應,不代表遊戲已發放物品。
預期結果: 已設定自己的測試 URL,帶有簽章的範例請求取得 2xx 回應。開發人員可以在伺服器紀錄中找到它。實際發貨仍須透過第 5 步的測試購買確認。
遇到問題: 確認 URL 可從外部透過 HTTPS 存取、端點接受 POST,並使用本端點的測試金鑰,對未經修改的原始請求內文驗章。查看探測結果中的 HTTP 回應或逾時資訊。請參閱 Webhook 疑難排解。
新建的發貨端點預設訂閱:
- 訂單:
order.succeeded、order.canceled、order.expired、order.failed。 - 退款:
refund.created、refund.failed。 - 爭議:
dispute.created、dispute.closed。
預設不包含 order.created。若使用現有端點,請在開發者設定中確認事件訂閱;實際只會投遞設定中的事件。
讀取訂單並發放物品
以下為本例需要讀取的欄位節錄,並非完整 Webhook。讀取前應先對完整的原始請求驗章。實際事件 ID 與訂單 ID 由 Tokenz 產生,請勿將範例 ID 寫死在程式中。
{
"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 時應排查,不可猜測接收帳號。請參閱重試與冪等性。開發人員也可以登錄交付紀錄,作為已完成發貨的證據。
refund.created 表示退款申請已建立,不代表退款已成功。請決定全額/部分退款分別應收回哪些物品或權益。若收到申請就收回,請處理 refund.failed,在退款失敗時恢復已收回的內容。請參閱退款。
4. 驗證接收者 ID
如果第一次購買使用了 Tokenz 測試伺服器,請先串接自己的遊戲伺服器,再繼續。設定玩家驗證後,使用自己的伺服器完成第 5 步。玩家驗證 URL 與訂單事件 URL 是兩項獨立串接,各有自己的簽章金鑰;即使兩個端點部署在同一個應用程式中,也須分別設定。
- 在測試遊戲中建立玩家
player-42931,或統一改用一個已存在的測試帳號。購買前記下該帳號的寶石餘額。 - 請開發人員提供 HTTPS POST 驗證端點。端點使用驗證金鑰檢查
Tokenz-Signature,在測試遊戲的玩家資料中查詢提交的 ID,並於 3 秒內回傳 JSON 判定結果。 - 在測試模式開啟 設定 > 開發者 > 使用者驗證,或發貨頁面的 開啟使用者驗證。選擇 設定驗證,填入 URL 並儲存,複製僅顯示一次的簽章金鑰。
- 使用 傳送測試驗證,分別提交
player-42931與測試遊戲中不存在的 ID,例如player-missing。
驗證請求範例:
{
"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 回傳對應結果:
{ "valid": true }
{ "valid": false }
預期結果: 已存在的測試玩家回傳 valid: true,不存在的玩家回傳 valid: false。否定結果也應透過正常的 HTTP 回應傳回,而不是 HTTP 錯誤。主控台中的探測不會建立結帳,也不代表物品能成功發放。
遇到問題: 非 2xx 回應、JSON 格式錯誤或非布林值的 valid 都屬於服務故障;逾時也會阻擋結帳。確認驗證 URL 自己的金鑰與原始請求內文驗章邏輯。test 為 true 時,應查詢測試玩家資料。不要回傳玩家詳情:Tokenz 不會轉送原始回應,但玩家可以得知判定結果。
正式環境中,同一商家專案下同一接收者 ID 的驗證成功結果可能被重複使用,預設有效期為 5 分鐘,可用 validUntil 指定截止時間。因此,帳號封鎖狀態不一定立即反映到商城。否定結果不會被重複使用;測試模式每次都會呼叫您的伺服器。請參閱接收者 ID 驗證。
5. 進行測試購買
- 在測試模式開啟 商店 > 商城編輯器 > 開啟預覽,查看最後發布的測試商城。瀏覽器阻擋彈出視窗時,請使用 複製預覽連結,再開啟複製的連結。不要自行組合測試網址,預覽連結會提供存取憑證。
- 輸入
player-42931,選擇 500 Gems,購買一份。尚未設定驗證時,該 ID 會被直接接受;設定驗證後,必須通過測試遊戲的玩家查詢。 - 選擇信用卡,填入測試卡 4242 4242 4242 4242、任意 3 碼 CVC 與未來的到期日。頁面若有測試結果選項,請選擇成功。測試時不要使用真實卡片。測試卡參考列有其他卡號;請略過該頁透過 API 建立結帳的步驟,因為商城已經會開啟結帳頁面。
- 完成付款後,維持測試模式,在 訂單 中找到新訂單,並記下訂單 ID。
預期結果: 測試付款成功,訂單出現在測試訂單清單中。使用 Tokenz 測試伺服器時,只能確認結帳流程已跑通,遊戲餘額不會改變。使用自己的伺服器時,應找到帶簽章的 order.succeeded 事件與該訂單的發放紀錄。測試玩家餘額必須只增加一次,增加 500 顆寶石。
遇到問題: 開啟預覽無法使用時,先發布測試商城。找不到商品或無法購買時,確認測試模式、發布狀態、已上架價格方案、販售期間與庫存/購買上限。玩家驗證失敗時,請檢查第 4 步。付款成功卻未收到物品時,以訂單 ID 核對事件投遞結果與遊戲發放紀錄。2xx 只代表事件已接收,不代表物品已發放。
不能根據成功頁面或重新導向直接發貨。付款處理中,應等待 order.succeeded 事件,或查詢並確認訂單已成功;取消/失敗返回頁面不能觸發發放。請參閱訂單。
付款後,結帳會將玩家帶回您的商店,而不是遊戲。網路商店的返回 URL 依循商店位址。如果您的遊戲透過 API 自行建立 Checkout Session,請參閱返回您的應用程式。
上線前,使用自己的伺服器確認以下結果:
- 不存在的接收者 ID 回傳
{ "valid": false },並阻擋購買。 - 驗證請求逾時或回傳 HTTP
500時,購買會被阻擋,玩家可以重試。 - 未發布的商品、未上架的價格方案、販售期間外的商品,以及庫存耗盡或已達購買上限的商品均無法購買。
- 投遞失敗的事件會重試。重複投遞同一事件不會重複發放物品;請同時核對訂單紀錄與遊戲餘額。
修正與上述預期不符的行為。即使先前已透過 Tokenz 測試伺服器完成購買,也要使用自己的伺服器完成第 5 步。
6. 正式上線
操作: 將主控台切換到正式模式,開啟 商店 > 商城編輯器,完成 正式上線 清單中的各項:
| 項目 | 操作與預期結果 | 受阻時確認 |
|---|---|---|
| 合約 | 必要時透過 啟用帳戶 簽署。專案適用所屬組織的合約。正式收款需要 Tokenz 核准。 | 等待審核或聯絡支援;簽署完成不等於審核通過。 |
| 正式環境販售中的商品 | 建立/匯入實際販售的正式目錄,發布商品並確認價格方案已上架,核對幣別與金額。 | 測試商品與正式商品分開。只有範例確實對應您打算販售的真實商品時,才匯入正式環境。 |
| 商城 | 從測試複製會以已發布的測試商城取代正式草稿。檢查名稱、文字、網址、支援/政策連結與樣式。 | 修正提示的欄位,上線前替換所有範例內容。 |
| 訂單端點 | 只有自己的測試伺服器也能處理正式訂單時,才選擇 用於正式環境;否則 設定正式 URL。複製新的正式簽章金鑰。 | Tokenz 測試伺服器不能交付正式訂單。共用 URL 也須依模式使用不同金鑰與資料。 |
| 接收者 ID 驗證 | 設定正式驗證 URL,複製正式金鑰,並以獲授權的正式玩家測試。 | 測試驗證 URL 不會自動沿用;正式伺服器必須查詢正式玩家資料。 |
各項準備好後,選擇 啟用商城,發布正式商城。開啟主控台顯示的公開網址,核對正式商品、價格、語言、玩家 ID 說明與連結。不能以測試預覽證明公開商城已可使用。
預期結果: 獲授權的玩家能開啟公開商城,購買預期的正式商品。如果團隊要執行正式驗證購買,請先取得授權,使用支援的真實付款方式,並預期實際扣款。測試卡僅供測試模式使用。像測試時一樣,核對正式訂單、正式事件與遊戲內發放結果。
遇到問題: 公開商城、商品目錄或伺服器不正確時,先停止上線驗證,修正正式設定並重新發布。需要停止販售時,在商城編輯器中停用商城;修改尚未發布的草稿不會改變玩家正在看到的內容。
需要協助?
聯絡 Tokenz 支援時,請提供專案/商城網址、模式、訂單 ID(若已產生)、大致時間與錯誤或 HTTP 狀態。不要提供簽章金鑰或玩家詳情。保留伺服器的事件與發放紀錄,方便開發人員區分付款、投遞與遊戲處理環節的問題。