Loading search…

Loading search…

Skip to content
Checkout integrationSet up your webshop

Set up your webshop

Build a Tokenz-hosted shop, make a Test purchase, connect your game server, then launch in Live. You do not need to build a storefront or call the Checkout Session API for this walkthrough: the hosted shop opens checkout for the player.

We will sell 500 Gems for ¥480, using SKU gem-pack-500 and test player player-42931. One purchased pack must add 500 gems to that player's test account. The product and player are examples; use your own approved content and a real test account before launch.

Before you start

  1. Sign in to the Tokenz Dashboard. If you do not have access, ask your organization administrator or Tokenz support to arrange it.
  2. Open the organization/project switcher and select the project for your game. If it does not exist and you have permission, choose New Project. Fill in the project name, required katakana name (for example, Example Game and サンプルゲーム), contact email and a unique address slug. Confirm the legal-entity statement only if it applies to your project; otherwise contact Tokenz. Creating a project does not by itself enable Live payments.
  3. Switch the dashboard to Test. Confirm that you can open Shop > Products, Shop > Builder, and the developer settings. Ask an administrator for the missing permissions or webshop access if these pages are unavailable or read-only.
  4. Prepare a logo/image if you want one. For the later server steps, assign a developer who can expose two HTTPS handlers: one for player validation and one for order events. The first purchase can use the Tokenz test server without either handler.

Expected result: The correct game project and Test mode are selected. You can edit products and the webshop. You have not charged anyone or published a Live shop.

If you get stuck: Check the selected organization/project before changing permissions. If the project is missing, creation is unavailable or access remains blocked, ask your administrator or Tokenz support to finish account/project setup.

Products, shop content and webhook endpoints are separate for Test and Live. The shop address is shared: changing it in either mode also changes the other mode's address and checkout return URLs. Use the mode switch before every catalog or endpoint change.

1. Add products

For a reproducible first product, save the following as a UTF-8 file named products.csv. In Test, open Shop > Products, choose Import products, and upload it:

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

Review the preview, fix any errors, then select Import. The SKU identifies the product; the name is what players see. The price is 480 Japanese yen, the tax category is for in-game currency, and publish makes the product published rather than a draft. See Import products for images, other currencies and larger catalogs.

If you create the item through the form instead, use the same values. Add a One-time plan under Add New Plan, set its default price to 480 JPY, save the item, then publish it. Confirm that the price plan is listed: a published product without a listed plan is not purchasable.

Expected result: Products contains one published 500 Gems item with SKU gem-pack-500 and a listed one-time price plan showing ¥480. The Test catalog contains it; the Live catalog has not changed.

If you get stuck: An import preview with errors writes nothing; fix the named row and upload again. Import results can also report individual failures, so inspect the result. If the SKU already exists, import updates that product—do not keep retrying with new SKUs. If you cannot add/list a price plan or publish, ask your administrator for those permissions. For the first purchase, leave sale windows, stock and purchase limits unset.

Later, test any limits you enable. Daily, weekly, monthly and yearly purchase-limit resets use UTC; weeks start on Monday and years on January 1. Without a reset period, the per-player limit does not reset automatically.

2. Build the shop

  1. Open Shop > Builder > Edit Webshop. Set a unique shop address if the project does not already have one. Use the address shown by the dashboard; do not add a test- prefix yourself.
  2. Check the English shop/brand name and English game name. For this Test example, use Example Game Store and Example Game. English is always offered and supplies fallback text when a translation is empty.
  3. Add your logo/colours and any shop text you want. If an older shop still shows Fantasy Studio or its translated sample company name, replace it with your publisher's name or turn off Override Company Name. A sample company name can block activation. Hero images, the project brief and About text are optional; review the support and policy links you intend to show before launch.
  4. Under Player ID help, explain where players can find their ID in your game. For example: “Open Settings > Account and copy Player ID.” Replace that path with your game's actual instructions. Add the languages your players need and review their text.
  5. Select Save Changes, then Publish.

Expected result: Your Test shop has a saved, published version. The editor preview shows your chosen names and styling. Publishing Test does not activate the public Live shop. Changes saved after publishing remain a draft until you publish them again.

If you get stuck: Fix the field named in the validation message. Check the English names and sample company name first. A taken or reserved address needs a different slug. If the shopper preview looks older than the editor, save and publish again, then reopen the preview; it reads the published version.

3. Set up delivery

No server yet?

