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

1. 事前準備

本自助式程式碼研究室將逐步說明如何與 Standard 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 會傳送要求至合作夥伴代管的 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"
}

建立回應

成功讀取內送的回音要求後，即可開始建立回應。

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 建立連線！