ServiceWorkerRegistration.paymentManager — Eigenschaft · JavaScript-Referenz

Signatur

ServiceWorkerRegistration.paymentManager

Beschreibung

Die Eigenschaft paymentManager gehört zur Payment Handler API. Mit ihr kann eine Web-Anwendung als Zahlungsanbieter (Payment Handler) auftreten, zum Beispiel als Wallet, Bezahldienst oder Bank-App. Ruft ein Händler auf einer anderen Website new PaymentRequest(...) auf, kann der Browser den Service Worker des Anbieters starten. Dieser empfängt dann ein paymentrequest-Ereignis und wickelt die Zahlung ab.

Die Eigenschaft liefert ein PaymentManager-Objekt, das an genau diese Service-Worker-Registrierung gebunden ist. Darüber stellt der Anbieter unter anderem Folgendes ein:

userHint: ein kurzer Text, den der Browser im Auswahldialog neben dem Namen des Anbieters anzeigt, z. B. eine maskierte Kontonummer.
enableDelegations(delegations): teilt dem Browser mit, welche Angaben der Anbieter selbst liefern kann ("shippingAddress", "payerName", "payerEmail", "payerPhone"). Der Browser muss diese Daten dann nicht mehr selbst abfragen.
instruments: eine ältere, inzwischen aus der Spezifikation entfernte Schnittstelle zum Verwalten von Zahlungsmitteln.

Sie nutzen die Eigenschaft typischerweise direkt nach der Registrierung des Service Workers oder nach navigator.serviceWorker.ready. Die Zahlungsmethoden, die Ihr Dienst unterstützt, werden in der Regel über eine Payment Method Manifest-Datei auf Ihrem eigenen Server angemeldet, nicht über paymentManager selbst.

Rückgabewert

Typ

PaymentManager

Beschreibung

Das PaymentManager-Objekt dieser Registrierung. Ist die API nicht verfügbar, gibt es die Eigenschaft nicht, und der Zugriff liefert undefined.

Beispiele

Service Worker registrieren und Anbieter-Hinweis setzen

const setupPaymentHandler = async () => {
  if (!('serviceWorker' in navigator)) return;

  const registration = await navigator.serviceWorker.register('/pay-sw.js');
  await navigator.serviceWorker.ready;

  if (!registration.paymentManager) {
    console.log('Payment Handler API wird nicht unterstützt.');
    return;
  }

  // Text im Auswahldialog des Browsers, z. B. maskierte Kontonummer
  registration.paymentManager.userHint = 'Konto •••• 4711';
  console.log('Hinweis gesetzt:', registration.paymentManager.userHint);
};

setupPaymentHandler();

Hinweis gesetzt: Konto •••• 4711

Lieferadresse und Kontaktdaten übernehmen (Delegation)

const enableDelegations = async () => {
  const registration = await navigator.serviceWorker.ready;
  const pm = registration.paymentManager;

  if (!pm || typeof pm.enableDelegations !== 'function') {
    console.log('Delegation nicht verfügbar.');
    return;
  }

  try {
    await pm.enableDelegations([
      'shippingAddress',
      'payerName',
      'payerEmail'
    ]);
    console.log('Delegationen aktiviert.');
  } catch (err) {
    console.error('Fehler beim Aktivieren:', err);
  }
};

enableDelegations();

Delegationen aktiviert.

Gegenstück im Service Worker: paymentrequest verarbeiten

// pay-sw.js
self.addEventListener('paymentrequest', (event) => {
  const { total, methodData } = event;
  console.log('Zahlung angefordert:', total.value, total.currency);

  event.respondWith(new Promise(async (resolve, reject) => {
    try {
      // Bezahlfenster des Anbieters öffnen
      const client = await event.openWindow('/pay/checkout.html');
      if (!client) throw new Error('Fenster konnte nicht geöffnet werden');

      // Antwort des Fensters abwarten
      self.addEventListener('message', (msg) => {
        if (msg.data?.status === 'approved') {
          resolve({
            methodName: methodData[0].supportedMethods,
            details: { token: msg.data.token }
          });
        } else {
          reject(new Error('Zahlung abgebrochen'));
        }
      }, { once: true });
    } catch (err) {
      reject(err);
    }
  }));
});

Zahlung angefordert: 49.90 EUR

// Wichtig · Fallstricke

Experimentell und fast nur in Chromium: Nur Chrome, Edge und andere Chromium-Browser unterstützen die API. Firefox und Safari kennen paymentManager nicht. Prüfen Sie deshalb immer vorher, ob die Eigenschaft vorhanden ist.
Nur in sicherer Umgebung: Die API funktioniert ausschließlich über HTTPS (oder localhost) und mit einem aktiven Service Worker.
Zahlungsmittel: paymentManager.instruments wurde aus der Spezifikation entfernt und wird nicht mehr zuverlässig unterstützt. Verwenden Sie stattdessen ein Payment Method Manifest und das Web App Manifest.
Delegationen: enableDelegations() nimmt nur die festgelegten Zeichenketten an. Bei unbekannten Werten wird das Promise mit einem TypeError abgelehnt. Wenn Sie Delegationen aktivieren, muss Ihr Service Worker die zugesagten Daten in der Antwort auf paymentrequest auch wirklich mitliefern.
Sicherheit: Prüfen Sie im Service Worker Herkunft und Inhalt der Zahlungsanfrage, z. B. event.topOrigin und event.paymentRequestOrigin, bevor Sie Zahlungen freigeben. Geben Sie im userHint keine vollständigen Konto- oder Kartennummern an.

Siehe auch

ServiceWorkerRegistration.navigationPreload ServiceWorkerRegistration.pushManager ServiceWorkerRegistration.waiting ServiceWorkerRegistration.active ServiceWorkerRegistration.updateViaCache