基于 Web 的支付处理器 API

如果在商家调用 show() 方法时，某个基于 Web 的支付处理器尚未注册， 用户代理可以允许 用户在交易过程中注册这个基于 Web 的支付处理器 （“即时”）。

本节其余内容为非规范性内容。

用户代理可以通过推导 基于 Web 的支付处理器信息来执行即时安装，这些信息来自通过 支付方式 清单找到的内容，而该清单是通过商家请求的 基于 URL 的 支付方式 标识符发现的。

WebIDLpartial interface ServiceWorkerRegistration {
  [SameObject] readonly attribute PaymentManager paymentManager;
};

paymentManager 属性公开了基于 Web 的支付 处理器管理功能。

WebIDL[SecureContext, Exposed=(Window)]
interface PaymentManager {
  attribute DOMString userHint;
  Promise<undefined> enableDelegations(sequence<PaymentDelegation> delegations);
};

PaymentManager 由基于 Web 的支付处理器用来 管理其支持的委托项。

WebIDLenum PaymentDelegation {
  "shippingAddress",
  "payerName",
  "payerPhone",
  "payerEmail"
};

"shippingAddress"

基于 Web 的支付处理器将在需要时提供收货地址。

"payerName"

基于 Web 的支付处理器将在需要时提供付款方姓名。

"payerPhone"

基于 Web 的支付处理器将在需要时提供付款方电话。

"payerEmail"

基于 Web 的支付处理器将在需要时提供付款方电子邮件。

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler oncanmakepayment;
};

CanMakePaymentEvent 用作一个信号， 用于表明 基于 Web 的支付处理器是否能够响应支付请求。

WebIDL[Exposed=ServiceWorker]
interface CanMakePaymentEvent : ExtendableEvent {
  constructor(DOMString type);
  undefined respondWith(Promise<boolean> canMakePaymentResponse);
};

在收到一个 PaymentRequest 后，用户 代理 必须 运行以下步骤：

1. 如果用户代理设置禁止使用 CanMakePaymentEvent（例如，在私密 浏览模式下）， 则终止这些步骤。
2. 令 registration 为一个 ServiceWorkerRegistration。
3. 如果未找到 registration，则终止这些步骤。

4. 使用 CanMakePaymentEvent 在 registration 上触发 触发功能事件 "canmakepayment"。

给定一个 PaymentMethodData 以及 一个在支付 方式标识符上匹配的基于 Web 的支付处理器，如果该基于 Web 的支付处理器可用于 支付，则此算法返回 true：

1. 令 methodName 为 支付方式标识符 字符串，该字符串在 PaymentMethodData 中指定。
2. 令 methodData 为 PaymentMethodData 的支付方式特定数据。
3. 令 paymentHandlerOrigin 为该 基于 Web 的支付处理器的 ServiceWorkerRegistration 作用域 URL 的源。
4. 令 paymentMethodManifest 为 methodName 的摄取并 解析后的 支付方式 清单。
5. 如果 methodName 是一个基于 URL 的 支付方式 标识符，且在 paymentMethodManifest 中其 受支持的 源包含字符串 "*"，则返回 true。
6. 否则，如果基于 URL 的 支付方式标识符 methodName 与 paymentHandlerOrigin 具有相同的源，则在该 基于 Web 的支付处理器中触发 CanMakePaymentEvent， 并返回结果。
7. 否则，如果 paymentMethodManifest 中的 受支持的 源是一个包含 paymentHandlerOrigin 的有序 源集合，则在该 基于 Web 的支付处理器中触发 CanMakePaymentEvent 并返回 结果。
8. 否则，返回 false。

本规范扩展了 ServiceWorkerGlobalScope 接口。

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler onpaymentrequest;
};

PaymentRequestDetailsUpdate 包含更新后的 总额（可选地包含修饰项和配送选项）以及由于用户在 基于 Web 的支付处理器中选择某种支付方式、配送 地址或配送选项而产生的可能错误。

