Xử lý thông tin thanh toán không bắt buộc bằng trình chạy dịch vụ

Cách điều chỉnh ứng dụng thanh toán dựa trên web để phù hợp với tính năng Thanh toán trên web và mang đến trải nghiệm người dùng tốt hơn cho khách hàng.

Sau khi ứng dụng thanh toán dựa trên web nhận được yêu cầu thanh toán và bắt đầu giao dịch thanh toán, worker dịch vụ sẽ đóng vai trò là trung tâm giao tiếp giữa người bán và ứng dụng thanh toán. Bài đăng này giải thích cách ứng dụng thanh toán có thể chuyển thông tin về phương thức thanh toán, địa chỉ giao hàng hoặc thông tin liên hệ cho người bán bằng worker dịch vụ.

Xử lý thông tin thanh toán không bắt buộc bằng worker dịch vụ
Xử lý thông tin thanh toán không bắt buộc bằng trình chạy dịch vụ

Thông báo cho người bán về việc thay đổi phương thức thanh toán

Ứng dụng thanh toán có thể hỗ trợ nhiều phương thức thanh toán bằng nhiều phương thức thanh toán.

Khách hàng Phương thức thanh toán Phương thức thanh toán
A Công ty phát hành thẻ tín dụng 1 ****1234
Công ty phát hành thẻ tín dụng 1 ****4242
Ngân hàng X ******123
B Công ty phát hành thẻ tín dụng 2 ****5678
Ngân hàng X ******456

Ví dụ: trong bảng trên, ví trên web của Khách hàng A có hai thẻ tín dụng và một tài khoản ngân hàng đã đăng ký. Trong trường hợp này, ứng dụng đang xử lý 3 phương thức thanh toán (****1234, ****4242, ******123) và 2 phương thức thanh toán (Ngân hàng phát hành thẻ tín dụng 1 và Ngân hàng X). Trong một giao dịch thanh toán, ứng dụng thanh toán có thể cho phép khách hàng chọn một trong các phương thức thanh toán và sử dụng phương thức đó để thanh toán cho người bán.

Giao diện người dùng của bộ chọn phương thức thanh toán
Giao diện người dùng bộ chọn phương thức thanh toán

Ứng dụng thanh toán có thể cho người bán biết khách hàng đã chọn phương thức thanh toán nào trước khi gửi phản hồi thanh toán đầy đủ. Ví dụ: điều này sẽ hữu ích khi người bán muốn chạy chiến dịch chiết khấu cho một thương hiệu phương thức thanh toán cụ thể.

Với API Trình xử lý thanh toán, ứng dụng thanh toán có thể gửi sự kiện "thay đổi phương thức thanh toán" cho người bán thông qua một worker dịch vụ để thông báo giá trị nhận dạng phương thức thanh toán mới. Worker dịch vụ sẽ gọi PaymentRequestEvent.changePaymentMethod() bằng thông tin về phương thức thanh toán mới.

Thông báo cho người bán về việc thay đổi phương thức thanh toán
Thông báo cho người bán về việc thay đổi phương thức thanh toán

Ứng dụng thanh toán có thể truyền đối tượng methodDetails làm đối số thứ hai không bắt buộc cho PaymentRequestEvent.changePaymentMethod(). Đối tượng này có thể chứa thông tin chi tiết về phương thức thanh toán tuỳ ý mà người bán cần để xử lý sự kiện thay đổi.

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

Khi nhận được sự kiện paymentmethodchange từ API Yêu cầu thanh toán, người bán có thể cập nhật thông tin thanh toán và phản hồi bằng đối tượng 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);
});

Khi người bán phản hồi, lời hứa mà PaymentRequestEvent.changePaymentMethod() trả về sẽ được phân giải bằng đối tượng 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;

Sử dụng đối tượng này để cập nhật giao diện người dùng ở phần trước. Xem phần Phản ánh thông tin thanh toán đã cập nhật.

Thông báo cho người bán về việc thay đổi địa chỉ giao hàng

