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

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

Eiji Kitamura

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

טיפול בפרטי תשלום אופציונליים באמצעות שירות עבודה
טיפול בפרטי תשלום אופציונליים באמצעות שירות עובד

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

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

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

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

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

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

באמצעות Payment Handler API, אפליקציית התשלומים יכולה לשלוח אירוע 'שינוי של אמצעי תשלום' למוכר באמצעות שירות עובד (service worker) כדי להודיע על המזהה החדש של אמצעי התשלום. שירות ה-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;
…

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

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

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

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

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

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

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

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

באמצעות 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);
      …

המוכר יקבל אירוע 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);
});

כשהמוכר יגיב, ההבטחה 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 });
});

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

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

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

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

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

קוד לדוגמה

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

https://paymenthandler-demo.glitch.me

[payment handler] service worker

[payment handler] frontend

כדי לנסות:

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