PaymentManager — Schnittstelle · JavaScript-Referenz

Signatur

interface PaymentManager

Beschreibung

Das Interface PaymentManager gehört zur Web-based Payment Handler API. Mit dieser API kann eine Web-Anwendung als Zahlungs-App (Payment Handler) arbeiten. Händlerseiten sprechen sie dann über die Payment Request API an. Eine PaymentManager-Instanz legst du nicht selbst an. Du bekommst sie immer über die Eigenschaft paymentManager einer ServiceWorkerRegistration. Die Zahlungs-App ist also fest an einen Service Worker gebunden, der die Ereignisse paymentrequest und canmakepayment verarbeitet.

Wichtige Bestandteile:

PaymentManager.userHint – ein Text, den der Browser in der Auswahl der Zahlungsarten neben dem Namen der App anzeigt, z. B. die letzten Ziffern einer Karte oder eine E-Mail-Adresse.
PaymentManager.enableDelegations(delegations) – teilt dem Browser mit, dass die App bestimmte Daten selbst liefern kann: "payerName", "payerEmail", "payerPhone" und "shippingAddress". Der Rückgabewert ist ein Promise<void>.
PaymentManager.instruments – ein PaymentInstruments-Objekt für einzelne Zahlungsmittel. Diese Eigenschaft ist veraltet und in aktuellen Chromium-Versionen nicht mehr zuverlässig verfügbar.

Du brauchst PaymentManager, wenn du eine eigene Zahlungs-App im Web baust, etwa eine Wallet, einen Anbieter für Bankzahlungen oder ein Treuepunktesystem. Wenn du auf einer Händlerseite nur Zahlungen entgegennimmst, brauchst du dieses Interface nicht. Dafür genügt PaymentRequest.

Parameter

Name	Typ	Default	Beschreibung
$delegations Pflicht	Array<"payerName"\|"payerEmail"\|"payerPhone"\|"shippingAddress">		Parameter von `enableDelegations()`: Liste der Daten, die die Zahlungs-App anstelle des Browsers liefert. Unbekannte Werte führen zu einem `TypeError`.

Beispiele

Service Worker registrieren und PaymentManager abrufen

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

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

  if (!registration.paymentManager) {
    console.warn('Payment Handler API wird nicht unterstützt');
    return null;
  }
  console.log('PaymentManager verfügbar:', registration.paymentManager);
  return registration.paymentManager;
};

registerPaymentApp();

PaymentManager verfügbar: PaymentManager {userHint: ''}

Nutzerhinweis setzen und Delegationen aktivieren

const configurePaymentApp = async () => {
  const registration = await navigator.serviceWorker.ready;
  const manager = registration.paymentManager;
  if (!manager) return;

  // Wird in der Auswahl der Zahlungsarten angezeigt
  manager.userHint = 'max@example.com';

  try {
    await manager.enableDelegations(['payerName', 'payerEmail', 'shippingAddress']);
    console.log('Delegationen aktiviert');
  } catch (err) {
    console.error('Delegation fehlgeschlagen:', err.name);
  }
};

configurePaymentApp();

Delegationen aktiviert

Gegenstück im Service Worker (pay-sw.js)

// Prüfen, ob die App bezahlen kann
self.addEventListener('canmakepayment', (event) => {
  event.respondWith(Promise.resolve(true));
});

// Zahlungsanfrage des Händlers bearbeiten
self.addEventListener('paymentrequest', (event) => {
  event.respondWith((async () => {
    const client = await event.openWindow('/checkout.html');
    // Hier würde die App den Kunden authentifizieren ...
    return {
      methodName: event.methodData[0].supportedMethods,
      details: { token: 'demo-token-123' },
      payerName: 'Max Mustermann',
      payerEmail: 'max@example.com'
    };
  })());
});

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell. Sie wird nur in Chromium-Browsern (Chrome, Edge, Opera) unterstützt. Firefox und Safari unterstützen sie nicht. Prüfe daher vor der Nutzung immer, ob registration.paymentManager vorhanden ist.

Die API funktioniert nur in einem sicheren Kontext (HTTPS) und nur mit einem aktiv registrierten Service Worker.
Die Eigenschaft instruments und das Interface PaymentInstruments gelten als veraltet. In neuen Projekten besser nicht verwenden. Stattdessen userHint und ein Web-App-Manifest bzw. das Zahlungsmethoden-Manifest (payment-method-manifest) nutzen.
Nach enableDelegations() muss die App die angekündigten Daten in der Antwort auf paymentrequest auch liefern, wenn der Händler sie anfordert. Sonst wird die Zahlung abgelehnt.
userHint kann für andere sichtbar sein. Schreibe dort keine sensiblen Daten wie vollständige Kartennummern hinein.

Siehe auch

BatteryManager SyncManager PaymentAddress PushManager ContactsManager