איך יוצרים קישוריות לממשקי API של Payments ב-Node.js

1. לפני שמתחילים

בשיעור הזה תלמדו איך ליצור קישוריות ל-Standard Payments APIs.

דרישות מוקדמות

  • השלמתם את שלבים 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. הגדרת מספר חשבון משולב תשלומים (PIAID)

מספר החשבון של משלב התשלומים (PIAID) הוא מזהה שמשמש לזיהוי ייחודי של השילובים שלכם. לפני שמתחילים את המדריך הזה, צריך לוודא שקיבלתם מ-Google את מזהה PIAID אחרי שהשלמתם את הדרישות המוקדמות.

  1. מנווטים לקובץ server.js בספריית הפרויקט.
  2. מגדירים את המשתנה PIAID למזהה PIAID שהונפק לכם על ידי Google.
const PIAID = '{PAYMENT_INTEGRATOR_ACCOUNT_ID}';

4. הוספת מפתחות PGP

יוצרים את הקבצים הבאים במבנה הפרויקט ומוסיפים את מפתחות ה-PGP כדי להפעיל הצפנת PGP.

  • יוצרים קובץ בשם public.key ומוסיפים לקובץ את המפתח הציבורי בפורמט ASCII.
  • יוצרים קובץ בשם private.key ומוסיפים לקובץ את המפתח הפרטי בפורמט ASCII armoured.
  • יוצרים קובץ בשם 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. ה-API של אפליקציית הדוגמה echo מקבל בקשת POST בטקסט פשוט. אחרי קבלת הבקשה, נשלחת בקשה נוספת אל ה-API שמתארח ב-Google.

  $ 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."
}

שלב אחר שלב

אחרי שהשרת שלכם שלח בקשה בהצלחה, נסביר איך זה קרה.

הרכבת הבקשה

‫buildEchoRequestBody ב-bodyHelpers.js יוצר את הבקשה echo שנשלחת אל Google API.

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);

שליחת בקשת POST בקידוד base64url

ההודעה המוצפנת מקודדת בפורמט base64url באמצעות חבילת base64url ונשלחת באמצעות בקשת POST באמצעות axios.

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

כדי לבדוק את הקישוריות של ה-API של השותף, Google תשלח בקשה ל-API של השותף שמתארח אצל השותף.

כשאתם מוכנים, אתם יכולים לפנות לאיש הקשר שלכם ב-Google כדי להפעיל את הבקשה הזו מ-Google.

הבדיקה מסתיימת כשאתם מצליחים לקרוא את בקשת האקו הנכנסת מ-Google ולהשיב עם תגובת אקו תקינה.

שלב אחר שלב

אחרי שהבקשה התקבלה בהצלחה בשרת וטופלה, נבדוק איך זה קרה.

פענוח Base64url של הבקשה

כשמקבלים את הבקשה, קודם צריך לבצע לה פענוח base64url.

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

פענוח הבקשה

אחרי שמפענחים את הבקשה בקידוד base64url, צריך לפענח אותה.

const decryptedRequest = await crypto.decrypt(encryptedRequest);

קבלת הבקשה

‫Google שלחה מטען ייעודי (payload) של הודעה שדומה לזה שמופיע בהמשך, אחרי שהוא פוענח ופוענח.

{
  "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.