PaymentRequestEvent.total — Eigenschaft · JavaScript-Referenz

Signatur

PaymentRequestEvent.total

Beschreibung

Die schreibgeschützte Eigenschaft total gehört zum Interface PaymentRequestEvent aus der Payment Handler API. Das Event wird im Service Worker einer webbasierten Zahlungs-App ausgelöst (paymentrequest), sobald ein Händler über new PaymentRequest(...).show() eine Zahlung anfordert und der Nutzer diese Zahlungs-App auswählt.

total enthält ein PaymentCurrencyAmount-Objekt mit den Feldern currency (dreistelliger ISO-4217-Währungscode, z. B. "EUR") und value (Betrag als Zeichenkette in Dezimalschreibweise, z. B. "49.99"). Der Wert stammt aus details.total.amount der Händler-Anfrage.

Man nutzt total, um im Zahlungs-Handler den zu belastenden Betrag anzuzeigen, zu prüfen (z. B. Limits, unterstützte Währungen) und an das eigene Zahlungs-Backend weiterzureichen. Da es sich um eine Eigenschaft handelt, gibt es keine Parameter; der Wert kann nicht verändert werden.

Rückgabewert

Typ

PaymentCurrencyAmount

Beschreibung

Objekt der Form { currency: string, value: string } mit Währungscode und Gesamtbetrag der angeforderten Zahlung.

Beispiele

Gesamtbetrag im Service Worker auslesen

// sw.js – Service Worker der Zahlungs-App
self.addEventListener('paymentrequest', (event) => {
  const { currency, value } = event.total;
  console.log(`Angeforderter Betrag: ${value} ${currency}`);
});

Angeforderter Betrag: 49.99 EUR

Betrag und Währung vor der Zahlung prüfen

// sw.js
const ERLAUBTE_WAEHRUNGEN = ['EUR', 'USD'];
const MAX_BETRAG = 1000;

self.addEventListener('paymentrequest', (event) => {
  const { currency, value } = event.total;
  const betrag = Number.parseFloat(value);

  if (!ERLAUBTE_WAEHRUNGEN.includes(currency) || betrag > MAX_BETRAG) {
    // Promise ablehnen -> Händlerseite erhält einen Fehler
    event.respondWith(Promise.reject(new Error('Betrag oder Währung nicht unterstützt')));
    return;
  }

  event.respondWith(Promise.resolve({
    methodName: event.methodData[0].supportedMethods,
    details: { token: 'demo-token-123' }
  }));
});

Betrag an das Zahlungsfenster übergeben

// sw.js
self.addEventListener('paymentrequest', (event) => {
  let resolver;
  const antwort = new Promise((resolve) => { resolver = resolve; });
  event.respondWith(antwort);

  event.waitUntil((async () => {
    const client = await event.openWindow('/checkout.html');
    // Gesamtbetrag an die Checkout-Seite senden
    client?.postMessage({ typ: 'betrag', total: event.total });
  })());

  self.addEventListener('message', (e) => {
    if (e.data?.typ === 'bestaetigt') {
      resolver({ methodName: 'https://pay.example.com', details: e.data.details });
    }
  }, { once: true });
});

// Wichtig · Fallstricke

Experimentell: Die Payment Handler API wird nur von Chromium-basierten Browsern unterstützt; Firefox und Safari bieten sie nicht an. Vor produktivem Einsatz Feature-Erkennung und eine Alternative vorsehen.
Nur im Service Worker: PaymentRequestEvent und damit total sind nur im Service-Worker-Kontext einer registrierten Zahlungs-App verfügbar, nicht auf normalen Webseiten.
Zeichenkette statt Zahl: value ist ein String. Für Berechnungen nicht mit Gleitkommazahlen rechnen, sondern z. B. in Cent (Ganzzahlen) umrechnen, um Rundungsfehler zu vermeiden.
Nicht vertrauenswürdig: Der Betrag stammt von der Händlerseite. Die endgültige Belastung muss serverseitig gegen die tatsächliche Bestellung geprüft werden.
Einzelne Positionen (displayItems) sind im Event aus Datenschutzgründen nicht enthalten – nur der Gesamtbetrag.

Siehe auch

ImageTrackList.selectedTrack PaymentAddress.country PaymentRequestEvent.methodData PaymentRequestEvent.topOrigin PaymentRequestEvent.modifiers