DGFT Veritrans4G開発ガイド

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

MDKインストールガイド(.NET)

導入の前に

本ガイドの内容

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

.NET Framework 3.5および4.5向けの旧バージョンMDKからの差し替えをされる場合は、まず 5. 旧バージョンMDKからの変更点 をご確認ください。

導入準備

基本導入手順

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

  1. 実行環境の確認
  2. MDKモジュールの組込
  3. MDK設定

実行環境の確認と準備

VeriTrans4G MDK（.NET）の最新版およびサンプルプログラムを、こちらからダウンロードしてください。

VeriTrans4G MDK（.NET）は以下の環境が必要となります。

表 1 コンポーネント(パッケージ)要件
パッケージ・コンポーネント バージョン要件
.NET and .NET Core 2.1 以上
.NET Framework 4.6.2 以上

また、サンプルプログラムの実行には以下の環境が必要となります。

表 2 コンポーネント(パッケージ)要件
パッケージ・コンポーネント バージョン要件
.NET 6 以降 6.0以上

.NET SDKがインストールされていない場合は、以下のURLよりダウンロードしてインストールしてください。
https://dotnet.microsoft.com/download

MDKインストール

Mdk4G-net8-.zipを展開し、後述のNuGetパッケージをご利用の社内プライベート パッケージ レジストリや、ローカル フィード等に配置の上、アプリケーションプロジェクトからNuGetパッケージとして参照するよう設定してください。

アプリケーションプロジェクトにMDKへの参照を追加するためには、一般的には、Visual Studio等でNuGetパッケージマネージャーを開いて操作するか、以下のようなコマンドをプロジェクトファイルのあるパスで実行します。

dotnet add package cg-mdk
dotnet add package cg-mdk-dto

プライベートな環境にNuGetフィードをホスティングする方法については、以下のページを参照ください。

https://docs.microsoft.com/ja-jp/nuget/hosting-packages/overview

設定方法

MDKの確認

表3のファイルが揃っていることを確認します。

表3 .NET版 4G MDK ファイル一覧
ディレクトリ／ファイル名 説明
MdkNET tgMdk 3GPSMDK.ini MDK用設定ファイル
cg-mdk..nupkg MDK本体NuGetパッケージ
cg-mdk-dto..nupkg MDK用DTO NuGetパッケージ
README.txt README.txt

MDKの設定

【基本設定ファイル】

4G MDK設定ファイルは、3GPSMDK.iniです。設定ファイルには重要な情報が記載されているため、第三者に見えないようにしてください。また、バージョン1.1.0より基本設定をMDKの呼び出し元プログラムから引数で指定できるようになっているため、設定ファイルを使わない実装も可能です。

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

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

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

    HOST_URL = https://xxx.xxx.xxx.xxx:xxx
  • 特殊設定

    ※通常は指定する必要はありません。

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

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

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

  • ダミーモードの指定
    テスト用にダミー決済を発生させる場合に指定します。 
    DUMMY_REQUEST = x
「0」：ダミーモードOFF
「1」：ダミーモードON

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

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

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

（３）プロキシサーバに関連する設定

  • プロキシサーバURLの設定
    プロキシサーバを利用する場合、サーバホスト名／IPアドレス、ポート番号を設定して下さい。 

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

  • プロキシサーバ接続認証用ユーザIDの設定
    プロキシサーバを利用し、かつ接続に認証が必要な場合、プロキシサーバ接続用ユーザ名を設定して下さい。 

    PROXY_USERNAME = xxxxxxx

  • プロキシサーバ接続認証用パスワードの設定
    プロキシサーバを利用し、かつ接続に認証が必要な場合、プロキシサーバ接続用パスワードを設定して下さい。 

    PROXY_PASSWORD = xxxxxxx

（４）マーチャントCCID、認証鍵の設定

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

    MERCHANT_CC_ID = xxxxxxxxxxxxx

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

    MERCHANT_SECRET_KEY = xxxxxxxxxxxxxxxx

【ログについて】

