MDKチュートリアル(Ruby)

はじめに

VeriTrans4Gは、ECなどオンラインサービスからリアル店舗までマルチチャネルに対応可能な総合決済サービスを提供します。
MDKを利用することで、多彩な決済手段を導入可能となりますが、ここではMDKとサンプルプログラムを利用してクレジットカード決済の簡単な動作確認を行います。
お客様の環境へのMDKインストールにあたってはインストールガイドを参照の上実施してください。

【MDK】Merchant Development Kit

EC店舗サイトと各決済会社間の決済処理を安全に行うためのオンライン決済ソフトウェア

テストアカウントの申請

下記サイトにてMDKのテスト利用申請を行います。
URL: 無料テスト利用プログラムお申し込み

管理サイト(MAP)へのログイン

管理サイトにログインを行いMDKを利用する上で必要となる以下の情報を取得します。

URL: MAP

マーチャントCCID
マーチャント認証鍵
Token Api Key

上記情報は [ 管理サイト -> ダッシュボード -> API設定情報 ] から取得します。

MAP（Merchant Administration Portal）

ご契約情報および各取引を検索いただくための管理サイト

実行環境の確認

MDKの利用には、使用言語ごとに以下の環境をご準備ください

Ruby 2.7.0以上
OpenSSL 1.0.1i以上
log4r 1.1.1.9以上

ご利用上の注意

チュートリアルではUNIXコマンドを用いて説明しますので、環境に合わせて読み替えてください。

MDKダウンロード

テストを実行する言語のMDKを以下のダウンロードページから取得し、展開します。

MDKダウンロード

$ curl -OL https://www.veritrans.co.jp/trial/4g/Mdk4G-ruby-X.X.X.tar.gz
$ tar zxvf Mdk4G-ruby-X.X.X.tar.gz

MDKの確認

展開したMDKには以下のファイルが含まれています。

MdkRuby/
├── README.txt
├── resources
│   └── cert.pem                      CA証明書ストアファイル(MDKの設定ファイルに指定したパスに配置します)
└── tgMdk
    ├── lib                           MDK本体が格納されています
    ├── tg_mdk.ini                    MDK設定ファイル
    ├── tg_mdk_log4r.xml              ログ出力設定ファイル(ご利用のRubyパージョンが2.50以降の場合、こちらをご利用ください)
    ├── tg_mdk_log4r.yaml             ログ出力設定ファイル
    └── tg_mdk_log4r.yaml4log4r119    ログ出力設定ファイル(ご利用のlog4rパージョンが1.1.9以前の場合、こちらをご利用ください)

チュートリアルでは後続の手順でサンプルプログラム内のディレクトリにコピーし実行に必要な項目のみ設定を行います

実環境では tgMdk/ ディレクトリを、店舗様のアプリケーションが参照可能な任意のディレクトリにコピーして下さい。
詳細は[4G MDK インストールガイド(Ruby)] を参照してください

MDKサンプルプログラムダウンロード

テストを実施する言語のMDKサンプルプログラム以下のダウンロードページから取得し展開します。

MDKダウンロード

$ curl -OL https://www.veritrans.co.jp/trial/4g/Mdk4G-Sample-ruby-X.X.X.tar.gz
$ tar zxvf Mdk4G-Sample-ruby-X.X.X.tar.gz

MDKサンプルプログラムの利用準備

サンプルプログラムへのMDKのコピー

ダウンロードしたMDKをサンプルプログラム内にコピーします

$ cp -pr MdkRuby MdkSample-Ruby/command/lib/

MDKの設定

tg_mdk.iniファイルに以下の項目を設定します。

CA_CERT_FILE
MERCHANT_CC_ID
MERCHANT_SECRET_KEY

<MDK Sample 展開ディレクトリ>/MdkSample-Ruby/command/lib/MdkRuby/tgMdk/tg_mdk.ini

