تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

إيجي كيتامورا

ميليكا ميهاجليا

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

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

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

تتضمن العملية 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 في الخطوة الأولى، والتي تتضمّن ما يلي:

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

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

الخطوة 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();

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

اطّلِع على كيفية الإفصاح عن معرّف طريقة الدفع بالتفصيل في إعداد طريقة دفع.
تعرَّف على كيفية إنشاء تطبيق دفع خاص بنظام التشغيل الأساسي في دليل مطوِّري تطبيقات الدفع لتطبيقات Android.
تعرَّف على كيفية إنشاء تطبيق دفع مستند إلى الويب في دليل مطوِّري تطبيقات الدفع المستندة إلى الويب.