バージョン1.1.0よりlog4netを廃止し、Microsoft.Extensions.Logging名前空間のILoggerインターフェイスでロガーを受け付けるよう変更されました。MDKログは何かしら問題が発生した際のトラブルシューティングに必要となるため、必ずファイルシステムやログ収集システム等に保存するようにしてください。
サンプルプログラムでは、コンソールアプリケーションではNLogを、ASP.NET CoreアプリケーションではSerilogを利用した最低限のログ出力を実装していますが、ご利用のシステムに適したログの記録方法を入念に検討の上、実装してください。
.NETでのログプロバイダーについては、Microsoftの技術情報も合わせてご確認ください。
https://docs.microsoft.com/ja-jp/dotnet/core/extensions/logging-providers

【HttpClientを利用した場合の通信設定について】

バージョン1.1.3より、呼び出し元アプリケーションで管理されたHttpClientクラスのインスタンスを渡すことが可能な決済要求実行処理メソッドが追加されました。

本メソッドを利用する場合、接続に関する一部の設定はHttpClient側で行う必要があるため、接続タイムアウト、読み取りタイムアウト、プロキシサーバに関する設定は、引数や設定ファイルで指定された値が利用されません。

また、HttpClientの作成後、User-AgentリクエストヘッダーにMDKを識別するための文字列を設定するよう実装してください。User-Agent文字列はMerchantConfigクラスのGetUserAgentメソッドで取得することが可能です。

HttpClientを利用した実装を行う場合は、Microsoftの技術情報も合わせてご確認ください。

https://docs.microsoft.com/ja-jp/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests

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

Visual Studio 2022以降、JetBrains Rider、Visual Studio Code等をご利用下さい。

サンプルプログラムの構成

サンプルプログラムは主に以下のようなファイル構成になっています。(一部のみ抜粋しています)

表4 .NET版 4G MDK サンプルプログラム構成
ディレクトリ／ファイル名 説明
ConsoleApplication ConsoleApplication ConsoleApplication.csproj コンソールアプリケーション版サンプルのプロジェクトファイルです。VS Codeを利用する場合は本ファイルのあるディレクトリを開いてください
vscode VS Code用のタスクおよびデバッグ実行構成ファイルが置かれたディレクトリです。
ConsoleApplication.sln VS ConsoleApplication.csprojにリンクしたソリューションファイルです。Visual StudioやRiderで開いてください。
CoreMvcApplication CoreMvcApplication CoreMvcApplication.csproj ASP.NET Core版サンプルのプロジェクトファイルです。VS Codeを利用する場合は本ファイルのあるディレクトリを開いてください
vscode VS Code用のタスクおよびデバッグ実行構成ファイルが置かれたディレクトリです。
appsettings.json サンプルアプリケーションやMDK設定情報などが定義された設定ファイルです。
nuget.config 必要に応じてプライベートNuGetレジストリの設定等を追記してください。
CoreMvcApplication.sln CoreMvcApplication.csprojにリンクしたソリューションファイルです。
README.txt バージョンや更新履歴等が記載されています。

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

（１）Mdk4G-Sample-net-.zipを展開

ダウンロードしたMdk4G-Sample-net-.zipを展開します。
コマンドラインから動作確認が可能なサンプルプログラムはMdkSample-NET/ConsoleApplicationディレクトリにありますので、Visual Studio、Rider、Visual Studio Code等でプロジェクトを開いてください。

（２）サンプルソースの修正およびMDKの設定

ソースコード Program.cs を開き、MerchantConfigクラスのインスタンス生成時の引数を設定してください。従来の3GPSMDK.iniを示すFileInfoクラスを指定する方法に加え、3GPSMDK.iniの本文自体を指定する方法、マーチャントCCIDと認証鍵などを直接指定する方法があります。

（３）ビルドと実行

Visual StudioやRider、VS Codeなどでデバッグ実行してください。
コマンドラインから実行する場合、PowerShell等でConsoleApplication.csprojのあるディレクトリに移動し、以下のようにdotnet restore コマンドで依存関係を復元、dotnet run コマンドでサンプルプログラムを実行します。

dotnet restore ./ConsoleApplication.csproj
dotnet run --project ./ConsoleApplication.csproj card-authorize