Do this: On Shop > Builder, select Set up delivery. In Test, choose Use the Tokenz test server, leave the Test validation URL unset, then go to Make a test purchase. You will return here when your developer's handlers are ready.

Expected result: The Delivery page shows the Tokenz test server. It accepts Test order events and grants no game items. With no Test validation URL, the Test preview accepts the typed recipient ID without checking it.

If you get stuck: This option is for Test. If a Test validation URL is already configured, that server must answer; the order test server does not bypass a configured validator. Resolve the validation error or have your developer remove that Test configuration before trying the server-free route.

Connect your game server

  1. Ask your developer to create an HTTPS POST handler for order events and implement signature verification. For this example, map SKU gem-pack-500 to 500 gems in the test game.
  2. On the Test Delivery page, enter that handler's URL under Where orders go, then select Save endpoint. This also replaces the Tokenz test server when you are ready to leave it.
  3. Select Copy setup brief and send the brief to your developer. Copy the signing secret shown once and share it separately. Store it securely on the server.
  4. Select Send test event and inspect the result. The probe expects a response within 5 seconds. It is a sample event, not a real purchase: its IDs do not identify real orders and it may lack a recipientId. It tests receipt/signing/response, not actual item delivery.

Expected result: Your own Test URL is configured and the signed sample request receives a 2xx response. Your developer can identify it in server logs. You still need the real Test purchase in step 5 to prove delivery.

If you get stuck: Check that the URL is publicly reachable over HTTPS, the handler accepts POST, and the signature uses this endpoint's Test secret and the unchanged raw body. Inspect the HTTP response or timeout in the probe result. See Webhook troubleshooting.

A new Delivery endpoint subscribes to these events:

  • Orders: order.succeeded, order.canceled, order.expired, order.failed.
  • Refunds: refund.created, refund.failed.
  • Disputes: dispute.created, dispute.closed.

order.created is not included by default. For an existing endpoint, check its subscriptions in the developer settings; only the configured events are delivered.

Read the order and grant the items

This excerpt shows the fields your handler needs for our example, not the complete webhook. Verify the signature over the full raw request before reading it. Real event/order IDs are generated by Tokenz; do not hard-code these example IDs.

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 } } }
        ]
      }
    }
  }
}
Top-level id
Deduplicate event deliveries. Store the event durably before returning 2xx; process the work asynchronously.
eventData.data.order.id
Correlate the order with your game grant and delivery log.
eventData.data.order.recipientId
The recipient ID the player typed. Find test player player-42931; do not infer the player from the event ID or SKU.
Each item's detail.product.sku and detail.product.quantity
Grant 500 gems per gem-pack-500 pack: quantity 1 grants 500; quantity 2 grants 1,000.

Do not grant again when the same event is retried. Keep the game grant and its completion record consistent so a worker retry cannot duplicate it. An unknown SKU or missing recipientId needs investigation, not a guessed recipient. See Retries and idempotency. Your developer can also register delivery records as evidence of fulfillment.

refund.created means a refund was requested, not that it succeeded. Decide which items or entitlements to revoke for full/partial refunds. If you revoke on request, handle refund.failed to restore what you revoked when the refund fails. See Refunds.

4. Check recipient IDs

If you used the Tokenz test server for your first purchase, connect your game server before continuing. After setting up player validation, complete step 5 with your own server. The validation URL and order-event URL are separate integrations with separate signing secrets, even if your developer hosts both in one application.

  1. Create test player player-42931 in your test game, or replace this ID consistently with an existing test account. Record its gem balance before buying.
  2. Ask your developer to expose an HTTPS POST validation handler. It must verify Tokenz-Signature with the validation secret, look up the submitted ID in the test game's player records, and return a JSON verdict within 3 seconds.
  3. In Test, open Settings > Developers > User validation, or Open User validation on Delivery. Choose Set up validation, enter the handler's URL and save. Copy the signing secret shown once.
  4. Use Send test validation with player-42931, then with an ID your test game does not contain, such as player-missing.

A validation request looks like this:

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

Return HTTP 200 with the appropriate verdict:

json
{ "valid": true }
json
{ "valid": false }

Expected result: The existing test player returns valid: true; the missing player returns valid: false. A negative verdict is a normal successful HTTP response, not an HTTP error. The dashboard probe does not create a checkout or prove that items can be delivered.

If you get stuck: A non-2xx response, malformed JSON or a non-boolean valid is a service failure; a timeout also blocks checkout. Check the validation URL's own secret and raw-body signature verification. When test is true, use test player records. Return no player details: Tokenz does not forward the raw response, but the player can learn the verdict.