18  ; SSL暗号用 CA証明書ファイル名
19  CA_CERT_FILE           = <MDK Sample 展開ディレクトリ>/MdkSample-Ruby/command/lib/MdkRuby/resources/cert.pem #(フルパスで指定してください)
...
35  ; マーチャントCCID。VeriTrans指定のものを設定して下さい。
36  MERCHANT_CC_ID         = <管理サイト(MAP)で確認を行ったマーチャントCCIDを指定します>
37  ; マーチャントパスワード。VeriTrans指定のものを設定して下さい。
38  MERCHANT_SECRET_KEY    = <管理サイト(MAP)で確認を行ったマーチャント認証鍵を指定します>

ログ出力設定ファイル

tg_mdk_log4r.yaml の以下の項目を設定します

filename

任意のファイルを指定可能ですが、フルパスで設定をしてください。

<MDK Sample 展開ディレクトリ>/MdkSample-Ruby/command/lib/MdkRuby/tgMdk/tg_mdk_log4r.yaml

...
39      - name: "F1"
40        type: "FileOutputter"
41        filename: "<MDK Sample 展開ディレクトリ>/MdkSample-Ruby/mdk_ruby.log" #(フルパスで指定します)
...

決済の実行

このチュートリアルでは以下の順序でクレジットカードの決済を行います。

token
authorize
capture
cancel
search

クレジットカード情報をECサイト等に保存しないために、カード情報をトークン化しトークンを利用して Authorize(与信) 処理を実施します。

※ 通常この処理はクライアント側でJavaScript等を利用し実施しますが、チュートリアルではcurlコマンドを利用しトークンの発行を行います。

< Token API Key >には管理サイト(MAP)で確認を行ったToken Api Keyを設定します

$ curl -X POST "https://api.veritrans.co.jp:443/4gtoken" \
-H 'Accept:application/json' \
-H 'Content-Type:application/json' \
-d \
'{
    "card_number":"4111111111111111",
    "card_expire":"01/20",
    "security_code":"123",
    "cardholder_name":"TARO YAMADA",
    "token_api_key":"< Token API Key >",
    "lang":"en"
}'

テストで利用するクレジットカード番号に関して詳細は「導入テストガイド」を参照してください
トークンの発行に関しては詳細は「MDK トークン開発ガイド」を参照してください

トークンサーバーから取得したトークンは一度しかご利用いただけません。(ワンタイムトークン)
取得したトークンには有効期限（15分）があり、有効期限を過ぎるとそのトークンはご利用いただけなくなります。
次の手順（Authorize（与信）の実行）が完了すると、クレジットカード情報は再利用可能な状態で当社に保管されます。

成功した場合以下のような出力が表示されます。

{
"token": "aea5facd-8c53-497a-a0f3-8e1ad3e6a6a5",
"token_expire_date": "20221130145717",
"req_card_number": "411111********11",
"status": "success",
"code": "success",
"message": "Token has been successfully created."
}

レスポンスとして戻った token を利用し与信、決済を実行します。

与信サンプルプログラム「cli_card_authorize.rb」に前項で取得したトークンを設定します。

<MDK Sample 展開ディレクトリ>/MdkSample-Ruby/command/lib/command/card/cli_card_authorize.rb

32 #-------------------------------------------------------
33 # トークン
34 #-------------------------------------------------------
35 @token = "0a812412-682c-4dad-8a5d-720caf23bca0";
36

下記のコマンドを実行し与信を行います。

$ cd <MDK Sample 展開ディレクトリ>/MdkSample-Ruby/command/lib/
$ ruby command/card/cli_card_authorize.rb

[Status]: success

[Result Code]: A001000000000000

[Order ID]: dummy1669954544

[Center Reference Number]:

以下のエラーが表示される場合
/var/lib/gems/3.0.0/gems/log4r-1.1.10/lib/log4r/yamlconfigurator.rb:56:in `actual_load': undefined method `load_documents' for Psych:Module (NoMethodError) Did you mean? load_stream

