Komoju는 호스트 페이지를 제공하므로 이 페이지를 이용해 자유로이 어플리케이션에 적용시킬 수 있습니다. 호스트 페이지는 일본 국내에서 대부분의 주요 결제 수단 이용이 가능하며, 결제 방법을 기재한 메일을 일본어 또는 영어로 고객님께 전송합니다. 아래 화면이 Komoju를 이용한 결제 과정을 캡쳐한 페이지입니다.

Checkout 1 Checkout 2

Test 모드

계정 등록 후에 다음 URL에서 Komoju의 Test 모드로 엑세스가 가능합니다:

Test 모드 이용 목적은 Live 모드가 제공하는 기능 전부를 실제로 체험, Komoju 플랫폼으로의 통합을 원활히 진행하기 위해서입니다.

결제(지불) 방법

결제 수단 API 값
은행 입금 bank_transfer
비트 캐쉬 bit_cash
신용카드 credit_card
편의점 konbini
NET CASH net_cash
PayEasy pay_easy
웹머니 web_money

결제 작성

엔드포인트 (Endpoint)

결제 요청은 아래의 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 epoch 타임스템프 요청을 유효화시키기 위해 타임스템프는 서버 타임 5분 이내여야 합니다.
transaction[amount] 과세 이전의 합계 금액. 0 이상이어야 합니다. 소수점에는 ‘.’를 사용하고 천 단위를 표시하는 쉼표는 사용하지 않습니다. 예: 1234.56
transaction[cancel_url] 결제 과정을 취소한 후에 유저에게 회신하는 URL입니다。 http 또는 https를 사용한 유효 URL
transaction[currency] 결제 시 3자리의 ISO 통화 코드 JPY
transaction[return_url] 결제 과정의 정상 완료 시 유저에게 회신하는 URL입니다. http 또는 https를 사용한 유효 URL
transaction[tax] 과세 금액, 또는 현재 일본에서 정해진 소비세를 사용할 때는 ‘auto’를 설정합니다. 소수점에는 ‘.’를 사용하고 천 단위를 표시하는 쉼표는 사용하지 않습니다. 세금이 통화보다 정확한 단위일 경우, 반올림 알고리즘을 사용하여 조정합니다. 예: 1234.56
hmac HMAC 이외의 모든 값을 포함한 쿼리 문자열의 HMAC 인증 HMAC의 검증을 참조

임의 매개변수

매개변수 상세 내용
transaction[metadata][] key/value의 페어 세트. key명을 임의로 설정할 수 있습니다.
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('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

결제 완료 통지를 받기 위해서는 Webhook 설정을 해야 합니다. 고객님의 결제가 완료되면 Komoju에서 설정된 URL로 ’payment.captured’이벤트를 전송합니다. 당신의 어플리케이션은 이 통지를 처리하고 결제 완료를 기록해야 합니다.