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

Eiji Kitamura

الإصدار 62 من Chrome

خدمة 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']
 }
}];

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

الإصدار 57 من Chrome

يتوفّر 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، إلا أنّ Chrome 57 يتجاهل هذه السمة ويتعامل مع أي قيم في 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

يمكن الآن تسلسل JSON للكائن PaymentResponse والكائن PaymentAddress. يمكن للمطوّرين تحويل إحداها إلى كائن 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.
     });
}