---
title: "Checkout"
description: "Learn how to use Checkout to collect payments on your website."
source: "https://docs.tokenz.one/en/v2/checkout"
api_version: "v2"
locale: "en"
version_status: "current"
docs_stage: "prod"
---

# Checkout

Learn how to use Checkout to collect payments on your website.

Tokenz Checkout is a prebuilt payment form that allows businesses to securely accept payments online. Its built-in features reduce development time. You can accept payments by directing customers to a Tokenz-hosted payment page.

You can customize Checkout and access additional functionality with the Checkout Session API.

**Amount format:** All monetary values (such as `amount` fields) are expressed in the smallest minor unit of each currency. See [Supported currencies](https://docs.tokenz.one/en/v2/checkout/currency) for the exact encoding per currency.

## Start integrating

### Let your AI agent build it

Point Claude Code, Cursor, or Codex at the Tokenz MCP and it wires up a working test-mode integration — you review and ship.

```bash
claude mcp add --transport http tokenz https://mcp.tokenz.one/mcp --header "Authorization: Bearer secret_test_YOUR_KEY_HERE"
```

[Start with AI](https://docs.tokenz.one/en/v2/checkout/get-started)

### Integrate it yourself

Follow the quickstart: create a Checkout Session, redirect to the hosted page, and handle the webhook.

[Open the quickstart](https://docs.tokenz.one/en/v2/checkout/get-started#prerequisites)

## Checkout lifecycle

1. The customer selects items and clicks checkout on your website.
2. Your server creates a new Checkout Session with the Tokenz API.
3. The Tokenz API returns the Checkout Session.
4. Your server redirects the customer to the Tokenz-hosted payment page.
5. The customer completes the payment on the Tokenz-hosted payment page.
6. Tokenz redirects the customer back to your website.
7. Tokenz sends a webhook event to your server.
8. Your server fulfills the order using the `order.succeeded` event.

```mermaid
sequenceDiagram;
autonumber;
participant U as Merchant Client<br/> (Web Shop);
participant M as Merchant Server;
participant T as Tokenz API;
participant TC as Checkout;
%% 1 ── Purchase request;
U->>M: Select items and click checkout;
%% 2 ── Ask Tokenz for a Checkout Session;
M->>T: Create Checkout Session;
T-->>M: Return Checkout Session;
%% 3 ── Redirect the browser to Tokenz checkout;
M-->>TC: Redirect the Customer to the url from the<br/> Checkout Session;
TC->>TC: Customer completes the payment;
%% 4 -- Browser redirect;
TC-->>U: Customer returns to your page;
%% 5 ── Webhook;
T->>M: Webhook sent to your application;
M->>M: Fulfill the order;
```

## Checkout Session

The Checkout Session is a programmatic representation of what your customers see on the payment form. After creating a Checkout Session, redirect your customers to the `url` to complete the purchase. When customers complete their purchases, you can fulfill their orders by configuring webhooks on Order events. The following example shows how to create a Checkout Session.

```bash
curl --request POST \
  --url https://api.tokenz.one/v2/checkoutsession \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "itemDetails": [
      {
        "product": {
          "price": {
            "amount": 1000,
            "currency": "JPY"
          },
          "images": [
            "https://images.ctfassets.net/z82qbo7cv7ia/6LaDyyNBQ5Sqd1THQYxksI/ff5bce84e3864a4f826f5aed0822bd10/treasure-chest-1.png"
          ],
          "quantity": 1,
          "label": "Treasure Chest",
          "taxCategory": "DIGITAL_GOODS_AND_SERVICES"
        }
      }
    ],
    "successUrl": "https://example.com/success",
    "pendingUrl": "https://example.com/pending",
    "cancelUrl": "https://example.com/cancel",
    "customerInfo": {}
  }'
```

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 categories

Each product in your Checkout Session must include a `taxCategory` field for proper tax calculation and compliance. The following categories are supported:

- `VIRTUAL_CURRENCY`: In-game currency, tokens, or virtual coins
- `DIGITAL_GOODS_AND_SERVICES`: Digital products like game items, downloadable content, or digital services
- `EBOOK`: Electronic books and publications
- `SAAS`: Software as a Service subscriptions

Choose the category that best matches your product type to ensure accurate tax handling.

## Payment methods

You can customize which payment methods to offer to your customers on the Tokenz-hosted payment page. Send one or more supported options in the `paymentMethodKinds` argument to specify the payment methods available to the customer. If the argument is not included or an empty list is sent, all supported payment methods are displayed.