Hosted Page

KOMOJU Hosted Page is the easiest and most secure way to collect money from your customers.

With a single integration you can support the following features:

  • A fully international checkout supporting multiple languages and currencies.
  • Ability to show multiple payment methods allowing customers to pay how they want.
  • Secure and PCI compliant, allowing you to process credit card payments without worry.


Note, if you are looking for our older Hosted Page API you can find it here.

Accepting a payment

You will first need to create a Session to generate a Hosted Page URL which you can use to redirect your customer to pay.

Create a Session

Create a Session and pass the amount, currency, and your system's external_order_num. You can do this using our JSON API by making an authenticated HTTP request to /api/v1/sessions:

Example Request

curl -X POST \
  -u sk_12345: \
  -d "return_url=" \
  -d "amount=1000" \
  -d "currency=JPY"
  -d "payment_data[external_order_num]=my_order_number"

Example Response

  "id": "boc2hxvmyl497eekihyrwmmgm",
  "resource": "session",
  "mode": "payment",
  "payment": null,
  "session_url": "",
  "return_url": "",
  "default_locale": "ja",
  "payment_methods": [
      "type": "credit_card"
      "type": "konbini"
  "created_at": "2020-12-09T18:26:59.000+09:00",
  "cancelled_at": null,
  "completed_at": null,
  "status": "pending"

This is a simple request with minimal input parameters. Check out the Quick Reference for some more thorough examples.

Redirect your customer

After creating a Session redirect your customer to the session_url returned in the JSON response shown above. The customer will complete payment and be redirected to the return_url after completing the payment flow.

Check the payment status

You will need to setup a webhook to receive payment notification after the customer completes the payment flow. KOMOJU will send payment.captured to your backend system once payment is received. The payment.captured webhook includes a session parameter. Use this parameter to confirm whether the payment came from the session you created in the previous step.

Try not to rely on the return_url redirect for delivering goods to the customer. Some payment methods require explicit user interaction before redirecting to return_url, and so some customers may never be redirected.

When the customer is redirected to your return_url, it will include a session_id=xxxxx query parameter. For example, if the session was created with return_url=, the customer will be redirected to when done. You must perform a GET Session request with the given session_id to know the outcome. Here are the possible outcomes:

session.status meaning
completed The customer inputted their info successfully. The session object will contain a payment that is either authorized or captured.
cancelled The customer clicked "return to merchant" without paying. A pending payment may be present on the session object if the user tried and failed to pay.
pending This status is for newly-created sessions only. We will never redirect customers to your return_url for pending sessions.

Sequence diagram

ShopShopKOMOJUKOMOJUCustomerCustomerCreate SessionRedirect to `session_url`Complete payment flowRedirect to `return_url`GET /api/v1/sessions/{id}Check `payment.status=captured`Show order pending or complete pageWebhook `payment.captured`Deliver goods or service

One-click Payment

One click

One-click payment allows returning shoppers to checkout faster using credit card. When a customer enters checkout they can choose to store their card information for future purchases. This improves checkout conversion as customers don't have to re-input their card information.

You can enable this feature by passing the following parameter:

Parameter Description Value
external_customer_id A unique reference ID used to track a customer. A string, less than or equal to 255 characters long.

As a security precaution, make sure this value is unique to your customer. Don't use a value that could conflict with another customer or easily be duped by an attacker to allow unauthorized use of another customers payment details.

Request Examples

For more detailed field descriptions please see the KOMOJU API Reference.

  • cURL
  • Node.js
  • Ruby
curl -X POST \
  -u sk_123456: \
  -d "default_locale=ja" \
  -d "" \
  -d "metadata[test]=value" \
  -d "amount=8888" \
  -d "currency=JPY" \
  -d "payment_data[external_order_num]=my_custom_order" \
  -d "payment_data[name]=John" \
  -d "payment_data[name_kana]=ジョン" \
  -d "payment_types[]=credit_card" \
  -d "payment_types[]=konbini" \
  -d "return_url=" 
var querystring = require('querystring');
var https = require('https');
var secret_key = 'sk_123456'
var auth = 'Basic ' + Buffer.from(secret_key + ':').toString('base64');
var post_data = querystring.stringify({
  'default_locale': 'ja',
  'email': '',
  'metadata[test]': 'value',
  'amount': '8888',
  'currency': 'JPY',
  'payment_data[external_order_num]': 'my_custom_order',
  'payment_data[name]': 'John',
  'payment_data[name_kana]': 'ジョン',
  'payment_types[]': 'credit_card',
  'payment_types[]': 'konbini',
  'return_url': ''

var post_options = {
  host: '',
  port: '443',
  path: '/api/v1/sessions',
  method: 'POST',
  headers: {
    'Authorization': auth,
    'Content-Length': Buffer.byteLength(post_data)

var post_req = https.request(post_options, function(res) {
    res.on('data', function (chunk) {

require 'uri'
require 'net/https'
require 'json'
require 'base64'
require 'pp'
uri = URI.parse('')
https =, uri.port)
https.use_ssl = true
secret_key = 'sk_123456'
auth = Base64.encode64("#{secret_key}:")
headers = {
  'Content-Type' => 'application/json',
  'Authorization' => "Basic #{auth}"

body = {
  default_locale: "ja",
  email: "",
  metadata: {
    test: "value"
  amount: "8888",
  currency: "JPY",
  payment_data: {
    external_order_num: "my_custom_order",
    name: "John",
    name_kana: "ジョン"
  payment_types: [
  return_url: ""

res =

puts res.body
  "id": "e9x5mvx3jkpkofzcg7umfael6",
  "resource": "session",
  "mode": "payment",
  "amount": 8888,
  "currency": "JPY",
  "payment": null,
  "session_url": "",
  "return_url": "",
  "default_locale": "ja",
  "payment_methods": [
      "type": "credit_card"
      "type": "konbini",
      "brands": {
        "seven-eleven": "/images/konbini/seven-eleven.svg",
        "lawson": "/images/konbini/lawson.svg",
        "family-mart": "/images/konbini/family-mart.svg",
        "ministop": "/images/konbini/ministop.svg",
        "daily-yamazaki": "/images/konbini/daily-yamazaki.svg",
        "seicomart": "/images/konbini/seicomart.svg"
  "created_at": "2020-08-17T18:03:53.000+09:00",
  "cancelled_at": null,
  "completed_at": null,
  "status": "pending"