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

1- قبل البدء

هذا درس تطبيقي حول الترميز موجَّه ذاتيًا ويشرح كيفية إنشاء اتصال بواجهات برمجة تطبيقات Stanadard Payments.

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

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

المعلومات التي ستطّلع عليها

  • كيفية التحقّق من الاتصال من خلال تقديم طلب صالح إلى Google Standard Payments echo API
  • كيفية استلام طلب من Google وفك تشفيره وتحليله في Partner Host 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 API طلب 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 API

لاختبار اتصال echo API الخاص بالشريك، سترسل Google طلبًا إلى Partner host 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. تهانينا!

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