本頁面由 Cloud Translation API 翻譯而成。

與服務工作人員處理選擇性付款資訊

如何將網站式付款應用程式改為採用「網路付款」功能，為客戶提供更優質的使用者體驗。

Eiji Kitamura

網頁式付款應用程式收到付款要求並辦理付款後交易之後，Service Worker 就會做為商家和付款應用程式之間的通訊中樞。這篇文章說明付款應用程式如何傳遞付款方式相關資訊。收貨地址或提供聯絡資訊給商家。

通知商家付款方式變更

付款應用程式可支援多種付款方式，

客戶	付款方式	付款方式
A	信用卡發卡機構 1	`****1234`
	信用卡發卡機構 1	`****4242`
	X 銀行	`******123`
B	信用卡發卡機構 2	`****5678`
B	X 銀行	`******456`

例如，在上表中，客戶 A 的網頁式電子錢包有 2 筆信用額卡片和一個銀行帳戶已註冊完畢。在本例中，應用程式會處理三個付款方式 (****1234、****4242、******123) 和兩次付款 (信用卡核發機構 1 和銀行 X)。在付款交易中，您支付的款項應用程式能讓客戶選擇其中一種付款方式來付款商家。

付款應用程式可告知商家客戶使用的付款方式優先處理已收集的資訊。如果系統判定商家想針對特定付款方式品牌放送折扣廣告活動。例如

透過 Payment Handler API，付款應用程式可以傳送「付款方式變更」透過 Service Worker 向商家傳送事件，通知新的付款方式或 ID。Service Worker 應叫用使用新付款方式支付 PaymentRequestEvent.changePaymentMethod() 可能不準確或不適當

付款應用程式可以將 methodDetails 物件做為選用的第二個引數傳遞 (PaymentRequestEvent.changePaymentMethod())。這個物件可以包含商家處理變更時所需的任意付款方式詳細資料活動。

[付款處理常式] 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 事件時要求 API，他們可以更新付款資料，並以 PaymentDetailsUpdate 物件。

[商家]

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 物件。

[付款處理常式] 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。請參閱反映付款資料。

通知商家運送地址變更

付款應用程式可將客戶的運送地址提供給商家可能會發生付款交易

這對商家來說十分實用，因為商家可以將其地址集合委派給付款應用程式。同時，因為地址資料將按照標準資料格式，則商家可以預期收到結構一致的運送地址。

此外，消費者也可透過並重複使用付款應用程式給不同的商家。

付款應用程式可提供使用者介面，讓你編輯運送地址或選取客戶在付款交易中預先註冊的地址資訊。如果暫時決定運送地址，付款應用程式可以商家知道地址資訊遭到遮蓋。這樣商家就能多項優點：

商家可判斷客戶是否符合區域限制即可寄送商品 (例如僅限國內)。
商家可以根據運送地址 (例如國際一般或快遞)。
商家可以根據地址套用新的運費，總價

只要使用 Payment Handler API，付款應用程式即可傳送「運送地址」變更」通知商家新的運送服務，要求服務工作處理程序傳送新的讓我們看看 DNS 解析進一步探索內部和外部位址Service Worker 應叫用 PaymentRequestEvent.changeShippingAddress()敬上使用新地址物件。

[付款處理常式] 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 欄位，然後在商家的 DOM 引發 shippingaddresschange 事件。

商家會收到來自付款的「shippingaddresschange」事件要求 API，以便他們可以使用更新後的 PaymentDetailsUpdate 進行回應。

[商家]

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 物件。

[付款處理常式] 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 的商家可以將這個選項委派給付款應用程式。付款應用程式可以使用該資訊建構使用者介面，也就是讓顧客選擇運送方式

在商家 Payment Request API 中指定的運送選項清單為以 PaymentRequestEvent。

[商家]

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 叫用 PaymentRequestEvent.changeShippingOption()敬上新的運送選項 ID

[付款處理常式] 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」事件 Request API。商家應使用這項資訊更新總價然後依據 PaymentDetailsUpdate。

[商家]

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 物件。

[付款處理常式] 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 物件。付款處理常式可以使用結果來反映更新後的總價和運送選項位於使用者介面

注意： PaymentRequestDetailsUpdate 物件會從商家傳送，其中包含商家透過 Payment Request API 在 PaymentDetailsUpdate 物件中提供的確切資訊。想確保商家提供您預期的資訊，最好的方法就是提供優質的開發人員說明文件，或是提供用來控制資訊的 JavaScript 程式庫，或同時提供兩者。

商家傳回錯誤的可能原因如下：

系統不接受這個付款方式。
運送地址不在支援區域。
運送地址含有無效的資訊。
提供的運送地址無法選取運送選項，或是其他原因。

請使用以下屬性來反映錯誤狀態：

error：人類可讀的錯誤字串。這是要顯示的最佳字串為客戶提供最高的應用程式處理量並將延遲時間縮到最短
shippingAddressErrors： AddressErrors 物件，其中包含每個地址屬性的詳細錯誤字串。這是如果您想開啟表單，供客戶編輯地址，這種做法就很實用。且你必須直接把這些欄位指向無效欄位。
paymentMethodErrors：付款方式專屬的錯誤物件。你可以提問商家必須提供結構化錯誤，但 Web Payments 規格作者建議您保留簡單的字串

程式碼範例

您在本文件中看到的大部分程式碼範例皆摘錄自可運作的範例應用程式：

https://paymenthandler-demo.glitch.me

[付款處理常式] 服務工作人員

[付款處理常式] 前端

如要試用這項功能，請按照下列步驟操作：

前往 https://paymentrequest-demo.glitch.me/。
前往頁面底部。
按下「新增付款方式」按鈕。
在「付款方式 ID」欄位中輸入 https://paymenthandler-demo.glitch.me。
按下欄位旁的「付款」按鈕。