如何調整網頁式付款應用程式,使其符合 Web Payments 標準,為客戶提供更優質的使用者體驗。
網頁式付款應用程式收到付款要求並啟動付款交易後,Service Worker 會做為商家與付款應用程式之間的通訊中心。本文將說明付款應用程式如何使用 Service Worker,將付款方式、運送地址或聯絡資訊等資訊傳遞給商家。
通知商家
請務必告知商家下列異動。
變更付款方式
付款應用程式可支援多種付款工具,並提供不同的付款方式。
| 客戶 | 付款方式 | 付款方式 |
|---|---|---|
| A | 信用卡發卡機構 1 | ****1234 |
| 信用卡發卡機構 1 | ****4242 |
|
| 銀行 X | ******123 |
|
| B | 信用卡發卡機構 2 | ****5678 |
| 銀行 X | ******456 |
舉例來說,在上述表格中,顧客 A 的網頁式錢包註冊了兩張信用卡和一個銀行帳戶。在本例中,應用程式會處理三種付款工具 (****1234、****4242、******123) 和兩種付款方式 (信用卡發卡機構 1 和銀行 X)。在付款交易中,付款應用程式可讓消費者選擇其中一種付款方式,並用來支付商家款項。
付款應用程式可在傳送完整付款回應前,告知商家客戶選擇的付款方式。舉例來說,如果商家想針對特定付款方式品牌推出折扣活動,這項功能就非常實用。
透過網頁式 Payment Handler API,付款應用程式可以透過 Service Worker 向商家傳送「付款方式變更」事件,通知新的付款方式 ID。Service 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);
…
商家收到 Payment Request API 的 paymentmethodchange 事件後,可以更新付款詳細資料,並以 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() 傳回的 Promise 會解析為 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 向商家傳送「運送地址變更」事件,通知新的運送地址。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 欄位,然後在商家的 DOM 中引發 shippingaddresschange 事件。
商家會從 Payment Request API 收到 shippingaddresschange 事件,以便回應更新後的 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);
});
商家回應後,傳回的 Promise 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 中指定的運送選項清單,會以 PaymentRequestEvent 屬性的形式,傳播至付款應用程式的 Service Worker。
[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 應使用新的運送選項 ID 叫用 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);
…
商家會收到來自 Payment Request API 的 shippingoptionchange 事件。商家應使用這項資訊更新總價,然後回覆更新後的 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() 傳回的 Promise 會解析為 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:付款方式專屬的錯誤物件。您可以要求商家提供結構化錯誤,但 Web Payments 規格作者建議保持簡單的字串。