Payment Request API（支付请求 API）

PaymentRequest 使用所提供的 PaymentMethodData methodData 序列构建，其中包括任何 支付方式 特定的 data、PaymentDetailsInit details 以及 PaymentOptions options。

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

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) 方法 必须 (MUST) 按以下方式操作

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

   这允许用户代理不需要用户激活，例如支持重定向流程，因为在重定向时可能不存在用户激活。有关安全考量，请参阅 19.9 用户激活要求。

   另请参阅 issue #1022，关于在规范中提供更多指导的讨论，即用户代理何时应该或不应该要求用户激活以进行 show()。

3. 否则，消耗 相关全局对象 的用户激活。
4. 设 document 为 request 的 相关全局对象 的 关联 Document。
5. 如果 document 未 完全活跃 (fully active)，则返回 一个被拒绝的 promise，并带有 "InvalidStateError" 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 解析 该元组第二个元素的结果。
    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 进行交互。用户代理 应当 (SHOULD) 在呈现支付方式时优先考虑用户的偏好。用户界面 应当 (SHOULD) 使用与 document 的 文档元素 的 语言（如有）匹配的语言和基于本地的格式来呈现，如果该语言不可用，则使用适当的备用格式。

    注：支付用户界面的本地化
20. 如果传递了 detailsPromise，则
    1. 使用 detailsPromise、request 和 null 运行 更新 PaymentRequest 详情算法。
    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。可选地，用户代理 应当 (SHOULD) 将 request 中的适当数据发送给用户选择的 支付处理器，以便引导用户完成支付流程。这包括 request 的各种属性和其他 内部槽位（出于隐私原因，某些 可以 (MAY) 被排除）。

    [[serializedModifierData]] 内部槽位 中多个适用修饰符的处理属于 支付处理器 特有，不在本规范范围内。尽管如此，建议 (RECOMMENDED) 支付处理器 对 [[serializedModifierData]] 列表中的项使用“后者获胜 (last one wins)”的方法：也就是说，列表末尾的项总是优先于列表开头的任何项（参见下例）。

    acceptPromise 稍后将由 用户接受支付请求算法、用户中止支付请求算法（通过用户界面交互触发），或 支付处理器指示内部错误算法 解析或拒绝。

    如果在显示用户界面时 document 停止 完全活跃，或者到达此步骤时不再是完全活跃状态，则

    1. 关闭用户界面。
    2. 将 request.[[state]] 设为 "closed"。
    3. 将 request 的 支付相关浏览上下文 的 支付请求正在显示 布尔值设为 false。
    4. 在 用户交互任务源 上排队一个任务，以 拒绝 acceptPromise，并带有 "AbortError" DOMException。

abort() 方法 必须 (MUST) 按以下方式操作

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() 方法必须运行可进行支付算法。

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

