Payment Handler API

Auf einer Händler-Website wird eine Zahlungsanforderung durch die Erstellung eines neuen PaymentRequest-Objekts initiiert:

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

Die Eigenschaft supportedMethods gibt eine URL an, die die vom Händler unterstützte Zahlungsmethode repräsentiert. Um mehr als eine Zahlungsmethode zu verwenden, würden Sie sie in einem Array von Objekten angeben, so:

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

In unterstützten Browsern beginnt der Prozess mit der Anforderung einer Zahlungs-Methode-Manifestdatei von jeder URL. Ein Zahlungs-Methode-Manifest wird typischerweise als payment-manifest.json bezeichnet (der genaue Name kann beliebig sein) und sollte wie folgt strukturiert sein:

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

Angenommen, ein Zahlungs-Methode-Identifikator wie https://bobbucks.dev/pay ist gegeben, der Browser:

1. Beginnt mit dem Laden von https://bobbucks.dev/pay und überprüft dessen HTTP-Header.
   1. Wenn ein Link-Header mit rel="payment-method-manifest" gefunden wird, wird das Zahlungs-Methode-Manifest an diesem Ort stattdessen heruntergeladen (siehe Optionen, den Browser zu einem anderen Speicherort des Zahlungs-Methode-Manifests zu leiten für Details).
   2. Andernfalls wird der Antwortkörper von https://bobbucks.dev/pay als Zahlungs-Methode-Manifest analysiert.
2. Analysiert den heruntergeladenen Inhalt als JSON mit den Mitgliedern default_applications und supported_origins.

Diese Mitglieder haben folgende Zwecke:

• default_applications teilt dem Browser mit, wo die Standard-Zahlungs-App zu finden ist, die die BobBucks-Zahlungsmethode verwenden kann, falls noch keine installiert ist.
• supported_origins teilt dem Browser mit, welche anderen Zahlungs-Apps berechtigt sind, die BobBucks-Zahlung zu bearbeiten, falls erforderlich. Wenn sie bereits auf dem Gerät installiert sind, werden sie dem Benutzer als alternative Zahlungsoptionen neben der Standard-Anwendung präsentiert.

Aus dem Zahlungs-Methode-Manifest erhält der Browser die URL der Web-App-Manifestdateien der Standard-Zahlungs-Apps, die beliebig bezeichnet werden können und etwa so aussehen:

{
  "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"
        }
      ]
    }
  ]
}

Wenn die PaymentRequest.show()-Methode durch die Händler-App als Reaktion auf eine Benutzeraktion aufgerufen wird, verwendet der Browser die im Manifest gefundenen Informationen zu name und icons, um dem Benutzer die Zahlungs-Apps in der von ihm bereitgestellten Payment Request UI anzuzeigen.

• Wenn mehrere Zahlungs-App-Optionen verfügbar sind, wird dem Benutzer eine Liste von Optionen präsentiert, aus der er wählen kann. Die Auswahl einer Zahlungs-App startet den Zahlungsfluss, wodurch der Browser Just-In-Time (JIT) die Web-App installiert, wenn nötig, und den im serviceworker Mitglied festgelegten Service Worker registriert, damit er die Zahlung abwickeln kann.
• Wenn es nur eine Zahlungs-App-Option gibt, wird die PaymentRequest.show()-Methode den Zahlungsfluss mit dieser Zahlungs-App starten, sie JIT-installieren, wenn nötig, wie oben beschrieben. Dies ist eine Optimierung, um zu vermeiden, dem Benutzer eine Liste zu präsentieren, die nur eine Zahlungs-App-Auswahl enthält.

Weitere Details finden Sie unter Web-App-Manifest bereitstellen.

Die Methode PaymentRequest.canMakePayment() der Payment Request API gibt true zurück, wenn eine Zahlungs-App auf dem Gerät des Kunden verfügbar ist, was bedeutet, dass eine Zahlungs-App, die die Zahlungsmethode unterstützt, entdeckt wurde und dass die plattformspezifische Zahlungs-App installiert oder die webbasierten Zahlungs-App bereit ist, registriert zu werden.

