支付方法清单

本文档的状态

HEAD / HTTP/2
Host: alicepay.com
User-Agent: Mellblomenator/9000

HTTP/2 204
Link: </pay/payment-manifest.json>; rel="payment-method-manifest"

{
  "default_applications": ["https://alicepay.com/pay/app/webappmanifest.json"],
  "supported_origins": [
    "https://bobpay.xyz",
    "https://alicepay.friendsofalice.example"
  ]
}

2. 清单格式

有效支付方法清单文件是一个以 UTF-8 编码的文件，其中包含 可解析为 JSON 对象的内容。所得 JSON 对象最多必须包含 两项，可能的键为 "default_applications" 和 "supported_origins"。

default_applications 键的值（如果存在）必须是非空 JSON 数组。 数组中的每一项都必须是一个绝对 URL 字符串，并且所得解析后的 URL 的方案为 "https"。

supported_origins 键的值（如果存在）必须是字符串 "*"，或非空 JSON 数组。在后一种情况下，数组中的每一项必须是表示 HTTPS 绝对 URL 字符串的源。形式上，该字符串必须等于 所得解析后的 序列化的 URL 的 源。

Web 开发者必须确保其所有支付方法清单都是有效的。

与文件内容上的所有一致性要求一样，这些要求 面向 Web 开发者，而不是面向实现者。确切的处理模型（见 §3 处理模型）规定实现者如何处理所有支付 方法清单文件， 包括无效文件。

{
  "default_applications": ["https://alicepay.com/pay/app/webappmanifest.json"],
  "created_by": "Alice",
  "created_in": "Wonderland"
}

3. 处理模型

3.1. 对 Payment Request API 的修改

本规范通过修改 PaymentRequest(methodData, details, options) 构造器，与 Payment Request 生态系统的其余部分集成。它在算法完成并返回新构造的 PaymentRequest 对象之前，添加以下步骤。 在下文中，令 request 为正在构造的 PaymentRequest 实例。[PAYMENT-REQUEST]

1. 令 identifiers 为一个列表，由 request.[[serializedMethodData]] 中每一对的第一个项组成。

2. 令 client 为当前设置对象。

3. 给定 identifiers 和 client，摄取支付方法清单。

这些步骤会启动整个过程。§3 处理 模型的其余部分 负责定义此过程最终如何使新的支付 应用可供 用户使用。

随着本规范 获得多个实现者的兴趣，我们预计会将本节 移入 Payment Request API 规范本身，而不是在此维护猴子补丁。

3.2. 摄取支付方法清单

给定支付方法标识符列表 identifiers， 以及环境设置对象 client，用户 代理可以运行以下步骤，以摄取支付方法清单：

1. 给定 identifiers 和 client，获取支付方法清单，并等待其 以 manifestsMap 异步完成。如果结果为失败，则返回。

2. 对 manifestsMap 中的每个 identifier → manifest 执行：

   1. 令 parsed 为验证并解析 manifest 的结果。如果这 返回失败，则继续。

   2. 对 parsed 的默认 应用中的每个 url 执行：

      1. 给定 client，获取 Web 应用清单于 url，并等待其 以 webAppManifestString 异步完成。如果 结果为失败，则继续。

      2. 令 webAppManifest 为给定 webAppManifestString 运行处理 Web 应用 清单的步骤所得的结果。

         处理 Web 应用 清单的步骤非常宽容，会 返回空对象或缺少关键字段的对象，而不是失败。用户 代理将需要在下一步单独验证已处理的 Web 应用清单，以确保它 包含足够的数据供其使用。

      3. 以用户代理特定的方式，使用所得已处理的 Web 应用清单 webAppManifest，为由 identifier 标识的支付方法安装任何适用的支付应用。

         未来计划是存在一种 与用户代理无关的方式来 使用所得已处理的 Web 应用清单，方法是 查阅其 serviceworker 字段，并使用它来安装 符合 Payment Handler API 规范的基于 Web 的支付应用。[PAYMENT-HANDLER]

   3. 将受支持源关联到 identifier，以便 用户代理将来可以使用它来确定哪些第三方支付应用可以 为由 identifier 标识的支付方法显示。

3.3. 获取支付方法清单

