如何在 Node.js 中與 Payments API 建立連線

1. 事前準備

本自助式程式碼研究室將逐步說明如何與 Stanadard Payments API 建立連線。

必要條件

  • 您已完成導入程序的步驟 1 和 2。
  • 您可以使用 Google App Engine 或在透過 Google 設定的網域中使用自己的解決方案，代管採用 TLS 終止功能的 Node.js 伺服器。
  • 您的環境已安裝 Node.js。

課程內容

  • 如何向 Google Standard Payments echo API 發出有效要求來驗證連線。
  • 如何接收、解密及剖析 Google 傳送至 Partner Hosted Echo API 的要求。

2. 設定和需求

下載應用程式

下載 Node.js 程式碼範例。

安裝依附元件

前往專案目錄，然後執行下列指令來安裝必要的依附元件。如果您使用的是 App Engine，則可略過這個步驟。

npm install

3. 設定付款整合商帳戶 ID (PIAID)

付款整合商帳戶 ID (PIAID) 是用來識別整合項目的 ID。開始本教學課程前，請先完成事前準備，確保 Google 已取得你的 PIAID。

  1. 前往專案目錄中的 server.js 檔案。
  2. 將變數 PIAID 設為 Google 核發的 PIAID。
const PIAID = '{PAYMENT_INTEGRATOR_ACCOUNT_ID}';

4. 新增 PGP 金鑰

在專案結構中建立下列檔案，並新增 PGP 金鑰以啟用 PGP 加密。

  • 建立名為 public.key 的檔案，並在檔案中新增採用 ASCII 的公開金鑰。
  • 建立名為 private.key 的檔案，並在檔案中新增採用 ASCII 的私密金鑰。
  • 建立名為 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. 測試 Partner API 連線

為了測試合作夥伴 echo API 連線，Google 會將要求傳送至 Partner Hosted echo API。

準備就緒後，請與您的 Google 聯絡窗口合作，由 Google 觸發這項要求。

如果您能讀取來自 Google 的傳入 echo 要求，並傳回有效的 echo 回應，即代表 echo 測試完成。

詳細路線指示

現在伺服器已收到並處理要求，讓我們來看看運作方式。

使用 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"
}

建立回應

成功讀取傳入 echo 要求後，即可開始建構回應。

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. 恭喜！

在本程式碼研究室中，您已成功與 Echo API 建立連線！