async function checkCanMakePayment() {
  // ...

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

Die Payment Handler API fügt einen zusätzlichen Mechanismus hinzu, um sich auf die Abwicklung einer Zahlung vorzubereiten. Das Ereignis canmakepayment wird auf dem Service Worker einer Zahlungs-App ausgelöst, um zu überprüfen, ob sie bereit ist, eine Zahlung zu bearbeiten. Insbesondere wird es ausgelöst, wenn die Händler-Website den PaymentRequest()-Konstruktor aufruft. Der Service Worker kann dann die Methode CanMakePaymentEvent.respondWith() verwenden, um entsprechend zu antworten:

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

Das Versprechen, das von respondWith() zurückgegeben wird, wird mit einem Boolean-Wert aufgelöst, um zu signalisieren, dass es bereit ist, eine Zahlungsanforderung zu bearbeiten (true) oder nicht (false).

Nachdem die Methode PaymentRequest.show() aufgerufen wurde, wird ein paymentrequest-Ereignis auf dem Service Worker der Zahlungs-App ausgelöst. Dieses Ereignis wird innerhalb des Service Workers der Zahlungs-App abgehört, um die nächste Phase des Zahlungsprozesses zu beginnen.

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;

  // ...
});

Wenn ein paymentrequest-Ereignis empfangen wird, kann die Zahlungs-App ein Zahlungs-Handler-Fenster öffnen, indem sie PaymentRequestEvent.openWindow() aufruft. Das Zahlungs-Handler-Fenster präsentiert den Kunden eine Benutzeroberfläche der Zahlungs-App, in der sie sich authentifizieren, die Versandadresse und Optionen auswählen und die Zahlung autorisieren können.

Nachdem die Zahlung abgewickelt wurde, wird PaymentRequestEvent.respondWith() verwendet, um das Zahlungsergebnis an die Händler-Website zurückzugeben.

Siehe Empfangen eines Zahlungsanfrageereignisses vom Händler für mehr Details zu dieser Phase.

Sobald ein Service Worker einer Zahlungs-App registriert ist, können Sie die Instanz des PaymentManager des Service Workers (zugänglich über ServiceWorkerRegistration.paymentManager) verwenden, um verschiedene Aspekte der Funktionalität der Zahlungs-App zu verwalten.

Zum Beispiel:

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

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

  // ...
});

• PaymentManager.userHint wird verwendet, um dem Browser einen Hinweis anzuzeigen, zusammen mit dem Namen und dem Symbol der Zahlungs-App in der Payment Handler UI.
• PaymentManager.enableDelegations() wird verwendet, um die Verantwortung für die Bereitstellung verschiedener Teile der erforderlichen Zahlungsinformationen an die Zahlungs-App zu delegieren, statt sie vom Browser zu sammeln (zum Beispiel über Autofill).

CanMakePaymentEvent

Das Ereignisobjekt für das canmakepayment-Ereignis, das ausgelöst wird, wenn eine Zahlungs-App über einen Service Worker erfolgreich registriert wurde, um zu signalisieren, dass sie bereit ist, Zahlungen zu bearbeiten.

PaymentManager

Wird verwendet, um verschiedene Aspekte der Funktionalität von Zahlungs-Apps zu verwalten. Zugriff über die Eigenschaft ServiceWorkerRegistration.paymentManager.

PaymentRequestEvent Experimentell

Das Ereignisobjekt für das paymentrequest-Ereignis, das auf einem Service Worker einer Zahlungs-App ausgelöst wird, wenn ein Zahlungsfluss auf der Händler-Website über die Methode PaymentRequest.show() eingeleitet wurde.

canmakepayment Ereignis

Wird auf dem ServiceWorkerGlobalScope einer Zahlungs-App ausgelöst, wenn sie erfolgreich registriert wurde, um zu signalisieren, dass sie bereit ist, Zahlungen zu verarbeiten.

paymentrequest Ereignis

Wird auf dem ServiceWorkerGlobalScope einer Zahlungs-App ausgelöst, wenn ein Zahlungsfluss auf der Händler-Website über die Methode PaymentRequest.show() eingeleitet wurde.

ServiceWorkerRegistration.paymentManager

Gibt die Instanz des PaymentManager einer Zahlungs-App zurück, die verwendet wird, um verschiedene Funktionen der Zahlungs-App zu verwalten.

• BobBucks Beispiel Zahlungs-App
• Überblick über webbasierte Zahlungs-Apps
• Einrichten einer Zahlungsmethode
• Leben einer Zahlungstransaktion
• Verwendung der Payment Request API
• Konzepte der Zahlungsabwicklung