Komoju ではホストページを提供しておりますので、そのページをお使いのアプリケーションに自由に組み込んで利用することができます。ホストページは国内のほとんどのメジャーな決済方法に対応しており、さらに支払い方法を記載したメールを日本語または英語で顧客へ送信いたします。次のスクリーンショットは Komoju を使用した支払プロセスの一例です。

Checkout 1 Checkout 2

Test モード

アカウント作成後、次の URL から Komoju の Test モードにアクセスすることができます:

Test モードを利用する目的は、Live モードが提供する機能すべてを実際にデモしてみて、Komoju のプラットフォームへの統合をスムーズに行えるようにするためです。

決済(支払)方法

決済名 API 値
銀行振込 bank_transfer
ビットキャッシュ bit_cash
クレジットカード credit_card
コンビニ konbini
nanaco nanaco
NET CASH net_cash
PayEasy pay_easy
WebMoney web_money

ペイメントの作成

エンドポイント

支払リクエストは、以下の URL へ送られます:

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

URL パラメータ

詳細
locale リクエストが送信された地域の言語が特定できます。例) ja, en
merchant_uuid クライアントを一意に識別するためのクライアント UUID。アカウント作成後 に送られる情報です。
payment_method 決済方法を定義します。対応している決済方法は こちら

リクエストパラメータ

次のパラメータを、GET または POST HTTP 方式を使って上記 URL へ送信する必要があります。送信後、チェックアウトページに表示されるフォームはオプショナルのパラメータを使用して自動入力されます。この情報がすでに用意されている場合、支払プロセスは即座に完了し大変便利ですが、リクエストを確定する前にこの値を上書きすることも可能です。

必須のパラメータ

パラメータ 詳細
timestamp UTC における UNIX エポック タイムスタンプ リクエストが有効となるには、タイムスタンプはサーバータイム 5 分以内である必要があります
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’ を設定します。小数点には '.' を使用し、千の単位を表すカンマは使用しません。税金が通貨よりもさらに正確で細かい場合は、四捨五入のアルゴリズムを使用して調整します。 例: 1234.56
hmac HMAC 以外すべての値を含んだクエリ文字列の HMAC 認証 HMACの検証を参照

任意のパラメータ

パラメータ 詳細
transaction[metadata][] キーバリューのペアのセット。キー名を任意に設定できます。
transaction[customer][email] クライアントがメール送信の設定をした場合、コンビニ決済、Pay-easy、および銀行振り込みの支払方法が記載されたメールの送信先となる顧客のメールアドレスです。
transaction[customer][given_name] 顧客の名前
transaction[customer][given_name_kana] 顧客の名前のカタカナ読み。
transaction[customer][family_name] 顧客の苗字
transaction[customer][family_name_kana] 顧客の苗字のカタカナ読み。

HTTP エラーコード

エラーコード エラーラベル 詳細
400 Bad Request このエラーは、リクエストが有効なエンドポイントに到達したけれども、必須項目が入力されていない時に表示されます。トランザクションパラメータが不正、または特定されていないことが原因で発生することがあります。
401 Unauthorized このエラーは HMAC、タイムスタンプ、クライアント名、またはその他要素を特定する重要な情報に問題がある時に表示されます。例:401 - Unauthorized. The HMAC provided is not correct.
422 Unprocessable Entity このエラーはトランザクションが保存できない時に表示され、ほとんどの場合トランザクションレコードの認証に失敗していることが原因です。認証の失敗に関するエラーメッセージが届きます。例:422 - Unprocessable Entity. Amount is not a number

HMAC の検証

ユーザーの属性変更を含む Komoju API へのリクエストは、ハッシュベースメッセージ認証符号を使用してデータの整合性を確実に保ちます。

このハッシュは、ホストページの URL へ送信されたパラメータで計算された SHA-256 ハッシュのことです。お使いのアカウントで非公開 API を共有することができますので、メッセージの整合性を計算して検証することができます。ハッシュの計算には、次の制限がかけられます:

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

正常な結果が予想されたにも関わらず、もしも不正な 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(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";

Webhook

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