PaymentRequest: paymentmethodchange — Ereignis · JavaScript-Referenz

Signatur

paymentRequest.addEventListener("paymentmethodchange", handler)

Beschreibung

Das Ereignis paymentmethodchange gehört zur Payment Request API. Es wird an ein PaymentRequest-Objekt gesendet, während das Zahlungsformular über show() geöffnet ist und der Benutzer innerhalb eines Zahlungshandlers die Zahlungsmethode wechselt, etwa von einer Debit- zu einer Kreditkarte in Apple Pay. Das Ereignisobjekt ist vom Typ PaymentMethodChangeEvent (erbt von PaymentRequestUpdateEvent).

Wichtig ist das Ereignis vor allem dann, wenn der Preis von der Zahlungsart abhängt, etwa bei einer Kartengebühr, einem Rabatt für bestimmte Kartentypen oder anderen Steuern. Die Eigenschaft methodName nennt den Bezeichner der Zahlungsmethode (z. B. "https://apple.com/apple-pay"). In methodDetails steht ein methodenspezifisches Objekt, bei Apple Pay zum Beispiel mit type ("debit", "credit", …).

Innerhalb des Handlers rufst du event.updateWith() synchron auf. Du übergibst entweder ein PaymentDetailsUpdate-Objekt oder ein Promise, das zu einem solchen Objekt auflöst. Damit aktualisierst du Gesamtbetrag, Positionen (displayItems) oder Modifikatoren. Bis das Promise erfüllt ist, zeigt der Browser im Zahlungsformular einen Ladezustand an.

Registrieren lässt sich der Handler mit addEventListener("paymentmethodchange", …) oder über die Eigenschaft onpaymentmethodchange.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"paymentmethodchange"`.
$handler Pflicht	(event: PaymentMethodChangeEvent) => void		Callback mit dem Ereignisobjekt. Wichtige Mitglieder: `event.methodName` (string), `event.methodDetails` (object \| null) und `event.updateWith(detailsOrPromise)`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die aktualisierten Zahlungsdetails übergibst du mit event.updateWith().

Beispiele

Kreditkartengebühr bei Apple Pay berechnen

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

const baseDetails = {
  total: { label: 'Summe', amount: { currency: 'EUR', value: '50.00' } }
};

const request = new PaymentRequest(methods, baseDetails);

request.addEventListener('paymentmethodchange', (event) => {
  const isCredit = event.methodDetails?.type === 'credit';
  const fee = isCredit ? 1.5 : 0;
  console.log(`Methode: ${event.methodName}, Gebühr: ${fee}`);

  // updateWith muss synchron im Handler aufgerufen werden
  event.updateWith({
    displayItems: [
      { label: 'Warenkorb', amount: { currency: 'EUR', value: '50.00' } },
      { label: 'Kreditkartengebühr', amount: { currency: 'EUR', value: fee.toFixed(2) } }
    ],
    total: { label: 'Summe', amount: { currency: 'EUR', value: (50 + fee).toFixed(2) } }
  });
});

// Auslösen per Benutzergeste, z. B. Klick auf einen Button
document.querySelector('#pay').addEventListener('click', async () => {
  const response = await request.show();
  await response.complete('success');
});

Methode: https://apple.com/apple-pay, Gebühr: 1.5

Neuen Preis asynchron vom Server holen

const request = new PaymentRequest(
  [{ supportedMethods: 'https://apple.com/apple-pay', data: { /* … */ } }],
  { total: { label: 'Summe', amount: { currency: 'EUR', value: '20.00' } } }
);

request.addEventListener('paymentmethodchange', (event) => {
  // Promise sofort übergeben – der Browser wartet auf das Ergebnis
  event.updateWith((async () => {
    const res = await fetch('/api/preis', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ method: event.methodName, details: event.methodDetails })
    });
    const { total, displayItems } = await res.json();
    return { total, displayItems };
  })());
});

Handler über die on-Property setzen und wieder entfernen

const request = new PaymentRequest(
  [{ supportedMethods: 'https://apple.com/apple-pay', data: { /* … */ } }],
  { total: { label: 'Summe', amount: { currency: 'EUR', value: '10.00' } } }
);

request.onpaymentmethodchange = (event) => {
  console.log('Neue Methode:', event.methodName);
  event.updateWith({}); // keine Änderung am Betrag
};

// Später deaktivieren
request.onpaymentmethodchange = null;

// Alternative mit addEventListener/removeEventListener
const onChange = (event) => event.updateWith({});
request.addEventListener('paymentmethodchange', onChange);
request.removeEventListener('paymentmethodchange', onChange);

// Wichtig · Fallstricke

Browser-Unterstützung: Das Ereignis wird im Wesentlichen nur von Zahlungshandlern ausgelöst, die es auch unterstützen, in der Praxis vor allem Apple Pay in Safari. In Chromium-Browsern ist die API zwar vorhanden, das Ereignis kommt aber je nach Zahlungshandler selten oder gar nicht. Firefox unterstützt die Payment Request API nicht. Deshalb vorher mit 'PaymentRequest' in window prüfen und einen Ersatzweg anbieten.
event.updateWith() muss synchron im Handler aufgerufen werden, nicht erst nach einem await. Asynchrone Arbeit übergibst du als Promise. Ein zweiter Aufruf löst einen InvalidStateError aus.
Rufst du updateWith() gar nicht auf, bleiben die bisherigen Details bestehen. Der Browser kann dann aber einen veralteten Betrag anzeigen.
Der Inhalt von methodDetails hängt vom Zahlungshandler ab und ist nicht einheitlich. Prüfe Eigenschaften deshalb defensiv, z. B. mit ?..
Die API funktioniert nur in sicheren Kontexten (HTTPS). show() braucht eine Benutzergeste. Den endgültigen Betrag immer auf dem Server prüfen und nie allein dem Client vertrauen.

Siehe auch

MIDIInput: midimessage PaymentRequest: shippingoptionchange PaymentRequest: shippingaddresschange PaymentRequest: merchantvalidation PaymentResponse: payerdetailchange