DGFT Veritrans4G開発ガイド

お問い合わせ
  • TOP
  • MDK(SDK)導入ガイド
  • 開発環境へのMDK(SDK)導入
  • PHP8

MDKインストールガイド(PHP8)

導入の前に

本ガイドの内容

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

導入準備

基本導入手順

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

  1. 実行環境の確認と準備
  2. PHP用サポート・ライブラリの組込（有効化）
  3. MDK設定
  4. MDKパッケージの組込

実行環境の確認と準備

MDKのご利用には、以下の環境が必要です。

表 1 PHP実行環境要件
パッケージ バージョン要件 説明
PHP 7.4以上または8.0、8.1以上 PHP実行環境
Composer 2.2.7以上 依存関係管理ツール

※本サンプルのWebアプリケーションを実行するためにはPHP 8.0.2以上が必要です。

有効になっている必要のある拡張モジュールは以下の通りです。

表 2 PHP拡張モジュール要件
拡張モジュール 説明
マルチバイト文字列 (mbstring) マルチバイト対応の文字列関数を提供するモジュール
JSON JSONデコード、エンコード関数を提供するモジュール
OpenSSL ソケットについての暗号化を有効にするためのモジュール

導入されている環境のバージョンおよび有効となっている拡張モジュールを php -i コマンドの出力結果、あるいは phpinfo() 関数から該当の箇所を確認してください。
拡張モジュールが未導入の場合は事前に導入してください。

また、本MDKは default_charset および internal_encoding が UTF-8 となっている環境を前提としています。
PHP 5.6以降ではdefault_charsetには既定値としてUTF-8が設定され、internal_encodingもdefault_charsetの設定を利用するようになっていますので、変更せずそのままご利用ください。

注意事項

(1)MDKが依存するライブラリだけではなく、ファイルやディレクトリに設定された権限、ネットワークトラブル等によって、MDKが正しく動作しない可能性もあります。弊社より提供しているサンプルプログラムでは、MDK呼び出し部のエラーハンドリングを省略していますが、MDK組込みの際には、MDKが実行時エラー(Exception)を返すことも想定して下さい。また、MDK呼び出し部に関しても十分なテストを実施してください。

(2)本バージョンのMDKはロギングライブラリを同梱していないため、PSR-3 LoggerInterfaceを実装したLoggerインスタンスを呼び出し元からTGMDK_Loggerクラスにセットする必要があります。MDKのログは何かしらの問題が発生した際、調査のために必要なログとなりますので、サンプルコード等を参考に、正しくログが保存されるよう呼び出し元プログラムの実装を行ってください。

注意：
ログ出力の設定については、ログファイルの書込み権限、ログ出力先ディレクトリパスの実行権限、ディレクトリへの書込み権限等、ファイルの権限に関する設定に誤りがないようご注意下さい。
ログファイルが出力されている場合でも、権限不足によりログローテーションに失敗する場合があります。
ログファイルのローテーションに関する設定についてもご確認下さい。

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

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

【例】
・ソース・コンパイルの場合 r>./ configure （中略） --with-openssl --enable-sockets --enable-hash --enable-mbstring

表3 PHPサポート要件
設定事項 設定(PHP configure) オプション
OpenSSL サポートの有効化 --with-openssl
Socket サポートの有効化 --enable-sockets
hash サポートの有効化 --enable-hash
mbstring サポートの有効化 --enable-mbstring

有効化作業後、php -i コマンドラインインタフェースでの出力結果、またはphpinfo()関数の出力結果にてサポートが有効(enabled)となっているか確認して下さい。

設定方法

MDKの確認

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

表 2 PHP版4G MDKファイル一覧
ディレクトリ／ファイル名 説明
veritrans-tgmdk README.txt MDKの導入前にお読みください。
composer.json プロジェクトの依存情報が記述されています。
composer.lock 依存パッケージのバージョンリストが記述されています。
src/ tgMdk/ MDK本体が格納されています。
dto 各APIの要求、応答データクラスが格納されています。
3GPSMDK.properties MDK設定ファイル
resources/ cert.pem CA証明書ストアファイル
※MDKの設定ファイルに設定したパスに配置します。

MDKの設定

【基本設定ファイル】

4G MDK設定ファイルは、3GPSMDK.propertiesです。設定ファイルには重要な情報が記載されているため、第三者に見えないようにして下さい。

（１）サービスに関連する設定
  • ダミーモードの指定
    テスト用にダミー決済を発生させる場合に指定します。 
    DUMMY_REQUEST = x
