Web-based Payment Handler API

Konzepte und Nutzung

Auf einer Händler-Website wird eine Zahlungsanfrage 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 supportedMethods-Eigenschaft 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, wie folgt:

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

Zahlungsanwendungen verfügbar machen

In unterstützenden Browsern beginnt der Prozess mit der Anforderung einer Zahlungsanwendungsmethodendatei von jeder URL. Ein Zahlungsanwendungsmethodenmanifest 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"]
}

Bei einer Zahlungsanwendungskennung wie https://bobbucks.dev/pay lädt der Browser:

1. Beginnt mit dem Laden von https://bobbucks.dev/pay und prüft seine HTTP-Header.
   1. Wenn ein Link-Header mit rel="payment-method-manifest" gefunden wird, lädt er stattdessen das Zahlungsanwendungsmethodenmanifest an diesem Ort herunter (siehe Route den Browser optional, um das Zahlungsanwendungsmethodenmanifest an einem anderen Ort zu finden für Details).
   2. Andernfalls wird der Antwortinhalt von https://bobbucks.dev/pay als Zahlungsanwendungsmethodenmanifest analysiert.
2. Analysiert den heruntergeladenen Inhalt als JSON mit default_applications und supported_origins-Elementen.

Diese Elemente haben die folgenden Zwecke:

• default_applications teilt dem Browser mit, wo er die Standard-Zahlungsanwendung finden kann, die die BobBucks-Zahlungsmethode verwenden kann, wenn noch keine installiert ist.
• supported_origins teilt dem Browser mit, welche anderen Zahlungsanwendungen berechtigt sind, die BobBucks-Bezahlung bei Bedarf abzuwickeln. Wenn sie bereits auf dem Gerät installiert sind, werden sie dem Benutzer als alternative Zahlungsoptionen neben der Standardanwendung präsentiert.

Aus dem Zahlungsanwendungsmethodenmanifest erhält der Browser die URL der Web-App-Manifestdateien der Standard-Zahlungsanwendungen, die beliebig benannt sein können und etwa so aussehen:

{
  "name": "Pay with BobBucks",
  "short_name": "BobBucks",
  "description": "This is an example of the Web-based 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 von der Händleranwendung als Antwort auf eine Benutzeraktion aufgerufen wird, verwendet der Browser die name- und icons-Informationen, die in jedem Manifest gefunden wurden, um die Zahlungsanwendungen in der browserbasierten Payment Request-Benutzeroberfläche dem Benutzer zu präsentieren.

• Wenn es mehrere Zahlungsanwendungsoptionen gibt, wird dem Benutzer eine Liste von Optionen zur Auswahl präsentiert. Die Auswahl einer Zahlungsanwendung startet den Zahlungsablauf, der den Browser bei Bedarf veranlasst, die Web-App "Just-In-Time" (JIT) zu installieren, wobei der im serviceworker-Element angegebene Service Worker registriert wird, damit er die Bezahlung abwickeln kann.
• Wenn es nur eine Zahlungsanwendungsoption gibt, wird die PaymentRequest.show()-Methode den Zahlungsablauf mit dieser Zahlungsanwendung starten, sie bei Bedarf JIT installieren, wie oben beschrieben. Dies ist eine Optimierung, um dem Benutzer keine Liste zu präsentieren, die nur eine Zahlungsanwendungswahl enthält.

Siehe Dienen eines Web-App-Manifests für weitere Details.

Überprüfen, ob die Zahlungsanwendung zahlungsbereit ist

Die PaymentRequest.canMakePayment()-Methode der Payment Request API gibt true zurück, wenn eine Zahlungsanwendung auf dem Gerät des Kunden verfügbar ist, d.h. dass eine die Zahlungsmethode unterstützende Zahlungsanwendung entdeckt wurde und die plattformspezifische Zahlungsanwendung installiert ist oder die webbasierte Zahlungsanwendung 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 Web-basierte Payment Handler API fügt einen zusätzlichen Mechanismus hinzu zur Vorbereitung der Zahlungsabwicklung. Das canmakepayment-Ereignis wird im Service Worker einer Zahlungsanwendung ausgelöst, um zu überprüfen, ob sie bereit ist, eine Bezahlung zu bearbeiten. Es wird speziell ausgelöst, wenn die Händlerwebsite 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 von respondWith() zurückgegebene Promise löst sich mit einem booleschen Wert auf, um anzuzeigen, dass es bereit ist, eine Zahlungsanfrage zu bearbeiten (true) oder nicht (false).

Zahlungsabwicklung

Nachdem die PaymentRequest.show()-Methode aufgerufen wurde, wird ein paymentrequest-Ereignis im Service Worker der Zahlungsanwendung ausgelöst. Auf dieses Ereignis wird innerhalb des Service Workers der Zahlungsanwendung gehört, um den nächsten Schritt im Zahlungsprozess zu starten.

let paymentRequestEvent;
let resolver;
let client;

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

  // …
});

