支付处理程序 API

安全上下文：此功能仅在安全上下文（HTTPS）中，某些或所有支持的浏览器中可用。

实验性：这是一个实验性技术
在生产环境中使用此功能之前，请仔细查看浏览器兼容性表。

注意：此功能在Web Workers中可用。

支付处理程序 API 提供了一套标准化的功能，让 Web 应用程序可以直接处理支付，而不是必须被重定向到另一个网站进行支付处理。

当商户网站通过支付请求 API启动支付时，支付处理程序 API 会处理适用支付应用程序的发现，将它们作为选项呈现给用户，一旦用户做出选择，就会打开一个支付处理程序窗口，让用户输入支付详细信息，并处理与支付应用程序的支付交易。

与支付应用程序（授权、支付凭据传递）的通信通过 Service Workers 处理。

概念和用法

在商户网站上，支付请求是通过构造一个新的PaymentRequest对象来启动的

js
const request = new PaymentRequest(
  [
    {
      supportedMethods: "https://bobbucks.dev/pay",
    },
  ],
  {
    total: {
      label: "total",
      amount: { value: "10", currency: "USD" },
    },
  },
);

supportedMethods 属性指定了一个 URL，表示商户支持的支付方式。要使用多种支付方式，您可以在对象数组中指定它们，例如

js
const request = new PaymentRequest(
  [
    {
      supportedMethods: "https://alicebucks.dev/pay",
    },
    {
      supportedMethods: "https://bobbucks.dev/pay",
    },
  ],
  {
    total: {
      label: "total",
      amount: { value: "10", currency: "USD" },
    },
  },
);

让支付应用程序可用

在支持的浏览器中，该流程从向每个 URL 请求支付方式清单文件开始。支付方式清单通常被称为 payment-manifest.json（确切的名称可以是您喜欢的任何名称），其结构应如下所示

json
{
  "default_applications": ["https://bobbucks.dev/manifest.json"],
  "supported_origins": ["https://alicepay.friendsofalice.example"]
}

给定一个像 https://bobbucks.dev/pay 这样的支付方式标识符，浏览器会

  1. 开始加载 https://bobbucks.dev/pay 并检查其 HTTP 标头。
    1. 如果找到了带有 rel="payment-method-manifest" 的Link 标头，则它会从该位置下载支付方式清单（有关详细信息，请参阅可选地将浏览器路由到另一个位置以查找支付方式清单）。
    2. 否则，将 https://bobbucks.dev/pay 的响应主体解析为支付方式清单。
  2. 将下载的内容解析为包含 default_applications 和 supported_origins 成员的 JSON。

这些成员具有以下用途

  • default_applications 告诉浏览器在哪里可以找到可以使用 BobBucks 支付方式的默认支付应用程序（如果它尚未安装）。
  • supported_origins 告诉浏览器哪些其他支付应用程序可以根据需要处理 BobBucks 支付方式。如果它们已安装在设备上，它们将作为替代支付选项与默认应用程序一起呈现给用户。

从支付方式清单中，浏览器会获取默认支付应用程序的Web 应用程序清单文件 URL，这些文件可以根据您的需要命名，看起来像这样

json
{
  "name": "Pay with BobBucks",
  "short_name": "BobBucks",
  "description": "This is an example of the Payment Handler API.",
  "icons": [
    {
      "src": "images/manifest/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/manifest/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "serviceworker": {
    "src": "service-worker.js",
    "scope": "/",
    "use_cache": false
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.android.samplepay",
      "min_version": "1",
      "fingerprints": [
        {
          "type": "sha256_cert",
          "value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB"
        }
      ]
    }
  ]
}

当商户应用程序响应用户手势调用PaymentRequest.show() 方法时，浏览器会使用在每个清单中找到的name 和icons 信息，在浏览器提供的支付请求 UI 中将支付应用程序呈现给用户。

  • 如果有多个支付应用程序选项，将向用户呈现选项列表，供他们选择。选择支付应用程序将启动支付流程，这会导致浏览器根据需要即时（JIT）安装 Web 应用程序，注册在serviceworker 成员中指定的 Service Worker，以便它可以处理支付。
  • 如果只有一个支付应用程序选项，PaymentRequest.show() 方法将使用此支付应用程序启动支付流程，根据需要即时（JIT）安装它，如上所述。这是一种优化，可以避免向用户呈现仅包含一个支付应用程序选项的列表。

注意：如果在支付应用程序清单中将prefer_related_applications 设置为 true，则浏览器将启动在related_applications 中指定的特定于平台的支付应用程序来处理支付（如果可用），而不是 Web 支付应用程序。

