คำแนะนำในการพัฒนาเว็บที่ทันสมัยพร้อมใช้งานแล้ว อัปเกรด Agent การเขียนโค้ดด้วยแนวทางปฏิบัติแนะนำในการพัฒนาเว็บที่ผ่านการตรวจสอบโดยผู้เชี่ยวชาญ อ่านประกาศ

Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

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

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

Eiji Kitamura

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

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

แจ้งให้ผู้ขายทราบ

คุณต้องแจ้งให้ผู้ขายทราบถึงการเปลี่ยนแปลงต่อไปนี้

การเปลี่ยนแปลงวิธีการชำระเงิน

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

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

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

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

เมื่อใช้ 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 เพื่อแก้ไขที่อยู่สำหรับจัดส่งหรือเลือกข้อมูลที่อยู่ที่ลงทะเบียนไว้ล่วงหน้าสำหรับลูกค้าในธุรกรรมการชำระเงิน เมื่อมีการกำหนดที่อยู่สำหรับจัดส่งชั่วคราว แอปการชำระเงินจะแจ้งให้ผู้ขายทราบถึงข้อมูลที่อยู่ที่มีการปกปิดบางส่วนได้ ซึ่งจะช่วยให้ผู้ขายได้รับประโยชน์หลายประการ ดังนี้

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

เมื่อใช้ 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);
});

เมื่อผู้ขายตอบกลับ สัญญา 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 สามารถมอบสิทธิ์การเลือกนี้ให้กับแอปการชำระเงินได้ แอปการชำระเงินจะใช้ข้อมูลนี้เพื่อสร้าง 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;
…

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

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

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

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

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

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

error: สตริงข้อผิดพลาดที่มนุษย์อ่านได้ นี่คือสตริงที่ดีที่สุดที่จะแสดงต่อลูกค้า
shippingAddressErrors: AddressErrors ออบเจ็กต์ที่มีสตริงข้อผิดพลาดโดยละเอียดต่อพร็อพเพอร์ตี้ที่อยู่ ซึ่งจะเป็นประโยชน์หากคุณต้องการเปิดแบบฟอร์มที่ให้ลูกค้าแก้ไขที่อยู่ และคุณต้องชี้ให้ลูกค้าเห็นช่องที่ไม่ถูกต้องโดยตรง
paymentMethodErrors: ออบเจ็กต์ข้อผิดพลาดเฉพาะวิธีการชำระเงิน คุณสามารถขอให้ผู้ขายระบุข้อผิดพลาดที่มีโครงสร้างได้ แต่ผู้เขียนข้อกำหนดเฉพาะของ Web Payments แนะนำให้ใช้สตริงธรรมดา