Skip to content

Browse docs

GuidesAPI Reference
Build with AI
Checkout integrationIntegrate checkout

Integrate checkout

Integrate our seamless checkout solution and empower your players with payment methods across APAC.

Automatic integration (AI-assisted)

Copy the prompt below into your AI coding tool (Claude Code, Cursor, Codex, …) inside your project directory. The agent fetches our machine-readable docs and implements a complete test-mode integration; you review the changes, add your API keys, and go live.

Even better — connect the Tokenz MCP. If your AI tool supports MCP, add our server and the agent can search the docs, create test checkout sessions, and verify webhook signatures directly — a guided, self-verifying integration. The prompt below works with or without it.

bash
claude mcp add --transport http tokenz https://mcp.tokenz.one/mcp --header "Authorization: Bearer secret_test_YOUR_KEY_HERE"
Prompt: integrate Tokenz Checkout end-to-end in test mode
You are integrating Tokenz — a Merchant of Record (MoR) checkout — into this project, end to end, in TEST MODE.

If a Tokenz MCP server is connected to you (you will see tools like `search_docs`, `get_openapi`, `create_test_checkout_session`, and `verify_webhook_signature`), use it throughout the steps below: prefer `search_docs`/`get_doc` over fetching raw doc URLs, and use `create_test_checkout_session` + `get_order` to prove the integration works against the real API. Everything below still applies either way.

Before writing any code:
1. Detect my project's stack, then ask me the questions below immediately — and fetch https://docs.tokenz.one/llms-full.txt while you wait for my answers. Treat that file as the single source of truth for everything below. Follow the v2 (current) sections; ignore v1 (legacy). If you cannot fetch URLs, ask me to paste its contents.
2. The questions:
   - What product(s) should the checkout sell (name, amount, currency)?
   - Which environment file should hold my Tokenz sandbox secret key and webhook signing secret (e.g. .env.local)? I will fill in the values myself.
   - Confirm the framework/stack you detected in this project before patching anything.
   - If this project only runs locally: how should Tokenz reach the webhook endpoint? (Offer to set up a tunnel such as ngrok or cloudflared, or ask me for a deployed HTTPS URL.)

Constraints (non-negotiable):
- Never hardcode, log, or commit secrets — API keys and webhook signing secrets alike; read them from environment variables only.
- Create Checkout Sessions server-side only; never expose the secret key to the browser.
- Define products and prices server-side; never trust amounts sent by the browser. Amounts are in minor units, and every product item needs a taxCategory from the docs' enum.
- Verify webhook signatures (Tokenz-Signature header) over the raw, unparsed request body; do not skip this.
- Fulfill orders from verified webhook events (order.succeeded), never from the customer reaching the success page — redirects prove navigation, webhooks prove payment. Handle webhook retries idempotently; the same event can be delivered more than once.
- Build redirect URLs from a configured base URL, not from request headers such as Origin.
- Stay in Tokenz test mode until I explicitly ask to go live.
- Keep changes minimal; do not refactor unrelated code.
- Communicate with me in the language I use with you.

Deliverables — verify each actually works before claiming it is done:
1. A server endpoint that creates a Tokenz Checkout Session and returns its URL.
2. A checkout button/flow that redirects the customer to the hosted checkout.
3. Success, processing, and canceled pages wired to the session's redirect URLs. (Some payment methods settle asynchronously — the processing page is not optional.)
4. A webhook endpoint that receives events, verifies the signature, and updates order state. As soon as the webhook URL is known, tell me so I can register it in the Tokenz Dashboard (remind me: register it in TEST mode; the Dashboard shows the signing secret once, and I will put it into the env file myself — never ask me to paste it in chat) — then keep building while I do that.
5. A completed end-to-end test purchase using the test cards from the docs, with the webhook received and verified. If you have browser-automation tools, perform the test purchase yourself; otherwise give me exact steps.
6. A short go-live checklist for me: everything that must change to leave test mode (live keys, live webhook registration with its new signing secret, a stable public webhook URL, real tax/fulfillment handling), plus anything you stubbed.

If any step is blocked (missing key, docs ambiguity, unsupported stack), stop and ask me instead of guessing.

Prerequisites

Before you can have a working integration, make sure you have the API credentials (public key and secret key) from Tokenz. You can find your credentials on the Development page on the Tokenz Dashboard.

For more details on how Tokenz Checkout works, please see Checkout.

While integrating, use your test API keys (they contain test_, e.g. secret_test_...): Checkout Sessions created with them run in test mode and no real money moves. Switch to your live keys when you go live.

Set up the server

python
import os
from flask import Flask, request, redirect
from flask_cors import CORS
import requests

# Replace the keys with yours
SECRET_KEY = os.environ.get("SECRET_KEY", "secret_test_YOUR_KEY_HERE")

app = Flask(__name__, static_url_path="")
CORS(app)

root = "../client/build"


@app.route("/", methods=["GET"])
def index():
    return redirect("http://localhost:3080")

Create a Checkout Session

