支付请求 API

PaymentRequest 是使用提供的 PaymentMethodData 序列 methodData（包括任何支付方式特定的 data）、 PaymentDetailsInit details 和 PaymentOptions options 构造的。

PaymentRequest(methodData, details, options) 构造函数必须按如下方式操作：

1. 如果此相关全局对象的关联 Document 不允许使用 "payment" 权限，则抛出一个 "SecurityError" DOMException。
2. 建立请求的 ID：
   1. 如果 details.id 缺失，则向 details 添加一个 id 成员，并将其值设置为一个 UUID [RFC4122]。
3. 令 serializedMethodData 为一个空列表。
4. 处理支付方式：
   1. 如果 methodData 序列的长度为零，则 抛出一个 TypeError， 可以选择性地通知开发者至少需要一种支付方式。
   2. 令 seenPMIs 为空集。
   3. 对于 methodData 中的每个 paymentMethod：
      1. 运行 验证支付方式标识符的步骤，使用 paymentMethod.supportedMethods。 如果返回 false，则抛出一个 RangeError 异常。 可以选择性地通知开发者支付方式标识符无效。
      2. 令 pmi 为使用 基本 URL 解析器解析 paymentMethod.supportedMethods 的结果：
         1. 如果失败，则将 pmi 设置为 paymentMethod.supportedMethods。
      3. 如果 seenPMIs 包含 pmi，则抛出一个 RangeError DOMException， 可以选择性地通知开发者此支付方式标识符是重复的。
      4. 追加 pmi 到 seenPMIs。
      5. 如果 paymentMethod 的 data 成员缺失，则令 serializedData 为 null。 否则，令 serializedData 为将 paymentMethod.data 序列化为 JSON 字符串的结果。重新抛出任何异常。
      6. 如果 serializedData 不为 null，并且定义 paymentMethod.supportedMethods 的规范指定了附加数据类型：
         1. 令 object 为 JSON 解析 serializedData 的结果。

         2. 令 idl 为将 object 转换为 附加数据类型的 IDL 值的结果。重新抛出任何异常。

         3. 运行定义 paymentMethod.supportedMethods 的规范中的验证支付方式数据的步骤（如果有），作用于 object。重新抛出任何异常。

            注意

            这些步骤确保尽早捕获任何 IDL 类型转换和验证错误。

      7. 将元组 (paymentMethod.supportedMethods, serializedData) 添加到 serializedMethodData。
5. 处理总额：
   1. 检查并规范化总金额 details.total.amount。 重新抛出任何异常。
6. 如果 details 的 displayItems 成员存在，则对于 details.displayItems 中的每个 item：
   1. 检查并规范化金额 item.amount。重新抛出任何异常。
7. 令 selectedShippingOption 为 null。
8. 如果 options 的 requestShipping 成员存在且设置为 true，则处理配送选项：
   1. 令 options 为一个空的 sequence<PaymentShippingOption>。
   2. 如果 details 的 shippingOptions 成员存在，则：
      1. 令 seenIDs 为一个空集。
      2. 对于 details.shippingOptions 中的每个 option：
         1. 检查并规范化金额 item.amount。重新抛出任何异常。
         2. 如果 seenIDs 包含 option.id，则抛出一个 TypeError。 可以选择性地通知开发者配送选项 ID 必须唯一。
         3. 否则，将 option.id 追加到 seenIDs。
         4. 如果 option.selected 为 true，则将 selectedShippingOption 设置为 option.id。
   3. 将 details.shippingOptions 设置为 options。
9. 令 serializedModifierData 为一个空列表。
10. 处理支付详情修饰符：
    1. 令 modifiers 为一个空的 sequence<PaymentDetailsModifier>。
    2. 如果 details 的 modifiers 成员存在，则：
       1. 将 modifiers 设置为 details.modifiers。
       2. 对于 modifiers 中的每个 modifier：
          1. 如果 modifier 的 total 成员存在，则：
             1. 检查并规范化总金额 modifier.total.amount。 重新抛出任何异常。
          2. 如果 modifier 的 additionalDisplayItems 成员存在，则对于 modifier.additionalDisplayItems 中的每个 item：
             1. 检查并规范化金额 item.amount。 重新抛出任何异常。
          3. 如果 modifier 的 data 成员缺失，则令 serializedData 为 null。 否则，令 serializedData 为将 modifier.data 序列化为 JSON 字符串的结果。重新抛出任何异常。
          4. 将元组 (modifier.supportedMethods, serializedData) 添加到 serializedModifierData。
          5. 移除 modifier 的 data 成员（如果存在）。
    3. 将 details.modifiers 设置为 modifiers。
11. 令 request 为一个新的 PaymentRequest。
12. 将 request.[[handler]] 设置为 null。
13. 将 request.[[options]] 设置为 options。
14. 将 request.[[state]] 设置为 "created"。
15. 将 request.[[updating]] 设置为 false。
16. 将 request.[[details]] 设置为 details。
17. 将 request.[[serializedModifierData]] 设置为 serializedModifierData。
18. 将 request.[[serializedMethodData]] 设置为 serializedMethodData。
19. 将 request.[[response]] 设置为 null。
20. 将 request 的 shippingOption 属性的值设置为 selectedShippingOption。
21. 将 request 上的 shippingAddress 属性的值设置为 null。
22. 如果 options.requestShipping 设置为 true， 则将 request 上的 shippingType 属性的值设置为 options.shippingType。否则，将其设置为 null。
23. 返回 request。

获取时，id 属性返回此 PaymentRequest 的 [[details]].id。

show(optional detailsPromise) 方法必须按如下方式操作：

1. 令 request 为此。
2. 如果 request 的相关全局对象没有 瞬时激活，则用户代理可以：
   1. 返回一个被拒绝的 promise，并带有 "SecurityError" DOMException。
   注意

   这允许用户代理不需要用户激活，例如支持重定向流程，其中重定向后可能不存在用户激活。有关安全注意事项，请参见 19.9 用户激活要求。

   另请参见 问题 #1022，其中讨论了在规范中提供更多关于用户代理何时应该或不应该为 show() 要求用户激活的指导。

