تعرَّف على كيفية دمج التجّار لتطبيقات الدفع وطريقة عمل معاملات الدفع باستخدام واجهة برمجة التطبيقات Payment Request API.
واجهات برمجة التطبيقات Web Payments API هي ميزات دفع مخصّصة تم دمجها في المتصفّح للمرة الأولى. باستخدام Web Payments، يصبح دمج التاجر مع تطبيقات الدفع أكثر بساطة، بينما تصبح تجربة العميل أكثر سلاسة وأمانًا.
للاطّلاع على مزيد من المعلومات عن مزايا استخدام Web Payments، اطّلِع على تفعيل تطبيقات الدفع باستخدام Web Payments.
ترشدك هذه المقالة خلال معاملة دفع على موقع إلكتروني للتاجر، وhelps you understand how payment app integration works.
تتضمن هذه العملية 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
، يمكن للتاجر الاستعلام عمّا إذا كان العميل لديه
تطبيق الدفع متاحًا.
هل يملك العميل تطبيق الدفع؟
تُعرِض 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();
الخطوات التالية
- تعرَّف على كيفية الإفصاح عن معرّف طريقة الدفع بالتفصيل في مقالة إعداد طريقة دفع.
- اطّلِع على دليل مطوّري تطبيقات الدفع على Android للتعرّف على كيفية إنشاء تطبيق دفع خاص بمنصّة معيّنة.
- تعرَّف على كيفية إنشاء تطبيق دفع مستند إلى الويب في guía para desarrolladores de aplicaciones de pago basadas en web.