Add an endpoint on your server that creates a Checkout Session. A Checkout Session controls what your customer sees on the Tokenz-hosted payment page, such as line items, the order amount, currency, and available payment methods.

Define the line items

Always keep sensitive information about your product inventory, like price and availability, on your server to prevent customer manipulation from the client. Define product information when you create the Checkout Session.

The order total is always computed from the itemDetails prices. The top-level amount field shown in some examples is optional, but if you provide it, it must match the itemDetails total or the request is rejected.

Tax. This quickstart (and its example payloads) documents the Merchant of Record (MoR) model — the default for Tokenz accounts — where Tokenz computes and collects tax automatically and you only set each item's taxCategory. If your account is specially configured for the Payment Gateway model, every Checkout Session must additionally include a top-level tax object in minor units (for example "tax": { "amount": 0, "currency": "USD" }); requests without it are rejected with order.tax-required. If you're unsure which model your account uses, check with your Tokenz contact.

Supply success and cancel URLs

Specify URLs for success and cancel pages—make sure they're publicly accessible so Tokenz can redirect customers to them. You can also handle the successful and canceled states with the same URL.

[optional] Define available payment method(s)

Specify the list of payment methods offered to your customer for this checkout. If the payment methods are not provided or an empty list is sent, all available payment methods will be displayed to the customer.

Redirect the customer to the Tokenz checkout

After creating the session, redirect your customer to the checkout page's URL returned in the response.

python
@app.route("/create-tokenz-checkout", methods=['POST'])
def create_tokenz_checkout():
    CALLBACK_URL_PREFIX = request.headers['referer']

    headers = {"Authorization": f'Bearer {SECRET_KEY}'}
    print(headers)

    payload = {
        "amount": {
            "currency": "JPY",
            "amount": 5200
        },
        "itemDetails": [
            {
              "product": {
                  "label": "ひとにぎりのエメラルド",
                  "description": "80+8",
                  "images": [
                      "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp"
                  ],
                  "quantity": 3,
                  "price": {
                      "currency": "JPY",
                      "amount": 1200
                  },
                  "taxCategory": "DIGITAL_GOODS_AND_SERVICES"
              }
            },
            {
              "product": {
                  "label": "エメラルドの荷車",
                  "description": "100+10",
                  "images": [],
                  "quantity": 1,
                  "price": {
                      "currency": "JPY",
                      "amount": 1600
                  },
                  "taxCategory": "DIGITAL_GOODS_AND_SERVICES"
              }
            }
        ],
        "customerInfo": {},
        "successUrl": "http://localhost:9000/success",
        "pendingUrl": "http://localhost:9000/pending",
        "cancelUrl": "http://localhost:9000/cancel"
    }

    res = requests.post(
        "https://api.tokenz.one/v2/checkoutsession", json=payload, headers=headers
    )
    
    session = res.json()

    return redirect(session["url"], 303)

Build your checkout

Add a success page

Create a success page for the URL you provided as the Checkout Session successUrl to display order confirmation messaging or order details to your customer. Tokenz redirects to this page after the customer successfully completes the checkout.

html
<!DOCTYPE html>
<html>
<head>
  <title>Thanks for your order!</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <section>
    <p>
      We appreciate your business! If you have any questions, please email
      <a href="mailto:orders@example.com">orders@example.com</a>.
    </p>
  </section>
</body>
</html>

Add a processing payment page

For asynchronous payment methods, like convenience store payment or bank transfer, the payment might be in a processing state for a few minutes up to a few days. Add a page for the pendingUrl. Tokenz redirects to this page after the customer closes the instructions page for asynchronous payments.

html
<!DOCTYPE html>
<html>
<head>
  <title>Thanks for your order!</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <section>
    <p>
      Your payment is being processed! We will let you know as soon as it is completed.
      If you have any questions, please email
      <a href="mailto:orders@example.com">orders@example.com</a>.
    </p>
  </section>
</body>
</html>

Add a canceled page

Add another page for cancelUrl. Tokenz redirects customers to this page when they click the back button during checkout.

html
<!DOCTYPE html>
<html>
<head>
  <title>Checkout canceled</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <section>
    <p>Forgot to add something to your cart? Shop around then come back to pay!</p>
  </section>
</body>
</html>

Add a checkout button

Finally, add a page to show customers a preview of their order. Allow them to review or modify their order—as soon as they land on the Checkout page, the order is final, and they can't modify it without creating a new Checkout Session.

Add a button to your order preview page. Customers are redirected to the Tokenz-hosted payment page when they click this button.

html
<!DOCTYPE html>
<html>
  <head>
    <title>Buy cool new product</title>
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <section>
      <div class="product">
        <img src="https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp" alt="ひとにぎりのエメラルド" />
        <div class="description">
          <h3>ひとにぎりのエメラルド</h3>
          <h5>1,200円</h5>
        </div>
      </div>
      <form action="/create-tokenz-checkout" method="POST">
        <button type="submit" id="checkout-button">Checkout</button>
      </form>
    </section>
  </body>
</html>