Payment Handler API

Auf einer Händler-Website wird eine Zahlungsanforderung durch die Konstruktion 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 diese in einem Array von Objekten angeben, wie folgt:

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

In unterstützenden Browsern beginnt der Prozess mit der Anforderung einer Payment Method Manifest-Datei von jeder URL. Ein Payment Method Manifest wird typischerweise als payment-manifest.json bezeichnet (der genaue Name kann beliebig gewählt werden) und sollte folgendermaßen strukturiert sein:

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

Bei einem Bezahlmethoden-Identifikator wie https://bobbucks.dev/pay führt der Browser folgende Schritte aus:

1. Er beginnt, https://bobbucks.dev/pay zu laden und überprüft dessen HTTP-Header.
   1. Wird ein Link-Header mit rel="payment-method-manifest" gefunden, wird das Payment Method Manifest stattdessen von diesem Ort heruntergeladen (siehe Optionally route the browser to find the payment method manifest in another location für weitere Details).
   2. Ansonsten wird der Antwortinhalt von https://bobbucks.dev/pay als Payment Method Manifest geparst.
2. Der heruntergeladene Inhalt wird als JSON mit den Mitgliedern default_applications und supported_origins analysiert.

Diese Mitglieder haben folgende Zwecke:

• default_applications gibt dem Browser an, wo die Standard-Zahlungs-App zu finden ist, die die BobBucks-Zahlungsmethode verwenden kann, falls sie nicht bereits installiert ist.
• supported_origins gibt dem Browser an, welche anderen Zahlungs-Apps berechtigt sind, die BobBucks-Zahlung bei Bedarf zu handhaben. Wenn sie bereits auf dem Gerät installiert sind, werden sie dem Benutzer als alternative Zahlungsoptionen neben der Standardanwendung präsentiert.

Aus dem Payment Method Manifest erhält der Browser die URL der Web-App-Manifestdateien der Standard-Zahlungs-Apps, die beliebig benannt 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 Methode PaymentRequest.show() von der Händler-App als Reaktion auf eine Benutzeraktion aufgerufen wird, verwendet der Browser die in jedem Manifest gefundenen Informationen name und icons, um die Zahlungs-Apps dem Benutzer in der vom Browser bereitgestellten Payment Request-Benutzeroberfläche zu präsentieren.

• Wenn mehrere Zahlungs-App-Optionen verfügbar sind, wird dem Benutzer eine Liste von Optionen angezeigt, aus denen er wählen kann. Die Auswahl einer Zahlungs-App startet den Zahlungsprozess, was dazu führt, dass der Browser die Web-App bei Bedarf Just-In-Time (JIT) installiert und den in dem Mitglied serviceworker angegebenen Service Worker registriert, damit er die Zahlung abwickeln kann.
• Wenn es nur eine Zahlungs-App-Option gibt, beginnt die Methode PaymentRequest.show() den Zahlungsprozess mit dieser Zahlungs-App und installiert sie bei Bedarf JIT, wie oben beschrieben. Dies ist eine Optimierung, um dem Benutzer eine Liste zu ersparen, die nur eine Zahlungs-App-Auswahl enthält.

Siehe Serve a web app manifest für weitere Details.

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 ist oder die webbasierte 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 Zahlungsabwicklung vorzubereiten. Das Ereignis canmakepayment wird auf einem Service Worker der Zahlungs-App ausgelöst, um zu überprüfen, ob es bereit ist, eine Zahlung zu verarbeiten. Insbesondere wird es ausgelöst, wenn die Händler-Website den Konstruktor PaymentRequest() 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 von respondWith() zurückgegebene Versprechen löst sich mit einem Boolean auf, um anzuzeigen, 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 überwacht, um den nächsten Schritt im Zahlungsprozess 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 Zahlungsfenster öffnen, indem sie PaymentRequestEvent.openWindow() aufruft. Das Zahlungsfenster bietet 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.

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

Siehe Receive a payment request event from the merchant für weitere Details zu diesem Schritt.

Sobald ein Zahlungs-App-Service Worker registriert ist, können Sie die Instanz 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 Icon der Zahlungs-App in der Payment Handler-Benutzeroberfläche.
• PaymentManager.enableDelegations() wird verwendet, um die Verantwortung für das Bereitstellen verschiedener Teile der erforderlichen Zahlungsinformationen an die Zahlungs-App zu delegieren, anstatt sie vom Browser zu erfassen (zum Beispiel über Autofill).

CanMakePaymentEvent

Das Ereignisobjekt für das canmakepayment-Ereignis, das auf einem Service Worker der Zahlungs-App ausgelöst wird, wenn es erfolgreich registriert wurde, um anzuzeigen, dass es bereit ist, Zahlungen zu bearbeiten.

PaymentManager

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

PaymentRequestEvent Experimentell

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

canmakepayment Ereignis

Wird auf dem ServiceWorkerGlobalScope einer Zahlungs-App ausgelöst, wenn es erfolgreich registriert wurde, um anzuzeigen, dass es bereit ist, Zahlungen zu bearbeiten.

paymentrequest Ereignis

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

ServiceWorkerRegistration.paymentManager

Gibt die PaymentManager-Instanz einer Zahlungs-App zurück, die zur Verwaltung verschiedener Funktionen der Zahlungs-App verwendet wird.

• BobBucks Sample Payment App
• Überblick über webbasierte Zahlungs-Apps
• Einrichtung einer Zahlungsmethode
• Lebenszyklus einer Zahlungstransaktion
• Verwendung der Payment Request API
• Konzepte der Zahlungsabwicklung