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

1. قبل البدء

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

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

  • أن تكون قد أكملت الخطوتَين 1 و2 من عملية التنفيذ
  • يمكنك استضافة خادم Node.js المقدَّم مع إنهاء طبقة النقل الآمنة باستخدام 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) هو معرّف يُستخدَم لتحديد عمليات الدمج بشكلٍ فريد. من المفترض أن تكون قد تلقّيت معرّف 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 Hosted 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.