PaymentRequestEvent.topOrigin — Eigenschaft · JavaScript-Referenz

Signatur

PaymentRequestEvent.topOrigin

Beschreibung

Die Eigenschaft topOrigin eines PaymentRequestEvent gibt als String den Ursprung (Schema, Host und Port, z. B. https://shop.example) der obersten Seite zurück, auf der der Zahlungsempfänger den Aufruf new PaymentRequest() ausgelöst hat. Das Event wird im Service Worker einer Payment Handler-Anwendung (Web-basierte Zahlungs-App) im paymentrequest-Handler ausgelöst.

Wichtig ist die Unterscheidung zu PaymentRequestEvent.paymentRequestOrigin: Wird der Zahlungsvorgang aus einem eingebetteten <iframe> gestartet (z. B. einem Checkout-Widget eines Zahlungsdienstleisters), liefert paymentRequestOrigin den Ursprung des iframes, topOrigin hingegen den Ursprung der Hauptseite, die der Nutzer in der Adressleiste sieht. Ohne Einbettung sind beide Werte identisch.

Typische Einsatzzwecke sind die Anzeige des Händlers im Zahlungsfenster („Zahlung an shop.example“), Risiko- und Betrugsprüfungen (Abgleich mit einer Liste registrierter Händler) sowie Protokollierung. Die Eigenschaft ist schreibgeschützt und wird vom Browser gesetzt – die Seite des Händlers kann sie nicht fälschen.

Rückgabewert

Typ

string

Beschreibung

Serialisierter Ursprung des obersten Browsing-Kontexts, z. B. "https://shop.example" (ohne Pfad und ohne abschließenden Schrägstrich).

Beispiele

Händler-Ursprung im Service Worker auslesen

// sw.js – Service Worker der Zahlungs-App
self.addEventListener('paymentrequest', (event) => {
  console.log('Oberste Seite:', event.topOrigin);
  console.log('Aufrufender Kontext:', event.paymentRequestOrigin);
});

Oberste Seite: https://shop.example Aufrufender Kontext: https://checkout.psp.example

Nur registrierte Händler zulassen

// sw.js
const ERLAUBTE_HAENDLER = new Set([
  'https://shop.example',
  'https://store.example'
]);

self.addEventListener('paymentrequest', (event) => {
  if (!ERLAUBTE_HAENDLER.has(event.topOrigin)) {
    // Promise ablehnen -> PaymentRequest.show() schlägt beim Händler fehl
    event.respondWith(Promise.reject(
      new Error(`Händler nicht registriert: ${event.topOrigin}`)
    ));
    return;
  }

  event.respondWith(handlePayment(event));
});

const handlePayment = async (event) => {
  const client = await event.openWindow('/pay.html');
  // ... Kommunikation mit dem Zahlungsfenster, danach:
  return { methodName: event.methodData[0].supportedMethods, details: { token: 'abc123' } };
};

Händlernamen an das Zahlungsfenster übergeben

// sw.js
self.addEventListener('paymentrequest', (event) => {
  event.respondWith((async () => {
    const params = new URLSearchParams({
      merchant: new URL(event.topOrigin).hostname,
      amount: event.total.value,
      currency: event.total.currency
    });
    const client = await event.openWindow(`/pay.html?${params}`);
    return new Promise((resolve) => {
      self.addEventListener('message', (e) => {
        if (e.source?.id === client?.id) resolve(e.data);
      }, { once: true });
    });
  })());
});

// Zahlungsfenster öffnet z. B. /pay.html?merchant=shop.example&amount=49.90&currency=EUR

// Wichtig · Fallstricke

Kompatibilität: Die Payment Handler API ist experimentell und nur in Chromium-basierten Browsern (Chrome, Edge, Opera) verfügbar. Firefox und Safari unterstützen PaymentRequestEvent nicht.
Nur im Service Worker: Das Event und damit topOrigin existiert ausschließlich im Service-Worker-Kontext der Zahlungs-App, nicht auf der Händlerseite.
Nicht mit paymentRequestOrigin verwechseln: Bei eingebetteten iframes unterscheiden sich die Werte. Für Anzeige und Vertrauensentscheidungen gegenüber dem Nutzer ist meist topOrigin relevant.
Sicherheit: Der Wert ist vom Browser garantiert, aber ein Ursprung allein ist keine Händler-Authentifizierung. Zahlungsdaten zusätzlich serverseitig prüfen und den Wert beim Einfügen in HTML nicht per innerHTML ausgeben.
Nur in sicheren Kontexten (HTTPS) verfügbar.

Siehe auch

PaymentAddress.dependentLocality PaymentRequestEvent.modifiers PaymentRequestEvent.total PaymentRequestEvent.methodData PaymentRequestEvent.paymentRequestOrigin