PaymentRequest: shippingoptionchange — Ereignis · JavaScript-Referenz

Signatur

paymentRequest.addEventListener("shippingoptionchange", handler)

Beschreibung

Das Ereignis shippingoptionchange wird an ein PaymentRequest-Objekt gesendet, wenn die Zahlungsanforderung mit requestShipping: true erstellt wurde, in den Details Versandoptionen (shippingOptions) übergeben wurden und der Nutzer im Zahlungsdialog eine andere Option auswählt. Die neu gewählte Option steht anschließend in PaymentRequest.shippingOption (die id der Option) bereit.

Das Ereignisobjekt ist ein PaymentRequestUpdateEvent. Über dessen Methode updateWith() übergibt man – synchron innerhalb des Handlers – ein Objekt oder ein Promise, das die aktualisierten Zahlungsdetails liefert: meist einen neuen Gesamtbetrag (total), angepasste displayItems und die Liste der shippingOptions, in der die gewählte Option als selected: true markiert ist. Solange das Promise nicht erfüllt ist, zeigt der Browser einen Ladezustand an.

Registriert wird der Handler entweder mit addEventListener("shippingoptionchange", handler) oder über die Eigenschaft onshippingoptionchange. Typischer Einsatz: Versandkosten neu berechnen (ggf. serverseitig) und den Endbetrag im Dialog aktualisieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"shippingoptionchange"`.
$handler Pflicht	(event: PaymentRequestUpdateEvent) => void		Callback, der ein `PaymentRequestUpdateEvent` erhält. Muss `event.updateWith()` synchron aufrufen, wenn Details angepasst werden sollen.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Die neue Auswahl wird über request.shippingOption gelesen und über event.updateWith() beantwortet.

Beispiele

Versandkosten per addEventListener neu berechnen

const basisBetrag = 49.90;
const optionen = [
  { id: 'standard', label: 'Standard (3–5 Tage)', amount: { currency: 'EUR', value: '4.90' }, selected: true },
  { id: 'express', label: 'Express (1 Tag)', amount: { currency: 'EUR', value: '12.90' } }
];

const details = (gewaehlt) => {
  const shippingOptions = optionen.map((o) => ({ ...o, selected: o.id === gewaehlt }));
  const versand = Number(shippingOptions.find((o) => o.selected).amount.value);
  return {
    displayItems: [
      { label: 'Warenkorb', amount: { currency: 'EUR', value: basisBetrag.toFixed(2) } },
      { label: 'Versand', amount: { currency: 'EUR', value: versand.toFixed(2) } }
    ],
    shippingOptions,
    total: { label: 'Gesamt', amount: { currency: 'EUR', value: (basisBetrag + versand).toFixed(2) } }
  };
};

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

request.addEventListener('shippingoptionchange', (event) => {
  console.log('Neue Versandoption:', request.shippingOption);
  event.updateWith(details(request.shippingOption));
});

document.querySelector('#kaufen').addEventListener('click', async () => {
  const response = await request.show();
  await response.complete('success');
});

Neue Versandoption: express

Asynchrone Berechnung über den Server mit onshippingoptionchange

request.onshippingoptionchange = (event) => {
  const promise = fetch('/api/versandkosten', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ option: request.shippingOption })
  }).then((res) => res.json()); // liefert ein PaymentDetailsUpdate-Objekt

  // updateWith muss synchron aufgerufen werden – das Promise darf später erfüllt werden
  event.updateWith(promise);
};

Listener wieder entfernen

const onOptionChange = (event) => {
  event.updateWith(details(request.shippingOption));
};

request.addEventListener('shippingoptionchange', onOptionChange);

// z. B. nach Abbruch des Bezahlvorgangs
request.removeEventListener('shippingoptionchange', onOptionChange);
// bzw. bei Property-Variante:
request.onshippingoptionchange = null;

// Wichtig · Fallstricke

Synchroner Aufruf: event.updateWith() muss direkt im Handler aufgerufen werden, nicht erst nach einem await. Asynchrone Arbeit übergibt man als Promise. Sonst übernimmt der Browser die Auswahl ohne neue Beträge oder wirft einen InvalidStateError.
Auswahl markieren: Die gewählte Option muss in den zurückgegebenen shippingOptions mit selected: true markiert sein. Sonst zeigt der Dialog womöglich weiter die alte Auswahl an.
Das Ereignis kommt nur, wenn requestShipping: true gesetzt ist und mindestens eine Versandoption angeboten wird.
Kompatibilität: Die Payment Request API gibt es nur in sicheren Kontexten (HTTPS). Die Versand-Ereignisse unterstützen Chromium-Browser und Safari; Firefox bietet die API nicht standardmäßig an. Die Versand-Funktionen wurden teilweise als veraltet eingestuft. Chrome unterstützt die Versandabfrage nicht mehr für alle Zahlungsmethoden. Deshalb Funktionen prüfen und einen herkömmlichen Checkout als Ausweichlösung bereithalten.
Sicherheit: Beträge, die im Client berechnet werden, sind nur zur Anzeige da. Der endgültige Preis muss auf dem Server erneut geprüft werden.

Siehe auch

HTMLTextAreaElement: selectionchange PaymentRequest: shippingaddresschange PaymentRequest: paymentmethodchange PaymentRequest: merchantvalidation PaymentResponse: payerdetailchange