付款要求 API 的異動

Eiji Kitamura
Eiji Kitamura

Chrome 62

現已可使用 PaymentDetailsModifier

在付款要求中,您可能會想提供折扣或額外費用,具體取決於客戶選擇的付款方式。您可以使用 PaymentDetailsModifier 來達成這個目標。

modifiers 屬性新增至 PaymentRequest 建構函式的第二個引數,以及 PaymentDetailsModifier 物件陣列,該物件是顯示項目和總量修改方式的宣告規則,視客戶選擇的付款方式而定。

以下範例說明您如何聲明選擇信用卡付款時,系統會向使用者收取 $3 美元的處理費。

let methods = [{
 supportedMethods: 'basic-card',
 data: {
   supportedNetworks: ['visa', 'mastercard']
   supportedTypes: ['credit', 'debit']
 }
}];

let details = {
 displayItems: [{
   label: 'T-shirt',
   amount: { currency: 'USD', value: '68.00' }
 }],
 total: {
   label: 'Total price',
   amount: { currency: 'USD', value: '68.00' }
 },
 modifiers: [{
   supportedMethods: 'basic-card',
   data: {
     supportedTypes: ['credit']
   },
   additionalDisplayItems: [{
     label: 'Processing fee',
     amount: { currency: 'USD', value: '3.00' }
   }],
   total: {
     label: 'Credit card price',
     amount: {currency: ‘USD’, value: ‘71.00’}}
 }]
};

let options = {};

let request = new PaymentRequest(methods, details, options);

使用者選擇信用卡付款後,在實際的「付款要求」工作表中,使用者會看到其他名為「處理費」的顯示項目,其費用為 $3 美元,總價為 $71.00 美元。

PaymentDetailsModifier 包含下列參數:

資源名稱
supportedMethods 請指定套用這項規則的付款方式。
additionalDisplayItems 你要新增折扣或額外費用的其他顯示商品。
total 新增 additionalDisplayItems 後的總價。
data basic-card 付款時,這會使用 supportedTypes 篩選特定卡片類型。否則,這個參數的使用方式須視付款方式 (付款應用程式) 而定。請參閱各付款方式提供的說明文件。

設定運送選項時,可能會有點難度,因為 modifiers 的總價不能是固定價格,需要動態修改。

為此,您需要在 shippingaddresschangeshippingoptionchange 事件時修改 modifiers 屬性的 additionalDisplayItemstotal,就像對 PaymentDetails 物件的 displayItems 屬性一樣。

supportedMethods 屬性現在接受字串

PaymentMethodData 物件 (PaymentRequest 建構函式的第一個引數) 中的 supportedMethods 屬性已經採用代表付款方式的字串陣列。現在接受單一字串做為引數。

請注意,目前提供陣列將會繼續運作。

錯誤做法

舊版 - 目前仍然有效。

var methodData = [{
     supportedMethods: ['basic-card'],
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay']
     }
}, {
    supportedMethods: ['https://bobpay.xyz']
}];
正確做法

全新面貌。

var methodData = [{
     supportedMethods: 'basic-card',
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay']
     }
}, {
    supportedMethods: 'https://bobpay.xyz'
}];

Chrome 61

基本資訊卡中的 supportedTypes

supportedMethods 為「basic-card」時,您現在可以提供 supportedTypes 指出「credit」、「debit」和「prepaid」之間支援哪些類型的卡片。

var methodData = [{
 supportedMethods: 'basic-card',
 data: {
   supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
     'diners', 'discover', 'mir', 'unionpay']
   supportedTypes: ['credit', 'debit', 'prepaid']
 }
}];

請務必透過付款閘道再次確認卡片類型,因為這項篩選功能可能無法完全正常運作,具體取決於資料來源的來源。

Chrome 57

PaymentRequest 現可在 iframe 中使用

您現在可以將 allowpaymentrequest 屬性新增至 iframe 元素,從 iframe 中呼叫 Payment Request API。

<iframe src="/totally/fake/url" allowpaymentrequest></iframe>

PaymentMethodData 支援「basic-card」

PaymentRequest() 建構函式的第一個引數是付款方式資料陣列。此版本已變更 PaymentMethodData 格式。

錯誤做法

舊版 - 目前仍然有效。

var methodData = [{
     supportedMethods: ['visa', 'mastercard', 'amex', 'jcb']
}];
var request = new PaymentRequest(methodData, details, options);
正確做法

新結構:新結構。

var methodData = [{
     supportedMethods: ['basic-card'],
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay']
     }
}];
var request = new PaymentRequest(methodData, details, options);

data 屬性的格式取決於 supportedMethods 中的值,且以基本資訊卡規格為基礎。請注意,規格包含可接受 creditdebitprepaidsupportedTypes,但 Chrome 57 會忽略這個屬性,並將 supoprtedNetworks 中的所有值視為信用卡。

var methodData = [{
     supportedMethods: ['basic-card'],
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay'],
       supportedTypes: ['credit'] <= not available
     }
}];

Chrome 56

待處理

付款商品資訊中,開發人員可以新增 pending,表示價格尚未完全確定。pending 欄位接受布林值。

    {
      label: "State tax",
      amount: { currency: "USD", value : "5.00" },
      pending: true
    },

這種函式通常用於顯示依照所選運送地址或運送選項而定的運費或稅金等明細項目。Chrome 會顯示付款要求使用者介面中的待處理欄位。

requestPayerName

利用運送選項 (用於 PaymentRequest 的第三個引數),開發人員現在可以新增 requestPayerName,以除了運送地址資訊之外,要求付款人的姓名。requestPayerName 接受布林值。

shippingType

透過運送選項 (PaymentRequest 的第三個引數),開發人員現在可以新增 shippingType,要求 UI 顯示「交付」或「取貨」而非「運送」。shippingType 接受 shipping (預設)、deliverypickup 字串。

運送類型=&#39;交付&#39;
shippingType=" Delivery"
shippingType=&#39;pickup&#39;
shippingType="pickup"

適用於 PaymentResponse 和 PaymentAddress 的序列化程式函式

PaymentResponse 物件PaymentAddress 物件現在能以 JSON 序列化。開發人員可以呼叫 toJSON() 函式,將單一物件轉換為 JSON 物件,避免建立複雜的 toDict() 函式。

request.show().then(response => {
     let res = response.toJSON();
});

canMakePayment

除了 API 可用性之外,您還可以在叫用 Payment Request API 之前檢查使用者是否具備有效的付款方式。請注意,由於使用者仍可在付款 UI 中新增付款方式,因此此為選用步驟。

let request = new PaymentRequest(methods, details, options);
if (request.canMakePayment) {
     request.canMakePayment().then(result => {
       if (result) {
         // Payment methods are available.
       } else {
         // Payment methods are not available, but users can still add
        // a new payment method in Payment UI.
       }
     }).catch(error => {
       // Unable to determine.
     });
}