new PaymentMethodChangeEvent() — Methode · JavaScript-Referenz

Signatur

new PaymentMethodChangeEvent(type, options)

Beschreibung

Der Konstruktor PaymentMethodChangeEvent() erzeugt ein Ereignisobjekt vom Typ PaymentMethodChangeEvent, das von PaymentRequestUpdateEvent erbt. Normalerweise erzeugt der Browser dieses Ereignis selbst: Er löst es auf einem PaymentRequest aus, wenn der Nutzer im Zahlungsdialog die Zahlungsart wechselt, z. B. von einer Visa- auf eine Mastercard-Karte in Apple Pay oder Google Pay.

Das Ereignis hat zwei eigene Eigenschaften: methodName, also den Bezeichner der Zahlungsart wie "https://apple.com/apple-pay", und methodDetails, ein Objekt mit anbieterspezifischen Angaben wie dem Kartentyp. Da es von PaymentRequestUpdateEvent erbt, stellt es auch updateWith() bereit. Damit kann der Händler Gesamtbetrag, Gebühren oder Rabatte an die neue Zahlungsart anpassen.

Den Konstruktor selbst ruft man vor allem in Tests auf, zum Beispiel in Unit-Tests für die eigene Handler-Logik oder bei Polyfills. Ein selbst erzeugtes Ereignis ist nicht vertrauenswürdig (isTrusted === false). Es wird also nicht mit einem echten Zahlungsdialog verknüpft.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Praxis immer `"paymentmethodchange"`.
$options	object	{}	Optionales Initialisierungsobjekt. Neben den Optionen aus `EventInit` (`bubbles`, `cancelable`, `composed`) sind folgende Angaben möglich: `methodName` (`string`, Standard `""`): Bezeichner der Zahlungsart. `methodDetails` (`object \| null`, Standard `null`): anbieterspezifische Details zur gewählten Zahlungsart.

Rückgabewert

Typ

PaymentMethodChangeEvent

Beschreibung

Ein neues PaymentMethodChangeEvent-Objekt mit den übergebenen Werten für methodName und methodDetails.

Beispiele

Ereignis manuell erzeugen und auslesen

const event = new PaymentMethodChangeEvent('paymentmethodchange', {
  methodName: 'https://apple.com/apple-pay',
  methodDetails: { type: 'credit', network: 'visa' }
});

console.log(event.type);
console.log(event.methodName);
console.log(event.methodDetails.network);
console.log(event.isTrusted);

paymentmethodchange https://apple.com/apple-pay visa false

Aufpreis für Kreditkarten im echten Zahlungsdialog

const methods = [{
  supportedMethods: 'https://apple.com/apple-pay',
  data: {
    version: 3,
    merchantIdentifier: 'merchant.net.example',
    merchantCapabilities: ['supports3DS'],
    supportedNetworks: ['visa', 'masterCard'],
    countryCode: 'DE'
  }
}];

const baseTotal = { label: 'Summe', amount: { currency: 'EUR', value: '49.90' } };
const request = new PaymentRequest(methods, { total: baseTotal });

request.addEventListener('paymentmethodchange', (event) => {
  const isCredit = event.methodDetails?.type === 'credit';
  const fee = isCredit ? 1.5 : 0;

  event.updateWith({
    total: {
      label: 'Summe',
      amount: { currency: 'EUR', value: (49.9 + fee).toFixed(2) }
    },
    displayItems: isCredit
      ? [{ label: 'Kreditkartengebühr', amount: { currency: 'EUR', value: fee.toFixed(2) } }]
      : []
  });
});

// Muss durch eine Nutzeraktion ausgelöst werden
document.querySelector('#pay').addEventListener('click', async () => {
  const response = await request.show();
  await response.complete('success');
});

Handler-Logik isoliert testen

const calculateFee = (event) =>
  event.methodDetails?.type === 'credit' ? 1.5 : 0;

const creditEvent = new PaymentMethodChangeEvent('paymentmethodchange', {
  methodName: 'https://apple.com/apple-pay',
  methodDetails: { type: 'credit' }
});
const debitEvent = new PaymentMethodChangeEvent('paymentmethodchange', {
  methodName: 'https://apple.com/apple-pay',
  methodDetails: { type: 'debit' }
});

console.log(calculateFee(creditEvent));
console.log(calculateFee(debitEvent));

1.5 0

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser (ab 76) und Safari unterstützen das Ereignis. Firefox liefert die Payment Request API nicht standardmäßig aus. Prüfen Sie die Verfügbarkeit daher vorher, z. B. mit 'PaymentMethodChangeEvent' in window.
Die API steht nur in einem sicheren Kontext (HTTPS) zur Verfügung.
Selbst erzeugte Ereignisse haben isTrusted === false. Ruft man auf ihnen updateWith() auf, wird ein InvalidStateError ausgelöst, weil kein Zahlungsdialog aktiv ist.
updateWith() muss synchron im Ereignis-Handler aufgerufen werden. Für asynchrone Berechnungen übergibt man ein Promise, das später aufgelöst wird. Ein await vor dem Aufruf ist falsch.
Wie methodDetails aufgebaut ist, hängt vom Zahlungsanbieter ab. Viele Anbieter geben aus Datenschutzgründen nur wenige Angaben weiter, deshalb sollte man den Inhalt immer defensiv prüfen (z. B. mit ?.).

Siehe auch

new ExtendableCookieChangeEvent() new BufferedChangeEvent() new RTCDTMFToneChangeEvent() new HashChangeEvent() new IDBVersionChangeEvent()