本ガイドの内容

本ガイドは、株式会社DGフィナンシャルテクノロジーが提供するVeriTrans4Gを利用するための専用ソフトウェアMDK（Merchant Development Kit）をインターネット店舗などに導入する開発者向けのガイドです。
MDKファイル構成や設定方法、サンプルプログラム等について記載しています。

基本導入手順

VeriTrans4G MDK（Ruby）の導入にあたり、以下の作業が必要となります。

1. 実行環境の確認
2. Ruby用サポート・ライブラリの組込（有効化）
3. MDKモジュールの組込
4. MDK設定

実行環境の確認と準備

こちらからダウンロードしてください。

MDKのご利用には、以下の環境（TLS1.2以上で通信可能な環境）が必要です。

導入されているRuby環境環境のバージョン及びパッケージサポート状態を、ruby -v コマンドの出力結果から該当の箇所を確認して下さい。
サポートパッケージが未導入の場合は事前に導入して下さい。

*1 TLS1.2以上の通信をサポートするOpenSSLのバージョンは1.0.1以降となりますが、OpenSSLはいくつかの重大な脆弱性が発表されておりますので、本書ではバージョン1.0.1i以上のご利用を推奨しております。ただし、OpenSSLの脆弱性は、1.0.1i以上のバージョンでも報告されていますので、システムをアップグレードする際には、できるだけ最新バージョンをお使い頂きますようお願い申し上げます。

Ruby用サポート・ライブラリの組込（有効化）

Ruby実行環境として、下表に示すサポート要件を満たす必要があります。
各サポートの有効化方法については、環境によって異なりますので、店舗様にてご確認頂きますようお願いします。

MDKの確認

ダウンロードしたMdk4G-ruby-.tar.gzを解凍します。

アプリケーションへのMDKの組み込み

tgMdk/ディレクトリを、店舗様のアプリケーションが参照可能な任意のディレクトリにコピーして下さい。
ファイルの実行権限については、アプリケーションに合わせて下さい。
以下に、設定ファイルの設定方法をご説明します。

MDKの設定

【基本設定ファイル】

4G MDK設定ファイルは、tg_mdk.iniです。設定ファイルには重要な情報が記載されておりますので、第三者に見えないようにしてください。

（１）サービスに関連する設定

• （Ａ）ダミーモード
  テスト用にダミー決済を発生させる場合に指定します。

  DUMMY_REQUEST = x
  「0」：ダミーモードOFF
  
  「1」：ダミーモードON

• （Ｂ）MDK固有エラーモード
  決済サーバーに無関係な、MDK固有のエラーテスト用に指定します。

  MDK_ERROR_MODE = x
  「0」：MDKエラーモードOFF
  
  「1」：MDKエラーモードON

  ※エラーモードONの場合にはvResultCodeに "MA99" が返戻されます。

（２）接続に関連する設定

• （Ａ）接続先ホスト 接続先サーバ（決済サーバー）のURLを設定します。 ※デフォルトでの設定のままご利用下さい。

  HOST_URL = https://xxx.xxx.xxx.xxx:xxx

• （Ｂ）接続タイムアウト値(秒) 決済サーバーへの接続が確立できない場合に、接続試行を中断するまでの接続試行開始からの秒数を指定します。

  CONNECTION_TIMEOUT = XXX

• （Ｃ）読み取りタイムアウト値(秒) 決済サーバーからのレスポンスがない場合に、接続を切断するまでのリクエスト開始からの秒数を指定します。

  READ_TIMEOUT = XXX

  ※READ_TIMEOUTが未設定の場合は、読み取りタイムアウト値(秒)に接続タイムアウト値(秒)が適用されます。

• （Ｄ）SSL暗号用 CA（Certificate Authority）証明書ファイル名 同梱のCA証明書ファイル(PEM形式)を配置する絶対パスを指定します。

  CA_CERT_FILE = xxxxxxxxxxxxxx

• （Ｅ）SSLプロトコルの設定 ベリトランスとSSL暗号通信を行う際のSSLプロトコルを指定します。 ※デフォルトでの設定のままご利用下さい。

  SSL_PROTOCOL =　xxxxxxx

（３）プロキシサーバの設定

• （Ａ）プロキシサーバURL プロキシサーバをご利用の場合、この項目にサーバホスト名／IPアドレス、ポート番号を設定下さい。

  PROXY_SERVER_URL = http://xxxx.xxx.xxx.xxx:xxxx

• （Ｂ）プロキシサーバ接続認証用ユーザID プロキシサーバをご利用で且つ接続に認証が必要な場合、プロキシサーバ接続用ユーザ名を設定下さい。

  PROXY_USERNAME = xxxxxxx

