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:

Payment Methods

Name API Value
Bank transfer bank_transfer
BitCash bit_cash
Credit Card credit_card
Konbini konbini
nanaco nanaco
NET CASH net_cash
PayEasy pay_easy
WebMoney web_money

Creating a payment

Endpoint

Payment requests should be made to the following URL:

  • https://{env-domain}/{locale}/api/{merchant_uuid}/transactions/{payment_method}/new

Where

Name Description
env-domain Production or Sandbox e.g. sandbox.komoju.com, komoju.com
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

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.

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(OpenSSL::Digest::Digest.new('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";