PaymentResponse.shippingAddress — Eigenschaft · JavaScript-Referenz

Signatur

PaymentResponse.shippingAddress

Beschreibung

PaymentResponse.shippingAddress enthält die Lieferadresse, die der Benutzer im Bezahldialog der Payment Request API ausgewählt oder eingegeben hat. Die Eigenschaft gehört zu dem PaymentResponse-Objekt, mit dem das Promise von PaymentRequest.prototype.show() erfüllt wird. Hinweis: Die MDN-Kurzbeschreibung nennt hier fälschlich PaymentRequest. Dort gibt es zwar ebenfalls eine Eigenschaft shippingAddress, sie beschreibt aber die Adresse, die gerade im noch offenen Dialog ausgewählt ist.

Einen Wert erhältst du nur, wenn du beim Erzeugen des PaymentRequest in den Optionen requestShipping: true setzt. Ohne diese Option ist die Eigenschaft null. Das zurückgegebene Objekt hat unter anderem diese Felder: recipient, organization, addressLine (ein Array), city, region, postalCode, country (ISO-3166-Code), dependentLocality, sortingCode und phone. Mit toJSON() lässt es sich direkt serialisieren.

Typischer Ablauf: Du liest die Adresse aus der Antwort aus, prüfst sie auf dem Server (z. B. ob in dieses Land geliefert wird) und schließt den Dialog danach mit response.complete("success") oder response.complete("fail"). Wenn du Versandkosten dynamisch berechnen willst, solange der Dialog noch offen ist, reagierst du stattdessen auf das Ereignis shippingaddresschange des PaymentRequest.

Rückgabewert

Typ

ContactAddress | null

Beschreibung

Ein ContactAddress-Objekt (in älteren Browsern PaymentAddress) mit der Lieferadresse oder null, wenn keine Lieferadresse angefordert wurde.

Beispiele

Lieferadresse nach dem Bezahlen auslesen

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

const checkout = async () => {
  const request = new PaymentRequest(methods, details, { requestShipping: true });
  const response = await request.show();
  const addr = response.shippingAddress;
  console.log(addr.recipient, addr.addressLine.join(', '), addr.postalCode, addr.city, addr.country);
  await response.complete('success');
};

document.querySelector('#buy').addEventListener('click', checkout);

Max Mustermann Hauptstraße 1 10115 Berlin DE

Adresse serverseitig prüfen und Dialog passend abschließen

const finishOrder = async (response) => {
  const address = response.shippingAddress;
  if (!address) {
    await response.complete('fail');
    return;
  }
  const res = await fetch('/api/orders', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      shipping: address.toJSON(),
      option: response.shippingOption,
      payment: response.details
    })
  });
  await response.complete(res.ok ? 'success' : 'fail');
};

Ohne requestShipping ist die Eigenschaft null

const request = new PaymentRequest(
  [{ supportedMethods: 'https://google.com/pay' }],
  { total: { label: 'E-Book', amount: { currency: 'EUR', value: '9.99' } } }
);
const response = await request.show();
console.log(response.shippingAddress);
await response.complete('success');

null

// Wichtig · Fallstricke

Nur mit requestShipping: true: Ohne diese Option ist der Wert immer null. Prüfe deshalb vor jedem Zugriff auf null.
Kompatibilität: Chromium-Browser und Safari unterstützen die Eigenschaft, Firefox nur hinter einem Flag. Die Versand- und Adressfunktionen der Payment Request API gelten in der Spezifikation als gefährdet und sind auf MDN teils als veraltet markiert. Plane immer einen normalen Formular-Checkout als Ausweichlösung ein und prüfe vorher mit 'PaymentRequest' in window, ob die API vorhanden ist.
Die Schnittstelle hieß früher PaymentAddress und heißt heute ContactAddress. Verlass dich nicht auf instanceof-Prüfungen gegen einen dieser beiden Namen.
Die API funktioniert nur in einem sicheren Kontext (HTTPS). show() muss durch eine Benutzeraktion ausgelöst werden, zum Beispiel einen Klick.
Datenschutz: Solange der Dialog offen ist, schwärzen Browser beim Ereignis shippingaddresschange Teile der Adresse, etwa recipient, phone und addressLine. Die vollständige Adresse steht erst in der PaymentResponse. Prüfe die Adresse außerdem auf dem Server, denn Daten vom Client sind nicht vertrauenswürdig.

Siehe auch

PaymentResponse.shippingOption PaymentResponse.methodName PaymentResponse.details PaymentResponse.payerEmail PaymentResponse.requestId