「0」：ダミーモードOFF
「1」：ダミーモードON
  • MDK固有エラーモード
    決済サーバーに無関係な、MDK固有のエラーテスト用に指定します。 
    MDK_ERROR_MODE = x
「0」：MDKエラーモードOFF
「1」：MDKエラーモードON

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

（２）接続に関連する設定
  • 接続先URLの設定
    接続先サーバ（決済サーバー）のURLを設定します。

    ※デフォルトでの設定のままご利用下さい。

    HOST_URL = https://xxx.xxx.xxx.xxx:xxx
  • 接続タイムアウト値(秒)の設定
    決済サーバーへの接続が確立できない場合に、接続試行を中断するまでの接続試行開始からの秒数を指定します。 
    CONNECTION_TIMEOUT = XXX
  • 読み取りタイムアウト値(秒)の設定
    決済サーバーからのレスポンスがない場合に、接続を切断するまでのリクエスト開始からの秒数を指定します。 
    READ_TIMEOUT = XXX

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

  • SSL暗号用 CA（Certificate Authority）証明書ファイル名の設定
    同梱のCA証明書ファイル(PEM形式)を配置するパスを指定します。 MDKバージョン1.1.8以降では既定値でtgMdkディレクトリからの相対パスが設定されていますが、他の絶対パスを指定、またはパスを未指定にすることも可能です。

    ※未指定の場合は、MDK内部の処理で、SSLコンテキストオプションのcafileを上書きしなくなります。

    CA_CERT_FILE = "../../resources/cert.pem"
  • プロキシサーバURLの設定
    プロキシサーバを利用する場合、サーバホスト名／IPアドレス、ポート番号を設定して下さい。 
    PROXY_SERVER_URL = http://xxxx.xxx.xxx.xxx:xxxx
  • プロキシサーバ接続認証用ユーザID
    プロキシサーバを利用し、かつ接続に認証が必要な場合、プロキシサーバ接続用ユーザ名を設定下さい。 
    PROXY_USERNAME = xxxxxxx
  • プロキシサーバ接続認証用パスワード
    プロキシサーバを利用し、かつ接続に認証が必要な場合、プロキシサーバ接続用パスワードを設定下さい。 
    PROXY_PASSWORD = xxxxxxx
  • マーチャントCCIDの設定
    店舗サイト用CCID文字列を指定します。 
    MERCHANT_CC_ID = xxxxxxxxxxxxx
  • マーチャント認証鍵の設定
    店舗サイト用認証鍵文字列を指定します。

    マーチャントCCIDおよびマーチャント認証鍵についてはMAP（マーチャント管理ポータル）の「API設定情報」より確認が可能です。

    MERCHANT_SECRET_KEY = xxxxxxxxxxxxxxxx

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

本MDKはComposerパッケージとなっています。

呼び出し元アプリケーションのcomposer.jsonに以下のように依存関係を設定してください。
"repositories": [
    {
        "type": "path",
        "url": "../local_packages/veritrans-tgmdk",
        "options": {
            "symlink": false
        }
    }
],

この例では、呼び出し元アプリケーションの配置パスと同階層(composer.jsonの1つ上の階層)にlocal_packagesというディレクトリを作成し、その中にveritrans-tgmdkを配置した状態を想定しています。

サンプルプログラムの利用

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

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

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

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

veritrans-mdk-sample/local_packagesディレクトリ直下にMDKのveritrans-tgmdkディレクトリを配置します。

（３）MDKの設定

「3.2 MDKの設定」に従い、配置したveritrans-tgmdkディレクトリ内のsrc/tgMdk/3GPSMDK.propertiesをエディタで開き、必要な項目の設定をします。

（４）MDKの組み込み

commandディレクトリに移動し、composerコマンドで依存関係をインストールしてください。

composer install

（５）動作確認

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

$ cd app/command/card/
$ php -f CLI_CardAuthorize.php
success
Transaction Successfully Complete
[Result Code]: A001H00100000000
[Order ID]: dummy1444907080
$
  • エラーが発生する場合は、MDKが適切なディレクトリにコピーされていること、また、3GPSMDK.propertiesの設定内容が適切であることをご確認下さい。
    実行時のコンソールには、決済サーバーからのレスポンス値が出力されます。通信内容の詳細についてはログファイルをご確認ください。ログファイルはapp/LoggerDefine.phpにて、app/logsディレクトリに出力するよう設定されています。

サンプルプログラム（Webアプリケーション）設定・動作確認

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