Wenn ein paymentrequest-Ereignis empfangen wird, kann die Zahlungsanwendung ein Payment-Handler-Fenster öffnen, indem sie PaymentRequestEvent.openWindow() aufruft. Das Payment-Handler-Fenster wird den Kunden eine Schnittstelle der Zahlungsanwendung anbieten, in der sie die Zahlung authentifizieren, eine Versandadresse und Optionen wählen und die Zahlung autorisieren können.

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

Siehe Erhalte ein Zahlungsanfrage-Ereignis vom Händler für weitere Details zu diesem Schritt.

Verwaltung der Funktionalität von Zahlungsanwendungen

Sobald ein Service Worker einer Zahlungsanwendung registriert ist, können Sie die PaymentManager-Instanz des Service Workers (zugänglich über ServiceWorkerRegistration.paymentManager) verwenden, um verschiedene Aspekte der Funktionalität der Zahlungsanwendung 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 einen Hinweis für den Browser bereitzustellen, der zusammen mit dem Namen und Symbol der Zahlungsanwendung in der Web-basierte Payment Handler-Benutzeroberfläche angezeigt wird.
• PaymentManager.enableDelegations() wird verwendet, um die Verantwortung für die Bereitstellung verschiedener Teile der erforderlichen Zahlungsinformationen an die Zahlungsanwendung zu delegieren, anstatt sie über den Browser zu sammeln (zum Beispiel über Autofill).

Schnittstellen

CanMakePaymentEvent

Das Ereignisobjekt für das canmakepayment-Ereignis, das im Service Worker einer Zahlungsanwendung ausgelöst wird, wenn sie erfolgreich registriert wurde, um anzuzeigen, dass sie zahlungsbereit ist.

PaymentManager

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

PaymentRequestEvent Experimentell

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

Erweiterungen zu anderen Schnittstellen

canmakepayment Ereignis

Wird im ServiceWorkerGlobalScope einer Zahlungsanwendung ausgelöst, wenn sie erfolgreich registriert wurde, um anzuzeigen, dass sie zahlungsbereit ist.

paymentrequest Ereignis

Wird im ServiceWorkerGlobalScope einer Zahlungsanwendung ausgelöst, wenn ein Zahlungsablauf auf der Händler-Website über die PaymentRequest.show()-Methode initiiert wurde.

ServiceWorkerRegistration.paymentManager

Gibt eine PaymentManager-Instanz einer Zahlungsanwendung zurück, die verwendet wird, um verschiedene Zahlungsanwendungsfunktionen zu verwalten.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• BobBucks Beispiel-Zahlungsanwendung
• Übersicht über webbasierte Zahlungsanwendungen
• Einrichtung einer Zahlungsmethode
• Leben einer Zahlungstransaktion
• Verwendung der Payment Request API
• Konzepte der Zahlungsabwicklung