すべてのプロダクト
Search

このプロダクト

    Financial Intelligence Engine:ZOLOZ ゲートウェイの統合

    ドキュメントセンター

    Financial Intelligence Engine:ZOLOZ ゲートウェイの統合

    最終更新日:Jan 19, 2025

    ZOLOZ API はプログラミング言語に依存せず、ZOLOZ ゲートウェイサービスによって公開されます。 ZOLOZ API を統合する前に、ZOLOZ ゲートウェイサービスにアクセスできることを確認する必要があります。 このトピックでは、Java ライブラリまたは ZOLOZ ヘルパースクリプトを使用して ZOLOZ API を統合する方法について説明します。 また、ZOLOZ ヘルパースクリプトを使用して、指定したゲートウェイプロトコルの実装を検証する方法についても説明します。

    前提条件

    • ZOLOZ ゲートウェイサービスは、ゲートウェイプロトコルに基づいて実装されています。 ZOLOZ ゲートウェイプロトコル を理解している必要があります。

    • ZOLOZ ゲートウェイサービスと通信するために使用する API 認証情報を取得済みであること。 詳細については、「API 認証情報を取得する」をご参照ください。

    統合方法

    ZOLOZ ゲートウェイを統合するには、ZOLOZ が提供するゲートウェイプロトコルライブラリを使用するか、ゲートウェイプロトコルを指定します。

    • ZOLOZ は複数のライブラリを提供しています。 プログラミング言語と環境に基づいてライブラリを選択できます。

    • プログラミング言語が Java の場合は、Java ライブラリを使用できます。 詳細については、このトピックの「Java ライブラリを追加する」セクションを参照してください。

    • シェル環境で ZOLOZ API を呼び出す場合は、ヘルパースクリプトを使用できます。 詳細については、このトピックの「ヘルパースクリプトを使用する」セクションを参照してください。

    • ZOLOZ ゲートウェイを統合するためにゲートウェイプロトコルを指定する場合は、ZOLOZ ヘルパースクリプトを使用して、指定したゲートウェイプロトコルの実装を検証できます。 詳細については、このトピックの「方法 2: 指定されたゲートウェイプロトコルを使用する」セクションを参照してください。

    認証テスト操作

    この例では、認証テスト操作が呼び出されます。 認証テスト操作は、さまざまなサービスの認証テストに使用される特別な API 操作です。 有効な JSON オブジェクトを含む API リクエストを開始して、認証テスト操作を呼び出すことができます。 この操作は、JSON 文字列の形式で同じ JSON オブジェクトを含むレスポンスを返します。 これは、echo コマンドの機能に似ています。

    認証テスト操作を呼び出す前に、ZOLOZ ゲートウェイを統合する必要があります。 認証テスト操作の呼び出し方法がわかれば、他の API 操作も簡単に呼び出すことができます。

    方法 1: ZOLOZ が提供するゲートウェイプロトコルライブラリを使用する

    Java ライブラリを追加する

    ZOLOZ の Java ライブラリは Maven Central Repository で公開されています。 このセクションでは、パブリック Java ライブラリを使用して ZOLOZ ゲートウェイを統合し、ZOLOZ API を呼び出す方法について説明します。

    1. Java 用 ZOLOZ SDK を統合します。

      プロジェクトの pom.xml ファイルに次の依存関係を追加します。 このようにして、Java ライブラリがプロジェクトに追加されます。 依存関係の最新バージョンは、GitHub から取得できます。

    <dependency>
 <groupId>com.zoloz.api.sdk</groupId>
 <artifactId>zoloz-api-sdk</artifactId>
 <version>1.0.2</version>
</dependency>

    1. OpenApiClient クラスをインポートします。

    import com.zoloz.api.sdk.client.OpenApiClient;

    1. OpenApiClient クラスをインスタンス化して構成します。

    // 次の変数に適切な値を割り当てます。
