การจัดการข้อมูลการชำระเงินที่ไม่บังคับด้วย Service Worker

วิธีปรับแอปการชำระเงินบนเว็บให้ใช้กับการชำระเงินผ่านเว็บได้และมอบประสบการณ์การใช้งานที่ดีขึ้นให้แก่ลูกค้า

Eiji Kitamura

คำเตือน: เราเคยนำการรองรับการจัดส่งและที่อยู่ใน Payment Request API ออกจากข้อกำหนดเฉพาะและจาก Chrome แต่ตอนนี้กำลังเปลี่ยนกลับในข้อกำหนดเฉพาะ ดังนั้นเราจึงเปลี่ยนกลับเอกสารประกอบเกี่ยวกับการจัดส่งและที่อยู่ด้วย

เมื่อแอปการชำระเงินบนเว็บได้รับคำขอการชำระเงินและเริ่มธุรกรรมการชำระเงิน Service Worker จะทำหน้าที่เป็นฮับสำหรับการสื่อสารระหว่างผู้ขายกับแอปการชำระเงิน โพสต์นี้จะอธิบายวิธีที่แอปการชำระเงินสามารถส่งข้อมูลเกี่ยวกับวิธีการชำระเงิน ที่อยู่สำหรับจัดส่ง หรือข้อมูลติดต่อไปยังผู้ขายโดยใช้ Service Worker

การจัดการข้อมูลการชำระเงินที่ไม่บังคับด้วย Service Worker

แจ้งผู้ขายเกี่ยวกับการเปลี่ยนแปลงวิธีการชำระเงิน

แอปการชำระเงินรองรับเครื่องมือการชำระเงินหลายรายการที่มีวิธีการชำระเงินต่างกัน

ลูกค้า	วิธีการชำระเงิน	เครื่องมือการชำระเงิน
A	ผู้ออกบัตรเครดิต 1	****1234
	ผู้ออกบัตรเครดิต 1	****4242
	ธนาคาร X	******123
B	ผู้ออกบัตรเครดิต 2	****5678
	ธนาคาร X	******456

ตัวอย่างเช่น ในตารางด้านบน กระเป๋าเงินบนเว็บของลูกค้า ก มีบัตรเครดิต 2 ใบและบัญชีธนาคาร 1 บัญชีที่ลงทะเบียนไว้ ในกรณีนี้ แอปจัดการเครื่องมือการชำระเงิน 3 อย่าง (****1234, ****4242, ******123) และวิธีการชำระเงิน 2 วิธี (ผู้ออกบัตรเครดิต 1 และธนาคาร X) ในธุรกรรมการชำระเงิน แอปการชำระเงินจะอนุญาตให้ลูกค้าเลือกเครื่องมือการชำระเงินรายการใดรายการหนึ่งและใช้เพื่อชำระเงินให้กับผู้ขายได้

UI เครื่องมือเลือกวิธีการชำระเงิน

แอปการชำระเงินช่วยให้ผู้ขายทราบว่าลูกค้าเลือกวิธีการชำระเงินใดก่อนที่จะส่งการตอบกลับการชำระเงินทั้งหมด ซึ่งจะเป็นประโยชน์เมื่อผู้ขายต้องการเรียกใช้แคมเปญส่วนลดสำหรับแบรนด์วิธีการชำระเงินที่เฉพาะเจาะจง เป็นต้น

เมื่อใช้ Payment Handler API แอปการชำระเงินสามารถส่งเหตุการณ์ "การเปลี่ยนแปลงวิธีการชำระเงิน" ไปยังผู้ขายผ่าน Service Worker เพื่อแจ้งตัวระบุวิธีการชำระเงินใหม่ Service Worker ควรเรียกใช้ PaymentRequestEvent.changePaymentMethod() ด้วยข้อมูลวิธีการชำระเงินใหม่

แจ้งผู้ขายเกี่ยวกับการเปลี่ยนแปลงวิธีการชำระเงิน

แอปการชำระเงินสามารถส่งออบเจ็กต์ methodDetails เป็นอาร์กิวเมนต์ที่ 2 ที่ไม่บังคับสำหรับ 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;
…

ใช้ออบเจ็กต์เพื่ออัปเดต UI ในฝั่งไคลเอ็นต์ โปรดดูแสดงรายละเอียดการชำระเงินที่อัปเดต

แจ้งผู้ขายเกี่ยวกับการเปลี่ยนแปลงที่อยู่สำหรับจัดส่ง

แอปการชำระเงินสามารถระบุที่อยู่สำหรับจัดส่งของลูกค้าให้แก่ผู้ขายได้เป็นส่วนหนึ่งของธุรกรรมการชำระเงิน

ซึ่งมีประโยชน์ต่อผู้ขายเนื่องจากสามารถมอบสิทธิ์การเก็บรวบรวมที่อยู่ให้กับแอปการชำระเงินได้ และเนื่องจากข้อมูลที่อยู่จะระบุในรูปแบบข้อมูลมาตรฐาน ผู้ขายจึงจะได้รับที่อยู่สำหรับจัดส่งในรูปแบบที่สอดคล้องกัน

นอกจากนี้ ลูกค้ายังสามารถลงทะเบียนข้อมูลที่อยู่กับแอปการชำระเงินที่ต้องการและใช้ข้อมูลดังกล่าวกับผู้ขายรายอื่นได้

UI เครื่องมือเลือกที่อยู่สำหรับจัดส่ง