PaymentRequest 的 shippingType 属性是用于完成交易的送货类型。其值要么是一个 PaymentShippingType 枚举值，要么是在构造期间未由开发者提供时的 null（参见 PaymentOptions 的 shippingType 成员）。

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，如果用户接受支付请求，它将被解析。
[[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，则用户代理会选择序列中的最后一个。

shippingOptions 成员仅在 PaymentRequest 使用 PaymentOptions 构造且 requestShipping 设置为 true 时使用。

注

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 可在 error 成员中包含一条消息，如果 PaymentDetailsUpdate 指出不存在有效的 shippingOptions（且 PaymentRequest 在构造时将 requestShipping 选项设置为 true），则该消息将显示给用户。

total 成员

包含非负 amount 的 PaymentItem。

注

本规范中接受 PaymentDetailsUpdate 字典的算法，如果 total.amount.value 为负数，则会抛出异常。

shippingAddressErrors 成员

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

payerErrors 成员

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

paymentMethodErrors 成员

支付方式特定错误。

retry(errorFields) 方法必须按照以下方式执行

1. 令 response 为 this。
2. 令 request 为 response.[[request]]。
3. 令 document 为 request 的相关全局对象的关联 Document。
4. 如果 document 不处于完全活动状态，则返回一个被拒绝的 Promise，其拒绝理由为 "InvalidStateError" 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
11. 如果以下任何一项为 true，可选地在开发者控制台中显示警告
12. request.[[options]].requestPayerName 为 false，且 errorFields.payer.name 存在。
13. request.[[options]].requestPayerEmail 为 false，且 errorFields.payer.email 存在。
14. request.[[options]].requestPayerPhone 为 false，且 errorFields.payer.phone 存在。
15. request.[[options]].requestShipping 为 false，且 errorFields.shippingAddress 存在。

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

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

const payer = {
  email: "The domain is invalid.",
  phone: "Unknown country code.",
  name: "Not in database.",
};
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，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。
3. 如果 response.[[retryPromise]] 不为 null，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。
4. 令 promise 为一个新 Promise。
5. 令 serializedData 为将 details.data 序列化为 JSON 字符串的结果。
6. 如果序列化抛出异常，则返回一个以该异常 拒绝的 Promise。
7. 如果定义 response.methodName 的规范有要求
   1. 令 json 为调用 JSON 的 parse() 方法并传入 serializedData 的结果。
   2. 令 idl 为将 json 转换为定义 response.methodName 的规范所指定类型的 IDL 值的结果。
   3. 如果转换为 IDL 值抛出异常，则返回一个以该异常 拒绝的 Promise。
   4. 如果定义 response.methodName 的规范有要求，则验证 idl 的成员。如果成员的值无效，则返回一个以 TypeError 拒绝的 Promise。
      注: 恢复的机会
8. 将 response.[[complete]] 设为 true。
9. 返回 promise 并并行执行剩余步骤。
10. 如果在显示用户界面时 document 停止 完全活跃，或者到达此步骤时不再是完全活跃状态，则
    1. 关闭用户界面。
    2. 将 request 的 支付相关浏览上下文的 支付请求显示中布尔值设为 false。
    3. 在 用户交互任务源上排队一个任务，以使用 "AbortError" DOMException 拒绝 promise。
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]] 不为 "已创建"，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。
3. 设 document 为 request 的 相关全局对象 的 关联 Document。
4. 如果 document 未 完全活跃 (fully active)，则返回 一个被拒绝的 promise，并带有 "InvalidStateError" DOMException。
5. 可选地，由顶级浏览上下文自行决定，返回一个以 "NotAllowedError" DOMException 拒绝的 Promise。
   注

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

6. 令 hasHandlerPromise 为一个新 Promise。
7. 返回 hasHandlerPromise，并并行执行其余步骤。
8. 对于 request.[[serializedMethodData]] 中的每个 paymentMethod 元组
9. 设 identifier 为 paymentMethod 元组的第一个元素。
10. 如果用户代理有一个支持处理 identifier 支付请求的支付处理程序，则用 true 解析 hasHandlerPromise 并终止此算法。

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

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

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

   对于商户而言，由此产生的 ContactAddress 对象提供了足够的信息来（例如）计算运费，但在大多数情况下，不足以在物理上定位和唯一识别收件人。

   不幸的是，即使有了 redactList，收件人的匿名性也无法保证。这是因为在一些国家，邮政编码的粒度非常细，以至于它们可以唯一识别收件人。

4. 令 redactList 为空列表。将 redactList 设为 « "organization", "phone", "recipient", "addressLine" »。
5. 令 address 为运行通过用户提供的输入创建 contactaddress 步骤（传入 redactList）的结果。
6. 将 request.shippingAddress 设为 address。
7. 使用 request 和 "shippingaddresschange" 运行 PaymentRequest 更新算法。

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

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

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

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

1. 断言: request.[[updating]] 为 false。一次只能进行一个更新。
2. 断言: request.[[state]] 为 "交互中"。
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. 在 用户交互任务源上排队一个任务以运行以下步骤
5. 断言：request.[[updating]] 为 false。
6. 断言：request.[[state]] 为 "交互中"。
7. 令 options 为 request.[[options]]。
8. 如果 付款人姓名 发生变化且 options.requestPayerName 为 true
   1. 将 response.payerName 属性设置为 付款人姓名。
9. 如果 付款人电子邮件 发生变化且 options.requestPayerEmail 为 true
   1. 将 response.payerEmail 设置为 付款人电子邮件。
10. 如果 付款人电话 发生变化且 options.requestPayerPhone 为 true
    1. 将 response.payerPhone 设置为 付款人电话。
11. 令 event 为使用 PaymentRequestUpdateEvent 创建事件 的结果。
12. 将 event 的 type 属性初始化为 "payerdetailchange"。
13. 在 response 上 分发 event。
14. 如果 event.[[waitForUpdate]] 为 true，则禁用用户界面中任何可能导致再次触发付款人详细信息更改的部分。
15. 否则，将 event.[[waitForUpdate]] 设置为 true。

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

