Node.js で Payments API との接続を確立する方法

1. 始める前に

これは、Stanadard Payments API との接続を確立する方法を説明するセルフガイドの Codelab です。

前提条件

  • 実装プロセスのステップ 1 と 2 が完了しました。
  • 提供された Node.js サーバーを TLS 終端付きでホストするには、Google App Engine または Google で構成されたドメインで独自のソリューションを使用します。
  • Node.js が環境にインストールされている。

学習内容

  • Google Standard Payments echo API に有効なリクエストを送信して接続を確認する方法。
  • Google から Partner Hosted Echo API へのリクエストを受信、復号、解析する方法。

2. 設定と要件

アプリケーションをダウンロードする

Node.js サンプルコードをダウンロードします。

依存関係のインストール

プロジェクト ディレクトリに移動し、次のコマンドを実行して必要な依存関係をインストールします。App Engine を使用している場合は、この手順を省略できます。

npm install

3. 決済インテグレーター アカウント ID（PIAID）を構成する

決済インテグレーター アカウント ID（PIAID）は、統合を一意に識別するために使用される識別子です。このチュートリアルを開始する前に、前提条件を満たしていれば、Google から PIAID を受け取っているはずです。

  1. プロジェクト ディレクトリ内の server.js ファイルに移動します。
  2. 変数 PIAID を、Google から発行された PIAID に設定します。
const PIAID = '{PAYMENT_INTEGRATOR_ACCOUNT_ID}';

4. PGP 鍵を追加する

PGP 暗号化を有効にするには、プロジェクト構造で次のファイルを作成し、PGP 鍵を追加します。

  • public.key という名前のファイルを作成し、そのファイルに ASCII Armor の公開鍵を追加します。
  • private.key という名前のファイルを作成し、そのファイルに ASCII Armor の秘密鍵を追加します。
  • passphrase.txt という名前のファイルを作成し、そのファイルにシークレット パスフレーズを追加します。

PGP 鍵の追加

これで、アプリケーションを実行する準備が整いました。

5. アプリケーションを実行する

次のコマンドを実行して、アプリを起動します。

$ node server.js
Server listening on port 8080...

事前構成済みの App Engine インスタンスを実行している場合は、代わりにこのコマンドを実行します。

$ gcloud app deploy

デフォルトでは、サーバーはポート 8080 をリッスンします。

6. Google Standard Payments API の接続をテストする

アプリケーションが実行されたら、Google Standard Payments echo API との接続をテストします。

次のコマンドを実行して、サンプル アプリケーションのインスタンスから Google のサーバーへの呼び出しを開始します。サンプル アプリケーションの echo API は、平文の POST リクエストを受け入れます。リクエストを受信すると、後続のリクエストは Google がホストする API に送信されます。

  $ curl -X POST -H 'Content-Type: text/plain' -d 'Hello from Little Bear' https://{HOSTNAME}/echo

API リクエストが成功すると、Google から次のようなレスポンスが返されます。

{
   "responseHeader":{
      "responseTimestamp":"1606710026723"
   },
   "clientMessage":"Hello from Little Bear",
   "serverMessage":"Server message."
}

詳細なルート

サーバーによってリクエストが正常に送信されたので、その仕組みを確認しましょう。

リクエストを作成する

bodyHelpers.js の buildEchoRequestBody は、Google の API に送信される echo リクエストを作成します。

const message = bodyHelpers.buildEchoRequestBody(req.body);

生成されるリクエストには、clientMessage と複数のデフォルト値フィールドが含まれます。

{
   "requestHeader":{
      "protocolVersion":{
         "major":1,
         "minor":0,
         "revision":0
      },
      "requestId":"ddfe0fd0-ffdc-4fcf-991a-f0611ec83970",
      "requestTimestamp":"1606715389040"
   },
   "clientMessage":"Hello from Little Bear"
}

リクエストを暗号化する

すべてのリクエストは暗号化され、base64url でエンコードされます。このサンプルの crypto.js には、暗号化と復号を行うヘルパー メソッドが含まれています。crypto.encrypt メソッドは、Google の公開鍵を使用して暗号化を実行します。

const encrypted = await crypto.encrypt(message);

base64url でエンコードされた POST リクエストを送信する

暗号化されたメッセージは、base64url パッケージを使用して base64url エンコードされ、axios を使用して POST リクエストを介して送信されます。

const response = await axios.post(ECHO_URL, base64url(encrypted), AXIOS_CONFIG);

レスポンスを復号して返す

Google からのレスポンスが base64url でエンコードされ、暗号化されているとします。したがって、これをデコードして復号しないと平文で返す必要があります。

const encryptedMessage = base64url.toBuffer(response.data);
const decryptedResponse = await crypto.decrypt(encryptedMessage);
res.status(200);
res.send(decryptedResponse);

7. パートナー API の接続をテストする

パートナー echo API の接続をテストするために、Google は Partner Hosted echo API にリクエストを送信します。

準備が整ったら、Google の担当者と連携して、Google からのこのリクエストをトリガーしてください。

Google からの受信エコー リクエストを読み取り、有効なエコー レスポンスを返すことができれば、エコーテストは完了です。

詳細なルート

サーバーがリクエストを正常に受信して処理したので、次はその仕組みを確認しましょう。

Base64url でリクエストをデコードする

リクエストを受け取ったら、まず base64url でデコードする必要があります。

const encryptedRequest = base64url.toBuffer(req.body);

リクエストを復号する

base64url でリクエストをデコードしたら、復号する必要があります。

const decryptedRequest = await crypto.decrypt(encryptedRequest);

リクエストを受け取る

デコードと復号が完了すると、Google が次のようなメッセージ ペイロードを送信しました。

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G1MQ0YERJ0Q7LPM",
    "requestTimestamp": {
      "epochMillis":1481899949606
    },
    "paymentIntegratorAccountId": "abcdef123456"
  },
  "clientMessage": "echo Me"
}

レスポンスを作成する

インバウンド エコー リクエストが正常に読み取られたら、レスポンスを作成する準備は完了です。

clientMessage = JSON.parse(decryptedRequest).clientMessage;
responseBody = bodyHelpers.buildEchoResponseBody(clientMessage);

レスポンスには、Google からのメッセージに加えて、サーバーから送信されたタイムスタンプとメッセージが含まれます。

{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis":1481899950236
    }
  },
  "clientMessage": "echo Me",
  "serverMessage": "Debug ID 12345"
}

レスポンスを暗号化し、Base64 でエンコードする

レスポンス メッセージを作成したら、暗号化し、base64url でエンコードできます。

encryptedResponse = await crypto.encrypt(responseBody);
const encodedResponse = base64url(encryptedResponse);

レスポンスを返す

これで、POST レスポンスを送信する準備が整いました。

res.send(encodedResponse);

8. お疲れさまでした

この Codelab では、Echo API との接続が正常に確立されました。