支付处理程序 API

如果在商家调用 show() 方法时未注册相应的支付处理程序，用户代理可以允许用户在交易过程中注册该支付处理程序（“及时注册”）。

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

用户代理可以通过从商家请求的 基于 URL 的支付方法标识符 找到的 payment method manifest 推导出支付处理程序信息，从而执行即时安装。

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

paymentManager 属性公开了支付处理程序的管理功能。

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

PaymentManager 被 支付处理程序 用于管理其支持的委托类型。

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

"shippingAddress"

支付处理程序将在需要时提供收货地址。

"payerName"

支付处理程序将在需要时提供付款人的姓名。

"payerPhone"

支付处理程序将在需要时提供付款人的电话。

"payerEmail"

支付处理程序将在需要时提供付款人的电子邮件。

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler oncanmakepayment;
};

CanMakePaymentEvent 用作信号，用于表明支付处理程序是否能够响应支付请求。

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

通过 PaymentRequest 收到请求后，用户代理必须（MUST） 运行以下步骤：

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

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

给定一个 PaymentMethodData 和一个依据 支付方法标识符匹配的支付处理程序，如果该支付处理程序可用于支付，则此算法返回 true：

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

本规范扩展了 ServiceWorkerGlobalScope 接口。

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler onpaymentrequest;
};

PaymentRequestDetailsUpdate 包含更新后的总额（可选地包含修饰符和配送选项）以及因用户选择支付方法、收货地址或配送选项而产生的可能错误，这些选择发生在支付处理程序中。

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

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

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.PaymentRequest.show() 接收到 PaymentRequest，并且用户随后选择了支付处理程序后，用户代理 必须（MUST）运行以下步骤：

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

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

   topOrigin

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

   paymentRequestOrigin

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

   methodData

   执行 方法数据填充算法 的结果。

   modifiers

   执行 修饰符填充算法 的结果。

   total

   来自相应 PaymentDetailsInit 的 total 字段的副本。

   paymentRequestId

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

   paymentOptions

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

   shippingOptions

   来自相应 PaymentDetailsInit 的 shippingOptions 字段的副本。

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

   1. 等待 dispatchedEvent 的 延长生命周期的 Promise 全部解析。
   2. 如果 支付处理程序未提供 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 的来源与与该支付处理程序关联的 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 的来源与与该支付处理程序关联的 service worker client 的来源不同，则：
    1. 以 null 解决 promise。
    2. 中止这些步骤。
15. 令 client 为以 newContext 作为参数运行 create window client 算法的结果。
16. 将 event 的 [[windowClient]] 设为 client。
17. 以 client 解决 promise。

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

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

1. 以给定的 methodName 和 methodDetails 参数构造 PaymentMethodChangeEvent event，并运行 payment method changed algorithm。
2. 如果 event 的 updateWith(detailsPromise) 未被运行，则返回 null。
3. 如果 event 的 updateWith(detailsPromise) 抛出异常，则重新抛出该错误。
4. 如果 event 的 updateWith(detailsPromise) 超时（可选），则抛出 "InvalidStateError" DOMException。
5. 从 event.updateWith(detailsPromise) 中的 detailsPromise 构造并返回一个 PaymentRequestDetailsUpdate。

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

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

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

1. 如果 event 的 isTrusted 为 false， 则抛出 "InvalidStateError" DOMException 并中止这些步骤。
2. 如果 event 的 dispatch flag 未设置，则抛出 "InvalidStateError" DOMException 并中止这些步骤。
3. 如果 event 的 [[respondWithCalled]] 为 true，则抛出 "InvalidStateError" DOMException 并中止这些步骤。
4. 将 event 的 [[respondWithCalled]] 设为 true。
5. 设置 event 的 stop propagation flag 和 event 的 stop immediate propagation flag。
6. 将 handlerResponsePromise 添加到 event 的 extend lifetime promises 中。
7. 将 event 的 pending promises count 增加 1。
8. 当被拒绝时（Upon rejection）， 针对 handlerResponsePromise：
   1. 运行 支付应用失败算法 并中止这些步骤。
