كيفية إنشاء اتصال بواجهات برمجة تطبيقات Payments في Node.js

‫1. قبل البدء

هذا درس تطبيقي ذاتي التوجيه يشرح كيفية إنشاء إمكانية الاتصال بواجهات برمجة التطبيقات لعمليات الدفع العادية.

المتطلبات الأساسية

  • لقد أكملت الخطوتين 1 و2 من عملية التنفيذ.
  • يمكنك استضافة خادم Node.js المتوفّر مع إنهاء بروتوكول أمان طبقة النقل (TLS) باستخدام Google App Engine أو الحلّ الخاص بك على النطاق الذي تم إعداده باستخدام Google.
  • يجب أن يكون Node.js مثبّتًا في بيئتك.

ما ستتعلمه

  • كيفية التحقّق من الربط من خلال إرسال طلب صالح إلى واجهة برمجة التطبيقات echo في Google Standard Payments
  • كيفية تلقّي طلب من Google إلى واجهة برمجة التطبيقات Partner Hosted Echo API وفك تشفيره وتحليله

‫2. الإعداد والمتطلبات

تنزيل التطبيق

نزِّل نموذج الرمز البرمجي Node.js.

تثبيت الحِزم التابعة

انتقِل إلى دليل المشروع ونفِّذ الأمر التالي لتثبيت التبعيات المطلوبة. إذا كنت تستخدم App Engine، يمكنك تخطي هذه الخطوة.

npm install

3- ضبط معرّف حساب خدمة تكامل الدفع (PIAID)

معرّف حساب خدمة تكامل الدفع (PIAID) هو معرّف يُستخدَم لتحديد عمليات التكامل بشكلٍ فريد. من المفترض أن تكون قد تلقّيت معرّف PIAID من Google بعد إكمال المتطلبات الأساسية قبل بدء هذا الدليل التعليمي.

  1. انتقِل إلى الملف server.js في دليل المشروع.
  2. اضبط المتغيّر PIAID على معرّف PIAID الذي أصدرته لك Google.
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 الخاصة بالتطبيق النموذجي طلب POST بنص عادي. بعد تلقّي الطلب، يتم إرسال طلب لاحق إلى واجهة برمجة التطبيقات المستضافة على Google.

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

سيؤدي طلب البيانات الناجح من واجهة برمجة التطبيقات إلى تلقّي الردّ التالي من Google.

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

الخطوات بالتفصيل

بعد أن أرسل الخادم طلبًا بنجاح، لنراجع كيفية عمل ذلك.

إنشاء الطلب

تنشئ buildEchoRequestBody في bodyHelpers.js طلب echo يتم إرساله إلى واجهة برمجة التطبيقات من Google.

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 Hosted echo API، سترسل Google طلبًا إلى هذه الواجهة.

عندما تكون مستعدًا، يُرجى التواصل مع جهة الاتصال المعنية في 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. تهانينا!

في هذا الدرس العملي، تمكّنت من إنشاء اتصال بنجاح مع Echo API.