付款请求 API 的变更

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 的总价不能是静态的，需要动态修改。

为此，您需要在 shippingaddresschange 和 shippingoptionchange 事件发生时修改 modifiers 属性的 additionalDisplayItems 和 total，就像对 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']
 }
}];

请务必通过 Payment Gateway 仔细检查卡类型，因为此过滤功能可能无法完美运行，具体取决于其来源。

Chrome 57

PaymentRequest 现已在 iframe 中提供

现在，通过向 iframe 元素添加 allowpaymentrequest 属性，可以从 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 中的值，并基于基本卡规范。请注意，规范包含 supportedTypes，它接受 credit、debit 或 prepaid，但 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，以请求界面显示“送货”或“自提”，而不是“配送”。shippingType 接受字符串 shipping（默认值）、delivery 或 pickup。

shippingType='delivery'
shippingType="delivery"
shippingType='pickup'
shippingType="pickup"

PaymentResponse 和 PaymentAddress 现已支持序列化函数

PaymentResponse 对象和 PaymentAddress 对象现在可进行 JSON 序列化。开发者可以通过调用 toJSON() 函数将一个对象转换为 JSON 对象，从而避免创建繁琐的 toDict() 函数。

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

canMakePayment

除了 API 可用性之外，您还可以在调用 Payment Request API 之前检查用户是否有有效的支付方式。请注意，这是可选操作，因为用户仍可在付款界面上添加新的支付方式。

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