String clientId = "<クライアント ID>";
String zolozPublicKey = "<Base64 でエンコードされた ZOLOZ トランザクション公開鍵>";
String merchantPrivateKey = "<Base64 でエンコードされた加盟店トランザクション秘密鍵>";

// デフォルトで署名検証と暗号化の両方が有効になっている OpenApiClient オブジェクトを作成します。
OpenApiClient client = new OpenApiClient(); 
client.setHostUrl("<ZOLOZ ゲートウェイ URL>");
client.setClientId(clientId);
client.setMerchantPrivateKey(merchantPrivateKey);
client.setOpenApiPublicKey(zolozPublicKey);
// 注: レスポンスの署名検証をスキップする場合は、次の行のコメントを外します。
//client.setSigned(false); 
// 注: 暗号化を無効にする場合は、次の行のコメントを外します。
//client.setEncrypted(false);

    コード内の次のパラメーターの値を実際の値に置き換える必要があります。 clientId、zolozPublicKey、および merchantPrivateKey パラメーターの値を取得する方法の詳細については、「API 認証情報を取得する」をご参照ください。

    • clientId: クライアント ID。

    • zolozPublicKey: Base64 でエンコードされた ZOLOZ トランザクション公開鍵。

    • merchantPrivateKey: Base64 でエンコードされた加盟店トランザクション秘密鍵。

    • setHostUrl: ZOLOZ ゲートウェイの URL。 ZOLOZ ゲートウェイの URL を取得する方法の詳細については、「サイトと環境を選択する」をご参照ください。

    1. 認証テスト操作を呼び出します。

    // 認証テスト操作の名前を指定します。
String apiName = "v1.zoloz.authentication.test";

// 単純な JSON オブジェクトを含むリクエストを開始します。
String request = "{\"title\": \"hello\", \"description\": \"just for demonstration.\"}";

// 操作を呼び出します。 レスポンスは、JSON 文字列の形式で同じ JSON オブジェクトになるはずです。
String response = client.callOpenApi(apiName, request);

    ヘルパースクリプトを使用する

    1. ZOLOZ ヘルパースクリプトを取得します。

    # スクリプトをローカルマシンにダウンロードします。
wget https://raw.githubusercontent.com/zoloz-pte-ltd/zoloz-api-script/master/zoloz.sh

# スクリプトを実行できるようにします。
chmod u+x zoloz.sh

    1. 移植可能なオペレーティングシステムインタフェース ( POSIX ) 標準をサポートするシェル環境でスクリプトを実行して、認証テスト操作を呼び出します。

    # たとえば、zoloz.sh が現在の作業ディレクトリにあるとします。
