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"

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

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: ["credit_card", "konbini"],
  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"