• （Ｃ）プロキシサーバ接続認証用パスワード プロキシサーバをご利用で且つ接続に認証が必要な場合、プロキシサーバ接続用パスワードを設定下さい。

  PROXY_PASSWORD = xxxxxxx

（４）マーチャント認証用の設定

• （Ａ）マーチャントCCIDの設定 ベリトランスより通知の店舗サイト用CCID文字列を指定します。

  MERCHANT_CC_ID = xxxxxxxxxxxxx

• （Ｂ）マーチャント認証鍵の設定 ベリトランスより通知の、店舗サイト用認証鍵文字列を指定します。

  MERCHANT_SECRET_KEY = xxxxxxxxxxxxxxxx

（５）環境に関連する設定

• （Ａ）文字列のエンコードに関連する設定 要求電文に用いている文字列のエンコードを指定します。

  DTO_ENCODE = xxxxxxxxxxxxxxxx

リクエストDTOにセットする全角文字列パラメータは、必ずUTF-8である必要がありますが、DTO_ENCODEを指定すると、指定したUTF-8以外のエンコーディングからUTF-8への変換をMDK内部で自動的に行います。

注１） 本項目を指定しない場合はマーチャントプログラム内で明示的にUTF-8に変換する必要があります。
注２） 本項目を指定した場合はマーチャントプログラム内でエンコーディング処理を行わないでください。

ここで指定できる日本語エンコーディング名は以下の通りです。

• UTF-8（UTF-8を指定した場合は変換無し）
• Shift_JIS（Windows系）、SJIS（UNIX系）
• EUC-JP

【ログ設定ファイル】

ログ設定ファイルはtg_mdk_log4r.yaml、もしくはtg_mdk_log4r.xmlです。
両方の設定ファイルが存在する場合はYAML形式のログ設定ファイルが優先して参照されます。
Ruby2.5.0以上をご利用の場合については、log4rにてYAML形式のファイルを扱うことができないため、XML形式のログ設定ファイル（tg_mdk_log4r.xml）をご利用ください。

※tg_mdk_log4r.yamlを削除することでtg_mdk_log4r.xmlが参照されるようにしてください。
（以降の記述についても、xmlをご利用の場合は適宜読み替えて下さい。）

以下にyaml形式を例に、設定方法を記載します。

1. ログ出力レベルの指定
   MDKのログ出力レベルを指定します。
   指定可能値：「OFF／FATAL／ERROR／WARN／INFO／DEBUG（※）」

   ※より多くの情報を出力したい場合は、DEBUGを設定して下さい。

   loggers:
   ～ 省略 ～
       - name: "Veritrans"
         type: "Log4r::Logger"
         level: "DEBUG"
         trace: "true"
         outputters:
           - "E1"
           - "F1"

2. ログ出力ファイルの指定
   ログ出力ファイルのパスを指定します。

   outputters:
   ～ 省略 ～
       - name: "F1"
         type: "Log4r::FileOutputter"
         filename: "/logfile_dir_change_here/mdk_ruby.log"
         trunc: "false"
         formatter:
           name: "P2"
           type: "Log4r::PatternFormatter"
           pattern: "%d [%l] %C(%c) - %M"
           pattern2: "%d [%l] %C(%t) - %M"
           date_pattern: "%Y/%m/%d %H:%M:%S"

サンプルプログラム（コマンドラインプログラム）設定・動作確認

（１）Mdk4G-Sample-ruby-.tar.gzを解凍

ダウンロードしたMdk4G-Sample-ruby-.tar.gzを解凍します。
コマンドラインから動作確認が可能なサンプルプログラムはMdkSample-Ruby/commandディレクトリにあります。

（２）4G MDK本体のファイル群の配置

MdkSample-Ruby/command/lib ディレクトリ直下に、MDKのMdkRubyディレクトリを配置します。

（３）MDKの設定

「3.3 MDKの設定」 に従い、MDKの設定をします。

（４）動作確認

MdkSample-Ruby/command/lib/command/[サービス名]/ 直下にあるサンプルプログラムを実行します。
以下の例では、クレジットカード決済（与信）のサンプルプログラムを実行しています。

$ cd MdkSample-Ruby/command/lib/
$ ruby command/card/cli_card_authorize.rb
...Transaction Successfully Complete
[Status]: successfailure
[Result Code]: A001OC09H001000000000000
[Order ID]: dummy1444983947
$

