new PaymentRequestUpdateEvent() — Methode · JavaScript-Referenz

Signatur

new PaymentRequestUpdateEvent(type, options)

Beschreibung

Der Konstruktor PaymentRequestUpdateEvent() erzeugt ein Event-Objekt vom Typ PaymentRequestUpdateEvent. Solche Events löst der Browser selbst aus, wenn der Nutzer im Zahlungsdialog etwas ändert, zum Beispiel die Lieferadresse (shippingaddresschange), die Versandart (shippingoptionchange) oder die Zahlungsmethode (paymentmethodchange, dort als Unterklasse PaymentMethodChangeEvent).

In der Praxis ruft man den Konstruktor selten selbst auf. Meistens bekommt man das Event im Handler und ruft darin event.updateWith(promiseOderDetails) auf, um Gesamtbetrag, Versandoptionen oder Fehlermeldungen neu zu setzen. Einen eigenen Aufruf braucht man vor allem in Tests, bei Polyfills oder wenn man Event-Handler ohne echten Zahlungsdialog prüfen will.

Ein Event, das per Konstruktor erzeugt und über dispatchEvent() ausgelöst wurde, gilt als nicht vertrauenswürdig (isTrusted === false). Ruft man darauf updateWith() auf, wirft der Browser einen InvalidStateError. Echte Aktualisierungen des Zahlungsdialogs sind also nur mit Events möglich, die der Browser selbst auslöst.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events, z. B. `"shippingaddresschange"` oder `"shippingoptionchange"`.
$options	EventInit	{}	Optionales Wörterbuch mit den Standard-Event-Optionen `bubbles`, `cancelable` und `composed` (jeweils `boolean`, Standard `false`). Weitere, eigene Felder definiert `PaymentRequestUpdateEventInit` derzeit nicht.

Rückgabewert

Typ

PaymentRequestUpdateEvent

Beschreibung

Ein neues PaymentRequestUpdateEvent-Objekt mit der Methode updateWith().

Beispiele

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

const event = new PaymentRequestUpdateEvent('shippingaddresschange', {
  bubbles: false,
  cancelable: false
});

console.log(event.type);
console.log(event instanceof Event);
console.log(typeof event.updateWith);
console.log(event.isTrusted);

shippingaddresschange true function false

Typische Nutzung: Versandkosten bei Adressänderung anpassen

const details = {
  total: { label: 'Summe', amount: { currency: 'EUR', value: '49.90' } },
  shippingOptions: []
};

const request = new PaymentRequest(
  [{ supportedMethods: 'https://google.com/pay' }],
  details,
  { requestShipping: true }
);

// Der Browser liefert hier ein echtes PaymentRequestUpdateEvent
request.addEventListener('shippingaddresschange', (event) => {
  const country = request.shippingAddress?.country;
  const shipping = country === 'DE' ? '4.90' : '12.90';

  event.updateWith(Promise.resolve({
    total: {
      label: 'Summe',
      amount: { currency: 'EUR', value: (49.90 + Number(shipping)).toFixed(2) }
    },
    shippingOptions: [{
      id: 'standard',
      label: `Standardversand (${country})`,
      amount: { currency: 'EUR', value: shipping },
      selected: true
    }]
  }));
});

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

Nicht lieferbare Adresse per Fehlermeldung ablehnen

request.onshippingaddresschange = (event) => {
  const { country } = request.shippingAddress;
  if (!['DE', 'AT', 'CH'].includes(country)) {
    event.updateWith({
      error: 'Wir liefern leider nur nach Deutschland, Österreich und in die Schweiz.',
      shippingOptions: []
    });
    return;
  }
  event.updateWith({ shippingOptions: [/* ... */] });
};

updateWith() auf selbst erzeugtem Event schlägt fehl

const fake = new PaymentRequestUpdateEvent('shippingoptionchange');
try {
  fake.updateWith({});
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Nicht vertrauenswürdig: Per Konstruktor erzeugte Events haben isTrusted === false. updateWith() wirft darauf einen InvalidStateError. Den Zahlungsdialog kann man also nur über Events aktualisieren, die der Browser selbst auslöst.
Synchron aufrufen: updateWith() muss synchron im Handler aufgerufen werden. Asynchrone Daten, etwa die Versandkosten aus fetch(), gibt man als Promise weiter. Ein Aufruf nach einem await ist zu spät, und ein zweiter Aufruf wirft ebenfalls einen InvalidStateError.
Kompatibilität: Die Payment Request API gibt es nur in sicheren Kontexten (HTTPS). Chromium-Browser und Safari unterstützen sie. Firefox liefert sie standardmäßig nicht aus. Vor der Nutzung sollte man per 'PaymentRequest' in window prüfen, ob die API vorhanden ist.
Die Events shippingaddresschange und shippingoptionchange kommen nur, wenn requestShipping: true gesetzt ist. Einige Browser geben die Lieferadresse vor der Bestätigung aus Datenschutzgründen nur unvollständig heraus (z. B. ohne Straße).

Siehe auch

new BackgroundFetchUpdateUIEvent() new PaymentRequestEvent() new PaymentMethodChangeEvent() new PaymentRequest() new TextFormatUpdateEvent()