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