التغييرات في واجهة برمجة التطبيقات لطلب الدفع

Eiji Kitamura

Chrome 62

أصبح العنصر PaymentDetailsModifier متاحًا الآن

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

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

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

let methods = [{
 supportedMethods: 'basic-card',
 data: {
   supportedNetworks: ['visa', 'mastercard']
   supportedTypes: ['credit', 'debit']
 }
}];

let details = {
 displayItems: [{
   label: 'T-shirt',
   amount: { currency: 'USD', value: '68.00' }
 }],
 total: {
   label: 'Total price',
   amount: { currency: 'USD', value: '68.00' }
 },
 modifiers: [{
   supportedMethods: 'basic-card',
   data: {
     supportedTypes: ['credit']
   },
   additionalDisplayItems: [{
     label: 'Processing fee',
     amount: { currency: 'USD', value: '3.00' }
   }],
   total: {
     label: 'Credit card price',
     amount: {currency: ‘USD’, value: ‘71.00’}}
 }]
};

let options = {};

let request = new PaymentRequest(methods, details, options);

في ورقة طلب الدفع الفعلية، بعد اختيار طريقة الدفع ببطاقة الائتمان، سيظهر للمستخدم عنصر عرض إضافي يُسمى "رسوم المعالجة" مع تحصيل رسوم بقيمة 3 دولار أمريكي، بالإضافة إلى السعر الإجمالي الذي يبلغ 71.00 دولار أمريكي.

يحتوي PaymentDetailsModifier على المَعلمات التالية:

اسم الموقع
supportedMethods	حدِّد طريقة الدفع التي تطبّق هذه القاعدة.
additionalDisplayItems	عناصر العرض الإضافية التي تريد إضافة خصومات أو رسوم إضافية إليها
total	السعر الإجمالي بعد إضافة عناصر العرض الإضافية
data	بالنسبة إلى الدفع باستخدام basic-card، سيتم استخدام هذا الإجراء لفلترة أنواع بطاقات معيّنة باستخدام supportedTypes. بخلاف ذلك، يعتمد استخدام هذه المَعلمة على طريقة الدفع (تطبيق الدفع). يُرجى الرجوع إلى المستندات التي تقدّمها كل طريقة دفع.

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

لتحقيق ذلك، عليك تعديل additionalDisplayItems وtotal في موقع modifiers عند وقوع حدثَي shippingaddresschange وshippingoptionchange، تمامًا كما تُعدّل displayItems في كائن PaymentDetails.

تستقبل السمة supportedMethods الآن سلسلة.

كانت سمة supportedMethods في عنصر PaymentMethodData (الوسيطة الأولى لصانع PaymentRequest) تأخذ صفيفًا من السلاسل التي تشير إلى طريقة دفع. يتم الآن استخدام سلسلة واحدة كوسيطة.

يُرجى العلم أنّ تقديم صفيف سيظلّ يعمل في الوقت الحالي.

الإجراءات غير المُوصى بها

قديم - لا يزال يعمل في الوقت الحالي

var methodData = [{
     supportedMethods: ['basic-card'],
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay']
     }
}, {
    supportedMethods: ['https://bobpay.xyz']
}];

الإجراءات الموصى بها

ميزة "الإصدار الجديد":

var methodData = [{
     supportedMethods: 'basic-card',
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay']
     }
}, {
    supportedMethods: 'https://bobpay.xyz'
}];

Chrome 61

توفُّر supportedTypes في البطاقة الأساسية

عندما تكون قيمة supportedMethods هي "basic-card"، يمكنك الآن تقديم supportedTypes للإشارة إلى نوع البطاقات المتوافقة من بين credit وdebit وprepaid.

var methodData = [{
 supportedMethods: 'basic-card',
 data: {
   supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
     'diners', 'discover', 'mir', 'unionpay']
   supportedTypes: ['credit', 'debit', 'prepaid']
 }
}];

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

Chrome 57

يتوفّر PaymentRequest الآن داخل إطارات iframe.

يمكن الآن استدعاء Payment Request API من داخل iframe عن طريق إضافة سمة allowpaymentrequest إلى عنصر iframe.

<iframe src="/totally/fake/url" allowpaymentrequest></iframe>

تتيح PaymentMethodData استخدام "basic-card"

الوسيطة الأولى لإنشاء PaymentRequest() هي صفيف لبيانات payment method. تم تغيير تنسيق PaymentMethodData في هذا الإصدار.

الإجراءات غير المُوصى بها

قديم - لا يزال يعمل في الوقت الحالي

var methodData = [{
     supportedMethods: ['visa', 'mastercard', 'amex', 'jcb']
}];
var request = new PaymentRequest(methodData, details, options);

الإجراءات الموصى بها

جديد: الهيكل الجديد.

var methodData = [{
     supportedMethods: ['basic-card'],
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay']
     }
}];
var request = new PaymentRequest(methodData, details, options);

يعتمد تنسيق السمة data على القيمة في supportedMethods ويستند إلى مواصفات البطاقة الأساسية. يُرجى العلم أنّ المواصفات تتضمّن supportedTypes التي تقبل credit أو debit أو prepaid، ولكن الإصدار 57 من Chrome يتجاهل هذه السمة ويتعامل مع أي قيم في supoprtedNetworks على أنّها بطاقات ائتمانات.

var methodData = [{
     supportedMethods: ['basic-card'],
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay'],
       supportedTypes: ['credit'] <= not available
     }
}];

Chrome 56

في انتظار المراجعة

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

    {
      label: "State tax",
      amount: { currency: "USD", value : "5.00" },
      pending: true
    },

ويُستخدَم هذا الإجراء عادةً لعرض عناصر مثل مبالغ الشحن أو الضرائب التي تعتمد على اختيار عنوان الشحن أو خيارات الشحن. يشير Chrome إلى الحقول التي لم تكتمل في واجهة مستخدم طلب الدفع.

requestPayerName

كجزء من خيار الشحن (الوسيطة الثالثة لسمة PaymentRequest)، يمكن للمطوّرين الآن إضافة requestPayerName لطلب اسم المسؤول عن الدفع بشكل منفصل عن معلومات عنوان الشحن. requestPayerName يقبل قيمة منطقية.

shippingType

كجزء من خيار الشحن (الوسيطة الثالثة لـ PaymentRequest)، يمكن للمطوّرين الآن إضافة shippingType لطلب عرض واجهة المستخدم "التسليم" أو "استلام" بدلاً من "الشحن". تقبل shippingType السلاسل shipping (الإعداد التلقائي) أو delivery أو pickup.

shippingType="delivery"

shippingType="pickup"

وظائف تحويل البيانات إلى سلسلة متوفرة لكل من PaymentResponse وPaymentAddress

يمكن الآن تسلسل كائن PaymentResponse وكائن PaymentAddress باستخدام تنسيق JSON. يمكن للمطوّرين تحويل أحدهما إلى عنصر JSON من خلال استدعاء دالة toJSON() وتجنُّب إنشاء دالات toDict() مُربكة.

request.show().then(response => {
     let res = response.toJSON();
});

canMakePayment

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

let request = new PaymentRequest(methods, details, options);
if (request.canMakePayment) {
     request.canMakePayment().then(result => {
       if (result) {
         // Payment methods are available.
       } else {
         // Payment methods are not available, but users can still add
        // a new payment method in Payment UI.
       }
     }).catch(error => {
       // Unable to determine.
     });
}