איך מטפלים בפרטי תשלום אופציונליים באמצעות Service Worker

איך להתאים את אפליקציית התשלומים מבוססת-האינטרנט שלכם ל-Web Payments ולספק חוויית משתמש טובה יותר ללקוחות.

Eiji Kitamura

זהירות: התמיכה במשלוח ובכתובת ב-Payment Request API הוסרה בעבר מהמפרט ומ-Chrome. השינוי הזה בוטל במפרט. לכן, ביטלנו גם את התיעוד לגבי משלוח וכתובת.

אחרי שאפליקציית תשלומים מבוססת-אינטרנט מקבלת בקשת תשלום ומתחילה עסקה, ה-Service Worker משמש כמרכז התקשורת בין המוכר לבין אפליקציית התשלומים. בפוסט הזה נסביר איך אפליקציית תשלומים יכולה להעביר למוכר מידע על אמצעי התשלום, הכתובת למשלוח או הפרטים ליצירת קשר באמצעות Service Worker.

טיפול בפרטי תשלום אופציונליים באמצעות Service Worker

הודעה למוכר

חשוב ליידע את המוכר על השינויים הבאים.

שינוי אמצעי התשלום

אפליקציות תשלומים יכולות לתמוך בכמה אמצעי תשלום שונים.

לקוח	אמצעי תשלום	אמצעי תשלום
A	מנפיק כרטיס אשראי 1	****1234
	מנפיק כרטיס אשראי 1	****4242
	בנק X	******123
B	מנפיק כרטיס אשראי 2	****5678
	בנק X	******456

לדוגמה, בטבלה שלמעלה, בארנק מבוסס-האינטרנט של לקוח א' רשומים שני כרטיסי אשראי וחשבון בנק אחד. במקרה הזה, האפליקציה מטפלת בשלושה אמצעי תשלום (****1234,‏ ****4242,‏ ******123) ובשתי שיטות תשלום (מנפיק כרטיס אשראי 1 ובנק X). בעסקת תשלום, אפליקציית התשלומים יכולה לאפשר ללקוח לבחור אחד מאמצעי התשלום ולהשתמש בו כדי לשלם למוכר.

ממשק המשתמש לבחירת אמצעי תשלום

אפליקציית התשלומים יכולה להודיע למוכר באיזה אמצעי תשלום הלקוח בחר לפני שליחת התגובה המלאה לתשלום. האפשרות הזו שימושית, למשל, כשהמוכר רוצה להפעיל קמפיין הנחות למותג ספציפי של אמצעי תשלום.

באמצעות Web-based Payment Handler API, אפליקציית התשלומים יכולה לשלוח אירוע "שינוי אמצעי תשלום" למוכר דרך Service Worker כדי להודיע על המזהה החדש של אמצעי התשלום. ה-service worker צריך להפעיל את 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);
});

כשהמוכר מגיב, ההבטחה (promise) שמוחזרת על ידי 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;
…

משתמשים באובייקט כדי לעדכן את ממשק המשתמש בקצה הקדמי. איך מעדכנים את פרטי התשלום?

שינוי הכתובת למשלוח

אפליקציות תשלומים יכולות לספק למוכר את הכתובת למשלוח של הלקוח כחלק מעסקת תשלום.

האפשרות הזו שימושית למוכרים כי הם יכולים להאציל את איסוף הכתובות לאפליקציות תשלומים. בנוסף, מכיוון שנתוני הכתובת יסופקו בפורמט הנתונים הרגיל, המוכר יכול לצפות לקבל כתובות למשלוח במבנה עקבי.

בנוסף, הלקוחות יכולים לרשום את פרטי הכתובת שלהם באפליקציית התשלומים המועדפת עליהם ולהשתמש בהם שוב אצל מוכרים שונים.

ממשק המשתמש של הכלי לבחירת כתובת למשלוח

אפליקציות תשלומים יכולות לספק ממשק משתמש לעריכת כתובת למשלוח או לבחירת פרטי כתובת שנרשמו מראש עבור הלקוח בעסקת תשלום. כשהכתובת למשלוח נקבעת באופן זמני, אפליקציית התשלומים יכולה להודיע למוכר על פרטי הכתובת המצונזרים. היתרונות של התכונה הזו למוכרים:

• המוכר יכול לקבוע אם הלקוח עומד בהגבלה האזורית למשלוח הפריט (לדוגמה, משלוח מקומי בלבד).
• המוכר יכול לשנות את רשימת אפשרויות המשלוח בהתאם לאזור של הכתובת למשלוח (לדוגמה, משלוח רגיל או אקספרס בינלאומי).
• המוכר יכול להחיל את עלות המשלוח החדשה על סמך הכתובת ולעדכן את המחיר הכולל.

באמצעות Web-based Payment Handler API, אפליקציית התשלומים יכולה לשלוח אירוע של "שינוי כתובת למשלוח" למוכר מ-Service Worker כדי להודיע על הכתובת החדשה למשלוח. ה-service worker צריך להפעיל את 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);
});

כשהמוכר מגיב, ה-promise 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 של המוכר מועברת ל-Service Worker של אפליקציית התשלומים כמאפיין של 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, אפליקציית התשלומים יכולה לשלוח אירוע של "שינוי אפשרות המשלוח" למוכר מ-Service Worker. ה-service worker צריך להפעיל את 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 });
});

כשהמוכר מגיב, ההבטחה (promise) שמוחזרת על ידי 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 נפוץ. ה-payment handler יכול להשתמש בתוצאה כדי להציג בממשק המשתמש את המחיר הכולל המעודכן ואת אפשרויות המשלוח המעודכנות.

הערה: האובייקט PaymentRequestDetailsUpdate מועבר מהמוכר, והוא מכיל את המידע המדויק שהמוכר הזין באובייקט PaymentDetailsUpdate באמצעות Payment Request API. כדי לוודא שהמוכרים מספקים לכם את המידע שאתם מצפים לקבל, אתם צריכים לספק תיעוד טוב למפתחים או ספריית JavaScript לשליטה במידע, או את שניהם.

יכולות להיות כמה סיבות לשגיאות שמוחזרות מהמוכרים:

• אמצעי התשלום לא קביל.
• הכתובת למשלוח נמצאת מחוץ לאזורים הנתמכים שלהם.
• הכתובת למשלוח מכילה מידע לא תקין.
• אי אפשר לבחור את אפשרות המשלוח בגלל הכתובת למשלוח שצוינה או מסיבה אחרת.

אפשר להשתמש במאפיינים הבאים כדי לשקף את סטטוס השגיאה:

• ‫error: מחרוזת שגיאה קריאה לאנשים. זו המחרוזת הכי טובה להצגה ללקוחות.
• ‫shippingAddressErrors: אובייקט מסוג AddressErrors שמכיל מחרוזת שגיאה מפורטת לכל מאפיין של כתובת. האפשרות הזו שימושית אם רוצים לפתוח טופס שמאפשר ללקוח לערוך את הכתובת שלו, וצריך להפנות אותו ישירות לשדות הלא חוקיים.
• ‫paymentMethodErrors: אובייקט שגיאה ספציפי לאמצעי התשלום. אתם יכולים לבקש מהמוכרים לספק שגיאה מובנית, אבל מחברי המפרט של Web Payments ממליצים להשאיר אותה כמחרוזת פשוטה.