3. 否则， 消耗相关全局对象的用户激活。
4. 令 document 为 request 的相关全局对象的 关联 Document。
5. 如果 document 不是完全激活的，则返回一个被拒绝的 promise，并带有 "AbortError" DOMException。
6. 如果 document 的可见性状态不是 "visible"， 则返回一个被拒绝的 promise，并带有 "AbortError" DOMException。

7. 可选地，如果用户代理希望禁止调用 show() 以保护用户，则返回一个被拒绝的 promise，并带有 "SecurityError" DOMException。例如，用户代理可以限制页面调用 show() 的速率，如 19. 隐私和安全注意事项部分所述。

8. 如果 request.[[state]] 不是 "created"，则返回一个被拒绝的 promise，并带有 "InvalidStateError" DOMException。
9. 如果用户代理的支付请求正在显示 布尔值为 true，则：
   1. 将 request.[[state]] 设置为 "closed"。
   2. 返回一个被拒绝的 promise，并带有 "AbortError" DOMException。
10. 将 request.[[state]] 设置为 "interactive"。
11. 令 acceptPromise 为一个新的 promise。
12. 将 request.[[acceptPromise]] 设置为 acceptPromise。

13. 可选地：

    1. 用 "AbortError" DOMException 拒绝 acceptPromise。
    2. 将 request.[[state]] 设置为 "closed"。
    3. 返回 acceptPromise。
    注意

    这允许用户代理自行决定，表现得好像用户立即中止了支付请求。例如，在“隐私浏览”模式或类似模式下，用户代理可能会利用此步骤。

14. 将 request 的与支付相关的浏览上下文的 支付请求正在显示布尔值设置为 true。
15. 返回 acceptPromise 并并行执行其余步骤。
16. 令 handlers 为一个空的列表。
17. 对于 request.[[serializedMethodData]] 中的每个 paymentMethod 元组：
    1. 令 identifier 为 paymentMethod 元组中的第一个元素。
    2. 令 data 为JSON 解析 paymentMethod 元组中第二个元素的结果。
    3. 如果定义 identifier 的规范指定了 附加数据类型，则将 data 转换为该类型的 IDL 值。 否则，将 data 转换为 object。
    4. 如果转换导致异常 error：
       1. 将 request.[[state]] 设置为 "closed"。
       2. 用 error 拒绝 acceptPromise。
       3. 将 request 的与支付相关的浏览上下文的支付请求正在显示布尔值设置为 false。
       4. 终止此算法。
    5. 令 registeredHandlers 为支付方式 identifier 的已注册支付处理程序的列表。
       注意: 支付处理程序注册
    6. 对于 registeredHandlers 中的每个 handler：
       1. 令 canMakePayment 为运行 handler 的 检查是否可以进行支付的步骤并使用 data 的结果。
       2. 如果 canMakePayment 为 true，则将 handler 追加到 handlers。
18. 如果 handlers 为空，则：
    1. 将 request.[[state]] 设置为 "closed"。
    2. 用 "NotSupportedError" DOMException 拒绝 acceptPromise。
    3. 将 request 的与支付相关的浏览上下文的 支付请求正在显示布尔值设置为 false。
    4. 终止此算法。

19. 呈现一个用户界面，允许用户与 handlers 交互。用户代理应该在呈现支付方式时优先考虑用户的偏好。用户界面应该使用与 document 的文档元素的语言（如果有）匹配的语言和基于区域设置的格式，或者如果不可用，则使用适当的回退。

    注意: 支付用户界面的本地化
20. 如果传递了 detailsPromise，则：
    1. 运行更新 PaymentRequest 详情算法，使用 detailsPromise、request 和 null。
    2. 等待 detailsPromise 稳定下来。
       注意

       根据 detailsPromise 的稳定方式，更新 PaymentRequest 详情算法决定支付 UI 的行为方式。也就是说，在 detailsPromise 被拒绝时，支付请求中止。否则，在 detailsPromise 被满足时，用户代理重新启用支付请求 UI，支付流程可以继续。

21. 将 request.[[handler]] 设置为最终用户选择的支付处理程序。
22. 令 modifiers 为一个空列表。
23. 对于 [[serializedModifierData]] 中的每个 tuple：
    1. 如果 tuple 的第一个元素（一个 PMI）与 request.[[handler]] 的支付方式标识符匹配，则将 tuple 的第二个元素（序列化的方法数据）追加到 modifiers。

24. 传递转换后的 paymentMethod 元组中的第二个元素和 modifiers。可选地，用户代理应该将 request 中的适当数据发送给用户选择的支付处理程序，以指导用户完成支付过程。这包括 request 的各种属性和其他内部插槽（出于隐私原因，在适当的情况下可以排除某些内容）。

    [[serializedModifierData]] 内部插槽中多个适用修饰符的处理是支付处理程序特定的，超出了本规范的范围。然而，建议支付处理程序对 [[serializedModifierData]] 列表中的项目使用“后来者居上”的方法：也就是说，列表末尾的项目始终优先于列表开头的任何项目（参见下面的示例）。

    acceptPromise 稍后将由用户接受支付请求算法或用户中止支付请求算法解析或拒绝，这些算法通过与用户界面的交互触发。

    如果在显示用户界面时 document 不再完全激活，或者在此步骤到达时不再是，则：

    1. 关闭用户界面。
    2. 将 request 的与支付相关的浏览上下文的 支付请求正在显示布尔值设置为 false。

abort() 方法必须按如下方式操作：

