آلية عمل Payment Request API

تعرَّف على آلية عمل واجهة برمجة التطبيقات Payment Request API على مستوى عالٍ.

Eiji Kitamura

واجهة برمجة التطبيقات لطلب الدفع

عندما يحاول أحد العملاء شراء منتج من موقعك الإلكتروني، يجب أن يطلب الموقع الإلكتروني من العميل تقديم معلومات الدفع ومعلومات أخرى اختيارية، مثل طريقة الشحن المفضّلة. يمكنك تحقيق ذلك بسهولة وبسرعة باستخدام Payment Request API (PR API).

البنية الأساسية

يتطلّب إنشاء عنصر PaymentRequest مَعلمتَين: payment methods وpayment details. بالإضافة إلى ذلك، تكون مَعلمة خيارات الدفع الثالثة اختيارية. يمكن إنشاء طلب أساسي على النحو التالي:

const request = new PaymentRequest(paymentMethods, paymentDetails);

لنلقِ نظرة على كيفية إنشاء كل مَعلمة واستخدامها.

طُرق الدفع

المَعلمة الأولى، paymentMethods، هي قائمة بطرق الدفع المتوافقة في متغيّر مصفوفة. يتألّف كل عنصر في الصفيف من مكوّنين، supportedMethods وdata اختياريًا.

بالنسبة إلى supportedMethods، على التاجر تحديد معرّف طريقة الدفع مثل https://bobbucks.dev/pay. يعتمد توفُّر data ومحتواه على محتوى supportedMethods وتصميم مقدّم تطبيق الدفع.

يجب أن يقدّم مقدّم تطبيق الدفع كلا المقطعَين من المعلومات.

// Supported payment methods
const paymentMethods = [{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: {
    ... // Optional parameters defined by the payment app provider.
  }
}];

تفاصيل الدفع

يتم تمرير المَعلمة الثانية، paymentDetails، كعنصر وتحدِّد تفاصيل الدفع للمعاملة. يحتوي على القيمة المطلوبة total، التي تحدّد إجمالي المبلغ المستحق من العميل. يمكن لهذه المَعلمة أيضًا إدراج السلع التي تم شراؤها اختياريًا.

في المثال أدناه، تظهر قائمة السلع المشتراة الاختيارية (سلعة واحدة فقط في هذا المثال)، بالإضافة إلى المبلغ الإجمالي المطلوب. وفي كلتا الحالتَين، يتم تحديد وحدة العملة مع كل مبلغ فردي.

const paymentDetails = {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
};

التحقّق ممّا إذا كانت طريقة الدفع متاحة

يتحقّق Chrome ممّا إذا كان المستخدم والبيئة جاهزين لإجراء الدفع أثناء إنشاء عنصر PaymentRequest.

للتحقّق مما إذا كان المستخدم والبيئة جاهزين لإجراء عملية دفع، اتصل بالرقم canMakePayment() قبل تنفيذ إجراءات الدفع. يؤدي استدعاء canMakePayment() إلى عرض true إذا كان المتصفّح يتيح أسلوب دفع واحدًا على الأقل محدّدًا في الكائن.

request.canMakePayment().then(result => {
  if (result) {
    // This browser supports the specified payment method.
  } else {
    // This browser does NOT support the specified payment method.
  }
}).catch(e => {
  // An exception
});

مزيد من المعلومات حول دالة PaymentRequest.canMakePayment() على MDN

طريقة show()

بعد ضبط المَعلمتَين وإنشاء عنصر request كما هو موضّح أعلاه، يمكنك استدعاء طريقة show() التي تعرِض واجهة مستخدم تطبيق الدفع.

request.show().then(response => {
  // [process payment]
  // send to a PSP etc.
  response.complete('success');
});

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

أخيرًا، يمكنك إغلاق واجهة مستخدم طلب الدفع من خلال إكمال العملية باستخدام response.complete('success') أو response.complete('fail') استنادًا إلى نتيجة العميل التي يعرضها نظام معالجة الدفعات.

المحتوى التالي

مزيد من المعلومات حول "الدفعات على الويب"