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

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

Twitter GitHub تأثير اهتزاز Mastodon

الإصدار 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	السعر الإجمالي بعد إضافة DisplayItems الإضافية.
data	بالنسبة إلى basic-card الدفعات، سيتم استخدام هذه الطريقة لفلترة أنواع بطاقات معيّنة باستخدام supportedTypes. وبخلاف ذلك، يعتمد استخدام هذه المَعلمة على طريقة الدفع (تطبيق الدفع). يُرجى مراجعة المستندات التي توفّرها كل طريقة دفع.

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

لتنفيذ ذلك، عليك تعديل السمة additionalDisplayItems والسمة total في السمة modifiers عند الحدثَين shippingaddresschange وshippingoptionchange، تمامًا كما تفعل مع السمة displayItems في العنصر PaymentDetails.

تأخذ سمةedMethods الآن سلسلة

إنّ السمة 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'
}];

الإصدار 61 من Chrome

تتوفرsupportTypes في البطاقة الأساسية.

عندما تكون قيمة 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 استخدام "البطاقة الأساسية"

الوسيطة الأولى لأداة الإنشاء PaymentRequest() هي مصفوفة من بيانات طريقة الدفع. تم تغيير تنسيق 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

يمكن الآن تحويل الكائن 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.
     });
}