序章

統合ガイドのドキュメントは、サンプルの加盟店サイトを用いて、3DS2認証フローを統合するプロセスを一から説明します。これは3DSリクエスターと3DSクライアントを、3DSリクエスター環境と呼ばれる加盟店チェックアウトプロセスに、EMV 3Dセキュア2.0の仕様を実装するためのものです。

この統合ガイドは、提供された3DSリクエスターデモのプロジェクトに基づいており、二つのパートで構成されています:

• HTML/JavaScriptのフロントエンド - デモのオンラインショップと、BRW、3RI、APP、EnrolのAPI呼び出しのためのテストページ
• バックエンド - フロントエンドページとリソースのホスト。また、ページ転送の実行とx509認証によるActiveServer認証APIの呼び出しを行います。

フロントエンドWebページとJavaScriptの実装は以下のフレームワーク、コンポーネントを使用します。

• Bootstrap 4.1.3
• Font Awesome 5.2.0
• Moment.js
• JQuery 3.3.1

前提条件¶

このガイドを使用するための前提条件は以下の通りです:

• Webフロントエンドの開発知識 (HTML、 CSS、JavaScript)
• Gitクライアント
• アクティブ化され、実行中のActiveServerインスタンス
• Java、PHP もしくは C#のプログラミングの重要知識

サンプルコードのチェックアウト¶

3DSリクエスターデモのコードはGitHubにホストされており、以下のレポジトリから複製する事が出来ます:

https://github.com/gpayments/gp-3ds-requestor-demo.git

サンプルコードをチェックアウトするには、以下のコマンドをローカル環境で実行してください:

1

git clone https://github.com/gpayments/gp-3ds-requestor-demo.git

レポジトリが複製されると、このチュートリアルの全ての必要なデモコードが以下のディレクトリ内に見つかります:

1
2
3

$ cd gp-3ds-requestor-demo
gp-3ds-requestor-demo $  ls　
dotnet  go  java  php  README.md

GPaymentsは現在Java 、PHP 、C# 、Go向けのバックエンドのサンプルコードを提供しています。統合ガイドを通して、バックエンドの言語間で説明が異なる場所では、その言語のタブをクリックすることで言語別の説明が表示されます。

すべてのバックエンドのサンプルは、JavaScriptを使用して書かれテンプレート化にMustacheを利用した実装方法になっています。

サーバー側の依存性¶

サーバー側の3DSリクエスターデモのコードは、言語により異なりますが、以下の依存性とライブラリをデモの3DSリクエスターを実行する前にインストールする必要があります:

クライアント証明書の取得¶

バックエンドがActiveServer認証APIを呼び出し自身を認証する前に、クライアント証明書をセットアップする必要があります。このクライアント証明書により、バックエンドはActiveServerで相互に認証されたTLS接続をセットアップする事が出来ます。

クライアント証明書を取得するには、こちらを参照してください。ActiveServerインスタンスへのアクセスを持っておらず、GPayments TestLabsを使用する場合は、techsupport@gpayments.com宛てにメールを送り、証明書を取得してください。

クライアント証明書キーストアファイルの用意が出来たら、好みのディレクトリにそれをコピーし、そのファイルパスをバックエンドにて指定してください。

証明書は3DSリクエスターデモプロジェクトディレクトリ内にコピーする必要はありませんが、クライアント証明書をプロジェクト内に保存する事で、管理しやすくなります。

プロジェクトのディレクトリ構造を確認するには、ディレクトリ構造で詳細を参照してください。

3DSリクエスターデモの設定¶

3DSリクエスターデモを実行するために、システムを起動する前に以下の設定を行う必要があります:

1. 3DSリクエスターは、ActiveServerに自身のエントリーポイントをコールバックURLとして送信する必要があります。さらに、認証APIを実行するためにActiveServerの認証API URLも設定する必要があります。

   AsAuthUrlとBaseUrlをバックエンドリソースファイルで設定してください。これらの値はアプリケーションが起動され再起動しないと変更出来ない時に時に使用されます:

   • AsAuthUrl - ActiveServerインスタンスのAPI URLを設定します。GPayments TestLabsを利用する場合はデフォルトの値をお使いください。
   • BaseUrl - アプリケーションが起動されアクセスされるURLになります。
   Java

   1 2 3 4 5 6

   //application.yml gpayments: asAuthUrl: https://api.as.testlab.3dsecure.cloud:7443 baseUrl: http://localhost:8082 certFileName: # Client Certificate file (.p12 or .pfx) path ...

   C#

   1 2 3 4 5 6 7 8

   //Web.config <appSettings> <add key="AsAuthUrl" value="https://api.as.testlab.3dsecure.cloud:7443"/> <add key="BaseUrl" value="http://localhost:8082"/> ... </appSettings> //Please note that you may need to configure your IIS listening port to `8082` to match the `BaseUrl` setting in the configuration.

   PHP

   1 2 3 4

   //application.ini asAuthUrl = https://api.as.testlab.3dsecure.cloud:7443 baseUrl = http://localhost:8082 ...

   Go

   1 2 3 4 5

   //application.yml gpayments: asAuthUrl: https://api.as.testlab.3dsecure.cloud:7443 baseUrl: http://localhost:8082 ...

   注釈

   もしサンプル内で使用される標準のポートが使用されている場合はエラーが発生する事があります。その場合はportとbaseUrlを適切な値に設定してください。

