---
title: "Hosted Fields | Tokens Integration"
description: "Guide to using KOMOJU Hosted Fields in token mode — collecting a payment token from the browser and processing it server-side, suitable for custom subscription or billing systems."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/hosted-fields-tokens-integration"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/hosted-fields-tokens-integration.md"
language: en
last_modified: "2026-03-25"
---

A standard Fields integration submits payment information directly from the browser to KOMOJU. It's probably the simplest in most cases, but sometimes you might want or need the final submission to happen from your backend. KOMOJU Fields supports such cases by hooking into our tokens API.

The goal of the token integration method is to use Fields to get a token, send the token to your backend, then process it from there.

![](https://files.readme.io/3db4807-1000002134.svg)

# Step 1: create payment session on backend

This step is the same as in standard. Fields always needs a session with an amount and currency in order to render inputs, _even if you don't intend to make a payment immediately_.

Save the `id` field and send it to your frontend.

# Step 2: use session ID to render fields on frontend

Once you have your session, you can render payment fields on your frontend.

Don't forget to specify the `token` boolean attribute.

```html
<script type="module" src="https://multipay.komoju.com/fields.js"></script>

<komoju-fields
  token
  session-id={your_session_id}
  publishable-key={your_publishable_key}
></komoju-fields>

```

# Step 3: decide how you want users to submit

There are 2 ways to submit the fields:

1. Place your `<komoju-fields>` inside of a `<form>` element, and submit the `<form>` like normal, OR
2. Use JS to call `submit()` on your `<komoju-fields>` component: `const token = await document.querySelector('komoju-fields').submit()`.

Different from a standard integration, method 1 _will_ submit your form like normal. In effect, the `<komoju-fields>` element behaves like an `<input>` tag with `value` set to a tokenized version of the user's input. The `name` defaults to `"komoju_token"` and can optionally be changed by changing the `name` attribute on your `<komoju-fields>` element. This token can be safely transmitted to your server, and can be used to make payments or subscription customers.

If you choose method 2, it's up to you to send the `token` to your backend via Fetch or similar.

## Example: fields in a form tag (method 1)

```html
<script type="module" src="https://multipay.komoju.com/fields.js"></script>

<form method="POST" action="/pay">
  <komoju-fields
    session-id={your_session_id}
    publishable-key={your_publishable_key}
    name="komoju_token"
  ></komoju-fields>

  <button type="submit">Pay</button>
</form>

```

```javascript
// Example server in expressjs
app.get('/pay', async (req, res) => {
  const token = req.body['komoju_token']
  const payment = await fetch('https://komoju.com/api/v1/payments', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Basic ${btoa(secretKey + ':')}`
    },
    body: JSON.stringify({
      amount: 1000,
      currency: 'JPY',
      payment_details: token
    })
  }).then(r => r.json())

  console.log(payment)
  // ...
})

```

## Example: manual submit via JS (method 2)

```html
<script type="module" src="https://multipay.komoju.com/fields.js"></script>

<komoju-fields
  id="fields"
  session-id={your_session_id}
  publishable-key={your_publishable_key}
></komoju-fields>

<button type="button" onclick="submit()">Pay</button>

<script>
  async function submit() {
    const fields = document.getElementById('fields');
    const token = await fields.submit();

    await sendTokenToBackendForProcessing(token.id);
  }
</script>

```

If you want to handle errors, see [Handling Hosted Fields Errors](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/hosted-fields-handling-errors.md).

# Step 4: create payment on backend

Once you've sent your token to your backend, you can use it to make payments.

The simplest way to do this is to pay for the session you created in step 1, but you can use this `token` in place of the `payment_details` object for just about any API call.