• Help & Support
• Sign up
• English

  • 日本語
  • English

Legacy Hosted Page

KOMOJU provides a white-labeled hosted page which you can embed inside your web applications. The hosted page supports all major Japanese payment options, it also emails payment instructions to your customers in Japanese and English. Below are some screenshots of the checkout process:

Creating a payment

Endpoint

Payment requests should be made to the following URL:

• https://komoju.com/{locale}/api/{merchant_uuid}/transactions/{payment_method}/new

URL Parameters

Name	Description
locale	Defines the language locale e.g. ja, en
merchant_uuid	Provided to you after applying for an account
payment_method	Defines the payment method. See available payment methods

Payment Methods

NOTE: Support for LINE Pay and Merpay is currently in development and will be coming to KOMOJU very soon.

Name	API Value
Bank transfer	bank_transfer
BitCash	bit_cash
Credit Card	credit_card
Konbini	konbini
NET CASH	net_cash
PayEasy	pay_easy
WebMoney	web_money
Japan Mobile	japan_mobile
LINE Pay	linepay
Merpay	merpay
PayPay	paypay
Rakuten Pay	rakutenpay
Alipay	alipay
Bancontact	bancontact
BLIK	blik
EPS	eps
Giropay	giropay
iDEAL	ideal
Multibanco	multibanco
MyBank	mybank
paysafecard	paysafe_card
paysafecash	paysafe_cash
Przelewy24	przelewy24
SOFORT Banking	sofortbanking
UnionPay	unionpay
Wechat Pay	wechatpay
PAYCO	payco
Dragonpay	dragonpay
GrabPay Singapore	grabpayotp
eNETS	enets
DOKU Wallet	doku_wallet
OVO	ovo
FPX Online Banking	fpx
Happy Money	happy_money
Culture Voucher	culture_voucher
Carrier Billing	mobile
Paidy	paidy
Toss	toss
Kakao Pay	kakaopay

Request Parameters

The following parameters must be passed using GET or POST HTTP methods to the URL mentioned above. Optional parameters if passed, will be used to pre-populate the form displayed on checkout page. This can greatly help speed up the checkout process if you already have this information available. However, the customer will be able to overwrite those values before validating their purchase.

Required

Parameter	Description	Value
timestamp	A UNIX epoch timestamp in UTC	A timestamp must be within 5 minutes of the server time in order for the request to be considered valid.
transaction[amount]	The amount to be charged before tax. Must be equal or greater than 0. Use a '.' as a decimal separator, and no thousands seperator	Example: 1234.56
transaction[cancel_url]	The URL to send the user back to after cancelling the transaction process.	A valid URI using http or https
transaction[currency]	3 letter ISO currency code of the transaction	JPY
transaction[external_order_num]	This is your applications unique ID used to track this payment.	A string, less than or equal to 255 characters long.
transaction[return_url]	The URL to send the user back to upon successful completion of the process.	A valid URI using http or https
transaction[tax]	The amount of tax to be charged, or ‘auto’ to use the current consumption tax rate in Japan. Use a ‘.’ as a decimal separator, and no thousands separator. If the tax is more precise than the currency allows, it will be rounded using a round half up algorithm.	Example: 1234.56
hmac	HMAC verification of the query string with all values other than the HMAC	See HMAC Verification

Optional

Parameter	Description
transaction[metadata][]	A set of configurable key/value pairs.
transaction[customer][email]	The customer’s e-mail, to which an e-mail will be sent with payment information for convenience store, Pay-easy and bank transfer payments if the merchant is configured to send e-mails
transaction[customer][given_name]	The customer's given name.
transaction[customer][given_name_kana]	The phonetic pronunciation of the customer’s given name. This is common practice when writing Japanese names.
transaction[customer][family_name]	The customer’s family name.
transaction[customer][family_name_kana]	The phonetic pronunciation of the customer’s family name. This is common practice when writing Japanese names.
transaction[customer][phone]	The customer's phone number.

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:

