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

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

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

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

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

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

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

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

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

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

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

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

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

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

[payment معالج] service- employee.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.

[التاجر]

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 معالج] service- employee.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 معالج] service- employee.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 المعدّلة.

[التاجر]

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 معالج] service- employee.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.

[التاجر]

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 معالج] service- employee.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 المعدَّلة.

[التاجر]

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 معالج] service- employee.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 بإبقاءها سلسلة بسيطة.

نموذج التعليمات البرمجية

كانت معظم نماذج الرموز التي رأيتها في هذا المستند مقتطفات من نموذج التطبيق العامل التالي:

https://paymenthandler-demo.glitch.me

[payment معالج] مشغّل خدمات

[payment handling] الواجهة الأمامية

لتجربتها:

انتقِل إلى https://paymentrequest-demo.glitch.me/.
انتقل إلى أسفل الصفحة.
اضغط على إضافة زر دفع.
أدخِل https://paymenthandler-demo.glitch.me في الحقل معرّف طريقة الدفع.
اضغط على الزر دفع بجانب الحقل.