1. 令 request 为此。
2. 如果 request.[[response]] 不为 null，且 request.[[response]].[[retryPromise]] 不为 null，则返回一个被拒绝的 promise，并带有 “InvalidStateError” DOMException。
3. 如果 request.[[state]] 的值不是 “interactive”，则返回一个被拒绝的 promise ，并带有 “InvalidStateError” DOMException。
4. 令 promise 为一个新的 promise。
5. 返回 promise 并并行执行其余步骤。
6. 尝试中止当前与支付处理程序的用户交互，并关闭任何剩余的用户界面。
7. 在用户交互任务源上排队一个任务以执行以下步骤：
   1. 如果无法中止当前用户交互， 则用 “InvalidStateError” DOMException 拒绝 promise 并中止这些步骤。
   2. 将 request.[[state]] 设置为 “closed”。
   3. 用 “AbortError” DOMException 拒绝 promise request.[[acceptPromise]]。
   4. 用 undefined 解析 promise。

canMakePayment() 方法必须运行can make payment 算法。

当用户提供送货地址时，会填充 PaymentRequest 的 shippingAddress 属性。默认情况下，它为 null。当用户提供送货地址时，会运行送货地址更改算法。

PaymentRequest 的 shippingType 属性是用于完成交易的送货类型。其值为 PaymentShippingType 枚举值，如果开发者在构造期间未提供（请参阅 PaymentOptions 的 shippingType 成员），则为 null。

PaymentRequest 的 onshippingaddresschange 属性是名为 shippingaddresschange 的 PaymentRequestUpdateEvent 的EventHandler。

当用户选择送货选项时，会填充 PaymentRequest 的 shippingOption 属性。默认情况下，它为 null。当用户选择送货选项时，会运行送货选项更改算法。

PaymentRequest 的 onshippingoptionchange 属性是名为 shippingoptionchange 的 PaymentRequestUpdateEvent 的EventHandler。

PaymentRequest 的 onpaymentmethodchange 属性是名为 “paymentmethodchange” 的 PaymentMethodChangeEvent 的EventHandler。

PaymentRequest 的实例是使用下表中的内部插槽创建的：

内部插槽	描述 (非规范性)
[[serializedMethodData]]	提供给构造函数的 methodData，但表示为包含支持的方法和字符串或 null 数据的元组（而不是原始对象形式）。
[[serializedModifierData]]	一个列表，其中包含序列 [[details]].modifier 中每个对应项的每个 data 成员的序列化字符串形式，如果不存在此类成员，则为 null。
[[details]]	支付请求的当前 PaymentDetailsBase，最初提供给构造函数，然后通过调用 updateWith() 进行更新。请注意， modifiers 成员中包含的 PaymentDetailsModifier 实例的所有 data 成员都将被删除，因为它们以序列化形式存储在 [[serializedModifierData]] 内部插槽中。
[[options]]	提供给构造函数的 PaymentOptions。
[[state]]	支付请求的当前状态，其转换如下： “created” 支付请求已构建且尚未呈现给用户。 “interactive” 支付请求正在呈现给用户。 “closed” 支付请求已完成。 状态转换如下图所示：
[[updating]]	如果存在用于更新支付请求的待处理 updateWith() 调用，则为 True，否则为 false。
[[acceptPromise]]	在 show() 期间创建的待处理 Promise，如果用户接受支付请求，则该 Promise 将被解析。
[[response]]	Null，或由此 PaymentRequest 实例化的 PaymentResponse。
[[handler]]	与此 PaymentRequest 关联的支付处理程序。初始化为 null。

如果一个 JavaScript 字符串按给定顺序包含以下代码点，则它是一个有效的十进制货币值：

1. 可选地，一个 U+002D (-)，表示金额为负。
2. 一个或多个 U+0030 (0) 到 U+0039 (9) 范围内的代码点。
3. 可选地，一个 U+002E (.)，后跟一个或多个 U+0030 (0) 到 U+0039 (9) 范围内的代码点。

^-?[0-9]+(\.[0-9]+)?$

要检查并规范化金额（给定一个 PaymentCurrencyAmount amount），请执行以下步骤：

1. 如果 IsWellFormedCurrencyCode(amount.currency) 的结果为 false，则抛出一个 RangeError 异常，并可选择通知开发者货币无效。
2. 如果 amount.value 不是一个有效的十进制货币值，则抛出一个 TypeError，并可选择通知开发者货币无效。
3. 将 amount.currency 设置为 ASCII 大写 amount.currency 的结果。

要检查并规范化总金额（给定一个 PaymentCurrencyAmount amount），请执行以下步骤：

1. 检查并规范化金额 amount。重新抛出任何异常。
2. 如果 amount.value 的第一个代码点是 U+002D (-)，则抛出一个 TypeError，并可选择通知开发者总额的值不能为负数。

WebIDLdictionary PaymentDetailsBase {
    sequence<PaymentItem> displayItems;
    sequence<PaymentShippingOption> shippingOptions;
    sequence<PaymentDetailsModifier> modifiers;
};

displayItems 成员

一个 PaymentItem 字典序列，包含用户代理可能显示的支付请求的行项目。

注意

shippingOptions 成员

包含供用户选择的不同送货选项的序列。

如果序列中的某个项目将 selected 成员设置为 true，则这将是默认使用的送货选项，并且 shippingOption 将被设置为此选项的 id，而不会运行 送货选项更改算法。如果序列中有多个项目将 selected 设置为 true，则用户代理会选择序列中的最后一个。

仅当使用 PaymentOptions 构造 PaymentRequest 并且将 requestShipping 设置为 true 时，才会使用 shippingOptions 成员。

注意

modifiers 成员

一个 PaymentDetailsModifier 字典序列，其中包含特定支付方式标识符的修饰符。例如，它允许您根据支付方式调整总金额。

WebIDLdictionary PaymentDetailsInit : PaymentDetailsBase {
    DOMString id;
    required PaymentItem total;
};

除了从 PaymentDetailsBase 字典继承的成员外，以下成员也是 PaymentDetailsInit 字典的一部分：

id 成员

此支付请求的自由格式标识符。

注意

total 成员

一个 PaymentItem，包含支付请求的非负总金额。

注意