แอปการชำระเงินสามารถแสดง UI เพื่อแก้ไขที่อยู่สำหรับจัดส่งหรือเลือกข้อมูลที่อยู่ซึ่งลงทะเบียนไว้ล่วงหน้าสำหรับลูกค้าในธุรกรรมการชำระเงิน เมื่อระบุที่อยู่สำหรับจัดส่งเป็นการชั่วคราว แอปการชำระเงินจะแจ้งข้อมูลที่อยู่ที่มีการปกปิดบางส่วนให้ผู้ขายทราบได้ ซึ่งมีข้อดีหลายประการดังนี้

• ผู้ขายสามารถกำหนดได้ว่าลูกค้ามีคุณสมบัติตรงตามข้อจำกัดระดับภูมิภาคหรือไม่เพื่อจัดส่งสินค้า (เช่น ภายในประเทศเท่านั้น)
• ผู้ขายสามารถเปลี่ยนรายการตัวเลือกการจัดส่งตามภูมิภาคของที่อยู่สำหรับจัดส่งได้ (เช่น จัดส่งแบบปกติหรือด่วนระหว่างประเทศ)
• ผู้ขายสามารถใช้ค่าจัดส่งใหม่ตามที่อยู่และอัปเดตราคารวมได้

เมื่อใช้ Payment Handler API แอปการชำระเงินสามารถส่งเหตุการณ์ "การเปลี่ยนแปลงที่อยู่สำหรับจัดส่ง" ไปยังผู้ขายจาก 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);
});

เมื่อผู้ขายตอบกลับ ระบบจะแสดงผลคำมั่นสัญญา 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;
…

ใช้ออบเจ็กต์เพื่ออัปเดต UI ในฝั่งไคลเอ็นต์ โปรดดูแสดงรายละเอียดการชำระเงินที่อัปเดต

แจ้งผู้ขายเกี่ยวกับการเปลี่ยนแปลงตัวเลือกการจัดส่ง

ตัวเลือกการจัดส่งคือวิธีการนำส่งที่ผู้ขายใช้เพื่อจัดส่งสินค้าที่ซื้อให้แก่ลูกค้า ตัวเลือกการจัดส่งทั่วไปมีดังนี้

• จัดส่งฟรี
• การจัดส่งด่วน
• การจัดส่งระหว่างประเทศ
• การจัดส่งแบบพรีเมียมระหว่างประเทศ

โดยแต่ละรายการจะมีค่าใช้จ่ายแตกต่างกันไป โดยปกติแล้ววิธีการ/ตัวเลือกที่เร็วกว่าจะมีราคาแพงกว่า

ผู้ขายที่ใช้ Payment Request API สามารถมอบสิทธิ์การเลือกนี้ให้กับแอปการชำระเงินได้ แอปการชำระเงินสามารถใช้ข้อมูลดังกล่าวเพื่อสร้าง UI และให้ลูกค้าเลือกตัวเลือกการจัดส่ง

UI เครื่องมือเลือกตัวเลือกการจัดส่ง

ระบบจะส่งต่อรายการตัวเลือกการจัดส่งที่ระบุไว้ใน 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;
…

ใช้ออบเจ็กต์เพื่ออัปเดต UI ในฝั่งไคลเอ็นต์ โปรดดูแสดงรายละเอียดการชำระเงินที่อัปเดต

แสดงรายละเอียดการชำระเงินที่อัปเดตแล้ว

เมื่อผู้ขายอัปเดตรายละเอียดการชำระเงินเสร็จแล้ว คำมั่นสัญญาที่แสดงผลจาก .changePaymentMethod(), .changeShippingAddress() และ .changeShippingOption() จะแก้ไขด้วยออบเจ็กต์ PaymentRequestDetailsUpdate เดียวกัน แฮนเดิลการชำระเงินสามารถใช้ผลลัพธ์เพื่อแสดงราคารวมและตัวเลือกการจัดส่งที่อัปเดตแล้วใน UI

หมายเหตุ: ระบบจะส่งออบเจ็กต์ PaymentRequestDetailsUpdate จากผู้ขาย ซึ่งประกอบด้วยข้อมูลที่ถูกต้องที่ผู้ขายใส่ไว้ในออบเจ็กต์ PaymentDetailsUpdate ผ่าน Payment Request API วิธีที่ดีที่สุดในการช่วยให้มั่นใจว่าผู้ขายจะให้ข้อมูลที่คุณคาดหวังคือให้เอกสารประกอบที่ดีสำหรับนักพัฒนาแอป หรือให้ไลบรารี JavaScript เพื่อควบคุมข้อมูล หรือทั้ง 2 อย่าง

ผู้ขายอาจแสดงข้อผิดพลาดเนื่องจากสาเหตุบางประการต่อไปนี้

• เราไม่ยอมรับวิธีการชำระเงินนี้
• ที่อยู่สำหรับจัดส่งอยู่นอกภูมิภาคที่รองรับ
• ที่อยู่สำหรับจัดส่งมีข้อมูลที่ไม่ถูกต้อง
• เลือกตัวเลือกการจัดส่งสำหรับที่อยู่สำหรับจัดส่งที่ระบุไม่ได้หรือด้วยเหตุผลอื่น

ใช้พร็อพเพอร์ตี้ต่อไปนี้เพื่อแสดงสถานะข้อผิดพลาด

• 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. กดปุ่มชำระเงินข้างช่อง