WebIDLdictionary PaymentRequestDetailsUpdate {
  DOMString error;
  PaymentCurrencyAmount total;
  sequence<PaymentDetailsModifier> modifiers;
  sequence<PaymentShippingOption> shippingOptions;
  object paymentMethodErrors;
  AddressErrors shippingAddressErrors;
};

PaymentRequestEvent 表示在用户选择之后， Payment Handler 可用的数据和方法。用户代理 会将 PaymentRequest 中可用数据的一个子集传递给 Payment Handler。

WebIDL[Exposed=ServiceWorker]
interface PaymentRequestEvent : ExtendableEvent {
  constructor(DOMString type, optional PaymentRequestEventInit eventInitDict = {});
  readonly attribute USVString topOrigin;
  readonly attribute USVString paymentRequestOrigin;
  readonly attribute DOMString paymentRequestId;
  readonly attribute FrozenArray<PaymentMethodData> methodData;
  readonly attribute object total;
  readonly attribute FrozenArray<PaymentDetailsModifier> modifiers;
  readonly attribute object? paymentOptions;
  readonly attribute FrozenArray<PaymentShippingOption>? shippingOptions;
  Promise<WindowClient?> openWindow(USVString url);
  Promise<PaymentRequestDetailsUpdate?> changePaymentMethod(DOMString methodName, optional object? methodDetails = null);
  Promise<PaymentRequestDetailsUpdate?> changeShippingAddress(optional AddressInit shippingAddress = {});
  Promise<PaymentRequestDetailsUpdate?> changeShippingOption(DOMString shippingOption);
  undefined respondWith(Promise<PaymentHandlerResponse> handlerResponsePromise);
};

WebIDLdictionary PaymentRequestEventInit : ExtendableEventInit {
  USVString topOrigin;
  USVString paymentRequestOrigin;
  DOMString paymentRequestId;
  sequence<PaymentMethodData> methodData;
  PaymentCurrencyAmount total;
  sequence<PaymentDetailsModifier> modifiers;
  PaymentOptions paymentOptions;
  sequence<PaymentShippingOption> shippingOptions;
};

PaymentRequestEvent 的实例 会使用下表中的内部 槽创建：

当通过 PaymentRequest.show() 接收到一个 PaymentRequest，并且用户随后选择了某个基于 Web 的支付处理器时，用户 代理 必须 运行以下步骤：

1. 令 registration 为与用户选择的基于 Web 的支付处理器对应的 ServiceWorkerRegistration。
2. 如果未找到 registration，则用一个 "InvalidStateError" DOMException 拒绝由 PaymentRequest.show() 创建的 Promise，并 终止这些步骤。

3. 在 registration 上，使用 PaymentRequestEvent 触发 触发功能事件 "paymentrequest"，并带有以下属性：

   topOrigin

   顶层收款方网页的 源的序列化表示。

   paymentRequestOrigin

   PaymentRequest 被初始化所在上下文的 源的序列化表示。

   methodData

   执行 MethodData 填充 算法 的结果。

   modifiers

   执行 Modifiers 填充 算法 的结果。

   total

   对应 PaymentRequest 中 PaymentDetailsInit 上 total 字段的一个副本。

   paymentRequestId

   来自 PaymentRequest 的 \[\[details\]\].id。

   paymentOptions

   传递给对应 PaymentRequest 构造函数的 paymentOptions 字典的一个副本。

   shippingOptions

   对应 PaymentRequest 中 PaymentDetailsInit 上 shippingOptions 字段的一个副本。

   然后，以 dispatchedEvent 并行运行以下步骤：

   1. 等待 dispatchedEvent 的所有 延长 生命周期 promise 解析完成。
   2. 如果基于 Web 的支付处理器尚未提供 PaymentHandlerResponse， 则使用一个 "OperationError" DOMException 拒绝由 PaymentRequest.show() 创建的 Promise。