WebIDLdictionary PaymentDetailsUpdate : PaymentDetailsBase {
    DOMString error;
    PaymentItem total;
    AddressErrors shippingAddressErrors;
    PayerErrors payerErrors;
    object paymentMethodErrors;
};

PaymentDetailsUpdate 字典用于使用 updateWith() 更新支付请求。

除了从 PaymentDetailsBase 字典继承的成员外，以下成员也是 PaymentDetailsUpdate 字典的一部分：

error 成员

一个人类可读的字符串，解释为什么无法将商品运送到所选的送货地址，或任何其他导致没有可用送货选项的原因。当使用 updateWith() 更新支付请求时，如果 PaymentDetailsUpdate 表明没有有效的 shippingOptions（并且 PaymentRequest 是使用 requestShipping 选项设置为 true 构造的），则 PaymentDetailsUpdate 可以在 error 成员中包含一条消息，该消息将显示给用户。

total 成员

一个 PaymentItem，包含一个非负的 amount。

注意

本规范中接受 PaymentDetailsUpdate 字典的算法将在 total.amount.value 为负数时抛出异常。

shippingAddressErrors 成员

表示与潜在事件目标关联的送货地址的验证错误。

payerErrors 成员

与付款人详细信息相关的验证错误。

paymentMethodErrors 成员

支付方式特定错误。

retry(errorFields) 方法必须按以下方式操作：

1. 令 response 为this。
2. 令 request 为 response.[[request]]。
3. 令 document 为 request 的相关全局对象的关联 Document。
4. 如果 document 不是完全激活状态，则返回一个被拒绝的 promise，并带有 "AbortError" DOMException。
5. 如果 response.[[complete]] 为 true，则返回一个被拒绝的 promise，并带有 "InvalidStateError" DOMException。
6. 如果 response.[[retryPromise]] 不为 null，则返回一个被拒绝的 promise，并带有 "InvalidStateError" DOMException。
7. 将 request.[[state]] 设置为 "interactive"。
8. 令 retryPromise 为一个新的 promise。
9. 将 response.[[retryPromise]] 设置为 retryPromise。
10. 如果传递了 errorFields：
    1. 可选地，如果以下任一情况为 true，则在开发者控制台中显示警告：
       1. request.[[options]].requestPayerName 为 false，且 errorFields.payer.name 存在。
       2. request.[[options]].requestPayerEmail 为 false，且 errorFields.payer.email 存在。
       3. request.[[options]].requestPayerPhone 为 false，且 errorFields.payer.phone 存在。
       4. request.[[options]].requestShipping 为 false，且 errorFields.shippingAddress 存在。
    2. 如果传递了 errorFields.paymentMethod 成员，并且如果定义 response.methodName 的规范要求，则将 errorFields 的 paymentMethod 成员转换为那里指定的类型的 IDL 值。否则，转换为 object。
    3. 将 request 的支付相关浏览上下文的支付请求正在显示布尔值设置为 false。
    4. 如果转换导致异常 error：
       1. 用 error 拒绝 retryPromise。
       2. 将用户代理的支付请求正在显示布尔值设置为 false。
       3. 返回。
    5. 通过将 errorFields 的成员与用户代理 UI 中的输入字段匹配，向最终用户指示支付响应的数据存在问题。例如，用户代理可能会在浏览器的 UI 中将用户的注意力吸引到错误的 errorFields，并以有助于用户修复每个错误的方式显示每个字段的值。类似地，如果传递了 error 成员，则在用户代理的 UI 中显示错误。在成员的值为空字符串的情况下，用户代理可以用适当的错误消息替换该值。
11. 否则，如果未传递 errorFields，则向最终用户发出信号以尝试重试支付。重新启用任何允许最终用户重试接受支付请求的 UI 元素。
12. 如果在显示用户界面时 document 不再是完全激活状态，或者到达此步骤时不再是，则：
    1. 关闭用户界面。
    2. 将 request 的支付相关浏览上下文的支付请求正在显示布尔值设置为 false。
13. 最后，当 retryPromise 解决时，将 response.[[retryPromise]] 设置为 null。
14. 返回 retryPromise。
    注意

    retryPromise 稍后将由用户接受支付请求算法解决，或由用户中止支付请求算法或中止更新拒绝。

WebIDLdictionary PaymentValidationErrors {
    PayerErrors payer;
    AddressErrors shippingAddress;
    DOMString error;
    object paymentMethod;
};

WebIDLdictionary PayerErrors {
    DOMString email;
    DOMString name;
    DOMString phone;
};

const payer = {
    email: "域名无效。",
    phone: "未知的国家代码。",
    name: "不在数据库中。",
};
await response.retry({ payer });

用户选择用于完成交易的支付方式的支付方式标识符。

由支付方式生成的object或字典，商家可以使用它来处理或验证交易（取决于支付方式）。

如果在传递给 PaymentRequest 构造函数的 PaymentOptions 中将 requestShipping 成员设置为 true，则 shippingAddress 将是用户选择的完整且最终的送货地址。

如果在传递给 PaymentRequest 构造函数的 PaymentOptions 中将 requestShipping 成员设置为 true，则 shippingOption 将是所选送货选项的 id 属性。

如果在传递给 PaymentRequest 构造函数的 PaymentOptions 中将 requestPayerName 成员设置为 true，则 payerName 将是用户提供的姓名。

如果在传递给 PaymentRequest 构造函数的 PaymentOptions 中将 requestPayerEmail 成员设置为 true，则 payerEmail 将是用户选择的电子邮件地址。

如果在传递给 PaymentRequest 构造函数的 PaymentOptions 中将 requestPayerPhone 成员设置为 true，则 payerPhone 将是用户选择的电话号码。

生成此支付响应的相应支付请求 id。

在支付请求被接受并将 PaymentResponse 返回给调用者之后，但在调用者调用 complete() 之前，支付请求用户界面保持待处理状态。此时，用户界面不应提供取消命令，因为已返回对支付请求的接受。但是，如果出现问题并且开发者从未调用 complete()，则用户界面将被阻止。