※依存関係を復元する前に、NuGet.ConfigにMDKのNuGetパッケージを配置したパッケージソースが追記されているかご確認ください。

一般的に、Windows環境の場合は以下のパスにNuGet構成ファイルが保存されています。

%AppData%\NuGet\NuGet.config

上記パスが存在しない場合、以下のdotnet nugetコマンドを実行することでディレクトリおよびファイルが作成されます。

dotnet nuget locals all -l

クレジットカード決済（与信）の動作を確認する場合は、実行時引数に、"card-authorize" を指定します。
その他の決済サービスを確認する場合は、Program.csに記載のキーワードを実行時引数に指定して下さい。

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

（１）Mdk4G-Sample-net-.zipを展開

ダウンロードしたMdk4G-Sample-net-.zipを展開します。
ブラウザから動作確認が可能なサンプルプログラムはMdkSample-NET/CoreMvcApplicationディレクトリにありますので、Visual Studio、Rider、Visual Studio Code等でプロジェクトを開いてください。

（２）appsettings.jsonの修正

appsettings.json を開き、Token Api Keyの値、マーチャントCCID、認証鍵、ダミーモード、必要に応じてPush通知受信サンプルのログ出力先パス等を設定してください。TokenApiKeyの値は、設定したマーチャント用のToken Api Keyを設定してください。

※MdkIniPathに3GPSMDK.ini のパスを指定した場合はそちらの設定が優先されます。