1. 令 event 为此 PaymentRequestEvent。
2. 如果 event 的 isTrusted 属性为 false，则返回一个 被拒绝并带有 "InvalidStateError" DOMException 的 Promise。
3. 令 request 为触发此 PaymentRequestEvent 的 PaymentRequest。
4. 令 url 为对 url 参数执行解析的结果。
5. 如果 url 解析抛出异常，则返回一个 被该异常拒绝的 Promise。
6. 如果 url 是 about:blank，则返回一个 被 TypeError 拒绝的 Promise。
7. 如果 url 的源与和该基于 Web 的支付处理器相关联的 service worker 的源不同， 则返回一个以 null 解决的 Promise。
8. 令 promise 为一个新的 Promise。
9. 返回 promise，并并行执行其余步骤：
10. 如果 event.[[windowClient]] 不为 null，则：
    1. 如果 event.[[windowClient]].visibilityState 不为 "unloaded"，则用一个 "InvalidStateError" DOMException 拒绝 promise， 并中止这些步骤。
11. 令 newContext 为一个新的 顶级 浏览 上下文。
12. 将 newContext 导航 到 url，并启用 异常和替换。
13. 如果导航抛出异常，则用该异常拒绝 promise， 并中止这些步骤。
14. 如果 newContext 的源与和该基于 Web 的支付处理器相关联的 service worker 客户端源不同，则：
    1. 以 null 解决 promise。
    2. 中止这些步骤。
15. 令 client 为使用 newContext 作为 参数运行 create window client 算法的结果。
16. 将 event.[[windowClient]] 设为 client。
17. 以 client 解决 promise。

用户代理通过对提供给相应 PaymentRequestEvent 接口的 respondWith 函数的 Promise 进行解析，来接收来自基于 Web 的 支付处理器的成功响应。应用程序应当使用一个包含支付响应的 PaymentHandlerResponse 实例来解析该 Promise。若用户取消或发生错误， 应用程序可以通过拒绝该 Promise 来表示失败。

PaymentHandlerResponse 通过以下字典进行传递：

WebIDLdictionary PaymentHandlerResponse {
DOMString methodName;
object details;
DOMString? payerName;
DOMString? payerEmail;
DOMString? payerPhone;
AddressInit shippingAddress;
DOMString? shippingOption;
};

当以 methodName 和 methodDetails 参数调用此算法时，用户代理 必须 运行 以下步骤：

1. 使用根据给定 methodName 和 methodDetails 参数构造的 PaymentMethodChangeEvent event， 运行 支付方式 更改算法。
2. 如果没有运行 event.updateWith(detailsPromise)， 则返回 null。
3. 如果 event.updateWith(detailsPromise) 抛出异常，则重新抛出该 错误。
4. 如果 event.updateWith(detailsPromise) 超时 （可选），则抛出 "InvalidStateError" DOMException。
5. 根据 event.updateWith(detailsPromise) 中的 detailsPromise 构造并返回一个 PaymentRequestDetailsUpdate。

当以 shippingAddress 或 shippingOption 调用此算法时，用户代理 必须 运行以下 步骤：

1. 使用根据 更新后的详情（shippingAddress 或 shippingOption）构造的 PaymentRequestUpdateEvent event， 运行 PaymentRequest 更新算法。
2. 如果没有运行 event.updateWith(detailsPromise)， 则返回 null。
3. 如果 event.updateWith(detailsPromise) 抛出异常，则重新抛出该 错误。
4. 如果 event.updateWith(detailsPromise) 超时 （可选），则抛出 "InvalidStateError" DOMException。
5. 根据 event.updateWith(detailsPromise) 中的 detailsPromise 构造并返回一个 PaymentRequestDetailsUpdate。

当以 event 和 handlerResponsePromise 参数调用此算法时，用户代理 必须 运行 以下步骤：