因此，实现可以为开发者调用 complete() 设置超时。如果超时到期，则实现将表现得如同调用了不带参数的 complete() 一样。

complete() 方法必须按以下方式操作：

1. 令 response 为this。
2. 如果 response.[[complete]] 为 true，则返回一个被拒绝的 promise，并带有 "InvalidStateError" DOMException。
3. 如果 response.[[retryPromise]] 不为 null，则返回一个被拒绝的 promise，并带有 "InvalidStateError" DOMException。
4. 令 promise 为一个新的 promise。
5. 令 serializedData 为将 details.data 序列化为 JSON 字符串的结果。
6. 如果序列化抛出异常，则返回一个被拒绝的 promise，并带有该异常。
7. 如果定义 response.methodName 的规范要求：
   1. 令 json 为使用 serializedData 调用 JSON 的 parse() 的结果。
   2. 令 idl 为将 json 转换为由定义 response.methodName 的规范指定的类型的 IDL 值的结果。
   3. 如果转换为 IDL 值抛出异常，则返回一个被拒绝的 promise，并带有该异常。
   4. 如果定义 response.methodName 的规范要求，则验证 idl 的成员。如果成员的值无效，则返回一个被拒绝的 promise，并带有 TypeError。
      注意: 恢复机会
8. 将 response.[[complete]] 设置为 true。
9. 返回 promise 并并行执行其余步骤。
10. 如果在显示用户界面时 document 不再是完全激活状态，或者到达此步骤时不再是，则：
    1. 关闭用户界面。
    2. 将 request 的支付相关浏览上下文的支付请求正在显示布尔值设置为 false。
11. 否则：
    1. 关闭任何剩余的用户界面。用户代理可以使用值 result 和 serializedData 来影响用户体验。
    2. 将 request 的支付相关浏览上下文的支付请求正在显示布尔值设置为 false。
    3. 用 undefined 解析 promise。

允许开发者处理“payerdetailchange”事件。

PaymentResponse 的实例是使用下表中的内部插槽创建的：

WebIDLdictionary AddressErrors {
    DOMString addressLine;
    DOMString city;
    DOMString country;
    DOMString dependentLocality;
    DOMString organization;
    DOMString phone;
    DOMString postalCode;
    DOMString recipient;
    DOMString region;
    DOMString sortingCode;
};

AddressErrors 字典的成员表示实际地址特定部分的验证错误。每个字典成员都有双重功能：首先，它的存在表示地址的特定部分存在验证错误。其次，字符串值允许开发者描述验证错误（以及最终用户如何修复错误）。

addressLine 成员

表示地址行存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 addressLine 属性值的输入字段。

city 成员

表示城市存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 city 属性值的输入字段。

country 成员

表示国家/地区存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 country 属性值的输入字段。

dependentLocality 成员

表示下属地区存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 dependentLocality 属性值的输入字段。

organization 成员

表示组织存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 organization 属性值的输入字段。

phone 成员

表示电话号码存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 phone 属性值的输入字段。

postalCode 成员

表示邮政编码存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 postalCode 属性值的输入字段。

recipient 成员

表示收件人存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 addressLine 属性值的输入字段。

region 成员

表示地区存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 region 属性值的输入字段。

sortingCode 成员

分拣码存在验证错误。在用户代理的 UI 中，此成员对应于提供 ContactAddress 的 sortingCode 属性值的输入字段。

WebIDL[SecureContext, Exposed=Window]
interface PaymentMethodChangeEvent : PaymentRequestUpdateEvent {
    constructor(DOMString type, optional PaymentMethodChangeEventInit eventInitDict = {});
    readonly attribute DOMString methodName;
    readonly attribute object? methodDetails;
};

WebIDLdictionary PaymentMethodChangeEventInit : PaymentRequestUpdateEventInit {
    DOMString methodName = "";
    object? methodDetails = null;
};

WebIDL[SecureContext, Exposed=Window]
interface PaymentRequestUpdateEvent : Event {
    constructor(DOMString type, optional PaymentRequestUpdateEventInit eventInitDict = {});
    undefined updateWith(Promise<PaymentDetailsUpdate> detailsPromise);
};

PaymentRequestUpdateEvent 使开发者能够响应用户交互来更新支付请求的详细信息。

WebIDLdictionary PaymentRequestUpdateEventInit : EventInit {};

“可以付款”算法检查用户代理是否支持使用构建 PaymentRequest 时所用的付款方式进行付款。

1. 令 request 为调用该方法的 PaymentRequest 对象。
2. 如果 request.[[state]] 不是“created”，则返回一个被拒绝的 promise，并附带一个“InvalidStateError”DOMException。
3. 可选地，由顶级浏览上下文自行决定，返回一个被拒绝的 promise，并附带一个“NotAllowedError”DOMException。
   注意

   这允许用户代理应用启发式方法来检测和防止滥用调用方法进行指纹识别，例如创建具有各种受支持付款方式的 PaymentRequest 对象，并相继对它们触发“可以付款”算法。例如，用户代理可能会根据顶级浏览上下文或进行这些调用的时间段来限制可以进行的成功调用次数。

4. 令 hasHandlerPromise 为一个新的 promise。
5. 返回 hasHandlerPromise，并并行执行其余步骤。
6. 对于 request.[[serializedMethodData]] 中的每个 paymentMethod 元组：
   1. 令 identifier 为 paymentMethod 元组中的第一个元素。
   2. 如果用户代理具有支持处理 identifier 付款请求的付款处理程序，则使用 true 解析 hasHandlerPromise 并终止此算法。
7. 使用 false 解析 hasHandlerPromise。

当用户提供新的送货地址时，会运行送货地址更改算法。它必须运行以下步骤：