{
...
    "SampleSettings": {
...
    "Push": {
        "OutputDirectory": "C:\\temp"
    },
...
    "Token": {
        "TokenApiKey": "",
...
    "Mdk": {
...
        "MerchantCcId": "",
        "MerchantSecret": "",
        "Dummy": true,
        "MdkIniPath": "",
...
}

（３）ビルドと実行

Visual StudioやRider、VS Codeなどでデバッグ実行してください。
コマンドラインから実行する場合、PowerShell等でCoreMvcApplication.csprojのあるディレクトリに移動し、以下のようにdotnet restore コマンドで依存関係を復元、dotnet buildコマンドでビルドとクライアント側ライブラリの復元を行い、dotnet run コマンドでサンプルプログラムを実行します。

dotnet restore ./CoreMvcApplication.csproj
dotnet build ./CoreMvcApplication.csproj
dotnet run --project ./CoreMvcApplication.csproj

ローカルホストの56470番、および44354番ポートで待ち受けが始まるので、https://localhost:44354をブラウザで開いてください。

サンプルプログラム(結果通知受信用プログラム)設定・動作確認

サンプルプログラムでは、決済サーバーから送信される各種結果通知を、店舗側アプリケーションで受信する処理の実装を確認できます。以下は追加で必要な設定のみ説明します。

（1）受信データ保存ディレクトリの設定

appsettings.json にファイル保存ディレクトリを設定します。

"Push": {
    "OutputDirectory": "C:\\temp"
},

（2）通知受信URLの設定

店舗側の通知受信URLは、MAP（マーチャント管理ポータル）の「各種設定変更」より設定が可能です。詳しくはMAPのご利用ガイドをご参照ください。
決済サービスによっては、ダミー決済時に限り、決済申込時（与信時）に通知受信URL（通知URL）を設定することが可能です。詳しくは、サービス毎のインターフェース詳細をご参照ください。

本サンプルでの設定例です
  • MPIホスティング ： https://example.com/Push/MpiPushReceipt
  • 銀行決済： https://example.com/Push/BankPushReceipt
  • コンビニ決済： https://example.com/Push/CvsPushReceipt
  • 電子マネー決済： https://example.com/Push/EmPushReceipt
  • PayPal決済： https://example.com/Push/PayPalPushReceipt
  • 銀聯ネット決済（UPOP）： https://example.com/Push/UpopPushReceipt
  • Alipay決済： https://example.com/Push/AlipayPushReceipt
  • キャリア決済： https://example.com/Push/CarrierPushReceipt
  • ショッピングクレジット決済： https://example.com/Push/OricoscPushReceipt
  • 楽天ID決済： https://example.com/Push/RakutenPushReceipt
  • リクルートかんたん支払い： https://example.com/Push/RecruitPushReceipt
  • LINE Pay： https://example.com/Push/LinepayPushReceipt
  • PayPay： https://example.com/Push/PayPayPushReceipt
  • AmazonPay： https://example.com/Push/AmazonPayPushReceipt
  • ワンクリック継続課金サービス(洗替機能)用： https://example.com/Push/PayNowIdCardCleaningPushReceipt
  • ワンクリック継続課金サービス(継続課金機能)用： https://example.com/Push/PayNowIdRecurringPushReceipt

結果通知データを受信すると、appsettings.jsonに設定したディレクトリにCSV形式のファイルが作成されます。
（結果通知項目の詳細は、VeriTrans4G開発ガイドを参照して下さい）

旧バージョンMDKからの変更点

本MDKでは、.NET Framework 3.5および4.5向けの旧バージョンMDKから以下の点が変更となっています。

配布形式をNuGetパッケージに変更

本MDKでは、旧バージョンのDLL単独の形式から、Microsoft .NET標準のNuGetパッケージ形式に改善されています。
ご利用の社内プライベート パッケージ レジストリや、ローカル フィード等にパッケージを配置の上、アプリケーションプロジェクトからNuGetパッケージとして参照するよう設定してください。
プライベートな環境でNuGetフィードをホスティングする方法については、Microsoftの技術情報も合わせてご確認ください。
https://docs.microsoft.com/ja-jp/nuget/hosting-packages/overview

log4netの利用を廃止

本MDKでは、Application Insights等のログプロバイダーでもログ記録ができるよう、log4netの利用を廃止し、Microsoft.Extensions.Logging名前空間のILoggerインターフェイスでロガーを受け付けるよう改善されています。

MDKログは何かしら問題が発生した際のトラブルシューティングに必要となるため、必ずファイルシステムやログ収集システム等に保存するようにしてください。

サンプルプログラムでは、コンソールアプリケーションではNLogを、ASP.NET CoreアプリケーションではSerilogを利用した最低限のログ出力を実装していますが、ご利用のシステムに適したログの記録方法を入念に検討の上、実装してください。
.NETでのログプロバイダーについては、Microsoftの技術情報も合わせてご確認ください。
https://docs.microsoft.com/ja-jp/dotnet/core/extensions/logging-providers

マーチャント設定のインスタンス化に対応

旧バージョンのMDKでは、ファイルシステム上の3GPSMDK.ini ファイルへの参照が必要となっており、また、設定を保存する変数がThreadStaticとなっていて分かりづらいなど、複数のマーチャントを切り替えたい場合や、サーバーレスで動かしたい場合などに難点がありました。
本バージョンのMDKではマーチャント設定をMerchantConfigクラスのインスタンスとして扱えるよう改善されており、マーチャントCCIDや認証鍵をパラメータとして設定することや、3GPSMDK.ini をファイルシステムオブジェクト、または内容をStringとして渡して初期化することが可能です。

Transactionクラスのコンストラクタ等の変更

上記の改善にともない、各設定の初期化方法や、Transactionクラスのコンストラクタのシグネチャが旧バージョンから変更となっています。

実装例 旧バージョンMDK 本MDK
ログ設定の初期化 log4net.Config.XmlConfigurator.Configure
(new System.IO.FileInfo(@"C:\somedir\log4net.config")); 		廃止
マーチャント設定の初期化 jp.veritrans.tercerog.mdk.MdkContext.Configure(new System.IO.FileInfo(@"C:\somedir\3GPSMDK.ini"));

var config = new MerchantConfig(logger, new FileInfo(@"C:\somedir\3GPSMDK.ini"));
または
var config = new MerchantConfig(logger, "{merchant_ccid}", "{merchant_secret}", isDummy);

Transactionクラスのインスタンス化 var tran = new Transaction(); var transaction = new Transaction(logger, config);

※決済パラメータを渡すためのDTOクラスについては変更ありません。

旧バージョンからMDKの差し替えを行う場合は、お手数ですがプログラムの該当箇所の改修をしていただくようお願いいたします。
実際のコード例については、コンソールアプリケーション、およびASP.NET Core Webアプリケーションのサンプルプログラムをご参照ください。