9. 当被兑现时（Upon fulfillment）， 针对 handlerResponsePromise：
   1. 令 handlerResponse 为将 value 转换为 IDL 值 的结果，类型为 PaymentHandlerResponse。若此操作抛出异常， 则运行 支付应用失败算法 并中止这些步骤。
   2. 校验 handlerResponse 中所有必需成员是否存在且格式正确。
      1. 若 handlerResponse 的 methodName 不存在，或未设置为 event 的 methodData 中的某个值，则运行 支付应用失败算法 并中止这些步骤。
      2. 若 handlerResponse 的 details 不存在或不是可 JSON 序列化的， 则运行 支付应用失败算法 并中止这些步骤。
      3. 令 shippingRequired 为关联的 PaymentRequest 的 requestShipping 取值，来自 paymentOptions。 如果 shippingRequired 且 handlerResponse 的 shippingAddress 不存在，则运行 支付应用失败算法 并中止这些步骤。
      4. 如果 shippingRequired 且 handlerResponse 的 shippingOption 不存在，或未设置为来自 event 的 shippingOptions 中的某个配送选项标识符，则运行 支付应用失败算法 并中止这些步骤。
      5. 令 payerNameRequired 为关联的 PaymentRequest 的 requestPayerName 取值，来自 paymentOptions。 如果 payerNameRequired 且 handlerResponse 的 payerName 不存在，则运行 支付应用失败算法 并中止这些步骤。
      6. 令 payerEmailRequired 为关联的 PaymentRequest 的 requestPayerEmail 取值，来自 paymentOptions。 如果 payerEmailRequired 且 handlerResponse 的 payerEmail 不存在，则运行 支付应用失败算法 并中止这些步骤。
      7. 令 payerPhoneRequired 为关联的 PaymentRequest 的 requestPayerPhone 取值，来自 paymentOptions。 如果 payerPhoneRequired 且 handlerResponse 的 payerPhone 不存在，则运行 支付应用失败算法 并中止这些步骤。
   3. 序列化 handlerResponse 的必需成员（methodName 与 details 始终必需； 当 shippingRequired 为 true 时，shippingAddress 与 shippingOption 必需； 当 payerNameRequired、payerEmailRequired、payerPhoneRequired 分别为 true 时，payerName、payerEmail、payerPhone 必需）：
      1. 对 handlerResponse 中的每个 member，令 serializeMember 为调用 StructuredSerialize 处理 handlerResponse.member 的结果。若有异常则重新抛出。
   4. 用户代理MUST运行 [payment-request] 中定义的 user accepts the payment request algorithm，并以以下步骤替换其第 9-15 步或其等效步骤。
      1. 反序列化已序列化的成员：
         1. 对每个 serializeMember，令 member 为调用 StructuredDeserialize 处理 serializeMember 的结果。若有异常则重新抛出。
      2. 如果上述步骤中出现任何异常，则运行 支付应用失败算法 并中止这些步骤。
      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. 当被兑现（Upon fulfillment）或 当被拒绝（upon rejection） handlerResponsePromise 时， 将一个微任务排入队列以执行以下步骤：
    1. 将 event 的 pending promises count 减一。
    2. 令 registration 为 this 的 相关全局对象 所关联的 service worker 的 containing 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",
  });
}));

由于隐私问题，Web Payments 工作组从最初版本的 Payment Request API 中移除了对收货地址和账单地址的支持；参见 issue 842。为给仍继续支持此能力的实现提供文档，工作组现正恢复该功能，并期望同时解决隐私问题。在此过程中，工作组也可能基于其他 API 的演进（例如 Content Picker API）对 Payment Request API 进行更改。

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

• 本规范未定义用户代理在首次注册支付处理程序时如何获取用户同意。用户代理可能在注册期间通知和/或提示用户。
• 出于安全原因（例如 SSL 证书无效），用户代理MAY拒绝支付处理程序注册，并且在发生这种情况时SHOULD通知用户。

• 本规范的一个目标是尽量减少完成支付所需的用户交互。然而，我们也希望确保用户有机会同意进行支付。由于支付处理程序并不要求必须打开窗口与用户交互，用户代理应采取必要措施，以确保用户（1）在支付请求被调用时得到知悉，且（2）在商家收到该支付处理程序的响应之前，有机会与支付处理程序进行交互。

• 按照设计，来自一个来源的支付处理程序会与另一个来源（例如商家网站）共享数据。
• 为减轻网络钓鱼攻击，用户代理明确告知用户支付处理程序的来源非常重要。
• 用户代理应帮助用户理解他们正在跨源共享信息，且理想情况下应让用户了解正在共享哪些信息。

• 参见 Service Worker 安全注意事项
• 支付方法的安全性不在本规范范围内，该问题由支持相应支付方法的支付处理程序来处理。

• 负责某一支付方法的一方通过 支付方法清单（payment method manifest） 来授权支付应用。细节参见 处理 CanMakePaymentEvent 算法。
• 对于存在安全问题的支付处理程序，用户代理没有义务将其提供给用户使用。安全问题可能包括：
  • 证书过期、被吊销、自签名等；
  • 混合内容；
  • 通过 HTTPS 可用的页面重定向到非 HTTPS 的页面；
  • 依据安全浏览数据库，支付处理程序已知为恶意。

  当出于安全原因导致某支付处理程序不可用时，用户代理应向支付处理程序开发者提供理由（例如通过控制台消息），并且也可以告知用户以帮助避免困惑。

• 支付方法清单 授权各来源为给定支付方法分发支付应用。用户代理在判断某支付处理程序是否与 支付方法清单 中列出的来源匹配时，会使用该支付处理程序 service worker 注册 的作用域 URL。

• 为缓解被劫持的收款方站点向其服务器提交欺诈或格式错误的支付方法数据（或相应的支付请求数据）的情形，收款方服务器应验证数据格式，并将数据与服务器上的权威信息进行关联，例如可接受的支付方法、总额、显示项以及收货地址。

• 当在“私密浏览模式”下调用 Payment Request API 时，用户代理应在私密上下文中启动支付处理程序。这通常会阻止站点访问任何先前存储的信息。相应地，这很可能需要用户登录到该来源或重新输入支付详情。
• CanMakePaymentEvent 事件在私密浏览模式下不应被触发。用户代理应表现得如同 respondWith() 被以 false 作为参数调用。我们承认由此带来的风险：如果某个实体同时控制发起 Payment Request API 调用的来源与支付处理程序的来源，该实体可能推断出用户处于私密浏览模式。