要获取 支付方法清单，给定列表形式的JavaScript 字符串 supportedMethods 以及环境设置对象 client，执行 以下步骤。 此算法将以一个映射（可能为空）异步完成，该映射从 URL 到字节序列，将支付方法标识符映射到相应 清单的内容。

1. 令 identifierURLs 为空列表。

2. 对 supportedMethods 中的每个 string 执行：

   1. 令 identifierURL 为对 string 进行基本 URL 解析的结果。如果 结果为失败，则继续。

      对于任何不是基于 URL 的支付方法 标识符的支付方法标识符，即对于 标准化支付方法 标识符，结果将为失败。

   2. 如果对 identifierURL 进行验证 返回 false，则继续。

   3. 可选地，继续。

      此步骤允许实现出于用户代理特定的原因跳过任何给定的支付方法 标识符。§4 安全和 隐私考量讨论了用户 代理可能倾向于只摄取某些标识符的一些原因。

   4. 将 identifierURL 追加到 identifierURLs。

3. 令 manifestsMap 为空映射。

4. 对 identifierURLs 中的每个 identifierURL 执行：

   1. 令 identifierRequest 为一个新的请求，其方法为 `HEAD`，url 为 identifierURL，client 为 client，mode 为 "cors"，credentials mode 为 "omit"，且redirect mode 为 "error"。

   2. 获取 identifierRequest。要使用响应 identifierResponse 处理响应：

      1. 如果 identifierResponse 是网络错误，或 identifierResponse 的状态不是ok 状态，则继续。

      2. 令 linkHeaders 为给定 `Link` 和 identifierResponse 的标头列表提取标头列表值的结果。

      3. 令 manifestURLString 为 null。

      4. 对 linkHeaders 中的每个 linkHeader 执行：

         1. 按照 link-value 产生式解析 linkHeader。如果无法 解析，则继续。[RFC8288]

         2. 如果解析后的标头包含一个参数，其名称与字符串 "rel" 进行 ASCII 大小写不敏感匹配， 且其值与字符串 "payment-method-manifest" 进行 ASCII 大小写不敏感匹配， 则将 manifestURLString 设置为解析后 标头中由 URI-Reference 产生式给出的 字符串，并中断。

      5. 如果 manifestURLString 不为 null，则：

         1. 令 manifestURL 为对 manifestURLString 执行基本 URL 解析的结果， 其基 URL 由 identifierResponse 的url 给出。如果 结果为失败，则继续。

         2. 如果 manifestURL 的方案不是 "https"， 则继续。

         3. 令 manifestRequest 为一个新的请求，其url 为 manifestURL，client 为 client，mode 为 "cors"，credentials mode 为 "omit"，且redirect mode 为 "error"。

         4. 获取 manifestRequest。要使用响应 manifestResponse 处理响应 体结束：

            1. 如果 manifestResponse 是网络错误，或 manifestResponse 的状态不是ok 状态，则继续。

            2. 令 body 为 manifestResponse 的body。

            3. 如果 body 为 null，则继续。

            4. 令 reader 为从 body获取读取器的结果。

            5. 令 promise 为使用 reader 从 body读取 所有字节的结果。

            6. 当 promise 以字节序列 bytes 兑现时， 将 manifestsMap[identifierURL] 设置为 bytes。

5. 一旦上述步骤启动的所有正在进行的获取算法均完成， 包括所指定的处理响应和处理响应体结束步骤， 以 manifestsMap 异步 完成此算法。

3.4. 验证并解析支付方法清单

已解析 支付方法清单是一个结构，包含两个字段：

默认应用

有序集合，其中包含URL，可能 为空

受支持源

要么是字符串 "*"，要么是有序集合，其中包含 源

要验证并解析一个声称包含支付方法清单的字节序列 bytes，执行以下 步骤。结果要么是已解析支付方法清单，要么是失败。

1. 令 parsed 为给定 bytes，在 用户代理定义的 JavaScript 领域中从字节解析 JSON的结果。如果这抛出异常，则返回失败。

2. 如果 Type(parsed) 不是 Object， 则返回失败。

3. 令 defaultApps 为空有序集合。

4. 令 defaultAppsValue 为 Get(parsed, "default_applications")。

