التعامل مع معلومات الدفع الاختيارية باستخدام عامل خدمة

كيفية تكييف تطبيق الدفع المستند إلى الويب مع Web Payments وتقديم تجربة مستخدم أفضل للعملاء

Eiji Kitamura

تنبيه: تمت إزالة ميزة الشحن والعنوان في Payment Request API من المواصفات ومن Chrome. تم التراجع عن هذا التغيير في المواصفات، وبالتالي تراجعنا أيضًا عن التغييرات التي أجريناها على المستندات المتعلقة بالشحن والعنوان.

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

التعامل مع معلومات الدفع الاختيارية باستخدام مشغّل الخدمات

إعلام التاجر

من المهم إبلاغ التاجر بالتغييرات التالية.

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

يمكن أن تتيح تطبيقات الدفع استخدام وسائل دفع متعددة بطرق دفع مختلفة.

العميل	طريقة الدفع	وسيلة الدفع
A	جهة إصدار بطاقة الائتمان 1	****1234
	جهة إصدار بطاقة الائتمان 1	****4242
	المصرف X	******123
B	جهة إصدار بطاقة الائتمان 2	****5678
	المصرف X	******456

على سبيل المثال، في الجدول أعلاه، تحتوي محفظة العميل "أ" المستندة إلى الويب على بطاقتَي ائتمان وحساب مصرفي واحد مسجَّل. في هذه الحالة، يتعامل التطبيق مع ثلاث وسائل دفع (****1234 و****4242 و******123) وطريقتَي دفع (جهة إصدار بطاقة الائتمان 1 والمصرف X). في معاملة الدفع، يمكن لتطبيق الدفع أن يتيح للعميل اختيار إحدى وسائل الدفع واستخدامها للدفع للتاجر.

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

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

باستخدام Web-based Payment Handler API، يمكن لتطبيق الدفع إرسال حدث "تغيير طريقة الدفع" إلى التاجر من خلال مشغّل خدمات لإعلامه بمعرّف طريقة الدفع الجديدة. يجب أن يستدعي مشغّل الخدمات PaymentRequestEvent.changePaymentMethod() مع معلومات طريقة الدفع الجديدة.

إبلاغ التاجر بتغيير طريقة الدفع

يمكن لتطبيقات الدفع تمرير عنصر methodDetails كوسيطة ثانية اختيارية لـ PaymentRequestEvent.changePaymentMethod(). يمكن أن يحتوي هذا العنصر على تفاصيل عشوائية لطريقة الدفع المطلوبة من التاجر لمعالجة حدث التغيير.

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

[payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'PAYMENT_METHOD_CHANGED':
        const newMethod = e.data.paymentMethod;
        const newDetails = e.data.methodDetails;
        // Redact or check that no sensitive information is passed in
        // `newDetails`.
        // Notify the merchant of the payment method change
        details =
          await payment_request_event.changePaymentMethod(newMethod, newDetails);
      …

عندما يتلقّى التاجر حدث paymentmethodchange من Payment Request API، يمكنه تعديل تفاصيل الدفع والردّ باستخدام عنصر PaymentDetailsUpdate.

[merchant]

request.addEventListener('paymentmethodchange', e => {
  if (e.methodName === 'another-pay') {
    // Apply $10 discount for example.
    const discount = {
      label: 'special discount',
      amount: {
        currency: 'USD',
        // The value being string complies the spec
        value: '-10.00'
      }
    };
    let total = 0;
    details.displayItems.push(discount);
    for (let item of details.displayItems) {
     total += parseFloat(item.amount.value);
    }
    // Convert the number back to string
    details.total.amount.value = total.toString();
  }
  // Pass a promise to `updateWith()` and send updated payment details
  e.updateWith(details);
});

عندما يردّ التاجر، سيتم حلّ الوعد الذي يعرضه PaymentRequestEvent.changePaymentMethod() باستخدام عنصر PaymentRequestDetailsUpdate.

[payment handler] service-worker.js

…
        // Notify the merchant of the payment method change
        details = await payment_request_event.changePaymentMethod(newMethod, newDetails);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

استخدِم الكائن لتعديل واجهة المستخدم في الواجهة الأمامية. يُرجى الاطّلاع على تعديل تفاصيل الدفع.

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

يمكن أن توفّر تطبيقات الدفع عنوان الشحن الخاص بالعميل للتاجر كجزء من معاملة الدفع.

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

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

واجهة مستخدم أداة اختيار عنوان الشحن

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

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

باستخدام Payment Handler API المستنِد إلى الويب، يمكن لتطبيق الدفع إرسال حدث "تغيير عنوان الشحن" إلى التاجر من مشغّل الخدمات لإعلامه بعنوان الشحن الجديد. يجب أن يستدعي مشغّل الخدمات PaymentRequestEvent.changeShippingAddress() باستخدام عنصر العنوان الجديد.

إعلام التاجر بتغيير عنوان الشحن

[payment handler] service-worker.js

...
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_ADDRESS_CHANGED':
        const newAddress = e.data.shippingAddress;
        details =
          await payment_request_event.changeShippingAddress(newAddress);
      …

العبارة الرئيسية: عنوان تم إخفاؤه في هذه الحالة، ليس من الضروري إبلاغ التاجر بعنوان الشحن الكامل، لأنّ ذلك قد يعرّض خصوصية العملاء للخطر. يتلقّى التاجر فقط أجزاء العنوان التي يحتاج إليها لتحديد تكلفة الشحن. على وجه التحديد، سيمحو المتصفّح الحقول organization وphone وrecipient وaddressLine من العنوان الذي يوفّره تطبيق الدفع قبل رفع الحدث shippingaddresschange في نموذج DOM الخاص بالتاجر.

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

[merchant]

request.addEventListener('shippingaddresschange', e => {
  // Read the updated shipping address and update the request.
  const addr = request.shippingAddress;
  const details = getPaymentDetailsFromShippingAddress(addr);
  // `updateWith()` sends back updated payment details
  e.updateWith(details);
});

عندما يردّ التاجر، سيتم حلّ الوعد PaymentRequestEvent.changeShippingAddress() الذي تم عرضه باستخدام عنصر PaymentRequestDetailsUpdate.

[payment handler] service-worker.js

…
        // Notify the merchant of the shipping address change
        details = await payment_request_event.changeShippingAddress(newAddress);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

استخدِم الكائن لتعديل واجهة المستخدم في الواجهة الأمامية. يُرجى الاطّلاع على تعديل تفاصيل الدفع.

إعلام التاجر بتغيير خيار الشحن

خيارات الشحن هي طرق التسليم التي يستخدمها التجّار لشحن السلع التي تم شراؤها إلى العميل. تشمل خيارات الشحن المعتادة ما يلي:

• شحن مجاني
• الشحن السريع
• الشحن الدولي
• شحن دولي مميّز

ولكل منها تكلفته الخاصة. عادةً ما تكون الطرق والخيارات الأسرع أكثر تكلفة.

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

واجهة مستخدم أداة اختيار خيارات الشحن

يتم نشر قائمة خيارات الشحن المحدّدة في واجهة برمجة التطبيقات Payment Request API الخاصة بالتاجر إلى مشغّل الخدمات في تطبيق الدفع كسمة من سمات PaymentRequestEvent.

[merchant]

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: { transactionId: '****' }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  shippingOptions: [{
    id: 'standard',
    label: 'Standard',
    amount: { value: '0.00', currency: 'USD' },
    selected: true
  }, {
    id: 'express',
    label: 'Express',
    amount: { value: '5.00', currency: 'USD' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {  requestShipping: true });

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

باستخدام Payment Handler API، يمكن لتطبيق الدفع إرسال حدث "تغيير خيار الشحن" إلى التاجر من مشغّل الخدمات. يجب أن يستدعي مشغّل الخدمات PaymentRequestEvent.changeShippingOption() باستخدام معرّف خيار الشحن الجديد.

إعلام التاجر بتغيير خيار الشحن

[payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_OPTION_CHANGED':
        const newOption = e.data.shippingOptionId;
        details =
          await payment_request_event.changeShippingOption(newOption);
      …

سيتلقّى التاجر حدث shippingoptionchange من Payment Request API. على التاجر استخدام المعلومات لتعديل السعر الإجمالي ثم الردّ باستخدام PaymentDetailsUpdate المعدَّل.

[merchant]

request.addEventListener('shippingoptionchange', e => {
  // selected shipping option
  const shippingOption = request.shippingOption;
  const newTotal = {
    currency: 'USD',
    label: 'Total due',
    value: calculateNewTotal(shippingOption),
  };
  // `updateWith()` sends back updated payment details
  e.updateWith({ total: newTotal });
});

عندما يردّ التاجر، سيتم حلّ الوعد الذي يعرضه PaymentRequestEvent.changeShippingOption() باستخدام عنصر PaymentRequestDetailsUpdate.

[payment handler] service-worker.js

…
        // Notify the merchant of the shipping option change
        details = await payment_request_event.changeShippingOption(newOption);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

استخدِم الكائن لتعديل واجهة المستخدم في الواجهة الأمامية. يُرجى الاطّلاع على تعديل تفاصيل الدفع.

عرض تفاصيل الدفع المعدَّلة

بعد أن ينتهي التاجر من تعديل تفاصيل الدفع، سيتم حلّ الوعود التي تم إرجاعها من .changePaymentMethod() و.changeShippingAddress() و.changeShippingOption() باستخدام عنصر PaymentRequestDetailsUpdate شائع. يمكن لمعالِج الدفع استخدام النتيجة لعرض السعر الإجمالي المعدَّل وخيارات الشحن في واجهة المستخدم.

ملاحظة: يتم تمرير العنصر PaymentRequestDetailsUpdate من التاجر، ويحتوي على المعلومات الدقيقة التي وضعها التاجر في العنصر PaymentDetailsUpdate باستخدام Payment Request API. لضمان أن يقدّم لك التجّار المعلومات التي تتوقّعها، يمكنك توفير مستندات مطوّرين جيدة أو مكتبة JavaScript للتحكّم في المعلومات، أو كليهما.

قد يعرض التجّار أخطاءً لعدة أسباب:

• طريقة الدفع غير مقبولة.
• عنوان الشحن خارج المناطق المعتمدة.
• يحتوي عنوان الشحن على معلومات غير صالحة.
• لا يمكن تحديد خيار الشحن لعنوان الشحن المقدَّم أو لسبب آخر.

استخدِم السمات التالية لعرض حالة الخطأ:

• ‫error: سلسلة خطأ يمكن لشخص عادي قراءتها هذه هي أفضل سلسلة لعرضها للعملاء.
• shippingAddressErrors: AddressErrors عنصر يحتوي على سلسلة خطأ مفصّلة لكل سمة عنوان ويكون ذلك مفيدًا إذا أردت فتح نموذج يتيح للعميل تعديل عنوانه وكنت بحاجة إلى توجيهه مباشرةً إلى الحقول غير الصالحة.
• ‫paymentMethodErrors: عنصر خطأ خاص بطريقة الدفع يمكنك أن تطلب من التجّار تقديم خطأ منظَّم، ولكن مؤلفي مواصفات Web Payments ينصحون بإبقائه سلسلة بسيطة.