Signatur
Beschreibung
PaymentRequestUpdateEvent gehört zur Payment Request API. Ein Objekt dieses Typs erhält man, während das Zahlungsfenster des Browsers offen ist und der Nutzer darin etwas ändert, das den Preis betreffen kann. Das sind die Ereignisse shippingaddresschange (neue Versandadresse) und shippingoptionchange (andere Versandart, etwa „Express“). Das Ereignis paymentmethodchange verwendet die abgeleitete Schnittstelle PaymentMethodChangeEvent.
Die wichtigste Methode ist updateWith(detailsPromise). Damit teilt der Händler dem Browser neue Zahlungsdetails mit, zum Beispiel einen neu berechneten Gesamtbetrag, passende Versandoptionen, Steuern oder Fehlermeldungen wie „Kein Versand in dieses Land“. Solange das übergebene Promise nicht erfüllt ist, zeigt der Browser einen Ladezustand an, und der Nutzer kann die Zahlung nicht abschließen. Deshalb eignet sich die Methode auch für asynchrone Serveranfragen, etwa um Versandkosten zu berechnen.
Die Schnittstelle erbt alle Eigenschaften und Methoden von Event. Eigene Eigenschaften hat sie nicht. Welche Adresse oder Option neu gewählt wurde, liest man am auslösenden PaymentRequest-Objekt über event.target aus, mit shippingAddress bzw. shippingOption. Auf die Ereignisse hört man mit request.addEventListener("shippingaddresschange", handler) oder über die Eigenschaften onshippingaddresschange und onshippingoptionchange.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Nur für den Konstruktor new PaymentRequestUpdateEvent(type, options): Name des Ereignisses, z. B. "shippingaddresschange" oder "shippingoptionchange". |
|
| $options | EventInit | {} | Nur für den Konstruktor: übliche Ereignis-Optionen wie bubbles, cancelable und composed. |
| $detailsPromise Pflicht | PaymentDetailsUpdate | Promise<PaymentDetailsUpdate> | Für updateWith(): ein Objekt oder ein Promise auf ein Objekt mit aktualisierten Angaben wie total, displayItems, shippingOptions, modifiers, error oder shippingAddressErrors. |
Rückgabewert
updateWith() gibt nichts zurück. Den Erfolg der Aktualisierung sieht man daran, dass der Browser die neuen Daten im Zahlungsfenster anzeigt. Der Konstruktor liefert ein PaymentRequestUpdateEvent-Objekt.Beispiele
Versandkosten bei Adressänderung neu berechnen
const methods = [{ supportedMethods: 'https://google.com/pay', data: { /* ... */ } }];
const details = {
total: { label: 'Gesamt', amount: { currency: 'EUR', value: '49.90' } },
shippingOptions: []
};
const request = new PaymentRequest(methods, details, { requestShipping: true });
request.addEventListener('shippingaddresschange', (event) => {
// updateWith() muss synchron im Handler aufgerufen werden
event.updateWith((async () => {
const { country } = event.target.shippingAddress;
if (country !== 'DE' && country !== 'AT') {
return { error: 'Wir liefern nur nach Deutschland und Österreich.', shippingOptions: [] };
}
const shipping = country === 'DE' ? 4.90 : 9.90;
return {
total: { label: 'Gesamt', amount: { currency: 'EUR', value: (49.90 + shipping).toFixed(2) } },
shippingOptions: [{
id: 'standard',
label: 'Standardversand',
amount: { currency: 'EUR', value: shipping.toFixed(2) },
selected: true
}]
};
})());
});
const response = await request.show();
await response.complete('success');Versandart über die on-Eigenschaft auswerten
const options = {
standard: { label: 'Standard (3–5 Tage)', price: 4.90 },
express: { label: 'Express (1 Tag)', price: 12.90 }
};
const basis = 49.90;
request.onshippingoptionchange = (event) => {
const gewaehlt = event.target.shippingOption; // z. B. 'express'
const shippingOptions = Object.entries(options).map(([id, o]) => ({
id,
label: o.label,
amount: { currency: 'EUR', value: o.price.toFixed(2) },
selected: id === gewaehlt
}));
event.updateWith({
total: {
label: 'Gesamt',
amount: { currency: 'EUR', value: (basis + options[gewaehlt].price).toFixed(2) }
},
shippingOptions
});
};Instanz per Konstruktor erzeugen (z. B. für Tests)
const evt = new PaymentRequestUpdateEvent('shippingoptionchange');
console.log(evt instanceof Event, evt.type);
console.log(typeof evt.updateWith);// Wichtig · Fallstricke
- Synchron aufrufen:
updateWith()muss direkt im Ereignis-Handler aufgerufen werden, also nicht erst nach einemawait. Asynchrone Arbeit gehört in das übergebene Promise. Ein späterer Aufruf löst einenInvalidStateErroraus. - Nur einmal pro Ereignis: Ein zweiter Aufruf von
updateWith()für dasselbe Ereignis wirft ebenfalls einenInvalidStateError. Das gilt auch für Ereignisse, die nicht vom Browser stammen (isTrusted === false). - Wenn das Promise abgelehnt wird, bricht der Browser die gesamte Zahlungsanfrage ab, und das Promise von
show()wird mit einemAbortErrorabgelehnt. - Ruft man
updateWith()gar nicht auf, gelten die bisherigen Details weiter. Bei einer Adressänderung sollte man trotzdem immer antworten, damit Preise und Versandoptionen stimmen. - Aus Datenschutzgründen kann die Adresse im Ereignis unvollständig sein, z. B. ohne Straße oder Namen. Die vollständige Adresse gibt es erst im
PaymentResponse. - Kompatibilität: Nur in sicherem Kontext (HTTPS) verfügbar. Chromium-Browser und Safari unterstützen die Schnittstelle, Firefox bietet sie standardmäßig nicht an. Vorher mit
'PaymentRequest' in windowprüfen. Versandbezogene Funktionen sind in der Spezifikation als gefährdet markiert und werden nicht von allen Zahlungs-Apps unterstützt.