5. 如果 defaultAppsValue 不是 undefined：

   1. 如果 IsArray(defaultAppsValue) 为 false，则返回 失败。

   2. 令 defaultAppsList 为 CreateListFromArrayLike(defaultAppsValue, « String »)。如果这抛出异常，则返回失败。

   3. 如果 defaultAppsList 的大小为 0，则返回失败。

   4. 对 defaultAppsList 中的每个 defaultAppString 执行：

      1. 令 defaultAppURL 为对 defaultAppString 执行基本 URL 解析的结果。如果结果为失败，则返回失败。

      2. 如果 defaultAppURL 的方案不是 "https"，则返回 失败。

      3. 将 defaultAppURL 追加到 defaultApps。

6. 令 supportedOrigins 为空有序集合。

7. 令 supportedOriginsValue 为 Get(parsed, "supported_origins")。

8. 如果 supportedOriginsValue 是 "*"，则将 supportedOrigins 设置为 "*"。

9. 否则，如果 supportedOriginsValue 不是 undefined：

   1. 如果 IsArray(supportedOriginsValue) 为 false，则返回 失败。

   2. 令 supportedOriginsList 为 CreateListFromArrayLike(supportedOriginsValue, « String »)。如果这抛出 异常，则返回失败。

   3. 如果 supportedOriginsList 的大小为 0，则返回 失败。

   4. 对 supportedOriginsList 中的每个 supportedOriginString 执行：

      1. 令 supportedOriginURL 为对 supportedOriginString 执行基本 URL 解析的结果。如果结果为失败，则返回失败。

      2. 如果 supportedOriginURL 的方案不是 "https"，则返回 失败。

      3. 如果 supportedOriginURL 的用户名或密码不是空字符串， 则返回失败。

      4. 如果 supportedOriginURL 的路径的大小 不为 0，则返回失败。

      5. 如果 supportedOriginURL 的查询或片段不为 null，则返回失败。

      6. 将 supportedOriginURL 的源追加到 supportedOrigins。

10. 返回一个新的已解析支付方法清单，其中默认应用由 defaultApps 给出，且受支持源由 supportedOrigins 给出。

{
  "default_applications": ["https://alicepay.com/pay/app/webappmanifest.json"],
  "supported_origins": []
}

3.5. 获取 Web 应用清单

由于支付 应用的确定独立于任何嵌入的 HTML 文档， 因此获取提供默认支付应用信息的Web 应用清单的过程不同于通常的获取 Web 应用清单的步骤。

要获取默认 支付应用的 Web 应用清单，给定URL url 以及 环境设置对象 client，执行 以下步骤。此算法将 以标量值 字符串或失败异步完成。

1. 令 request 为一个新的请求， 其url 为 url，client 为 client，mode 为 "cors"，credentials mode 为 "omit"，且redirect mode 为 "error"。

2. 获取 request。要使用响应 response 处理响应体结束：

   1. 如果 response 是网络错误，或 response 的状态不是ok 状态， 则以失败异步完成此算法。

   2. 令 body 为 response 的body。

   3. 如果 body 为 null，则以失败异步完成此算法。

   4. 令 reader 为从 body获取读取器的结果。

   5. 令 promise 为使用 reader 从 body读取所有字节的结果。

   6. 当 promise 以字节序列 bytes 兑现时，以对 bytes 执行 UTF-8 解码的结果异步完成此算法。

   7. 当 promise 拒绝时，以失败异步 完成此算法。

4. 安全和隐私考量

摄取支付方法清单可能会向 支付服务泄露有关终端用户活动的信息。例如，一个仅在某个网站上受支持的支付方法可能会 允许该支付提供商发现访问该网站的用户的 IP 地址。

缓解这种情况的一种方式是，仅针对用户已安装或已明确表示感兴趣的支付应用获取清单。这会将 风险限制为仅与这些方共享用户的 IP 地址。

5. IANA 考量

5.1. payment-method-manifest 链接关系

此注册供社区审阅，并将提交给 IESG 进行审阅、批准， 并向 IANA 注册。

关系名称

payment-method-manifest

描述

链接到一个支付方法清单，该清单描述 Web Payments 生态系统中的特定支付方法。

参考

https://w3c.github.io/payment-method-manifest/

备注

请参见 §3.3 获取支付方法清单，了解此类链接 预期被获取的具体方式，并参见 §3.2 摄取支付方法 清单，了解其使用的更大上下文。

致谢

§3 处理模型主要基于 Rouslan Solomakhin 最初概述的算法。