下記のコマンドで修正を行ってください

$ sudo sed -i s/load_documents/load_stream/g /var/lib/gems/3.0.0/gems/log4r-1.1.10/lib/log4r/yamlconfigurator.rb

売上サンプルプログラム「cli_card_capture.rb」に前項で利用した order_id を設定します

<MDK Sample 展開ディレクトリ>/MdkSample-Ruby/command/lib/command/card/cli_card_capture.rb

12 #-------------------------------------------------------
13 # 取引ID 与信完了取引のIDを指定
14 #-------------------------------------------------------
15 # 対象の取引IDを指定します
16 @order_id = "dummy1669954544"

下記のコマンドを実行し、与信を実施した order_id を指定して売上を実施します

$ ruby  command/card/cli_card_capture.rb

[Status]: success
[Result Code]: A001000000000000
[Order ID]: dummy1669954544
[Card Number]:
[Center Reference Number]:

キャンセルサンプルプログラム「cli_card_cancel.rb」に前項で利用した order_id を設定します

<MDK Sample 展開ディレクトリ>/MdkSample-Ruby/command/lib/command/card/cli_card_cancel.rb

12 #-------------------------------------------------------
13 # 取引ID
14 #-------------------------------------------------------
15 # 対象の取引IDを指定します
16 @order_id = "dummy1669954544"

下記のコマンドを実行し、売上を実施した order_id を指定してキャンセルを実施します

$ ruby command/card/cli_card_cancel.rb
[Status]: success
[Result Code]: A001000000000000
[Order ID]: dummy1669954544
[Card Number]:
[Center Reference Number]:

検索サンプルプログラム「cli_search.rb」に前項で利用した order_id を設定します。

<MDK Sample 展開ディレクトリ>/MdkSample-Ruby/command/lib/command/search/cli_search.rb

...
89 #=================================================
90 # 1. 取引ID
91 #=================================================
92 @order_id = "dummy1669954544"
...

下記のコマンドを実行し、Authorize(与信)、Capture(売上)、Cancel(キャンセル)を実施した
order_id を指定して取引検索を実施します

$ ruby  command/search/cli_search.rb
[Status]: success
[Result Code]: N001000000000000
[Search Count]: 1
----- Search Results -----
*---------**---------*
Index: 0
Service Type: card
Order ID: dummy1669954544
Order Status: end
Card Transaction ID: 81317135
Currency:
---
Transaction ID: 81317135
Executed Command: Authorize
Transaction Status: success
Transaction Result Code: A001000000000000
Execute Time: 2022-12-02 13:15:44.232
Settlement Amount: 5
Card Transaction Type: a
Gateway Request Date: 20221202131544
Gateway Response Date: 20221202131544
Center Request Date: 20221202131544
Center Response Date: 20221202131544
Center Request Number:
Center Reference Number:
Request Auth Code:
---
Transaction ID: 81317181
Executed Command: Capture
Transaction Status: success
Transaction Result Code: A001000000000000
Execute Time: 2022-12-02 13:20:07.749
Settlement Amount: 5
Card Transaction Type: pa
Gateway Request Date: 20221202132007
Gateway Response Date: 20221202132007
Center Request Date:
Center Response Date:
Center Request Number:
Center Reference Number:
Request Auth Code:
---
Transaction ID: 81317229
Executed Command: Cancel
Transaction Status: success
Transaction Result Code: A001000000000000
Execute Time: 2022-12-02 13:24:22.53
Settlement Amount: 5
Card Transaction Type: vpa
Gateway Request Date: 20221202132420
Gateway Response Date: 20221202132422
Center Request Date: 20221202132420
Center Response Date: 20221202132420
Center Request Number:
Center Reference Number:
Request Auth Code:

このチュートリアルで実行したAuthorize(与信)、Capture(売上)、Cancel(キャンセル)の結果が表示されていることを確認してください。