In Live, a successful check may be reused for the same recipient ID within the same merchant project, for five minutes by default. Optional validUntil controls its deadline. Account blocks may therefore not take effect in the shop immediately. Invalid answers are not reused; Test checks always call your server. See Recipient ID checks.

5. Make a test purchase

  1. In Test, open Shop > Builder > Open preview. It opens the last published Test shop. If pop-ups are blocked, use Copy preview link and open the copied link. Do not construct a Test URL yourself; the preview link supplies access.
  2. Enter player-42931, select 500 Gems and buy one pack. If you have not configured validation yet, this ID is accepted unchecked. With your validator configured, it must pass your test-game lookup.
  3. Choose Card. Use test card 4242 4242 4242 4242, any 3-digit CVC and a future expiry date. If a test-result selector appears, choose Success. Never use a real card in Test. The test card reference lists more cards; skip that page's API session-creation steps because your webshop already opens checkout.
  4. Finish payment, then find the new order in Orders while still in Test. Record its order ID.

Expected result: The Test payment succeeds and the order appears in Test Orders. With the Tokenz test server, this proves the checkout flow only; the game balance does not change. With your own server, locate the signed order.succeeded event and the grant record for this order. The test player's balance must increase by 500 gems exactly once.

If you get stuck: If Open preview is disabled, publish Test first. If the product is missing or cannot be bought, check Test mode, publication, a listed price plan, sale window and any stock/limit. If player validation fails, check step 4. If payment succeeds but no gems arrive, compare the order ID, event delivery result and game grant log. A 2xx response proves receipt, not a successful grant.

A success page or redirect is not permission to grant items. A pending payment must wait for authoritative success; a cancel/failure return must not trigger a grant. Your developer should use order.succeeded or retrieve the authoritative order state. See Orders.

After payment, checkout returns the player to your shop, not to your game. The webshop's return URLs follow the shop address. If your game creates its own Checkout Sessions through the API, see Return to your app.

Before going Live, use your own server to check these outcomes:

  • An unknown recipient ID returns { "valid": false } and blocks the purchase.
  • A validation request that times out or returns HTTP 500 blocks the purchase and lets the player retry.
  • An unpublished product, an unlisted price plan, an item outside its sale window, or an exhausted stock or purchase limit cannot be purchased.
  • A failed event delivery is retried. Replaying the same event never grants items twice; verify the game balance as well as the order record.

Fix any behavior that does not match these results. Then complete step 5 with your own server, even if an earlier purchase with the Tokenz test server succeeded.

6. Go live

Do this: Switch the dashboard to Live and open Shop > Builder. Complete each Go Live checklist item:

Scroll horizontally if needed
ItemAction and expected resultIf blocked
AgreementUse Activate Account to sign if needed. A project uses its organization's agreement. Live payments need Tokenz's approval.Wait for review or contact support; signing alone is not approval.
Products on sale in LiveCreate/import the real Live catalog, publish the product and confirm a listed price plan. Review currency and amount.Test products are separate. Import the example only if it represents a real product you intend to sell.
ShopCopy from Test replaces the Live draft with the published Test shop. Review names, text, address, support/policy links and appearance.Fix the named field; replace example content before publishing.
Order endpointUse Use for Live only if your own Test server can also handle Live orders; otherwise Set up a Live URL. Copy the new Live secret.The Tokenz test server cannot fulfill Live orders. A shared URL still needs mode-specific secrets and data handling.
Recipient ID checkSet the Live validation URL and copy its Live secret. Test it with an authorized Live player.A Test validation URL is not carried over; the Live server must check Live records.

Select Activate Webshop once all items are ready. Activation publishes the Live shop. Open the public address shown in the dashboard and verify the Live product, price, language, player help and links. Do not use a Test preview as proof of public availability.

Expected result: An authorized player can open the public shop and buy the intended Live product. If your team performs a Live verification purchase, obtain authorization, use a real supported payment method and expect a real charge. Test cards are for Test only. Check the Live order, Live event and game grant just as in Test.

If you get stuck: Stop launch verification if the public shop/catalog or server is wrong. Correct the relevant Live settings and publish again. If you need to stop sales, deactivate the webshop in Builder; do not rely on editing an unpublished draft to change what players see.

Need help?

When contacting Tokenz support, include the project/shop address, mode, order ID if one exists, approximate time and the error or HTTP status. Do not include signing secrets or player details. Keep your server's event and grant logs so your developer can distinguish payment, delivery and game-processing failures.