Parameter	Description	Value
transaction[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.

HTTP Error Codes

Error code	Error label	Description
400	Bad Request	This error indicates that the request landed at a valid endpoint, but was missing required fields. The most likely cause is if the transaction parameter is not specified or malformed.
401	Unauthorized	This error indicates a problem with the HMAC, timestamp, account id, or other important identifying information. Example: 401 - Unauthorized. The HMAC provided is not correct.
422	Unprocessable Entity	This error indicates that the transaction was unable to be saved. This is likely due to a validation failure of the transaction record. You will receive an error message describing the issue. Example: 422 - Unprocessable Entity. Amount is not a number

HMAC Verification

Requests to the KOMOJU API which contain potentially user modifiable attributes will use a Hash-based Message Authentication Code to ensure data integrity.

The hash is a SHA-256 hash computed on the parameters passed to the hosted page URL. Your account will have a shared secret API key to compute and verify the integrity of the message. The following restrictions are placed on computation of the hash:

• The hash is case sensitive
• Only valid parameters to the API call are included in computation of the hash. Additional parameters will be removed before the hash is verified.
• The parameters must be alphabetically sorted before the hash is computed.
• The URL keys and values should both be escaped (i.e. they should only contain the following characters: a-z, A-Z, 0-9, _, ., -, and +)

If you encounter a 401 Unauthorized error reporting an incorrect HMAC when you expected a successful result, please verify that the URL you used to generate the HMAC is the same as the one in the HTTP response header. The value is both case sensitive and parameter order sensitive.

Code Examples

Ruby

# Note: This depends on openssl support built in to ruby
require 'openssl'
require 'cgi'

# Use your secret API key here
secret_key = "ABCD1234567890";
endpoint = "/en/api/example-mart/transactions/credit_card/new"

params = {
  "timestamp" => "#{Time.now.to_i}",
  "transaction[amount]" => "130",
  "transaction[currency]" => "JPY",
  "transaction[customer][given_name]" => "John",
  "transaction[customer][family_name]" => "Smith",
  "transaction[customer][given_name_kana]" => "John",
  "transaction[customer][family_name_kana]" => "Smith",
  "transaction[external_order_num]" => "M8x6U6Z5HEeXv3",
  "transaction[return_url]" => "http://example.com/?sucess=true",
  "transaction[cancel_url]" => "http://example.com/?cancel=true",
  "transaction[tax]" => "0"
}.map { |key, val| "#{CGI.escape key}=#{CGI.escape val}" }
params.sort!

query_string = params.join '&'
url = "#{endpoint}?#{query_string}"
hmac = OpenSSL::HMAC.hexdigest('sha256', secret_key, url)

puts "#{url}&hmac=#{hmac}\n";

PHP

# Note: This depends on PHP 5.1.2 or having an implementation of hash_hmac
# http://www.php.net/manual/en/function.hash-hmac.php

# Use your secret API key here
$secret_key = "ABCD1234567890";
$endpoint = "/en/api/degica-mart/transactions/credit_card/new";

$params = array(
  "transaction[amount]" => "130",
  "transaction[currency]" => "JPY",
  "transaction[customer][given_name]" => "John",
  "transaction[customer][family_name]" => "Smith",
  "transaction[customer][given_name_kana]" => "John",
  "transaction[customer][family_name_kana]" => "Smith",
  "transaction[external_order_num]" => "M8x6U6Z5HEeXv3",
  "transaction[return_url]" => "http://example.com/?sucess=true",
  "transaction[cancel_url]" => "http://example.com/?cancel=true",
  "transaction[tax]" => "0",
  "timestamp" => time(),
);
$qs_params = array();
foreach ($params as $key => $val) {
  $qs_params[] = urlencode($key) . '=' . urlencode($val);
}
sort($qs_params);

$query_string = implode('&', $qs_params);
$url = $endpoint . '?' . $query_string;

$hmac = hash_hmac('sha256', $url, $secret_key);

echo "$url&hmac=$hmac\n";

Webhooks

You will need to setup a webhook to receive payment notifications from KOMOJU. When a customer completes the payment flow KOMOJU will send a payment.captured webhook to your application. Your application must process this webhook and record the payment as captured.