PaymentRequest: shippingaddresschange — Ereignis · JavaScript-Referenz

Signatur

paymentRequest.addEventListener("shippingaddresschange", handler)

Beschreibung

Das Ereignis shippingaddresschange wird an ein PaymentRequest-Objekt gesendet, sobald der Benutzer im vom Browser angezeigten Zahlungsdialog eine Versandadresse auswählt oder eine vorhandene Adresse bearbeitet. Es tritt nur auf, wenn der Request mit requestShipping: true in den Optionen erzeugt wurde. Die neue Adresse steht dann in request.shippingAddress als PaymentAddress-Objekt bereit.

Der Handler bekommt ein PaymentRequestUpdateEvent. Mit event.updateWith() übergeben Sie aktualisierte Zahlungsdetails (PaymentDetailsUpdate) oder ein Promise darauf, z. B. neue Versandoptionen, einen geänderten Gesamtbetrag oder eine Fehlermeldung, falls an diese Adresse nicht geliefert werden kann. Solange das Promise nicht erfüllt ist, zeigt der Browser im Dialog einen Ladezustand an.

Registrieren können Sie den Handler mit addEventListener("shippingaddresschange", handler) oder über die Eigenschaft request.onshippingaddresschange. Das Ereignis wird nicht weitergereicht (bubbelt nicht) und lässt sich nicht abbrechen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"shippingaddresschange"`.
$handler Pflicht	(event: PaymentRequestUpdateEvent) => void		Callback, der das `PaymentRequestUpdateEvent` erhält. Darin muss `event.updateWith()` synchron aufgerufen werden, wenn sich die Details ändern sollen.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener() hat keinen Rückgabewert. Der Handler selbst gibt über event.updateWith(detailsOrPromise) aktualisierte PaymentDetailsUpdate-Daten an den Browser zurück.

Beispiele

Versandkosten je nach Land neu berechnen

const methods = [{ supportedMethods: 'https://google.com/pay', data: { /* ... */ } }];

const baseDetails = {
  total: { label: 'Gesamt', amount: { currency: 'EUR', value: '49.90' } },
  displayItems: [{ label: 'T-Shirt', amount: { currency: 'EUR', value: '49.90' } }]
};

const request = new PaymentRequest(methods, baseDetails, { requestShipping: true });

// Liefert neue Details abhängig von der Adresse
const computeDetails = async (address) => {
  const shippingCost = address.country === 'DE' ? 4.90 : 12.90;
  const total = (49.90 + shippingCost).toFixed(2);
  return {
    total: { label: 'Gesamt', amount: { currency: 'EUR', value: total } },
    shippingOptions: [{
      id: 'standard',
      label: address.country === 'DE' ? 'DHL Standard' : 'International',
      amount: { currency: 'EUR', value: shippingCost.toFixed(2) },
      selected: true
    }]
  };
};

request.addEventListener('shippingaddresschange', (event) => {
  // updateWith() muss synchron aufgerufen werden – ein Promise ist erlaubt
  event.updateWith(computeDetails(request.shippingAddress));
});

document.querySelector('#buy').addEventListener('click', async () => {
  const response = await request.show();
  console.log('Lieferung an:', response.shippingAddress.city);
  await response.complete('success');
});

Lieferung an: Berlin

Nicht belieferbare Adresse mit Fehlermeldung ablehnen

const request = new PaymentRequest(
  [{ supportedMethods: 'https://example.com/pay' }],
  { total: { label: 'Gesamt', amount: { currency: 'EUR', value: '20.00' } } },
  { requestShipping: true }
);

const allowedCountries = ['DE', 'AT', 'CH'];

request.onshippingaddresschange = (event) => {
  const { country } = request.shippingAddress;
  if (!allowedCountries.includes(country)) {
    event.updateWith({
      error: 'Wir liefern leider nur nach Deutschland, Österreich und in die Schweiz.',
      shippingAddressErrors: { country: 'Land wird nicht beliefert.' },
      shippingOptions: [] // leere Liste = kein Versand möglich
    });
    return;
  }
  event.updateWith({
    shippingOptions: [{
      id: 'dach', label: 'Standardversand',
      amount: { currency: 'EUR', value: '5.00' }, selected: true
    }],
    total: { label: 'Gesamt', amount: { currency: 'EUR', value: '25.00' } }
  });
};

Listener wieder entfernen

const request = new PaymentRequest(
  [{ supportedMethods: 'https://example.com/pay' }],
  { total: { label: 'Gesamt', amount: { currency: 'EUR', value: '10.00' } } },
  { requestShipping: true }
);

const onAddressChange = (event) => {
  console.log('Neues Land:', request.shippingAddress.country);
  event.updateWith({});
};

request.addEventListener('shippingaddresschange', onAddressChange);

// Später, z. B. nach Abbruch des Checkouts
request.removeEventListener('shippingaddresschange', onAddressChange);

// Alternative über die on-Property
request.onshippingaddresschange = null;

Neues Land: DE

// Wichtig · Fallstricke

Synchron aufrufen: event.updateWith() muss direkt im Handler aufgerufen werden, nicht erst nach einem await. Asynchrone Berechnungen übergeben Sie als Promise. Ein zweiter Aufruf löst eine InvalidStateError-Ausnahme aus.
Datenschutz: Solange der Benutzer nicht bezahlt hat, gibt der Browser die Adresse oft nur gekürzt heraus. addressLine, recipient, phone und organization sind dann leer. Rechnen Sie nur mit Land, Region, Stadt und Postleitzahl. Die vollständige Adresse steht erst in PaymentResponse.shippingAddress.
Das Ereignis wird nur ausgelöst, wenn der Request mit { requestShipping: true } erzeugt wurde.
Geben Sie eine leere shippingOptions-Liste zurück, bedeutet das „an diese Adresse kann nicht geliefert werden“. Zeigen Sie dann mit error bzw. shippingAddressErrors einen verständlichen Hinweis an.
Kompatibilität: Die Payment Request API gibt es nur im sicheren Kontext (HTTPS). Die Unterstützung ist uneinheitlich: Chromium-Browser und Safari haben sie, Firefox standardmäßig nicht. Die Versandadress-Funktionen gelten in manchen Browsern als veraltet. Prüfen Sie vorher mit 'PaymentRequest' in window und bieten Sie einen normalen Checkout als Ausweichlösung an.
Prüfen Sie Adressen und Preise immer auch auf dem Server. Werte aus dem Client sind nicht vertrauenswürdig.

Siehe auch

PaymentRequest: shippingoptionchange PaymentRequest: paymentmethodchange PaymentRequest: merchantvalidation PaymentResponse: payerdetailchange XMLHttpRequest: readystatechange MediaKeySession: keystatuseschange MIDIInput: midimessage