2. バックエンドリソースファイルのcertFileNameをダウンロードした証明書に設定します。

   • 加盟店クライアント証明書を利用する場合:

     • certFileNameをクライアント証明書の完全なファイル名とパスに設定。
     • groupAuthをfalseに設定。
     • merchantTokenを空白に設定。

   • 認証APIマスタークライアント証明書:

     • certFileNameをクライアント証明書の完全なファイル名とパスに設定。
     • groupAuthをtrueに設定。
     • merchantTokenを設定する。マーチャントトークンについてはこちらを参照してください。

     警告

     groupAuth = trueの場合、バックエンドはHTTPリクエストのHTTPヘッダーにAS-Merchant-Tokenフィールドを追加しmer​​chantTokenの値を設定する必要があります。バックエンド実装の詳細を確認するには、こちらを参照してください。

   Java

   1 2 3 4 5 6 7

   //application.yml gpayments: ... certFileName: # <クライアント証明書の完全なファイル名とパス>(.p12または.pfx) certFilePassword: # <クライアント証明書のパスワード> groupAuth: false merchantToken: # groupAuth = trueの場合のmerchantToken

   C#

   1 2 3 4 5 6 7 8 9 10 11 12 13 14

   //config.cs //Web.config <appSettings> ... <!--クライアント証明書の完全なファイル名とパス (.p12 or .pfx)--> <add key="CertFileName" value=""/> <add key="CertFilePassword" value=""/> <add key="GroupAuth" value="false"/> <!--groupAuth = trueの場合のmerchantToken--> <add key="MerchantToken" value=""/> ... </appSettings> //Please note that you may need to configure your IIS listening port to `8082` to match the `BaseUrl` setting in the configuration.

   PHP

   1 2 3 4 5 6 7 8

   //application.ini ... certFileName = ;パスワードなしでopensslコマンドを使用して生成された秘密鍵へのファイルパス。 keyFileName = groupAuth = true ; groupAuth = trueの場合のmerchantToken merchantToken =

   Go

   1 2 3 4 5 6 7 8

   //application.yml gpayments: asAuthUrl: https://api.as.testlab.3dsecure.cloud:7443 baseUrl: http://localhost:8082 certFileName: <クライアント証明書の完全なファイル名とパス> certFilePassword: <クライアント証明書のパスワード> groupAuth: false merchantToken: # groupAuth = trueの場合のmerchantToken

   備考

   クライアント証明書は任意の場所に保存することが出来ます。例えば、クライアント証明書をC:/Downloadsディレクトリ(Windowsの場合)にclient_certificate.p12のファイル名で保存した場合は、certFileNameをC:/Downloads/client_certificate.p12に変更してください。

3. Terminal(Linux)またはコマンドプロンプト(Windows)を開き以下のコマンドラインをプロジェクトのルートディレクトリで実行してください。これは初回実行時にはすべての必要な依存性をダウンロードする為に数分かかる事があります。

   Java

   1 2	$ cd java $ mvn spring-boot:run

   C#

   1 2	> cd dotnet > startup.bat

   PHP

   1 2 3 4

   $ cd php $ curl -sS https://getcomposer.org/installer | php $ php composer.phar install $ php -S localhost:8082

   Go

   1 2	$ cd go $ go run .

   Javaネットワークアクセスによるファイアーウォール警告

   WindowsではJavaのネットワークアクセスによりファイアーウォールセキュリティアラートが発生する可能性があります。その場合は、アクセスを許可して続けてください。

3DSリクエスターWebサイトを閲覧する¶

クライアント証明書とURLが適切に設定され、スタートアップコマンドが実行されると、3DSリクエスターデモが正常に起動されるはずです。3DSリクエスターページはhttp://localhost:8082(もしくは上記で指定したBaseURL)にアクセスする事で閲覧する事が出来ます。

ショップページを開くにはOnline Shop内のLaunchボタンを選択してください。いくつか商品をカートに追加し、デフォルトのカード会員の情報を使用してチェックアウトしてみてください。

すると3DSリクエスターデモはチェックアウトページを表示します:

Continue to Checkoutボタンで続行すると、3DSリクエスターデモは進捗画面を表示します:

そして最後に結果ページが表示されます(使用したカード番号により、セキュリティ確認画面が表示される事があります。詳細はサンプルコード機能を確認してください):

おめでとうございます！初めての3DSリクエスターのデモをローカル環境で正常に実行してテストしました。

サポート¶

この文書についてご質問のある場合は、お気軽にお問合わせ下さい。techsupport@gpayments.co.jpにEメールをお待ちしております。