1. 令 request 为用户正在与之交互的 PaymentRequest 对象。
2. 在用户交互任务源上排队一个任务以运行以下步骤：
   1. 注意：收件人信息的隐私

      redactList 限制了 API 与商家共享的关于收件人的个人信息量。

      对于商家而言，生成的 ContactAddress 对象提供了足够的信息（例如，用于计算运费），但在大多数情况下，不足以实际定位和唯一识别收件人。

      不幸的是，即使有 redactList，也无法保证收件人的匿名性。这是因为在某些国家/地区，邮政编码非常精细，可以唯一识别收件人。

   2. 令 redactList 为空列表。将 redactList 设置为 « "organization", "phone", "recipient", "addressLine" »。
   3. 令 address 为使用 redactList 运行从用户提供的输入创建联系人地址的步骤的结果。
   4. 将 request.shippingAddress 设置为 address。
   5. 使用 request 和 "shippingaddresschange" 运行PaymentRequest 更新算法。

当用户选择新的送货选项时，会运行送货选项更改算法。它必须运行以下步骤：

1. 令 request 为用户正在与之交互的 PaymentRequest 对象。
2. 在用户交互任务源上排队一个任务以运行以下步骤：
   1. 将 request 上的 shippingOption 属性设置为用户提供的 PaymentShippingOption 的 id 字符串。
   2. 使用 request 和 "shippingoptionchange" 运行PaymentRequest 更新算法。

当用户使用 methodDetails（一个字典、object 或 null）和 methodName（一个表示用户正在与之交互的支付处理程序的支付方式标识符的 DOMString）更改支付方式时，支付处理程序 可以运行支付方式更改算法。

1. 令 request 为用户正在与之交互的 PaymentRequest 对象。
2. 在用户交互任务源上排队一个任务以运行以下步骤：
   1. 断言：request.[[updating]] 为 false。一次只能进行一次更新。
   2. 断言：request.[[state]] 为 "interactive"。
   3. 使用 PaymentMethodChangeEvent 在 request 上触发一个名为 "paymentmethodchange" 的事件，其 methodName 属性初始化为 methodName，其 methodDetails 属性初始化为 methodDetails。

PaymentRequest 更新算法由上述其他算法运行，以触发一个事件，指示用户已对名为 request 的 PaymentRequest 进行了更改，事件名称为 name：

1. 断言：request.[[updating]] 为 false。一次只能进行一次更新。
2. 断言：request.[[state]] 为 "interactive"。
3. 令 event 为使用 PaymentRequestUpdateEvent 接口创建事件的结果。
4. 将 event 的 type 属性初始化为 name。
5. 在 request 上分派 event。
6. 如果 event.[[waitForUpdate]] 为 true，则禁用用户界面中可能导致触发另一个更新事件的任何部分。
7. 否则，将 event.[[waitForUpdate]] 设置为 true。

当用户在用户界面中更改付款人姓名、付款人电子邮件或付款人电话时，用户代理必须运行付款人详细信息更改算法：

1. 令 request 为用户正在与之交互的 PaymentRequest 对象。
2. 如果 request.[[response]] 为 null，则返回。
3. 令 response 为 request.[[response]]。
4. 在用户交互任务源上排队一个任务以运行以下步骤：
   1. 断言：request.[[updating]] 为 false。
   2. 断言：request.[[state]] 为 "interactive"。
   3. 令 options 为 request.[[options]]。
   4. 如果付款人姓名已更改且 options.requestPayerName 为 true：
      1. 将 response.payerName 属性设置为 付款人姓名。
   5. 如果付款人电子邮件已更改且 options.requestPayerEmail 为 true：
      1. 将 response.payerEmail 设置为 付款人电子邮件。
   6. 如果付款人电话已更改且 options.requestPayerPhone 为 true：
      1. 将 response.payerPhone 设置为 付款人电话。
   7. 令 event 为使用 PaymentRequestUpdateEvent 创建事件的结果。
   8. 将 event 的 type 属性初始化为 "payerdetailchange"。
   9. 在 response 上分派 event。
   10. 如果 event.[[waitForUpdate]] 为 true，则禁用用户界面中可能导致再次触发付款人详细信息更改的任何部分。
   11. 否则，将 event.[[waitForUpdate]] 设置为 true。

当用户接受支付请求并确认他们想要支付时，会运行用户接受支付请求算法。它必须在用户交互任务源上排队一个任务以执行以下步骤：

1. 令 request 为用户正在与之交互的 PaymentRequest 对象。
2. 如果 request.[[updating]] 为 true，则终止此算法并且不执行任何进一步操作。用户代理用户界面应该确保这种情况永远不会发生。
3. 如果 request.[[state]] 不是“interactive”，则终止此算法并且不执行任何进一步操作。用户代理用户界面应该确保这种情况永远不会发生。
4. 如果 request.[[options]] 的 requestShipping 值为 true，那么如果 request 的 shippingAddress 属性为 null，或者如果 request 的 shippingOption 属性为 null，则终止此算法并且不执行任何进一步操作。用户代理应该确保这种情况永远不会发生。
5. 如果 request.[[response]] 不为 null，则令 isRetry 为 true，否则为 false。
6. 如果 isRetry 为 true，则令 response 为 request.[[response]]，否则为一个新的 PaymentResponse。
7. 如果 isRetry 为 false，则初始化新创建的 response：
   1. 将 response.[[request]] 设置为 request。
   2. 将 response.[[retryPromise]] 设置为 null。
   3. 将 response.[[complete]] 设置为 false。
   4. 将 response 的 requestId 属性值设置为 request.[[details]].id 的值。
   5. 将 request.[[response]] 设置为 response。
8. 令 handler 为 request.[[handler]]。
9. 将 response 的 methodName 属性值设置为 handler 的支付方式标识符。
10. 将 response 的 details 属性值设置为运行 handler 的响应支付请求的步骤所产生的对象。
11. 如果 request.[[options]] 的 requestShipping 值为 false，则将 response 的 shippingAddress 属性值设置为 null。否则：
    1. 令 shippingAddress 为从用户提供的输入创建联系人地址的结果。
    2. 将 response 的 shippingAddress 属性值设置为 shippingAddress。
    3. 将 request 的 shippingAddress 属性值设置为 shippingAddress。
