• Help & Support
• Sign up
• English

  • 日本語
  • English

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 https://komoju.com/api/v1/sessions \
  -u sk_12345: \
  -d "return_url=https://example.com" \
  -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": "https://komoju.com/sessions/boc2hxvmyl497eekihyrwmmgz",
  "return_url": "https://example.com",
  "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=https://example.com, the customer will be redirected to https://example.com?session_id=xxxxx when done. You must perform a GET Session request with the given session_id to know the outcome. Here are the possible outcomes:

Sequence diagram

One-click Payment

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:

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 -X POST https://komoju.com/api/v1/sessions \
  -u sk_123456: \
  -d "default_locale=ja" \
  -d "email=test@example.com" \
  -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=https://example.com" 

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': 'test@example.com',
  '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': 'https://example.com'
});

var post_options = {
  host: 'komoju.com',
  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.setEncoding('utf8');
    res.on('data', function (chunk) {
        console.log(chunk);
    });
});

post_req.write(post_data);
post_req.end();

require 'uri'
require 'net/https'
require 'json'
require 'base64'
require 'pp'
uri = URI.parse('https://komoju.com/api/v1/sessions')
https = Net::HTTP.new(uri.host, 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: "test@example.com",
  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: "https://example.com"
}

res = https.post(
  uri.path,
  body.to_json,
  headers
)

puts res.body

{
  "id": "e9x5mvx3jkpkofzcg7umfael6",
  "resource": "session",
  "mode": "payment",
  "amount": 8888,
  "currency": "JPY",
  "payment": null,
  "session_url": "https://komoju.com/sessions/e9x5mvx3jkpkofzcg7umfael6",
  "return_url": "https://example.com",
  "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"
}