• サンプルプログラムでは、無効なtokenの値を送信しているため、OC09のエラーが発生しますが、これは想定通りの挙動です。その他のエラーが発生する場合は、MDKが適切なディレクトリにコピーされていること、また、tg_mdk.iniとtg_mdk_log4r.yamlの設定内容が適切であることをご確認下さい。
• 実行時のコンソールには、決済サーバーからのレスポンス値が出力されます。通信内容の詳細については、tg_mdk_log4r.yamlに指定したログファイルをご確認ください。

例：
＜デフォルト設定＞
# プッシュデータ保存ディレクトリ
def initialize
  @save_path = "#{rails_root}/tmp/push/"
end

＜店舗様の環境に合わせて変更＞
# プッシュデータ保存ディレクトリ
def initialize
  @save_path = "/home/my_push/"
end

MDKメソッドリスト

MDKのクラス、メソッドの一覧をRDoc形式で出力し、ダウンロードサイトに公開しています。
こちらからダウンロードしてください。

MDKで複数のマーチャントIDを使い分ける方法

（１）決済要求毎にマーチャントIDを切り替える

MDKは通常、設定ファイル（tg_mdk.ini）に記述されたマーチャントCCIDとSECRET_KEY（以下、認証情報）を利用して署名を算出し、決済要求時に付与して送信します。署名の算出は、処理要求単位（トランザクション単位）で行います。

マーチャントIDの切り替えを行うためには、決済要求の実行前に、MDKが保持しているメモリ上の認証情報を上書きする必要があります。

※MDKは、初回の呼び出し時に設定ファイルから読み込んだ認証情報を、スタティックな情報として保持しています。そのため、設定ファイル内の認証情報を書き換えても、アプリケーションの再起動を行うまで認証情報は反映されません。

認証情報を上書き設定する手順を以下に示します。

1. 利用する認証情報を取得する
2. メモリ上の認証情報を、取得した情報で上書き設定する(*1)
3. トランザクションオブジェクトを生成する
4. トランザクションを実行する

以下の点に注意して実装してください。

• MDKの仕様上、設定ファイル（tg_mdk.ini）内のマーチャントCCIDとSECRET_KEYには、適当な値(半角英数字)を設定してください。未設定の場合、MDKの初期化時にエラーとなります。
• 認証情報の上書き設定は、必ずトランザクションオブジェクトを生成する「前に」行ってください。
• MDKの設定はメモリ上に保持されますので、毎回認証情報を設定してください。スレッドが再利用されるケースでは、前回上書きした値が保持されますので、意図しないマーチャントIDで決済が行われる可能性があります。
• 本機能をご利用の際は、マーチャントIDが正しく切り替わっているかどうか、十分にテストを実施してください。

(*1)基本的に、スレッドスタティックな形で保持している情報が上書きされますが、切り換える場合は毎回、使用する情報を設定する形で実装する必要があります。※設定ファイルには認証情報Aが記述されているので、認証情報Bを使いたいときだけ上書きを行うということではありません。

【サンプルコード】

@request_data = Veritrans::Tercerog::Mdk::CardAuthorizeRequestDto.new
・・・

#==========================================================================
#  4G認証情報を設定
#==========================================================================
tmp_config = MdkConfig.instance
tmp_config.overwrite("MERCHANT_CC_ID", "A100000000000000000001CC")
tmp_config.overwrite("MERCHANT_SECRET_KEY", "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

#==========================================================================
#  実施
#==========================================================================
tran = Veritrans::Tercerog::Mdk::MdkTransaction.new
@response_data = tran.execute(@request_data)

（２） 結果通知における content-hmac の検証

VeriTrans4Gより通知される結果通知のPOSTリクエストには、content-hmac というヘッダが設定されています。この値はリクエストボディから算出されます。
この content-hmac のチェックを行うことで、リクエストが改竄されていないかどうかをチェックすることが可能ですが、算出に SECRET_KEY の値を利用するため、content-hmac のチェック時には注意が必要となります。

content-hmacのチェックには、MdkMerchantUtilityクラスのcheck_message_by_secret_key?メソッドを利用します。デフォルトのサンプルでは、content-hmac（検証用に利用する署名）のチェックにMdkMerchantUtilityクラスのcheck_message?メソッドで実装していますが、複数のマーチャントIDを使い分ける場合には、MdkMerchantUtilityクラスのcheck_message_by_secret_key?メソッドをご利用ください。

# 第１引数：マーチャント認証鍵（マーチャントパスワード）
# 第２引数：電文の本文
# 第３引数：content-hmac
# 戻り値：true＝改ざんされていない、 false：改ざんされている
Veritrans::Tercerog::Mdk::MdkMerchantUtility::check_message_by_secret_key?(merchant_secret_key, request.body.read, @content_hmac)