مسار معاملة الدفع

تعرَّف على كيفية دمج التجّار لتطبيقات الدفع وكيفية عمل معاملات الدفع باستخدام Payment Request API.

واجهات برمجة تطبيقات Web Payments هي ميزات دفع مخصّصة مدمجة في المتصفّح لأول مرة. من خلال Web Payments، يصبح دمج التاجر مع تطبيقات الدفع أبسط، بينما تصبح تجربة المستخدم أكثر سلاسة وأمانًا.

لمزيد من المعلومات حول مزايا استخدام Web Payments، يمكنك الاطّلاع على مقالة تعزيز تطبيقات الدفع باستخدام Web Payments.

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

تتضمّن العملية 6 خطوات:

  1. يبدأ التاجر معاملة دفع.
  2. يعرض التاجر زر دفع.
  3. يضغط العميل على زر الدفع.

    مخطّط بياني لموقع إلكتروني لمتجر جبن يتضمّن زر BobPay (تطبيق للدفع)

  4. يفتح المتصفّح تطبيق الدفع.

    مخطّط بياني لموقع متجر الجبن الإلكتروني مع تشغيل تطبيق BobPay في نافذة مشروطة تعرض النافذة المنبثقة خيارات الشحن والتكلفة الإجمالية.

  5. إذا غيّر العميل أي تفاصيل (مثل خيارات الشحن أو العنوان)، يعدّل التاجر تفاصيل المعاملة لتعكس التغيير.

    رسم بياني يعرض العميل وهو يختار خيار شحن مختلفًا في نافذة تطبيق BobPay رسم بياني ثانٍ يعرض التاجر وهو يعدّل إجمالي التكلفة المعروضة في BobPay

  6. بعد أن يؤكّد العميل عملية الشراء، يتحقّق التاجر من صحة الدفعة ويُكمل المعاملة.

    مخطّط بياني يوضّح العميل وهو يضغط على

الخطوة 1: يبدأ التاجر معاملة دفع

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

  • طرق الدفع المقبولة وبياناتها لمعالجة المعاملة
  • التفاصيل، مثل السعر الإجمالي (مطلوب) ومعلومات عن السلع
  • الخيارات التي يمكن للتجّار من خلالها طلب معلومات الشحن، مثل عنوان الشحن وخيار الشحن
  • يمكن للتجّار أيضًا طلب عنوان إرسال الفواتير واسم الدافع وعنوان بريده الإلكتروني ورقم هاتفه.
  • يمكن للتجّار أيضًا تضمين نوع الشحن الاختياري (shipping أو delivery أو pickup) في PaymentRequest. ويمكن لتطبيق الدفع استخدام هذه السمة كإشارة لعرض التصنيفات الصحيحة في واجهة المستخدم.
const request = new PaymentRequest([{
  supportedMethods: 'https://bobpay.xyz/pay',
  data: {
    transactionId: '****'
  }
}], {
  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' }
  }
}, {
  requestShipping: true,
  requestBillingAddress: true,
  requestPayerEmail: true,
  requestPayerPhone: true,
  requestPayerName: true,
  shippingType: 'delivery'
});
تضمين معرِّف معاملة

قد يطلب بعض معالِجي الدفع من التاجر تقديم معرّف المعاملة الذي تم إصداره مسبقًا كجزء من معلومات المعاملة. وتتضمّن عملية الدمج النموذجية التواصل بين خادم التاجر وخادم معالج الدفع لحجز السعر الإجمالي. يمنع ذلك العملاء الضارين من التلاعب بالسعر وخداع التاجر من خلال عملية تحقّق في نهاية المعاملة.

يمكن للتاجر تمرير معرّف معاملة كجزء من السمة data في عنصر PaymentMethodData.

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

لمعرفة آلية عمل عملية الاكتشاف بالتفصيل، يُرجى الاطّلاع على مقالة إعداد طريقة دفع.

الخطوة 2: يعرض التاجر زر الدفع

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

باستخدام مثيل PaymentRequest، يمكن للتاجر الاستعلام عما إذا كان العميل لديه تطبيق الدفع متاحًا.

هل يتوفّر تطبيق الدفع لدى العميل؟

تعرض طريقة canMakePayment() الخاصة بـ PaymentRequest القيمة true إذا كان تطبيق الدفع متاحًا على جهاز العميل. تعني الحالة "متاحة" أنّه تم العثور على تطبيق دفع متوافق مع طريقة الدفع، وأنّ تطبيق الدفع الخاص بالنظام الأساسي مثبَّت، أو أنّ تطبيق الدفع المستنِد إلى الويب جاهز للتسجيل.

const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
  // Fallback to other means of payment or hide the button.
}

الخطوة 3: يضغط العميل على زر الدفع

عندما يضغط العميل على زر الدفع، يستدعي التاجر طريقة show() من مثيل PaymentRequest الذي يؤدي على الفور إلى تشغيل واجهة مستخدم الدفع.

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

تأجيل إطلاق واجهة مستخدم الدفع

يمكنك الاطّلاع على عرض توضيحي حول تأجيل واجهة مستخدم الدفع إلى أن يتم تحديد السعر الإجمالي النهائي.

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

const getTotalAmount = async () => {
  // Fetch the total amount from the server, etc.
};

try {
  const result = await request.show(getTotalAmount());
  // Process the result…
} catch(e) {
  handleError(e);
}