12. 如果 request.[[options]] 的 requestShipping 值为 true，则将 response 的 shippingOption 属性设置为 request 的 shippingOption 属性的值。否则，将其设置为 null。
13. 如果 request.[[options]] 的 requestPayerName 值为 true，则将 response 的 payerName 属性设置为用户提供的付款人姓名，如果未提供则为 null。否则，将其设置为 null。
14. 如果 request.[[options]] 的 requestPayerEmail 值为 true，则将 response 的 payerEmail 属性设置为用户提供的付款人电子邮件地址，如果未提供则为 null。否则，将其设置为 null。
15. 如果 request.[[options]] 的 requestPayerPhone 值为 true，则将 response 的 payerPhone 属性设置为用户提供的付款人电话号码，如果未提供则为 null。设置 payerPhone 值时，用户代理应该将电话号码格式化以符合 [E.164]。
16. 将 request.[[state]] 设置为“closed”。
17. 如果 isRetry 为 true，则使用 undefined 解析 response.[[retryPromise]]。否则，使用 response 解析 request.[[acceptPromise]]。

当用户通过当前交互式用户界面中止支付请求时，会运行用户中止支付请求算法。它必须在用户交互任务源上排队一个任务以执行以下步骤：

1. 令 request 为用户正在与之交互的 PaymentRequest 对象。
2. 如果 request.[[state]] 不是“interactive”，则终止此算法并且不执行任何进一步操作。用户代理用户界面应该确保这种情况永远不会发生。
3. 将 request.[[state]] 设置为“closed”。
4. 将 request 的与支付相关的浏览上下文的支付请求正在显示布尔值设置为 false。
5. 令 error 为一个“AbortError”DOMException。
6. 令 response 为 request.[[response]]。
7. 如果 response 不为 null：
   1. 将 response.[[complete]] 设置为 true。
   2. 断言：response.[[retryPromise]] 不为 null。
   3. 使用 error 拒绝 response.[[retryPromise]]。
8. 否则，使用 error 拒绝 request.[[acceptPromise]]。
9. 中止当前用户交互并关闭任何剩余的用户界面。

更新 PaymentRequest 的详细信息算法接受一个 PaymentDetailsUpdate detailsPromise、一个 PaymentRequest request 和一个 pmi（一个 DOMString 或 null，即支付方式标识符）。这些步骤取决于 detailsPromise 的解决情况。如果 detailsPromise 永远不解决，则支付请求将被阻塞。用户代理应该为用户提供中止支付请求的方法。如果 detailsPromise 在合理的时间内没有解决，实现可以选择为待处理的更新实现超时。

如果发生超时、用户手动中止或支付处理程序决定中止此特定支付，用户代理必须运行用户中止支付请求算法。

1. 将 request.[[updating]] 设置为 true。
2. 并行地，禁用允许用户接受支付请求的用户界面。这是为了确保在用户界面更新任何新详细信息之前不接受支付。
3. 当 detailsPromise 被拒绝时：
   1. 使用 request 和一个“AbortError”DOMException 中止更新。
4. 当 detailsPromise 被满足且值为 value 时：
   1. 令 details 为将 value 转换为 PaymentDetailsUpdate 字典的结果。如果此操作抛出异常，则使用 request 和抛出的异常中止更新。
   2. 令 serializedModifierData 为一个空列表。
   3. 令 selectedShippingOption 为 null。
   4. 令 shippingOptions 为一个空的 sequence<PaymentShippingOption>。
   5. 验证并规范化详细信息：
      1. 如果 details 的 total 成员存在，则：
         1. 检查并规范化总金额 details.total.amount。如果抛出异常，则使用 request 和该异常中止更新。
      2. 如果 details 的 displayItems 成员存在，则对于 details.displayItems 中的每个 item：
         1. 检查并规范化金额 item.amount。如果抛出异常，则使用 request 和该异常中止更新。
      3. 如果 details 的 shippingOptions 成员存在，并且 request.[[options]].requestShipping 为 true，则：
         1. 令 seenIDs 为一个空集合。
         2. 对于 details.shippingOptions 中的每个 option：
            1. 检查并规范化金额 option.amount。如果抛出异常，则使用 request 和该异常中止更新。
            2. 如果 seenIDs[option.{{PaymentShippingOption/id}}] 存在，则使用 request 和一个 TypeError 中止更新。
            3. 将 option.id 附加到 seenIDs。
            4. 将 option 附加到 shippingOptions。
            5. 如果 option.selected 为 true，则将 selectedShippingOption 设置为 option.id。
      4. 如果 details 的 modifiers 成员存在，则：
         1. 令 modifiers 为序列 details.modifiers。
         2. 令 serializedModifierData 为一个空列表。
         3. 对于 modifiers 中的每个 PaymentDetailsModifier modifier：
            1. 使用 modifier.supportedMethods 运行验证支付方式标识符的步骤。如果返回 false，则使用 request 和一个 RangeError 异常中止更新。可选地，通知开发者支付方式标识符无效。
            2. 如果 modifier 的 total 成员存在，则：
               1. 检查并规范化总金额 modifier.total.amount。如果抛出异常，则使用 request 和该异常中止更新。
            3. 如果 modifier 的 additionalDisplayItems 成员存在，则对于 modifier.additionalDisplayItems 中的每个 PaymentItem item：
               1. 检查并规范化金额 item.amount。如果抛出异常，则使用 request 和该异常中止更新。
            4. 如果 modifier 的 data 成员缺失，则令 serializedData 为 null。否则，令 serializedData 为将 modifier.data 序列化为 JSON 字符串的结果。如果抛出异常，则使用 request 和该异常中止更新。
            5. 将 serializedData 添加到 serializedModifierData。
            6. 如果 modifier 的 data 成员存在，则移除它。
   6. 如果 paymentMethodErrors 成员存在且 identifier 不为 null：
      1. 如果定义 pmi 的规范要求，则将 paymentMethodErrors 转换为 IDL 值。
      2. 如果转换导致异常 error，则使用 error 中止更新。
      3. 支付处理程序应该为 paymentMethodErrors 的每个相关错误字段显示错误。
   7. 使用新详细信息更新 PaymentRequest：
      1. 如果 details 的 total 成员存在，则：
         1. 将 request.[[details]].total 设置为 details.total。
      2. 如果 details 的 displayItems 成员存在，则：
         1. 将 request.[[details]].displayItems 设置为 details.displayItems。
      3. 如果 details 的 shippingOptions 成员存在，并且 request.[[options]].requestShipping 为 true，则：
         1. 将 request.[[details]].shippingOptions 设置为 shippingOptions。
         2. 将 request 的 shippingOption 属性的值设置为 selectedShippingOption。
      4. 如果 details 的 modifiers 成员存在，则：
         1. 将 request.[[details]].modifiers 设置为 details.modifiers。
         2. 将 request.[[serializedModifierData]] 设置为 serializedModifierData。

      5. 如果 request.[[options]].requestShipping 为 true，并且 request.[[details]].shippingOptions 为空，则开发者已表示对于当前选择的送货地址（由 request 的 shippingAddress 给出）没有有效的送货选项。

         在这种情况下，用户代理应该显示一个错误来指示这一点，并且可以指示当前选择的送货地址在某种程度上无效。用户代理应该使用 details 的 error 成员（如果存在）来提供更多关于为什么该地址没有有效送货选项的信息。

         此外，如果 details["shippingAddressErrors"] 成员存在，用户代理应该为送货地址的每个错误字段专门显示一个错误。这是通过将 AddressErrors 的每个存在的成员与所显示用户界面中的相应输入字段进行匹配来完成的。

         类似地，如果 details["payerErrors"] 成员存在且 request.[[options]] 的 requestPayerName、requestPayerEmail 或 requestPayerPhone 为 true，则为每个错误字段专门显示一个错误。

         同样，如果 details.paymentMethodErrors 存在，则为特定支付方式的每个错误输入字段专门显示错误。

