טיפול בפרטי תשלום אופציונליים עם קובץ שירות (service worker)

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

Eiji Kitamura

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

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

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

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

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

באמצעות ה-Payment Handler API, אפליקציית התשלומים יכולה לשלוח 'שינוי אמצעי תשלום' אירוע למוכר דרך קובץ שירות (service worker) כדי להודיע על אמצעי התשלום החדש למזהה נתון. על קובץ השירות (service worker) להפעיל PaymentRequestEvent.changePaymentMethod() עם אמצעי התשלום החדש מידע.

אפליקציות תשלום יכולות להעביר אובייקט methodDetails כארגומנט השני האופציונלי עבור PaymentRequestEvent.changePaymentMethod(). האובייקט הזה יכול להכיל פרטים שרירותיים של אמצעי תשלום שנדרשים למוכר כדי לעבד את השינוי אירוע.

[מטפל בתשלומים] 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 מהתשלום בקשת API, יכולים לעדכן את פרטי התשלום ולהשיב עם PaymentDetailsUpdate לאובייקט.

[מוכר]

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 לאובייקט.

[מטפל בתשלומים] 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;
…

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

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

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

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

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

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

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

באמצעות Payment Handler API, אפליקציית התשלומים יכולה לשלוח 'כתובת למשלוח' שינוי" אירוע מ-Service Worker למוכר כדי להודיע על המשלוח החדש address. על קובץ השירות (service worker) להפעיל PaymentRequestEvent.changeShippingAddress() עם הכתובת החדשה לאובייקט.

[מטפל בתשלומים] 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);
      …

המוכר יקבל אירוע shippingaddresschange מהתשלום צריך לבקש מ-API אפשרות להשיב עם הגרסה המעודכנת של PaymentDetailsUpdate.

[מוכר]

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);
});

כשהמוכר משיב, ההבטחה PaymentRequestEvent.changeShippingAddress() תוחזר לפונקציה PaymentRequestDetailsUpdate לאובייקט.

[מטפל בתשלומים] 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

[מוכר]

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 למוכר. על קובץ השירות להפעיל PaymentRequestEvent.changeShippingOption() עם המזהה החדש של אפשרות המשלוח.

[מטפל בתשלומים] 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 מהתשלום בקשת API. המוכר צריך להשתמש במידע כדי לעדכן את המחיר הכולל. ואז להשיב עם PaymentDetailsUpdate

[מוכר]

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 לאובייקט.

[מטפל בתשלומים] 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 לאובייקט. רכיב ה-handler של התשלומים יכול להשתמש בתוצאה כדי לשקף את המחיר הכולל המעודכן ואפשרויות משלוח אחרות לממשק המשתמש.

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

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

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

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

קוד לדוגמה

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

https://paymenthandler-demo.glitch.me

[מטפל בתשלומים] קובץ שירות (service worker)

[מטפל בתשלומים] חזית

כדי לנסות את הכלים:

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