Ứng dụng thanh toán có thể cung cấp địa chỉ giao hàng của khách hàng cho người bán trong một giao dịch thanh toán.

Điều này rất hữu ích cho người bán vì họ có thể uỷ quyền việc thu thập địa chỉ cho các ứng dụng thanh toán. Ngoài ra, vì dữ liệu địa chỉ sẽ được cung cấp ở định dạng dữ liệu tiêu chuẩn, nên người bán có thể nhận được địa chỉ giao hàng có cấu trúc nhất quán.

Ngoài ra, khách hàng có thể đăng ký thông tin địa chỉ của họ bằng ứng dụng thanh toán mà họ ưu tiên và sử dụng lại thông tin đó cho nhiều người bán.

Giao diện người dùng của bộ chọn địa chỉ giao hàng
Giao diện người dùng bộ chọn địa chỉ giao hàng

Ứng dụng thanh toán có thể cung cấp giao diện người dùng để chỉnh sửa địa chỉ giao hàng hoặc chọn thông tin địa chỉ đã đăng ký trước cho khách hàng trong một giao dịch thanh toán. Khi một địa chỉ giao hàng được xác định tạm thời, ứng dụng thanh toán có thể cho người bán biết thông tin địa chỉ đã bị loại bỏ. Điều này mang lại cho người bán nhiều lợi ích:

  • Người bán có thể xác định xem khách hàng có đáp ứng quy định hạn chế theo khu vực để vận chuyển mặt hàng hay không (ví dụ: chỉ vận chuyển nội địa).
  • Người bán có thể thay đổi danh sách các phương thức vận chuyển dựa trên khu vực của địa chỉ giao hàng (ví dụ: quốc tế thông thường hoặc nhanh).
  • Người bán có thể áp dụng phí vận chuyển mới dựa trên địa chỉ và cập nhật tổng giá.

Với API Trình xử lý thanh toán, ứng dụng thanh toán có thể gửi sự kiện "thay đổi địa chỉ giao hàng" đến người bán từ worker dịch vụ để thông báo địa chỉ giao hàng mới. Worker dịch vụ sẽ gọi PaymentRequestEvent.changeShippingAddress() bằng đối tượng địa chỉ mới.

Thông báo cho người bán về việc thay đổi địa chỉ giao hàng
Thông báo cho người bán về việc thay đổi địa chỉ giao hàng

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

Người bán sẽ nhận được sự kiện shippingaddresschange từ API Yêu cầu thanh toán để có thể phản hồi bằng PaymentDetailsUpdate đã cập nhật.

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

Khi người bán phản hồi, lời hứa PaymentRequestEvent.changeShippingAddress() được trả về sẽ phân giải bằng đối tượng 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;

Sử dụng đối tượng này để cập nhật giao diện người dùng ở phần trước. Xem phần Phản ánh thông tin thanh toán đã cập nhật.

Thông báo cho người bán về việc thay đổi phương thức vận chuyển

Lựa chọn vận chuyển là phương thức giao hàng mà người bán sử dụng để vận chuyển các mặt hàng đã mua đến khách hàng. Các phương thức vận chuyển thông thường bao gồm:

  • Giao hàng miễn phí
  • Giao hàng nhanh
  • Giao hàng quốc tế
  • Dịch vụ vận chuyển quốc tế cao cấp

Mỗi loại đều có chi phí riêng. Thông thường, các phương thức/tuỳ chọn nhanh hơn sẽ có giá cao hơn.

Người bán sử dụng API Yêu cầu thanh toán có thể uỷ quyền lựa chọn này cho một ứng dụng thanh toán. Ứng dụng thanh toán có thể sử dụng thông tin này để tạo giao diện người dùng và cho phép khách hàng chọn một phương thức giao hàng.

Giao diện người dùng của bộ chọn phương thức vận chuyển
Giao diện người dùng bộ chọn phương thức giao hàng

Danh sách các lựa chọn vận chuyển được chỉ định trong API Yêu cầu thanh toán của người bán được truyền đến worker dịch vụ của ứng dụng thanh toán dưới dạng thuộc tính của 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 });

