1. Web
  2. Web API
  3. Payment Handler API

Payment Handler API

可用性有限

此特性不是基線特性，因為它在一些最廣泛使用的瀏覽器中不起作用。

安全上下文： 此功能僅在安全上下文（HTTPS）中可用，且支援此功能的瀏覽器數量有限。

實驗性： 這是一項實驗性技術
在生產中使用此技術之前，請仔細檢查瀏覽器相容性表格。

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

Payment Handler API 提供了標準化的功能集，供 Web 應用程式直接處理支付，而無需重定向到單獨的支付處理網站。

當商家網站透過 Payment Request API 發起支付時，Payment Handler 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 標頭，它將下載該位置的支付方式清單（有關詳細資訊，請參閱 Optionally route the browser to find the payment method manifest in another location）。
    2. 否則，將 https://bobbucks.dev/pay 的響應體解析為支付方式清單。
  2. 將下載的內容作為 JSON 進行解析，其中包含 default_applications 和 supported_origins 成員。

這些成員具有以下用途：

  • default_applications 告訴瀏覽器，如果沒有安裝預設支付應用程式，可以在哪裡找到可以使用 BobBucks 支付方式的預設支付應用程式。
  • supported_origins 告訴瀏覽器，在需要時，哪些其他支付應用程式被允許處理 BobBucks 支付。如果它們已安裝在裝置上，它們將與預設應用程式一起作為替代支付選項呈現給使用者。

從支付方式清單中，瀏覽器獲取預設支付應用程式的 Web App Manifest 檔案的 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 資訊，在瀏覽器提供的 Payment Request UI 中向用戶展示支付應用程式。

  • 如果存在多個支付應用程式選項，將向用戶展示一個選項列表供其選擇。選擇一個支付應用程式將啟動支付流程，這會導致瀏覽器在需要時即時（JIT）安裝 Web 應用程式，並註冊 serviceworker 成員中指定的 Service Worker，以便其可以處理支付。
  • 如果只有一個支付應用程式選項，PaymentRequest.show() 方法將與此支付應用程式啟動支付流程，並在必要時即時（JIT）安裝它，如上所述。這是一種最佳化，以避免向用戶展示只有一個支付應用程式選項的列表。

注意：如果支付應用程式清單中的 prefer_related_applications 設定為 true，瀏覽器將啟動 related_applications 中指定的平臺特定支付應用程式（如果可用）來處理支付，而不是 Web 支付應用程式。

有關更多詳細資訊，請參閱 Serve a web app manifest。

檢查支付應用程式是否準備好付款

Payment Request 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.
  }
}

Payment Handler API 增加了一個額外的機制來準備處理支付。當商家網站呼叫 PaymentRequest() 建構函式時，會向支付應用程式的 Service Worker 觸發 canmakepayment 事件，以檢查它是否已準備好處理支付。然後，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() 方法後，會向支付應用程式的 Service Worker 觸發一個 paymentrequest 事件。此事件在支付應用程式的 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() 將支付結果傳回商家網站。

有關此階段的更多詳細資訊，請參閱 Receive a payment request event from the merchant。

管理支付應用程式功能

一旦支付應用程式的 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 用於為瀏覽器提供提示，以在 Payment Handler UI 中與支付應用程式的名稱和圖示一起顯示。
  • PaymentManager.enableDelegations() 用於將提供各種必需支付資訊部分的責任委託給支付應用程式，而不是從瀏覽器收集（例如，透過自動填充）。

介面

CanMakePaymentEvent

用於 canmakepayment 事件的事件物件，該事件在支付應用程式的 Service Worker 成功註冊後觸發，以表明它已準備好處理付款。

PaymentManager

用於管理支付應用程式功能的各個方面。透過 ServiceWorkerRegistration.paymentManager 屬性訪問。

PaymentRequestEvent

用於 paymentrequest 事件的事件物件，該事件在商家網站透過 PaymentRequest.show() 方法發起支付流程後，在支付應用程式的 Service Worker 上觸發。

其他介面的擴充套件

canmakepayment 事件

當支付應用程式的 ServiceWorkerGlobalScope 成功註冊後觸發，以表明它已準備好處理付款。

paymentrequest 事件

當商家網站透過 PaymentRequest.show() 方法發起支付流程後，在支付應用程式的 ServiceWorkerGlobalScope 上觸發。

ServiceWorkerRegistration.paymentManager

返回支付應用程式的 PaymentManager 例項，用於管理各種支付應用程式功能。

規範

規範
Payment Handler API
# the-paymentrequestevent

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 ，由 MDN 貢獻者 修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題
© . Content available under a Creative Commons license.