ServiceWorkerGlobalScope: canmakepayment — Ereignis · JavaScript-Referenz

Signatur

self.addEventListener("canmakepayment", handler)

Beschreibung

Das Ereignis canmakepayment gehört zur Payment Handler API. Der Browser löst es im Service Worker einer installierten, webbasierten Zahlungs-App aus, sobald eine Händlerseite einen PaymentRequest mit einer passenden Zahlungsmethode (supportedMethods) erstellt. Die Zahlungs-App teilt dem Browser damit mit, ob sie gerade in der Lage ist, eine Zahlung anzunehmen. Das kann z. B. davon abhängen, ob der Nutzer angemeldet ist oder ein Zahlungsmittel hinterlegt hat.

Der Handler bekommt ein CanMakePaymentEvent. Mit event.respondWith() übergibt man einen boolean oder ein Promise<boolean>. Bei true zeigt der Browser die App als Zahlungsoption an und die Händlerseite erhält über PaymentRequest.canMakePayment() bzw. hasEnrolledInstrument() ein positives Ergebnis. Bei false oder wenn gar keine Antwort kommt, gilt die App als nicht bereit.

Registriert wird das Ereignis entweder mit self.addEventListener("canmakepayment", handler) oder über die Eigenschaft self.oncanmakepayment = handler. Wichtig ist der Datenschutz: Aus Gründen der Privatsphäre enthält das Ereignis in aktuellen Browsern keine Händlerdaten wie topOrigin, paymentRequestOrigin oder methodData mehr, damit Zahlungs-Apps den Nutzer nicht seitenübergreifend verfolgen können. Die Entscheidung muss also allein auf dem Zustand der App beruhen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, immer `"canmakepayment"`.
$handler Pflicht	(event: CanMakePaymentEvent) => void		Callback, der ein `CanMakePaymentEvent` erhält. Er muss synchron `event.respondWith(boolean \| Promise<boolean>)` aufrufen.
$options	boolean \| AddEventListenerOptions	false	Die üblichen Listener-Optionen wie `once`. Bei `addEventListener` sind sie optional.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die eigentliche Antwort an den Browser läuft über event.respondWith(true|false).

Beispiele

Grundgerüst: Zahlungsbereitschaft immer melden

// payment-sw.js – Service Worker der Zahlungs-App
self.addEventListener("canmakepayment", (event) => {
  // App ist immer bereit
  event.respondWith(true);
});

Bereitschaft abhängig vom Anmeldestatus (asynchron)

// payment-sw.js
const istAngemeldet = async () => {
  const cache = await caches.open("session");
  const antwort = await cache.match("/session-token");
  return Boolean(antwort);
};

self.addEventListener("canmakepayment", (event) => {
  // respondWith muss synchron aufgerufen werden – das Promise darf später erfüllt werden
  event.respondWith(
    istAngemeldet().catch(() => false)
  );
});

Alternative über die on-Property

// payment-sw.js
self.oncanmakepayment = (event) => {
  const bereit = self.registration.active !== null;
  console.log("canmakepayment – bereit:", bereit);
  event.respondWith(bereit);
};

canmakepayment – bereit: true

Händlerseite: Ereignis indirekt auslösen

// Seite des Händlers (nicht im Service Worker)
const request = new PaymentRequest(
  [{ supportedMethods: "https://bobbucks.dev/pay" }],
  { total: { label: "Summe", amount: { currency: "EUR", value: "19.99" } } }
);

const pruefen = async () => {
  const kannZahlen = await request.canMakePayment();
  console.log("Zahlungs-App bereit:", kannZahlen);
};

pruefen();

Zahlungs-App bereit: true

// Wichtig · Fallstricke

Kompatibilität: Das Ereignis ist experimentell und wird nur in Chromium-Browsern (Chrome, Edge, Opera) unterstützt. Firefox und Safari kennen die Payment Handler API nicht. Prüfen lässt sich die Unterstützung mit "oncanmakepayment" in self.
event.respondWith() muss synchron im Handler aufgerufen werden. Erfolgt der Aufruf erst nach einem await, wirft er eine InvalidStateError-Ausnahme.
Ruft der Handler respondWith() gar nicht auf oder wird das Promise abgelehnt, gilt die App als nicht bereit.
Der Browser gewährt nur ein kurzes Zeitfenster. Lange Netzwerkanfragen im Handler sollte man vermeiden und stattdessen gespeicherte Daten (Cache, IndexedDB) nutzen.
Datenschutz: Die früher vorhandenen Eigenschaften topOrigin, paymentRequestOrigin, methodData und modifiers wurden entfernt. Darauf sollte man sich nicht verlassen. Chrome löst das Ereignis außerdem nicht aus, wenn die App keine eigene Manifest-Datei für die Zahlungsmethode hat oder wenn sie nur per Just-in-Time-Installation angeboten wird.
Service Worker und damit das Ereignis funktionieren nur in einem sicheren Kontext (HTTPS).

Siehe auch

OfflineAudioContext: complete ServiceWorkerGlobalScope: paymentrequest ServiceWorkerGlobalScope: activate ServiceWorkerGlobalScope: contentdelete ServiceWorkerGlobalScope: cookiechange