旧ホストページ

旧ホストページは廃止予定であり、サポートを終了しております。こちらの新しいホストページを利用することを強く推奨します。

このページではKOMOJUのホストページを利用する導入方法について説明します。

ホストページ方式では、システムの決済フロー内にKOMOJUのホストページを組み込むことで、決済を実現できます。ホストページは日本国内における主要な決済方法のほとんどに対応しています。

次のスクリーンショットは、KOMOJUのホストページにおける決済画面の例です。

決済情報の作成

エンドポイント

決済リクエストは、GETあるいはPOSTによるHTTPリクエスト方式を用いて、以下のURLに送ってください。

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

URLパラメータ

値	詳細
`locale`	リクエストが送信された地域の言語を指定します。`"ja"`、`"en"`、`"ko"`のいずれかを指定してください。
`merchant_uuid`	クライアントを一意に識別するためのUUIDです。アカウント作成後に送付されます。
`payment_method`	決済方法を定義します。対応している決済方法の一覧およびパラメータ値は下記の通りです。

決済（支払い）方法

決済名	パラメータ値
銀行振込	`bank_transfer`
ビットキャッシュ	`bit_cash`
クレジットカード	`credit_card`
コンビニ	`konbini`
NET CASH	`net_cash`
PayEasy	`pay_easy`
WebMoney	`web_money`
キャリア決済(日本)	`japan_mobile`
LINE Pay	`linepay`
メルペイ	`merpay`
PayPay	`paypay`
楽天ペイ	`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 シンガポール	`grabpayotp`
eNETS	`enets`
DOKU Wallet	`doku_wallet`
OVO	`ovo`
FPX Online Banking	`fpx`
Happy Money	`happy_money`
Culture Voucher	`culture_voucher`
キャリア決済	`mobile`
Toss	`toss`
Kakao Pay	`kakaopay`

リクエストパラメータ

ホストページへの決済リクエストには、以下に示す必須パラメータを送信する必要があります。

任意パラメータを送信することで、決済画面における顧客情報の一部をあらかじめ入力しておくことができます。これによって、顧客の情報入力の手間を削減することができます。任意パラメータによって自動入力された情報は、顧客が決済画面上で書き換えることも可能です。

必須パラメータ

パラメータ	詳細	値
`timestamp`	リクエスト時におけるUTC基準のUNIXタイムスタンプです。リクエストが有効となるには、タイムスタンプはサーバの時間から5分以内である必要があります。	UNIXタイムスタンプ
`transaction[amount]`	課税前の合計金額を指定してください。金額は0以上である必要があります。小数点には`'.'`を使用してください。千の単位を表すカンマは省略してください。	例: 1234.56
`transaction[cancel_url]`	決済プロセスをキャンセルしたユーザーがリダイレクトするURLです。	httpまたはhttpsを使用した有効なURL
`transaction[currency]`	決済で利用する3文字のISO通貨コードを指定してください。	`"JPY"`
`transaction[external_order_num]`	決済プロセスを追跡するためにお使いのアプリケーションに割り当てられた一意のIDです。	255 文字以下の長さを持つ文字列
`transaction[return_url]`	決済プロセスが正常に完了したユーザーリダイレクトするURLです。	http または https を使用した有効な URL
`transaction[tax]`	課税する税金の金額です。現在、日本で定められている消費税を使用する時は ‘auto’ を設定してください。金額を指定する場合は、小数点には`'.'`を使用し、千の単位を表すカンマは省略してください。税額が通貨単位よりも細かい場合は、KOMOJU側で四捨五入されて調整します。	例: 1234.56
`hmac`	HMAC値以外のすべての値を含んだクエリ文字列によって生成されたHMAC認証値です。	HMACの検証を参照

任意パラメータ

パラメータ	詳細
`transaction[metadata][]`	決済取引に付与できるKey-Valueのペア値です。キー名は任意に設定でき、KOMOJUの管理画面上で確認できます。
`transaction[customer][email]`	コンビニ決済、Pay-easy、および銀行振込の支払方法が記載されたメールの送信先となる顧客のメールアドレスです。クライアントがメール送信設定を有効にした場合のみ利用します。
`transaction[customer][given_name]`	顧客の名前です。
`transaction[customer][given_name_kana]`	顧客の名前のフリガナです。
`transaction[customer][family_name]`	顧客の名字です
`transaction[customer][family_name_kana]`	顧客の名字のフリガナです。

ワンクリック決済

ワンクリック決済を利用することでリピート顧客の迅速な決済を実現できます。

顧客は決済時にクレジットカード情報を保存することを選ぶことができるようになります。この機能により、顧客はクレジットカード情報を再入力しなくてよくなるので、決済のコンバージョンが高まります。

ワンクリック機能は以下のパラメータを指定すると有効になります。

パラメータ	詳細	値
`transaction[external_customer_id]`	顧客に割り当てられたIDです。	255 文字以下の長さを持つ文字列

このパラメータには顧客ごとに一意となる値を指定してください。他の顧客と重複する可能性のある値や悪意のある攻撃者によるなりすましが可能な値を使用してはなりません。

HTTPエラーコード

エラーコード	エラーラベル	詳細
400	Bad Request	リクエストパラメータ不正を示すエラーです。このエラーは、必須項目が不足している場合や、不正なリクエストパラメータが指定された場合に表示されます。
401	Unauthorized	認証無効を示すエラーです。このエラーは、HMAC、タイムスタンプ、クライアント名、またはその他の要素を特定する重要な情報に問題がある時に表示されます。例: `401 - Unauthorized. The HMAC provided is not correct.`
422	Unprocessable Entity	このエラーは取引情報（`transaction`）が保存できない時に表示されます。ほとんどの場合、リクエストパラメータの形式が上述の仕様に沿っていないことが原因です。認証の失敗に関するエラーメッセージが届きますので、確認してください。例: `422 - Unprocessable Entity. Amount is not a number.`

HMACによる検証

完全性を確実に保つために、KOMOJUへのリクエストパラメータにはHMAC(Hash-based Message Authentication Code)によるハッシュ値が含まれています。

このハッシュ値は、ホストページのURLへ送信するリクエストパラメータと、非公開鍵を用いて計算する、SHA-256ハッシュ値です。お使いのアカウントの非公開鍵は、KOMOJUの管理画面から確認できます。このハッシュ値を検証することによって、KOMOJUはリクエストの完全性を保ちます。

ハッシュの計算における制限事項は下記の通りです。

ハッシュ値は大文字と小文字を区別する。
ハッシュ値の計算にはリクエストに対して有効なパラメータだけが含まれる。
- 余分に追加されたパラメータは、ハッシュ値の検証前に削除される。
ハッシュ値を計算する際、パラメータ群はキー名におけるアルファベット順に並べ替える必要がある。
パラメータのキー名と値はいずれもエスケープされている必要がある。
- つまり、いずれも次の文字だけ含んでいること: a-z, A-Z, 0-9, _, ., -, +

上記の仕様通りに算出したHMACを用いても不正なHMACを示す401認証エラーが発生した場合、HMACを生成するために使用したURLとHTTPレスポンスヘッダのURLが同じことを確認してください。これらは、大文字と小文字およびパラメータの順番も同じである必要があります。

コードサンプル

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";

Webhookで支払い完了通知を受信

お使いのアプリケーションがKOMOJUからの支払いの完了通知を受けるためには、Webhookの設定を行う必要があります。

顧客の支払いが完了したら、KOMOJUは設定されたURLにpayment.capturedイベントを送信します。あなたのアプリケーションはこの通知を処理して支払いの完了を記録する必要があります。