Signatur
Beschreibung
Die schreibgeschützte Eigenschaft methodDetails des Interfaces PaymentMethodChangeEvent enthält ein Objekt mit den Daten, die der Zahlungsdienstleister (Payment Handler) bereitstellt, um die Änderung der Zahlungsmethode zu beschreiben. Das Event wird als paymentmethodchange auf dem PaymentRequest-Objekt ausgelöst, z. B. wenn der Nutzer in Apple Pay oder Google Pay eine andere Karte auswählt.
Aufbau und Inhalt des Objekts hängen von der jeweiligen Zahlungsmethode ab, die in methodName steht. Bei Apple Pay ("https://apple.com/apple-pay") enthält es etwa den Kartentyp (type: "credit", "debit" …) und das Netzwerk; andere Anbieter liefern eigene Strukturen. Gibt es keine Details, ist der Wert null.
Typischer Einsatz: Anhand der Details passt der Händler den Preis an, etwa einen Aufschlag für Kreditkarten oder einen Rabatt für bestimmte Kartennetzwerke. Dazu ruft man im Handler event.updateWith() mit einem Promise bzw. Objekt vom Typ PaymentDetailsUpdate auf, um Gesamtbetrag und Positionen zu aktualisieren.
Rückgabewert
null, wenn keine Details vorliegen.Beispiele
Details beim Wechsel der Zahlungsmethode auslesen
const methods = [{
supportedMethods: 'https://apple.com/apple-pay',
data: {
version: 3,
merchantIdentifier: 'merchant.net.programmierung.shop',
merchantCapabilities: ['supports3DS'],
supportedNetworks: ['visa', 'masterCard'],
countryCode: 'DE'
}
}];
const details = {
total: { label: 'Gesamt', amount: { currency: 'EUR', value: '49.90' } }
};
const request = new PaymentRequest(methods, details);
request.addEventListener('paymentmethodchange', (event) => {
console.log('Methode:', event.methodName);
console.log('Details:', event.methodDetails);
});
// Muss durch eine Nutzeraktion ausgelöst werden
document.querySelector('#pay').addEventListener('click', async () => {
const response = await request.show();
await response.complete('success');
});Kreditkarten-Aufschlag mit updateWith() berechnen
const basePrice = 100;
const buildDetails = (surcharge) => {
const total = (basePrice + surcharge).toFixed(2);
const displayItems = [
{ label: 'Artikel', amount: { currency: 'EUR', value: basePrice.toFixed(2) } }
];
if (surcharge > 0) {
displayItems.push({
label: 'Kreditkartengebühr',
amount: { currency: 'EUR', value: surcharge.toFixed(2) }
});
}
return { total: { label: 'Gesamt', amount: { currency: 'EUR', value: total } }, displayItems };
};
request.onpaymentmethodchange = (event) => {
const info = event.methodDetails;
// methodDetails kann null sein – defensiv prüfen
const surcharge = info?.type === 'credit' ? 1.5 : 0;
event.updateWith(buildDetails(surcharge));
};Unbekannte Methoden sicher behandeln
request.addEventListener('paymentmethodchange', (event) => {
const { methodName, methodDetails } = event;
if (methodDetails === null) {
console.warn(`Keine Details für ${methodName}`);
event.updateWith({}); // Preis unverändert lassen
return;
}
console.log(Object.keys(methodDetails));
event.updateWith({});
});// Wichtig · Fallstricke
- Struktur nicht standardisiert: Der Inhalt hängt vollständig von der Zahlungsmethode (
methodName) ab. Immer zuerstmethodNameprüfen und aufnullbzw. fehlende Felder vorbereitet sein (Optional Chaining). - updateWith() synchron aufrufen:
event.updateWith()muss noch während der Event-Verarbeitung aufgerufen werden; asynchrone Preisberechnungen daher als Promise übergeben, nicht erst nach einemawaitaufrufen. - Keine sensiblen Daten:
methodDetailsenthält bewusst keine vollständigen Kartennummern oder Zahlungstoken – diese kommen erst mitPaymentResponse.details. Serverseitig trotzdem nie allein auf Client-Angaben für die Preisberechnung vertrauen. - Kompatibilität: Die Payment Request API braucht einen sicheren Kontext (HTTPS).
paymentmethodchangewird vor allem von Chromium-Browsern und Safari (Apple Pay) unterstützt, Firefox unterstützt es nicht. Vorher per'PaymentMethodChangeEvent' in windowprüfen.