ウェブショップを設定する
Tokenz がホスティングするショップを作り、テスト購入、ゲームサーバー連携、ライブ公開まで進めます。この手順ではストア画面の開発や Checkout Session API の呼び出しは不要です。ショップからプレイヤーの決済画面が開きます。
例として 500 Gems を 480円で販売します。SKU は gem-pack-500、テスト用プレイヤー ID は player-42931 です。1パックの購入で、このアカウントにジェムが500個付与されることを確認します。商品と ID は例です。公開前に、販売する実際の商品と利用可能なテストアカウントに置き換えてください。
始める前に
- Tokenz ダッシュボードにログインします。アクセスできない場合は、組織の管理者または Tokenz サポートに利用開始を依頼してください。
- 組織・プロジェクトの切り替えメニューからゲームのプロジェクトを選びます。まだ存在せず、作成権限がある場合は 新規プロジェクトを選びます。プロジェクト名、必須のカタカナ名(例:Example Game、サンプルゲーム)、連絡先メールアドレス、重複しないアドレス用スラッグを入力します。法人に関する確認事項は該当する場合のみ確認し、該当しない場合は Tokenz に相談してください。プロジェクトを作成しただけではライブ決済は有効になりません。
- テストモードに切り替えます。ショップ > 商品、ショップ > ビルダー、開発者設定を開けることを確認します。表示されない、または編集できない場合は、管理者に権限とウェブショップの利用可否を確認してください。
- 必要に応じてロゴや画像を用意します。後半の連携に向けて、プレイヤー検証と注文イベントを受け取る2つの HTTPS ハンドラーを開発者に準備してもらいます。最初の購入は、どちらも用意せず Tokenz のテストサーバーで試せます。
期待する結果: 対象ゲームのプロジェクトとテストモードが選択され、商品とショップを編集できます。課金やライブ公開はまだ行われていません。
うまくいかない場合: 権限を変更する前に、選択中の組織とプロジェクトを確認してください。プロジェクトが見つからない、作成できない、アクセスできない場合は、管理者または Tokenz サポートにアカウント・プロジェクトの設定を依頼します。
商品、ショップの内容、Webhook エンドポイントはテストとライブで別々です。ただしショップのアドレスは共通で、どちらかで変更すると両モードのアドレスと決済後の戻り先 URL が変わります。商品やエンドポイントを変更する前にモードを確認してください。
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 にして商品を保存・公開します。価格プランが販売対象になっていることも確認してください。公開済みでも、販売対象の価格プランがなければ購入できません。
期待する結果: テストの商品一覧に、SKU gem-pack-500 の公開済み商品 500 Gems があり、販売対象の買い切りプランに 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 は 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は1パック500個です。数量1なら500個、数量2なら1,000個付与します。
同じイベントの再送で再付与しないでください。ワーカーの再試行でも重複しないよう、付与と完了記録の整合性を保ちます。不明な SKU や recipientId の欠落は調査し、付与先を推測しないでください。再送とべき等性を参照してください。開発者は配送記録を登録して履行の証跡を残すこともできます。
refund.created は返金の依頼であり、成功の通知ではありません。全額・一部返金で何を回収するか決めてください。依頼時に回収するなら、refund.failed で返金が失敗したときに戻す処理も必要です。返金を参照してください。
4. 受取人 ID を確認する
最初の購入で Tokenz のテストサーバーを使った場合は、自社のゲームサーバーを接続してから進めてください。プレイヤー検証を設定したら、自社サーバーで手順5を実施します。検証 URL と注文イベント URL は別の連携で、同じアプリでホストしても署名シークレットは別です。
- テストゲームに
player-42931を作るか、既存のテストアカウントの ID にすべて置き換えます。購入前のジェム残高を記録します。 - 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 }
期待する結果: 存在する ID は valid: true、存在しない ID は valid: false になります。不一致も正常な HTTP 応答で返し、HTTP エラーにはしません。このテストは決済を作成せず、アイテム付与の確認にもなりません。
うまくいかない場合: 2xx 以外、不正な JSON、真偽値でない valid はサービス障害として扱われ、タイムアウトも購入を妨げます。検証 URL 専用のシークレットと生の本文での署名検証を確認してください。test が true ならテストのデータを使います。プレイヤーの詳細は返さないでください。元の応答は転送されませんが、プレイヤーは検証の成否を知ることができます。
ライブでは同じ加盟店プロジェクトの同じ受取人 ID に対する成功結果が、既定で5分間再利用されることがあります。任意の validUntil で期限を指定できます。そのためアカウント停止がショップに即時反映されるとは限りません。不一致は再利用されず、テストでは毎回サーバーを呼び出します。受取人 ID の確認を参照してください。
5. テスト購入する
- テストで ショップ > ビルダー > プレビューを開くを選びます。最後に公開したテストショップが開きます。ポップアップがブロックされたらプレビューリンクをコピーして開きます。アクセス情報を含むリンクなので、テスト URL を自作しないでください。
player-42931を入力し、500 Gems を1パック購入します。検証が未設定なら ID は未確認で受け付けられます。設定済みならテストゲームの照合に通る必要があります。- カード決済を選び、テストカード 4242 4242 4242 4242、任意の3桁の CVC、将来の有効期限を入力します。結果の選択肢が出たら成功を選びます。テストで実際のカードを使わないでください。テストカード一覧に他の番号もあります。このショップから決済が開くため、リンク先の API によるセッション作成手順は不要です。
- 決済後、テストの 注文で新しい注文を探し、注文 ID を記録します。
期待する結果: テスト決済が成功し、テストの注文一覧に表示されます。Tokenz のテストサーバーでは決済フローのみ確認でき、残高は変わりません。自社サーバーでは署名付きの order.succeeded と、この注文の付与記録を確認します。ジェム残高が一度だけ500個増えることが合格条件です。
うまくいかない場合: プレビューを開けなければテストを公開します。商品がない・購入できない場合は、テストモード、公開状態、価格プランの販売設定、期間、在庫・上限を確認します。ID の検証失敗は手順4、決済成功後に届かない場合は注文 ID、イベント送信結果、付与ログを照合します。2xx は受信の証明であり、付与成功の証明ではありません。
成功画面やリダイレクトだけで付与しないでください。保留中は確定を待ち、キャンセル・失敗の戻り先で付与してはいけません。order.succeeded または注文を取得した確定状態に基づいて処理します。注文を参照してください。
支払い後、チェックアウトはプレイヤーをゲームではなくショップに戻します。Web ショップの戻り先 URL はショップのアドレスに従います。ゲームが API で独自に Checkout Session を作成する場合は、アプリに戻すを参照してください。
ライブ公開前に、自社サーバーで次の結果を確認してください。
- 存在しない受取人 ID には
{ "valid": false }を返し、購入を受け付けません。 - 検証がタイムアウトするか HTTP
500を返すと、購入は中断され、プレイヤーは再試行できます。 - 未公開の商品、販売対象外の価格プラン、販売期間外の商品、在庫切れや購入上限に達した商品は購入できません。
- 送信に失敗したイベントは再送されます。同じイベントを再送しても二重に付与されないことを、注文記録とゲーム内の残高で確認します。
この結果と異なる動作があれば修正してください。Tokenz のテストサーバーで購入できていても、自社サーバーで手順5を実施します。
6. ライブ公開する
操作: ライブに切り替えて ショップ > ビルダーを開き、ライブ公開の各項目を完了します。
| 項目 | 操作と期待する結果 | 進めない場合 |
|---|---|---|
| 契約 | 必要なら アカウントを有効化から署名します。組織の契約がプロジェクトに適用され、ライブ決済には Tokenz の承認が必要です。 | 審査を待つかサポートに連絡します。署名だけでは承認になりません。 |
| ライブの販売商品 | 実際の商品を作成・インポートして公開し、販売対象の価格プラン、通貨、金額を確認します。 | テスト商品は別です。例の商品を取り込むのは実際に販売する場合だけにしてください。 |
| ショップ | テストからコピーすると公開済みのテストショップでライブの下書きを置き換えます。名前、本文、アドレス、各リンク、デザインを確認します。 | 指摘された項目を直し、公開前に例の内容を置き換えます。 |
| 注文エンドポイント | 自社テストサーバーがライブにも対応している場合だけ ライブでも使うを選び、それ以外はライブ URL を 設定します。新しいライブ用シークレットをコピーします。 | Tokenz のテストサーバーではライブの付与はできません。同じ URL でもモード別のシークレットとデータ処理が必要です。 |
| 受取人 ID の確認 | ライブの検証 URL とシークレットを設定し、利用許可のあるライブのプレイヤーでテストします。 | テスト用 URL は引き継がれません。ライブのデータで照合します。 |
すべて準備できたら ウェブショップを有効化します。ライブのショップが公開されます。ダッシュボードの公開アドレスで商品、価格、言語、ID のヘルプ、リンクを確認します。テスト用プレビューでは公開を確認できません。
期待する結果: 利用可能なプレイヤーが公開ショップから対象のライブ商品を購入できます。チームでライブの確認購入をする場合は、承認を得たうえで実際に使える決済手段を使ってください。実際に課金されます。テストカードはテスト専用です。テスト時と同様にライブの注文、イベント、ゲーム内付与まで確認します。
うまくいかない場合: 公開ショップ・商品やサーバーが違っていたら確認購入を中止し、ライブの設定を直して再公開します。販売を止めるにはビルダーでショップを無効化してください。未公開の下書きの編集だけでは表示中のショップは変わりません。
お困りの場合
Tokenz サポートにはプロジェクト・ショップのアドレス、モード、注文 ID(あれば)、おおよその時刻、エラーや HTTP ステータスを伝えてください。署名シークレットやプレイヤーの詳細は含めないでください。イベント・付与ログを保管し、開発者が決済、イベント送信、ゲーム内処理のどこで失敗したか切り分けられるようにします。