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.

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.

<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)

<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>

// 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)

<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.

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.