./zoloz.sh \
 -c 2188000123456789 \
 -P merchant_private_key.pem \
 -K 'MIIBIj...QIDAQAB' \
 -a /api/v1/zoloz/authentication/test \
 -d '{\n "title": "hello",\n "description": "just for demonstration."\n}'

    上記のコードで使用されているサンプル値は参照用です。 実際のシナリオでは、次のパラメーターの値を実際の値に置き換える必要があります。 クライアント ID と ZOLOZ トランザクション公開鍵の取得方法の詳細については、「API 認証情報を取得する」をご参照ください。

    • -c: クライアント ID。

    • -P: 加盟店トランザクション秘密鍵。 上記のコードでは、merchant_private_key.pem がサンプル値として使用されています。 サンプル値を加盟店トランザクション秘密鍵の実際のパスに置き換える必要があります。

    • -K: ZOLOZ トランザクション公開鍵。

    • -a: API 操作を呼び出すために使用されるパス。 上記のコードでは、認証テスト操作が呼び出されます。

    • -d: リクエストの内容。

    上記の パラメーターに加えて、必要に応じて次のパラメーターを追加できます。

    • -e: 暗号化を無効にします。

    • -i: レスポンスの署名検証をスキップします。

    方法 2: 指定されたゲートウェイプロトコルを使用する

    ゲートウェイプロトコルを指定して ZOLOZ API を統合できます。 その後、ZOLOZ ヘルパースクリプトを使用して、指定したゲートウェイプロトコルの実装を検証できます。 次の手順を実行します。

    1. 実装クラスを使用して API 操作を呼び出し、API 呼び出しの詳細を記録します。

      次の情報を記録する必要があります。

    • API 操作の呼び出しにかかる時間。

    • リクエストを暗号化するために高度暗号化標準 ( AES ) アルゴリズムを使用するランダムに生成されたキー。

    • 暗号化されたリクエスト。

    • リクエストの署名。

    1. ZOLOZ ヘルパースクリプトを使用して、同じリクエストを使用して同じ API 操作を呼び出し、スクリプトに次のパラメーターを追加します。

    • -v または -vv: 後で検証するために API 呼び出しの詳細を表示します。

    • -t <リクエスト時間>: API 操作の呼び出しにかかる時間。 手順 1 で記録した値を使用します。

    • -k <AES128 キー>: リクエストを暗号化するために AES-128 アルゴリズムを使用するキー。 手順 1 で記録した値を使用します。

    次のサンプルコードは、スクリプトを実行する方法の例を示しています。

    ./zoloz.sh \
 -c 2**************4 \
 -P merchant_private_key.pem \
 -K 'MIIBIj...QIDAQAB' \
 -a /api/v1/zoloz/authentication/test \
 -d '{
 "title": "hello",
 "description": "This is just a demonstration."
}' \
 -vv \
 -k 31313131313131313131313131313131 \
 -t 2020-12-01T00:00:00+0800

    次の図は、API 呼び出しの出力の詳細を示しています。

    API调用过程.png

    1. 手順 1 で記録した詳細と、手順 2 で表示された出力の詳細を比較します。

    1. 暗号化されたリクエストを検証します。

      暗号化されたリクエストの内容が、前の図の 2 でマークされたセクションの リクエスト本文 パラメーターの値と同じであることを確認します。

      注: ほとんどの場合、考えられる攻撃を回避するために、Rivest-Shamir-Adleman ( RSA ) アルゴリズムに基づいて暗号化されたリクエストにランダムなビット数が追加されます。 AES-128 アルゴリズムを使用してリクエストを暗号化する場合、出力は RSA アルゴリズムを使用して暗号化された出力とは異なります。 その後、異なるアルゴリズムを使用して暗号化されたリクエストの内容が同じであるかどうかを確認できます。

    2. リクエストの署名を検証します。

      リクエストヘッダーに入力したリクエストの署名が、前の図の 3 でマークされたセクションの URL エンコードされたリクエスト署名 パラメーターの値と同じであることを確認します。

    3. レスポンスの署名を検証します。

      前の図の 4 でマークされたセクションの レスポンス署名 パラメーターに表示されている署名が、実装クラスを使用してレスポンスの署名と一致するかどうかを確認します。 レスポンスの内容は、前の図の 4 でマークされたセクションの 検証されるレスポンスの内容 パラメーターに表示されます。

    4. 復号化されたレスポンスを検証します。

    • 復号化されたキーが、実装クラスを使用して AES-128 アルゴリズムに基づいて暗号化されたのと同じキーであるかどうかを確認します。 復号化されたキーは レスポンス対称キー パラメーターの値であり、AES-128 アルゴリズムに基づいて暗号化されたキーは、前の図の 5 でマークされたセクションの レスポンス暗号化対称キー パラメーターの値です。

    • 実装クラスを使用して、前の図の 5 でマークされたセクションの レスポンス本文 パラメーターに表示されている暗号化されたレスポンスを、前の図の 5 でマークされたセクションの レスポンスの内容 パラメーターに表示されているのと同じプレーンテキストに復号化できるかどうかを確認します。

    参考資料

    Java ライブラリの JAR パッケージと ZOLOZ ヘルパースクリプトは GitHub で入手できます。 ソースコードは、次のリンクから取得できます。