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 for the exact encoding per currency.

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.

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.

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.