1. 令 request 为用户正在交互的 PaymentRequest 对象。
2. 如果 request.[[updating]] 为 true，则终止此算法且不采取进一步操作。用户代理 用户界面 应该 确保这种情况永远不会发生。
3. 如果 request.[[state]] 不为 "交互中"，则终止此算法且不采取进一步操作。用户代理 用户界面 应该 确保这种情况永远不会发生。
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。否则，
12. 令 shippingAddress 为 从用户提供的输入创建 ContactAddress 的结果。
13. 将 response 的 shippingAddress 属性值设置为 shippingAddress。
14. 将 request 的 shippingAddress 属性值设置为 shippingAddress。

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

1. 令 request 为用户正在交互的 PaymentRequest 对象。
2. 若 request.[[state]] 不为 "交互中"，则终止此算法且不采取进一步操作。用户代理 用户界面 应该 确保这种情况永远不会发生。
3. 将 request.[[state]] 设置为 "已关闭"。
4. 将 request 的 与支付相关的浏览上下文 的 付款请求显示中 布尔值设置为 false。
5. 令 error 为一个 "AbortError" DOMException。
6. 令 response 为 request.[[response]]。
7. 若 response 不为 null
8. 将 response.[[complete]] 设置为 true。
9. 断言：response.[[retryPromise]] 不为 null。
10. 用 error 拒绝 response.[[retryPromise]]。

付款处理程序指示内部错误算法 在用户选择的 付款处理程序 遇到阻止其完成支付的内部错误时运行。发生此情况的原因包括操作系统终止了付款处理程序（例如，由于内存压力），或付款处理程序自身遇到了不可恢复的错误。

1. 在用户交互任务源上排队一个任务以执行以下步骤
   1. 令 request 为用户正在交互的 PaymentRequest 对象。
   2. 若 request.[[state]] 不为 "交互中"，则终止此算法且不采取进一步操作。
   3. 令 error 为一个 "OperationError" DOMException。
   4. 将 request.[[state]] 设置为 "已关闭"。
   5. 将 request 的 与支付相关的浏览上下文 的 付款请求显示中 布尔值设置为 false。
   6. 令 response 为 request.[[response]]。
   7. 若 response 不为 null
   8. 将 response.[[complete]] 设置为 true。
   9. 断言：response.[[retryPromise]] 不为 null。
   10. 用 error 拒绝 response.[[retryPromise]]。
2. 否则，用 error 拒绝 request.[[acceptPromise]]。
3. 可选地，向用户显示一条通用错误消息，表明无法完成付款。
4. 可选地，将详细错误信息记录到开发者控制台以进行调试。
5. 中止当前的用户交互并关闭所有剩余的用户界面。

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

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

1. 将 request.[[updating]] 设置为 true。
2. 并行地，禁用允许用户接受付款请求的用户界面。这是为了确保在用户界面更新了任何新详细信息之前，不会接受付款。
3. 在拒绝 detailsPromise 时
4. 用 request 和一个 "AbortError" DOMException 中止更新。

支付方式 所有者为收集用于支付方式的用户数据如何使用制定隐私政策。Payment Request API 明确期望数据将用于完成交易的目的，并且与此 API 关联的用户体验传达了该意图。收款方有责任确保任何数据使用符合支付方式政策。对于完成交易之外的任何允许用途，收款方应向用户明确传达该用途。

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

特别地，PaymentMethodData 的 data 和 PaymentResponse 的 details 成员允许进行任意数据交换。鉴于现有支付方式使用的数据模型范围广泛，在本 API 中规定数据细节将限制其有用性。details 成员承载来自付款处理程序的数据，无论是基于 Web 的（根据 Web-based Payment Handler API 定义）还是专有的。用户代理 不得 支持付款处理程序，除非它们包含足够的获取用户同意的机制（例如了解交易各方以及展示共享数据意图的机制）。

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

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

• 对 物理地址 使用 "redactList"（编校列表）。本规范利用 "redactList" 从 shippingAddress 中编校 地址行、组织、电话号码 和 收件人。
• 支持收款方的指令，识别从 支付方式 响应数据（通过 PaymentResponse.details 返回）中排除或包含的特定元素。收款方可以通过 PaymentMethodData.data 提供这些指令，使 支付方式 定义能够在无需更改当前 API 的情况下演进。

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

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

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

为了进行速率限制，用户代理可能会查看来自以下方面的重复调用

• 相同的 可注册域名。
• 顶级浏览上下文。或者，用户代理可以完全屏蔽已知为恶意参与者的 来源 对该 API 的访问。
• iframe 或弹出窗口的 来源。

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

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

为了缓解垃圾邮件，用户代理可以决定在达到某个阈值后执行用户激活要求，例如在用户已经无需在当前页面上进行用户激活即被显示付款请求 UI 之后。为了缓解点击劫持攻击，用户代理可以在对话框显示后立即忽略点击的时间阈值。

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