PaymentMethodChangeEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface PaymentMethodChangeEvent extends PaymentRequestUpdateEvent

Beschreibung

PaymentMethodChangeEvent gehört zur Payment Request API. Das Ereignis wird auf einem PaymentRequest-Objekt ausgelöst, wenn der Benutzer im Zahlungsdialog des Browsers das Zahlungsmittel wechselt, zum Beispiel von einer Debit- auf eine Kreditkarte oder zwischen zwei Karten in Apple Pay. Ob und wann das Ereignis kommt, hängt vom jeweiligen Zahlungsabwickler (Payment Handler) ab. Nicht jeder Abwickler löst es aus.

Die Schnittstelle erbt von PaymentRequestUpdateEvent und stellt deshalb die Methode updateWith() bereit. Damit kann der Händler den Zahlungsdialog anpassen, solange er noch offen ist. Typische Fälle sind eine Gebühr für bestimmte Kartentypen, ein Rabatt für ein bevorzugtes Zahlungsmittel oder eine Fehlermeldung, wenn ein Zahlungsmittel nicht akzeptiert wird.

Die Schnittstelle hat zwei eigene Eigenschaften:

methodName (string, nur lesbar): die Kennung des neu gewählten Zahlungsmittels, z. B. "https://apple.com/apple-pay" oder "https://google.com/pay".
methodDetails (object | null, nur lesbar): Details zum Zahlungsmittel, die der Abwickler liefert. Bei Apple Pay steht hier z. B. type ("debit", "credit" …). Ohne Details ist der Wert null.

Einen Handler registrieren Sie mit request.addEventListener("paymentmethodchange", handler) oder über die Eigenschaft request.onpaymentmethodchange.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Regel `"paymentmethodchange"`.
$options	object	{}	Optionales `PaymentMethodChangeEventInit`-Objekt. Es kann die Felder `methodName` (`string`, Standard `""`) und `methodDetails` (`object \| null`, Standard `null`) sowie die üblichen `EventInit`-Felder (`bubbles`, `cancelable`, `composed`) enthalten.

Rückgabewert

Typ

PaymentMethodChangeEvent

Beschreibung

Ein neues PaymentMethodChangeEvent-Objekt, wenn es über new PaymentMethodChangeEvent(type, options) erzeugt wird. Meistens erzeugt der Browser das Objekt selbst und übergibt es an den Ereignis-Handler.

Beispiele

Aufpreis für Kreditkarten bei Apple Pay

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: '49.90' } }
};

const request = new PaymentRequest(methods, baseDetails);

request.addEventListener('paymentmethodchange', (event) => {
  const { methodName, methodDetails } = event;
  console.log('Neues Zahlungsmittel:', methodName, methodDetails?.type);

  if (methodDetails?.type === 'credit') {
    // 1,50 € Kreditkartengebühr hinzufügen
    event.updateWith({
      displayItems: [
        { label: 'Warenwert', amount: { currency: 'EUR', value: '49.90' } },
        { label: 'Kreditkartengebühr', amount: { currency: 'EUR', value: '1.50' } }
      ],
      total: { label: 'Summe', amount: { currency: 'EUR', value: '51.40' } }
    });
  } else {
    event.updateWith(baseDetails);
  }
});

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

Neues Zahlungsmittel: https://apple.com/apple-pay credit

Asynchrone Prüfung per Server mit Promise in updateWith()

request.onpaymentmethodchange = (event) => {
  // updateWith() muss synchron im Handler aufgerufen werden,
  // darf aber ein Promise erhalten
  const updatePromise = (async () => {
    const res = await fetch('/api/pricing', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        method: event.methodName,
        details: event.methodDetails
      })
    });
    const { total, error } = await res.json();
    return error
      ? { ...baseDetails, error }   // Fehlermeldung im Dialog anzeigen
      : { total };
  })();

  event.updateWith(updatePromise);
};

Ereignis manuell erzeugen (z. B. für Tests)

const evt = new PaymentMethodChangeEvent('paymentmethodchange', {
  methodName: 'https://google.com/pay',
  methodDetails: { cardNetwork: 'VISA' }
});

console.log(evt.type);          // Ereignisname
console.log(evt.methodName);    // Zahlungsmittel
console.log(evt.methodDetails); // Details

paymentmethodchange https://google.com/pay { cardNetwork: 'VISA' }

// Wichtig · Fallstricke

updateWith() sofort aufrufen: Die Methode muss synchron im Handler aufgerufen werden, bevor der Handler zurückkehrt. Asynchrone Arbeit übergeben Sie als Promise an updateWith(). Wird die Methode erst nach einem await aufgerufen, wirft der Browser einen InvalidStateError.
Nicht jeder Abwickler löst das Ereignis aus: Das Ereignis ist optional. Bei einfachen Kartenzahlungen (basic-card ist veraltet) kommt es oft gar nicht. Die Preisberechnung darf also nicht davon abhängen. Prüfen Sie den Endbetrag immer auf dem Server.
methodDetails ist abwickler-spezifisch: Aufbau und Inhalt des Objekts unterscheiden sich je nach Zahlungsmittel. Aus Datenschutzgründen enthält es meist keine vollständigen Kartendaten.
Kompatibilität: Die Payment Request API funktioniert nur in sicheren Kontexten (HTTPS). Sie wird in Chromium-Browsern und Safari unterstützt, in Firefox nicht standardmäßig. Prüfen Sie die Unterstützung vorher, z. B. mit 'PaymentRequest' in window. In Iframes ist das Attribut allow="payment" nötig.
Gebühren je Zahlungsmittel: In der EU verbietet die Zahlungsdiensterichtlinie (PSD2) Aufschläge auf gängige Verbraucherkarten. Klären Sie Aufpreise daher vorher rechtlich.

Siehe auch

ContentVisibilityAutoStateChangeEvent BufferedChangeEvent RTCDTMFToneChangeEvent HashChangeEvent IDBVersionChangeEvent