PaymentRequestEvent.modifiers — Eigenschaft · JavaScript-Referenz

Signatur

PaymentRequestEvent.modifiers

Beschreibung

Die Eigenschaft modifiers des PaymentRequestEvent steht im Service Worker eines Zahlungs-Handlers (Payment Handler API) zur Verfügung. Sie enthält die Modifikatoren, die die Händlerseite im details-Objekt des Konstruktors new PaymentRequest(methodData, details) angegeben hat. Weitergereicht werden aber nur die Modifikatoren, die zu den Zahlungsmethoden passen, die dieser Handler unterstützt.

Jedes PaymentDetailsModifier-Objekt hat folgende Felder:

supportedMethods: Kennung der Zahlungsmethode, z. B. eine URL wie "https://bobbucks.dev/pay"
total (optional): ein abweichender Gesamtbetrag als PaymentItem mit label und amount
additionalDisplayItems (optional): zusätzliche Posten, z. B. Rabatte oder Gebühren
data (optional): methodenspezifische Zusatzdaten

Einsatzbereich: Ein Händler kann etwa für eine bestimmte Wallet einen Rabatt gewähren oder für eine Kreditkarte eine Gebühr aufschlagen. Der Zahlungs-Handler liest modifiers aus, sucht den passenden Eintrag für die eigene Methode und zeigt dem Nutzer den richtigen Endbetrag an. Gibt es keinen passenden Modifikator, gilt der Standardbetrag aus event.total.

Rückgabewert

Typ

Array<PaymentDetailsModifier> | null

Beschreibung

Ein Array von PaymentDetailsModifier-Objekten, gefiltert auf die Zahlungsmethoden des Handlers. Hat der Händler keine Modifikatoren angegeben, ist das Array leer bzw. je nach Implementierung null.

Beispiele

Händlerseite: Modifikator für eine Wallet definieren

// Im Shop-Frontend: 10 % Rabatt für BobBucks
const methodData = [{ supportedMethods: 'https://bobbucks.dev/pay' }];

const details = {
  total: { label: 'Gesamt', amount: { currency: 'EUR', value: '50.00' } },
  modifiers: [{
    supportedMethods: 'https://bobbucks.dev/pay',
    total: { label: 'Gesamt mit BobBucks', amount: { currency: 'EUR', value: '45.00' } },
    additionalDisplayItems: [{
      label: 'BobBucks-Rabatt',
      amount: { currency: 'EUR', value: '-5.00' }
    }]
  }]
};

const request = new PaymentRequest(methodData, details);
const response = await request.show();
await response.complete('success');

Service Worker: modifiers auslesen

// service-worker.js des Zahlungs-Handlers
self.addEventListener('paymentrequest', (event) => {
  const modifiers = event.modifiers ?? [];
  console.log(`Anzahl Modifikatoren: ${modifiers.length}`);
  for (const mod of modifiers) {
    console.log(mod.supportedMethods, mod.total?.amount.value);
  }
});

Anzahl Modifikatoren: 1 https://bobbucks.dev/pay 45.00

Effektiven Endbetrag bestimmen und Zahlungsfenster öffnen

const METHOD = 'https://bobbucks.dev/pay';

const getEffectiveTotal = (event) => {
  const match = (event.modifiers ?? []).find(
    (m) => m.supportedMethods === METHOD && m.total
  );
  return match ? match.total.amount : event.total;
};

self.addEventListener('paymentrequest', (event) => {
  const amount = getEffectiveTotal(event);
  const url = `/pay.html?value=${encodeURIComponent(amount.value)}&currency=${amount.currency}`;

  event.respondWith(new Promise(async (resolve, reject) => {
    const client = await event.openWindow(url);
    if (!client) return reject(new Error('Fenster konnte nicht geöffnet werden'));
    self.addEventListener('message', (e) => {
      if (e.data?.methodName) resolve(e.data);
    }, { once: true });
  }));
});

// Wichtig · Fallstricke

Experimentell: Die Payment Handler API wird nur von Chromium-basierten Browsern unterstützt. Firefox und Safari kennen weder PaymentRequestEvent noch das Event paymentrequest.
Die Eigenschaft gibt es nur im Service Worker eines registrierten Zahlungs-Handlers, nicht im normalen Fenster-Kontext.
Beträge sind Zeichenketten (z. B. "45.00"). Rechnen Sie nicht mit Gleitkommazahlen, sondern mit ganzzahligen Cent-Werten oder einer Dezimal-Bibliothek.
total und additionalDisplayItems sind optional. Prüfen Sie deshalb immer mit optionaler Verkettung (?.), und nutzen Sie event.total als Rückfallwert.
Sicherheit: Die Werte stammen von der Händlerseite. Setzen Sie label nicht ungeprüft per innerHTML in die Oberfläche ein, sonst droht XSS. Verwenden Sie textContent.
Der Handler bekommt nur Modifikatoren für die Methoden zu sehen, die er selbst unterstützt. Modifikatoren für andere Methoden fehlen im Array.

Siehe auch

PaymentAddress.sortingCode PaymentRequestEvent.topOrigin PaymentRequestEvent.total PaymentRequestEvent.methodData PaymentRequestEvent.paymentRequestId