Ứng dụng thanh toán có thể cho người bán biết khách hàng đã chọn phương thức giao hàng nào. Điều này rất quan trọng đối với cả người bán và khách hàng vì việc thay đổi phương thức vận chuyển cũng sẽ làm thay đổi tổng giá. Nhà bán hàng cần được thông báo về giá mới nhất để xác minh phương thức thanh toán sau này và khách hàng cũng cần biết về sự thay đổi này.

Với API Trình xử lý thanh toán, ứng dụng thanh toán có thể gửi sự kiện "thay đổi tuỳ chọn vận chuyển" cho người bán từ worker dịch vụ. Trình chạy dịch vụ sẽ gọi PaymentRequestEvent.changeShippingOption() bằng mã lựa chọn vận chuyển mới.

Thông báo cho người bán về việc thay đổi phương thức vận chuyển
Thông báo cho người bán về việc thay đổi phương thức vận chuyển

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

Người bán sẽ nhận được sự kiện shippingoptionchange từ API Yêu cầu thanh toán. Người bán nên sử dụng thông tin này để cập nhật tổng giá, sau đó phản hồi bằng PaymentDetailsUpdate đã cập nhật.

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

Khi người bán phản hồi, lời hứa mà PaymentRequestEvent.changeShippingOption() trả về sẽ được phân giải bằng đối tượng 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;

Sử dụng đối tượng này để cập nhật giao diện người dùng trên phần trước. Xem phần Phản ánh thông tin thanh toán đã cập nhật.

Phản ánh thông tin thanh toán đã cập nhật

Sau khi người bán hoàn tất việc cập nhật thông tin thanh toán, các lời hứa được trả về từ .changePaymentMethod(), .changeShippingAddress().changeShippingOption() sẽ phân giải bằng một đối tượng PaymentRequestDetailsUpdate chung. Trình xử lý thanh toán có thể sử dụng kết quả để phản ánh tổng giá và các lựa chọn vận chuyển đã cập nhật cho giao diện người dùng.

Người bán có thể trả về lỗi vì một số lý do:

  • Phương thức thanh toán không được chấp nhận.
  • Địa chỉ giao hàng nằm ngoài khu vực được hỗ trợ.
  • Địa chỉ giao hàng chứa thông tin không hợp lệ.
  • Bạn không thể chọn phương thức giao hàng cho địa chỉ giao hàng đã cung cấp hoặc vì một lý do nào đó.

Sử dụng các thuộc tính sau để phản ánh trạng thái lỗi:

  • error: Chuỗi lỗi mà con người có thể đọc được. Đây là chuỗi tốt nhất để hiển thị cho khách hàng.
  • shippingAddressErrors: đối tượng AddressErrors chứa chuỗi lỗi chi tiết cho mỗi thuộc tính địa chỉ. Điều này rất hữu ích nếu bạn muốn mở một biểu mẫu cho phép khách hàng chỉnh sửa địa chỉ của họ và bạn cần trỏ trực tiếp họ đến các trường không hợp lệ.
  • paymentMethodErrors: Đối tượng lỗi dành riêng cho phương thức thanh toán. Bạn có thể yêu cầu người bán cung cấp lỗi có cấu trúc, nhưng các tác giả của quy cách Thanh toán trên web đề xuất bạn nên giữ lỗi ở dạng chuỗi đơn giản.

Mã mẫu

Hầu hết các mã mẫu mà bạn thấy trong tài liệu này đều được trích từ ứng dụng mẫu hoạt động sau:

https://paymenthandler-demo.glitch.me

[payment handler] worker

[payment handler] giao diện người dùng

Cách dùng thử:

  1. Truy cập vào https://paymentrequest-demo.glitch.me/.
  2. Chuyển tới cuối trang.
  3. Nhấn vào Nút Thêm phương thức thanh toán.
  4. Nhập https://paymenthandler-demo.glitch.me vào trường Mã nhận dạng phương thức thanh toán.
  5. Nhấn nút Thanh toán bên cạnh trường này.