תודה שצפית ב-Google I/O! צפייה בתוכן על פי דרישה.

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

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

Eiji Kitamura

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

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

הודעה למוכר

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

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

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

לקוח	אמצעי תשלום	אמצעי תשלום
A	מנפיק כרטיס אשראי 1	`****1234`
	מנפיק כרטיס אשראי 1	`****4242`
	Bank X	`******123`
B	מנפיק כרטיס אשראי 2	`****5678`
B	Bank 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);
});

כשהמוֹכר מגיב, ההבטחה שהוחזרה 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, אפליקציית התשלום יכולה לשלוח אירוע מסוג shipping option change (שינוי אפשרות המשלוח) למוֹכר מ-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 });
});

כשהמוֹכר מגיב, ההבטחה שהוחזרה 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 יכול להשתמש בתוצאה כדי לשקף בממשק המשתמש את המחיר הכולל המעודכן ואת אפשרויות המשלוח.

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

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

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

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

קוד לדוגמה

רוב דוגמאות הקוד שראיתם במסמך הזה הן קטעים מתוך אפליקציה לדוגמה.

כדי לנסות:

עוברים לכתובת https://paymentrequest-demo.glitch.me/.
עבור לתחתית הדף.
לוחצים על הוספת לחצן תשלום.
מזינים https://paymenthandler-demo.glitch.me בשדה מזהה אמצעי התשלום.
לוחצים על הלחצן תשלום לצד השדה.

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

הודעה למוכר

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

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

הודעה למוֹכר על שינוי באפשרות המשלוח

לשקף את פרטי התשלום המעודכנים

קוד לדוגמה

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