PaymentRequest.shippingAddress — Eigenschaft · JavaScript-Referenz

Signatur

PaymentRequest.shippingAddress

Beschreibung

Die Eigenschaft shippingAddress eines PaymentRequest-Objekts enthält die Lieferadresse, die der Benutzer im nativen Zahlungsdialog des Browsers ausgewählt oder eingegeben hat. Gefüllt wird sie nur, wenn der Request mit der Option { requestShipping: true } erzeugt wurde. Vorher, oder solange noch keine Adresse gewählt ist, ist der Wert null.

Am häufigsten liest man die Eigenschaft im Handler des Events shippingaddresschange. Hier berechnet man Versandkosten und verfügbare Versandarten für die neue Adresse und übergibt sie mit event.updateWith(). Aus Datenschutzgründen kann der Browser die Adresse zu diesem Zeitpunkt anonymisieren. Dann sind nur grobe Angaben wie Land, Region, Stadt und Postleitzahl enthalten. Name, Straße und Telefonnummer fehlen.

Die vollständige Adresse bekommt man erst, wenn der Benutzer die Zahlung bestätigt. Sie steht dann in PaymentResponse.shippingAddress, nachdem das Promise von show() erfüllt wurde. Für den eigentlichen Versand sollte man deshalb immer die Adresse aus der Antwort nehmen und nicht die aus dem Request.

Rückgabewert

Typ

PaymentAddress | null

Beschreibung

Ein PaymentAddress-Objekt mit Feldern wie country, region, city, postalCode, addressLine (Array), recipient, organization und phone. Der Wert ist null, wenn keine Lieferadresse angefordert oder noch keine gewählt wurde.

Beispiele

Versandkosten bei Adressänderung neu berechnen

const methods = [{ supportedMethods: 'https://google.com/pay', data: { /* ... */ } }];
const details = {
  total: { label: 'Summe', amount: { currency: 'EUR', value: '49.90' } },
  shippingOptions: []
};

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

request.addEventListener('shippingaddresschange', (event) => {
  const address = request.shippingAddress;
  console.log('Neues Lieferland:', address.country);

  const isDomestic = address.country === 'DE';
  const shippingCost = isDomestic ? '4.90' : '14.90';

  event.updateWith({
    total: {
      label: 'Summe',
      amount: { currency: 'EUR', value: (49.90 + Number(shippingCost)).toFixed(2) }
    },
    shippingOptions: [{
      id: isDomestic ? 'dhl-de' : 'dhl-intl',
      label: isDomestic ? 'DHL Standard (DE)' : 'DHL International',
      amount: { currency: 'EUR', value: shippingCost },
      selected: true
    }]
  });
});

const response = await request.show();
await response.complete('success');

Neues Lieferland: DE

Nicht belieferbare Länder ablehnen

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

request.onshippingaddresschange = (event) => {
  const { country } = request.shippingAddress ?? {};

  if (!allowedCountries.includes(country)) {
    // Leere Versandoptionen + Fehlermeldung: Der Dialog lässt keinen Abschluss zu
    event.updateWith({
      error: `Leider liefern wir nicht nach ${country}.`,
      shippingOptions: []
    });
    return;
  }

  event.updateWith({ shippingOptions: standardOptions, total: baseTotal });
};

Vollständige Adresse erst aus PaymentResponse übernehmen

const request = new PaymentRequest(methods, details, { requestShipping: true });
console.log(request.shippingAddress); // vor show(): null

try {
  const response = await request.show();
  const addr = response.shippingAddress; // vollständig, nicht anonymisiert

  await fetch('/api/orders', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      recipient: addr.recipient,
      street: addr.addressLine.join(', '),
      zip: addr.postalCode,
      city: addr.city,
      country: addr.country,
      payment: response.details
    })
  });

  await response.complete('success');
} catch (err) {
  console.warn('Zahlung abgebrochen:', err.name);
}

null

// Wichtig · Fallstricke

Nur mit requestShipping: true: Ohne diese Option bleibt die Eigenschaft immer null, und das Event shippingaddresschange wird nie ausgelöst.
Anonymisierte Adresse: Im Event-Handler fehlen oft recipient, phone und addressLine, oder die Felder sind leer. Die Versandkosten sollte man deshalb nur aus Land, Region und PLZ berechnen.
Event immer beantworten: Rufen Sie im Handler event.updateWith() auf, zur Not mit einem Promise. Sonst kann der Dialog hängen bleiben oder abbrechen.
Kompatibilität: Lieferadressen im Payment Request API gelten als experimentell. Sie werden praktisch nur in Chromium-Browsern unterstützt, Safari/Apple Pay nutzt eigene Mechanismen. Prüfen Sie vorher mit 'PaymentRequest' in window und bieten Sie ein klassisches Formular als Ausweichlösung an.
Sicherer Kontext: Die API ist nur über HTTPS verfügbar und braucht für show() eine Benutzeraktion, zum Beispiel einen Klick.
Datenschutz: Adressdaten sind personenbezogen. Übertragen und speichern Sie nur, was für die Bestellung wirklich nötig ist.

Siehe auch

PaymentRequest.shippingType PaymentRequest.shippingOption PaymentRequest.payerName PaymentRequest.id PaymentResponse.shippingAddress