مدة معاملة الدفع

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

Eiji Kitamura
Milica Mihajlija

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

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

ترشدك هذه المقالة خلال معاملة دفع على موقع إلكتروني للتاجر، وhelps you understand how payment app integration works.

تتضمّن العملية 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: يعرض التاجر زرّ دفع

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

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

هل يملك العميل تطبيق الدفع؟

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

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() لإكمال المعاملة وإغلاق إشارة loading (التحميل).
  • يُرجى السماح للعميل بإعادة المحاولة من خلال استدعاء الطريقة 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();

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