إذا لم يتم تحديد وعد كوسيطة لـ show()، سيشغّل المتصفّح واجهة مستخدم الدفع على الفور.

الخطوة 4: يشغّل المتصفّح تطبيق الدفع

يمكن للمتصفّح تشغيل تطبيق دفع مخصّص لنظام أساسي معيّن أو تطبيق دفع مستنِد إلى الويب. (يمكنك الاطّلاع على مزيد من المعلومات حول كيفية تحديد Chrome لتطبيق الدفع الذي سيتم تشغيله).

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

عند تشغيل تطبيق الدفع، يتلقّى معلومات المعاملة التي تم تمريرها إلى العنصر PaymentRequest في الخطوة 1، والتي تتضمّن ما يلي:

  • بيانات طريقة الدفع
  • السعر الإجمالي
  • خيارات الدفع

يستخدم تطبيق الدفع معلومات المعاملة لتصنيف واجهة المستخدم الخاصة به.

الخطوة 5: كيف يمكن للتاجر تعديل تفاصيل المعاملة استنادًا إلى إجراءات العميل؟

يتوفّر للعملاء خيار تغيير تفاصيل المعاملة، مثل طريقة الدفع وخيار الشحن، في تطبيق الدفع. وعندما يُجري العميل تغييرات، يتلقّى التاجر أحداث التغيير ويعدّل تفاصيل المعاملة.

هناك أربعة أنواع من الأحداث التي يمكن للتاجر تلقّيها:

  • حدث تغيير طريقة الدفع
  • حدث تغيير عنوان الشحن
  • حدث تغيير خيار الشحن
  • حدث التحقّق من التاجر

حدث تغيير طريقة الدفع

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

request.addEventListener('paymentmethodchange', e => {
  e.updateWith({
    // Add discount etc.
  });
});

حدث تغيير عنوان الشحن

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

إذا عدّل العميل عنوان الشحن في تطبيق للدفع بعد بدء المعاملة، سيتم إرسال حدث 'shippingaddresschange' إلى التاجر. يساعد هذا الحدث التاجر في تحديد تكلفة الشحن استنادًا إلى العنوان الجديد، وتعديل السعر الإجمالي، وإرساله إلى تطبيق الدفع.

request.addEventListener('shippingaddresschange', e => {
  e.updateWith({
    // Update the details
  });
});

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

حدث تغيير خيار الشحن

يمكن للتاجر تقديم خيارات شحن متعدّدة للعميل ويمكنه تفويض هذا الخيار إلى تطبيق الدفع. يتم عرض خيارات الشحن كقائمة بالأسعار وأسماء الخدمات التي يمكن للعميل الاختيار من بينها. على سبيل المثال:

  • الشحن العادي: مجاني
  • شحن سريع: 5 دولار أمريكي

عندما يعدّل العميل خيار الشحن في تطبيق للدفع، سيتم إرسال حدث 'shippingoptionchange' إلى التاجر. ويمكن للتاجر بعد ذلك تحديد تكلفة الشحن وتعديل السعر الإجمالي وإرساله إلى تطبيق الدفع.

request.addEventListener('shippingoptionchange', e => {
  e.updateWith({
    // Update the details
  });
});

ويمكن للتاجر تعديل خيارات الشحن ديناميكيًا استنادًا إلى عنوان الشحن الخاص بالعميل أيضًا. ويكون ذلك مفيدًا عندما يريد التاجر تقديم مجموعات مختلفة من خيارات الشحن للعملاء المحليين والدوليين.

حدث التحقّق من التاجر

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

request.addEventListener('merchantvalidation', e => {
  e.updateWith({
    // Use `e.validateURL` to validate
  });
});

الخطوة 6: يتحقّق التاجر من صحة الدفعة ويكمل المعاملة

عندما يفوّض العميل الدفعة بنجاح، تعرض طريقة show() وعدًا يتم حله إلى PaymentResponse. يتضمّن الكائن PaymentResponse المعلومات التالية:

  • تفاصيل نتيجة الدفع
  • عنوان الشحن
  • خيار الشحن
  • معلومات الاتصال

في هذه المرحلة، قد تستمر واجهة مستخدم المتصفّح في عرض مؤشر تحميل، ما يعني أنّ المعاملة لم تكتمل بعد.

إذا تم إنهاء تطبيق الدفع بسبب تعذُّر الدفع أو حدوث خطأ، يتم رفض الوعد الذي تم إرجاعه من show()، وينهي المتصفّح معاملة الدفع.

معالجة الدفعة والتحقّق منها

‫details في PaymentResponse هو عنصر بيانات اعتماد الدفع الذي يتم عرضه من تطبيق الدفع. ويمكن للتاجر استخدام بيانات الاعتماد لمعالجة الدفعة أو التحقّق من صحتها. وتعتمد طريقة عمل هذه العملية المهمة على معالج الدفع.

إكمال المعاملة أو إعادة محاولة إجرائها

بعد أن يحدّد التاجر ما إذا كانت المعاملة ناجحة أو غير ناجحة، يمكنه تنفيذ أحد الإجراءَين التاليَين:

  • استدعِ الطريقة .complete() لإكمال المعاملة وإغلاق مؤشر التحميل.
  • اسمح للعميل بإعادة المحاولة من خلال استدعاء طريقة retry().
async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}

async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong…
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

الخطوات التالية