ダウンロードしたMdk4G-Sample-php8-.tar.gzを解凍します。
WEBアプリケーションとして実装されているサンプルプログラムはlaravel_sampleディレクトリにあります。

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

veritrans-mdk-sample/local_packagesディレクトリ直下にMDKのveritrans-tgmdkディレクトリを配置します。

（３）MDKの設定

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

（４）「sample_setting.php」ファイルの設定

laravel_sample/configディレクトリの中にあるsample_setting.phpファイルを、環境に合わせて編集します。

「MPIホスティング」を利用する場合

「MPIホスティング」のサービス用サンプルを利用する場合は、以下を設定して下さい。

  • redirect_url ： 決済サーバーから消費者ブラウザ経由で店舗へリダイレクトする際のURLを設定 
    'mpi' => [
    'redirect_url' => 'http://localhost:8000/mpi/result
],

「MDKトークン」を利用する場合

クレジットカードを利用した決済のサービス用サンプルを利用する場合は、以下を設定して下さい。

  • token_api_key ：店舗サイト毎に発行されたトークン取得用のキーを設定 
    'token' => [
    'token_api_key' => 'aaaaaaaa-0000-1111-bbbb-abcdef012345'
]

（５）動作確認

laravel_sampleディレクトリに移動し、composerで必要となるパッケージをインストールします。

composer install

その後、Laravel artisanコマンドでアプリケーションを起動します。

php artisan serve

上記のコマンド例では、ポート8000へのhttp要求を待ち受ける状態になりますので、ブラウザでhttp://localhost:8000/menuを開いてください。

付録

MDKメソッドリスト

MDKのクラス、メソッドの一覧をphpdoc形式で出力して公開しています。
ダウンロードサイトより「MDK_MethodList_PHP」を入手し、「index.html」よりご参照ください。

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

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

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

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

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

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

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

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

  • MDKの仕様上、設定ファイル（3GPSMDK.properties）内のマーチャントCCIDとSECRET_KEYには、適当な値(半角英数字)を設定してください。未設定の場合、MDKの初期化時にエラーとなります。
  • 認証情報の上書き設定は、必ずトランザクションオブジェクトを生成する「前に」行ってください。
  • 前回利用したマーチャント情報の設定が変数に残っている等で、意図しないマーチャントIDで決済が行われてしまうような事故を防止するため、トランザクションを実行する都度、毎回必ず認証情報の設定を行ってください。
  • 本機能をご利用の際は、マーチャントIDが正しく切り替わっているかどうか、十分にテストを実施してください。

(*1)
決済要求の都度、使用する情報を設定する形で実装してください。例えば、設定ファイルには認証情報Aが記述されているので、認証情報Bを使いたいときだけ上書きを行う、という実装では正しく切替ができない可能性があります。

【サンプルコード】

ここでは、認証情報がプロパティファイル（merchant_info.ini）に保存されているものとします。

merchant_info.ini

MERCHANT_CC_ID_1                 = A100000000000000000001CC
MERCHANT_SECRET_KEY_1            = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

MERCHANT_CC_ID_2                 = A100000000000000000002CC
MERCHANT_SECRET_KEY_2            = YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

MERCHANT_CC_ID_3                 = A100000000000000000003CC
MERCHANT_SECRET_KEY_3            = ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ

認証情報の上書き処理の実装例を以下に示します。

// ファイルへのパスは適宜調整してください
$merchant_infos = parse_ini_file("merchant_info.ini", false);

// サンプルとして、ユニーク値を1としています。
$merchantUniqueValue = "1";
$props["merchant_ccid"] = $merchant_infos["MERCHANT_CC_ID_".$merchantUniqueValue];
$props["merchant_secret_key"] = $merchant_infos["MERCHANT_SECRET_KEY_".$merchantUniqueValue];

$transaction = new TGMDK_Transaction();
// TGMDK_Transactionクラスの execute の第2引数に連想配列を渡す
$response_data = $transaction->execute($request_data, $props);

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

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

content-hmac のチェックには、 TGMDK_MerchantUtility クラスのcheckMessage関数を利用します。

TGMDK_MerchantUtility::checkMessageBySecretKey($secretKey, $msgBody, $sContentHmac)
$secretKey	：マーチャント認証鍵（SECRET_KEY）を指定します。
$msgBody	：リクエストボディを指定します。
$sContentHmac	：content-hmacヘッダの値を指定します。

※マーチャントIDの切替が不要な場合は、引数が２つの関数checkMessage($body, $hmac) を利用します。