1. 如果 event 的 isTrusted 为 false， 则抛出一个 "InvalidStateError" DOMException 并中止 这些步骤。
2. 如果 event 的 dispatch flag 未设置，则抛出一个 "InvalidStateError" DOMException 并中止 这些步骤。
3. 如果 event.[[respondWithCalled]] 为 true，则抛出一个 "InvalidStateError" DOMException 并中止 这些步骤。
4. 将 event.[[respondWithCalled]] 设为 true。
5. 设置 event 的 停止传播标志 和 event 的 立即停止传播 标志。
6. 将 handlerResponsePromise 添加到 event 的 延长 生命周期 promises
7. 将 event 的 待处理 promises 计数 加一。
8. 在 handlerResponsePromise 因 reason 而 被拒绝时：
   1. 以 reason 运行 支付应用 失败算法，并 终止这些步骤。
9. 在 handlerResponsePromise 兑现时：
   1. 令 handlerResponse 为 value 转换为 IDL 值 后的 PaymentHandlerResponse。 如果此过程抛出异常，则用一个 "OperationError" DOMException 运行 支付应用 失败算法， 并终止这些步骤。
   2. 验证 handlerResponse 中所有必需成员都存在 且格式良好。
      1. 如果 handlerResponse.methodName 不存在， 或未设置为来自 event.methodData 的值之一， 则用一个 "OperationError" DOMException 运行 支付应用失败算法， 并终止这些 步骤。
      2. 如果 handlerResponse.details 不存在 或不可 JSON 序列化， 则用一个 "OperationError" DOMException 运行 支付应用 失败算法， 并终止这些步骤。
      3. 令 shippingRequired 为关联 PaymentRequest 的 paymentOptions 中的 requestShipping 值。 如果 shippingRequired 为真且 handlerResponse.shippingAddress 不存在，则用一个 "OperationError" DOMException 运行 支付应用失败 算法， 并终止 这些步骤。
      4. 如果 shippingRequired 为真且 handlerResponse.shippingOption 不存在， 或未设置为来自 event.shippingOptions 的配送选项标识符之一， 则用一个 "OperationError" DOMException 运行 支付应用 失败算法， 并终止这些 步骤。
      5. 令 payerNameRequired 为关联 PaymentRequest 的 paymentOptions 中的 requestPayerName 值。 如果 payerNameRequired 为真且 handlerResponse.payerName 不存在， 则用一个 "OperationError" DOMException 运行 支付应用 失败算法， 并终止这些 步骤。
      6. 令 payerEmailRequired 为关联 PaymentRequest 的 paymentOptions 中的 requestPayerEmail 值。 如果 payerEmailRequired 为真且 handlerResponse.payerEmail 不存在， 则用一个 "OperationError" DOMException 运行 支付应用 失败算法， 并终止这些 步骤。
      7. 令 payerPhoneRequired 为关联 PaymentRequest 的 paymentOptions 中的 requestPayerPhone 值。 如果 payerPhoneRequired 为真且 handlerResponse.payerPhone 不存在， 则用一个 "OperationError" DOMException 运行 支付应用 失败算法， 并终止这些 步骤。
   3. 序列化 handlerResponse 的必需成员（ methodName 和 details 始终是必需的； 当 shippingRequired 为 true 时， shippingAddress 和 shippingOption 是必需的； 当 payerNameRequired、payerEmailRequired 和 payerPhoneRequired 分别为 true 时， payerName、payerEmail 和 payerPhone 是必需的。）：
      1. 对于 handlerResponse 中的每个 member， 令 serializeMember 为使用 handlerResponse.member 执行 StructuredSerialize 的结果。重新抛出任何 异常。
   4. 用户代理 必须 按照 [payment-request] 中的定义运行 用户 接受支付 请求算法， 并用这些步骤或其等效步骤替换其中的第 9-15 步。
      1. 反序列化已序列化的成员：
         1. 对于每个 serializeMember， 令 member 为使用 serializeMember 执行 StructuredDeserialize 的结果。重新抛出任何异常。
      2. 如果上述步骤中发生任何异常，则用一个 "OperationError" DOMException 运行 支付应用 失败算法， 并终止这些 步骤。
      3. 将 methodName 赋值给关联 PaymentRequest 的 response.methodName。
      4. 将 details 赋值给关联 PaymentReqeust 的 response.details。
      5. 如果 shippingRequired 为真，则将关联 PaymentReqeust 的 shippingAddress 属性设为 shippingAddress。否则，将其设为 null。
      6. 如果 shippingRequired 为真，则将关联 PaymentReqeust 的 shippingOption 属性设为 shippingOption。否则，将其设为 null。
      7. 如果 payerNameRequired 为真，则将关联 PaymentReqeust 的 payerName 属性设为 payerName。否则，将其设为 null。
      8. 如果 payerEmailRequired 为真，则将关联 PaymentReqeust 的 payerEmail 属性设为 payerEmail。否则，将其设为 null。
      9. 如果 payerPhoneRequired 为真，则将关联 PaymentReqeust 的 payerPhone 属性设为 payerPhone。否则，将其设为 null。
