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

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

Eiji Kitamura

Milica Mihajlija

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

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

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

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

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

3. يضغط العميل على زر الدفع.

   

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

   

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

   

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'
});

بعد تقديم معلومات المعاملة، يُجري المتصفّح عملية اكتشاف لتطبيقات الدفع المحدّدة في 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 للتعرّف على كيفية إنشاء تطبيق دفع خاص بمنصّة معيّنة.
• تعرَّف على كيفية إنشاء تطبيق دفع مستنِد إلى الويب في دليل مطوّري تطبيقات الدفع المستندة إلى الويب.