5. 将 request.[[updating]] 设置为 false。
6. 根据 request 中任何已更改的值更新用户界面。重新启用在此算法运行之前禁用的用户界面元素。

支付方式所有者制定关于如何使用为该支付方式收集的用户数据的隐私政策。Payment Request API 明确规定数据将用于完成交易的目的，并且与此 API 相关的用户体验传达了这一意图。收款人有责任确保任何数据使用都符合支付方式政策。对于超出完成交易范围的任何允许使用，收款人应向用户清楚地传达该使用情况。

用户代理不得在未经用户同意的情况下与开发者共享有关用户的信息（例如送货地址）。

特别是，PaymentMethodData 的 data 和 PaymentResponse 的 details 成员允许任意交换数据。鉴于现有支付方式使用的数据模型范围广泛，在此 API 中规定数据细节会限制其有用性。details 成员携带来自支付处理程序的数据，无论是基于 Web 的（由 支付处理程序 API 定义）还是专有的。用户代理不得支持支付处理程序，除非它们包含足够的用户同意机制（例如交易各方的知情权和表明共享数据意图的机制）。

用户代理不得出于促进交易完成以外的任何目的共享 displayItems 成员或 additionalDisplayItems 成员的值。

PaymentMethodChangeEvent 使收款人能够根据所选支付方式的特定信息更新显示的总额。例如，与所选支付方式关联的账单地址可能会影响税款计算（例如增值税），并且希望用户界面在付款人完成交易之前准确显示总额。同时，希望在完成付款之前尽可能少地共享信息。因此，当支付方式定义用户更改支付方式时的步骤时，重要的是尽量减少通过 PaymentMethodChangeEvent 的 methodDetails 属性共享的数据。最小化共享数据的要求和方法可能因支付方式而异，并且可能包括：

• 对实际地址使用“redactList”。当前规范使用“redactList”来编辑地址行、组织、电话号码和收件人（来自 shippingAddress）。
• 支持收款人识别要从支付方式响应数据（通过 PaymentResponse.details 返回）中排除或包含的特定元素的说明。收款人可以通过 PaymentMethodData.data 提供这些说明，从而使支付方式定义能够在不需要更改当前 API 的情况下进行演变。

在共享隐私敏感信息可能对用户不明显的情况下（例如，当更改支付方式时），建议用户代理告知用户正在与商家共享哪些确切信息。

canMakePayment() 方法为不同的支付方式提供功能检测。如果将来有大量支付方式可用，它可能会成为一个指纹识别向量。用户代理应保护用户免受该方法的滥用。例如，用户代理可以通过以下方式减少用户指纹识别：

• 限制使用不同参数调用的频率。

对于速率限制，用户代理可能会查看来自以下位置的重复调用：

• 相同的可注册域。
• 顶级浏览上下文。或者，用户代理可以完全阻止已知不良行为者的来源访问 API。
• iframe 或弹出窗口的来源。

这些速率限制技术旨在增加与重复调用相关的成本，无论是管理多个可注册域的成本，还是打开多个窗口（选项卡或弹出窗口）的用户体验摩擦。

如果用户代理不要求用户激活作为 show() 方法的一部分，则应考虑一些额外的安全缓解措施。不要求用户激活会增加垃圾邮件和点击劫持攻击的风险，因为它允许在用户没有立即与页面交互的情况下启动支付请求 UI。

为了缓解垃圾邮件，用户代理可以决定在某个阈值之后强制执行用户激活要求，例如在用户已经在当前页面上看到没有用户激活的支付请求 UI 之后。为了缓解点击劫持攻击，用户代理可以实现一个时间阈值，在该阈值内，在显示对话框后立即忽略点击。

show() 的步骤 6 中存在另一个相关的缓解措施，其中文档必须可见才能启动用户交互。