10. 在 handlerResponsePromise 兑现时 或 拒绝时， 排入一个微任务 以执行 以下步骤：
    1. 将 event 的 待处理 promises 计数 减一。
    2. 令 registration 为 this 的 相关 全局对象 所关联的 service worker 的 所属 service worker registration。
    3. 如果 registration 不为 null，则用 registration 调用 Try Activate。

以下示例展示了如何响应支付请求：

paymentRequestEvent.respondWith(new Promise(function(accept,reject) {
  /* ... processing may occur here ... */
  accept({
    methodName: "https://example.com/pay",
    details: {
      cardHolderName:   "John Smith",
      cardNumber:       "1232343451234",
      expiryMonth:      "12",
      expiryYear :      "2020",
      cardSecurityCode: "123"
     },
    shippingAddress: {
      addressLine: [
        "1875 Explorer St #1000",
      ],
      city: "Reston",
      country: "US",
      dependentLocality: "",
      organization: "",
      phone: "+15555555555",
      postalCode: "20190",
      recipient: "John Smith",
      region: "VA",
      sortingCode: ""
    },
    shippingOption: "express",
    payerEmail: "john.smith@gmail.com",
  });
}));

当以 reason 调用此算法时，用户代理 必须 运行 以下步骤：

1. 如果 reason 是一个 "OperationError" DOMException，则运行 [payment-request] 中定义的 支付 处理器指示内部错误算法。
2. 否则，运行 [payment-request] 中定义的 用户 中止支付请求算法。
   注

   本规范的先前版本并未定义当 支付应用 失败算法 被 调用时会发生什么。实际上，实现者的行为如同 运行了 用户 中止支付请求算法。 为了尽可能保持向后兼容，同时 仍然引入一种让基于 Web 的支付处理器指示 内部错误的方式，本规范现将除 "OperationError" DOMException 之外的所有 reason 值映射为用户中止。未来 版本的本规范可能会增加其他受处理的值。

由于隐私问题，Web Payments Working Group 在 Payment Request API 的原始版本中移除了对配送地址和 账单地址的支持；参见 issue 842。为了给那些仍继续支持此能力的实现提供文档，工作组现正 恢复该特性，并期望解决相关隐私 问题。在这样做的同时，工作组也可能基于其他 API 的演进（例如 Content Picker API）对 Payment Request API 作出修改。

• 该 API 不会共享关于用户已注册 的基于 Web 的支付处理器的信息。来自源的信息仅会 在用户同意的情况下与收款方共享。
• 在用户选择某个基于 Web 的支付 处理器之前，用户代理不应与任何 基于 Web 的支付处理器共享支付请求信息。
• 在支持 Web-based Payment Handler API 的浏览器中，当商家 使用基于 URL 的支付方式 标识符创建一个 PaymentRequest 对象时， CanMakePaymentEvent 将会在已注册的 基于 Web 的支付处理器中触发，这些处理器来自一个有限的源集合：支付方式清单的源 以及它们的 支持的 源。 该事件会在用户选择该支付处理器之前触发， 但它不包含关于触发源（即 商家网站）的任何信息，因此不能被直接用于跟踪用户。
• 我们承认通过 CanMakePaymentEvent 进行时序攻击的风险：
  • 商家网站通过后端通道（例如 fetch API）向某个基于 Web 的支付处理器源发送通知，分享它们 即将构造一个 PaymentRequest 对象这一事实。
  • 然后商家网站构造 PaymentRequest， 从而触发一个 CanMakePaymentEvent 向已安装的 基于 Web 的支付处理器触发。
  • 该基于 Web 的支付处理器联系其自身的源，并在 服务器端尝试关联这两个请求。