有关更多详细信息，请参阅提供 Web 应用程序清单。

检查支付应用程序是否已准备好使用

支付请求 API 的PaymentRequest.canMakePayment() 方法如果客户的设备上有一个支付应用程序，则返回 true，这意味着已发现支持该支付方式的支付应用程序，并且已安装特定于平台的支付应用程序，或者基于 Web 的支付应用程序已准备好注册。

js
async function checkCanMakePayment() {
  // ...

  const canMakePayment = await request.canMakePayment();
  if (!canMakePayment) {
    // Fallback to other means of payment or hide the button.
  }
}

支付处理程序 API 添加了一种额外的机制来准备处理支付。当商户网站调用PaymentRequest() 构造函数时，canmakepayment 事件会在支付应用程序的 Service Worker 上触发，以检查它是否已准备好处理支付。具体来说，它是为了检查支付应用程序是否已准备好处理支付。具体来说，它是在商户网站调用PaymentRequest() 构造函数时触发的。然后，Service Worker 可以使用CanMakePaymentEvent.respondWith() 方法进行适当的响应

js
self.addEventListener("canmakepayment", (e) => {
  e.respondWith(
    new Promise((resolve, reject) => {
      someAppSpecificLogic()
        .then((result) => {
          resolve(result);
        })
        .catch((error) => {
          reject(error);
        });
    }),
  );
});

respondWith() 返回的 Promise 将通过一个布尔值来解析，以表明它已准备好处理支付请求（true），或者没有准备好（false）。

处理支付

调用PaymentRequest.show() 方法后，paymentrequest 事件会在支付应用程序的 Service Worker 上触发。这个事件会在支付应用程序的 Service Worker 中监听，以开始支付流程的下一阶段。

js
let payment_request_event;
let resolver;
let client;

// `self` is the global object in service worker
self.addEventListener("paymentrequest", async (e) => {
  if (payment_request_event) {
    // If there's an ongoing payment transaction, reject it.
    resolver.reject();
  }
  // Preserve the event for future use
  payment_request_event = e;

  // ...
});

当收到 paymentrequest 事件时，支付应用程序可以通过调用PaymentRequestEvent.openWindow() 来打开一个支付处理程序窗口。支付处理程序窗口将向客户提供一个支付应用程序界面，让他们可以在其中进行身份验证、选择送货地址和选项以及授权支付。

当支付处理完毕后，PaymentRequestEvent.respondWith() 用于将支付结果传递回商户网站。

有关此阶段的更多详细信息，请参阅从商户接收支付请求事件。

管理支付应用程序功能

一旦注册了支付应用程序 Service Worker，您就可以使用 Service Worker 的PaymentManager 实例（通过ServiceWorkerRegistration.paymentManager 访问）来管理支付应用程序功能的各个方面。

例如

js
navigator.serviceWorker.register("serviceworker.js").then((registration) => {
  registration.paymentManager.userHint = "Card number should be 16 digits";

  registration.paymentManager
    .enableDelegations(["shippingAddress", "payerName"])
    .then(() => {
      // ...
    });

  // ...
});
  • PaymentManager.userHint 用于提供一个提示，让浏览器在支付请求 UI 中与支付应用程序的名称和图标一起显示。
  • PaymentManager.enableDelegations() 用于将提供所需支付信息的各个部分的责任委托给支付应用程序，而不是从浏览器（例如，通过自动填充）收集这些信息。

接口

CanMakePaymentEvent

当支付应用程序已成功注册以表明它已准备好处理支付时，将在支付应用程序的 Service Worker 上触发的canmakepayment 事件的事件对象。

PaymentManager

用于管理支付应用程序功能的各个方面。通过ServiceWorkerRegistration.paymentManager 属性访问。

PaymentRequestEvent

当商户网站通过PaymentRequest.show() 方法启动支付流程时，将在支付应用程序的 Service Worker 上触发的paymentrequest 事件的事件对象。

对其他接口的扩展

canmakepayment 事件

当支付应用程序的ServiceWorkerGlobalScope 已成功注册时触发，以表明它已准备好处理支付。

paymentrequest 事件

当在商户网站上通过 PaymentRequest.show() 方法启动支付流程时，在支付应用程序的 ServiceWorkerGlobalScope 上触发。

ServiceWorkerRegistration.paymentManager

返回支付应用程序的 PaymentManager 实例，用于管理各种支付应用程序功能。

规范

规范
支付处理程序 API
# the-paymentrequestevent

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