• 用户代理应允许用户禁用对 CanMakePaymentEvent 的支持。
• 在支持 Web-based Payment Handler API 的浏览器中， CanMakePaymentEvent 将在已注册的基于 Web 的支付 处理器中触发，这些处理器能够在需要时提供商家请求的所有信息， 包括配送地址和付款人的联系信息。

• 本规范未定义用户代理在基于 Web 的支付处理器首次注册时 如何建立用户同意。用户代理可能会在注册期间通知 和/或提示用户。
• 出于安全原因（例如 SSL 证书无效），用户代理可以拒绝 基于 Web 的支付处理器注册，并且在这种情况发生时应当 通知用户。

• 本规范的一个目标是尽量减少用户 为完成支付所需的交互。然而，我们也希望 确保用户有机会同意进行支付。由于基于 Web 的支付处理器 不要求必须打开窗口进行用户交互， 用户代理应采取必要步骤 以确保用户 (1) 在支付请求被调用时知晓此事， 且 (2) 在商家收到该 支付处理器响应之前，有机会与基于 Web 的 支付处理器进行交互。

• 按设计，来自一个源的基于 Web 的支付处理器会与 另一个源（例如商家站点）共享数据。
• 为减轻网络钓鱼攻击，用户代理 清楚地向用户表明基于 Web 的支付处理器的源非常重要。
• 用户代理应帮助用户理解他们正在跨源共享 信息，并且理想情况下还应让他们了解所共享的是哪些 信息。

• 参见 Service Worker 安全 注意事项
• 支付方式的安全性超出本 规范的范围，应由支持这些支付方式的基于 Web 的支付处理器 处理。

• 负责某种支付方式的一方通过 支付方式 清单来授权支付 应用。详情请参见 处理 CanMakePaymentEvent 算法。
• 用户代理不要求必须提供那些存在安全问题的基于 Web 的支付 处理器。安全问题可能包括：
  • 证书已过期、已吊销、自签名，等等。
  • 混合内容
  • 页面可通过 HTTPs 访问却重定向到一个不安全页面。
  • 支付处理器已被安全浏览数据库认定为 恶意

  当基于 Web 的支付处理器由于安全 原因而不可用时，用户代理应向基于 Web 的 支付处理器开发者提供原因说明（例如通过 控制台消息），并且 也可以告知用户以帮助避免混淆。

• 支付方式 清单授权各个源分发 某一特定支付方式的支付应用。当用户代理在 判断某个基于 Web 的支付处理器是否与某个 支付方式 清单中列出的源匹配时，用户代理使用的是该基于 Web 的支付处理器的 service worker registration 的作用域 URL。

• 为减轻这样一种场景：被劫持的收款方站点向 收款方服务器提交欺诈性或格式错误的支付方式数据 （或者就此而言，支付请求数据），收款方服务器 应验证数据格式，并将该数据与 服务器上的权威信息进行关联，例如可接受的支付 方式、总额、显示项和配送地址。

• 当 Payment Request API 在“隐私浏览 模式”下被调用时，用户代理应在 私有上下文中启动基于 Web 的支付处理器。这通常会阻止站点访问任何 先前存储的信息。反过来，这很可能要求 用户登录到相应源，或者重新输入支付详情。
• CanMakePaymentEvent 事件不应在 隐私浏览模式下触发。用户代理应当表现得如同 respondWith() 被以 false 调用一样。我们承认由此带来的风险：如果某个 实体同时控制 Payment Request API 调用的源以及 基于 Web 的支付处理器的源，那么该实体可能能够 推断出用户可能正处于隐私浏览模式。