PaymentAddress — Schnittstelle · JavaScript-Referenz

Signatur

interface PaymentAddress

Beschreibung

PaymentAddress ist ein schreibgeschütztes Datenobjekt der Payment Request API. Es enthält eine Postadresse, die der Nutzer im nativen Bezahldialog des Browsers ausgewählt oder eingegeben hat, etwa Empfänger, Straßenzeilen, Postleitzahl, Ort, Region, Land und Telefonnummer. Eine eigene Instanz erzeugt man nicht: Es gibt keinen öffentlichen Konstruktor. Der Browser stellt die Objekte über PaymentRequest.shippingAddress, PaymentResponse.shippingAddress oder, bei manchen Zahlungsarten, als Rechnungsadresse bereit.

Du brauchst das Interface, wenn dein Shop physische Waren verschickt. Dann setzt du in den Optionen von new PaymentRequest() den Wert requestShipping: true. Ändert der Nutzer im Dialog die Adresse, feuert das Ereignis shippingaddresschange. Dort liest du die neue Adresse aus, rechnest Versandkosten und Steuern neu und gibst sie mit event.updateWith() an den Dialog zurück.

Vor dem Absenden des Zahlungsdialogs gibt der Browser aus Datenschutzgründen oft nur eine geschwärzte Adresse heraus. Straßenzeilen, Empfänger, Organisation und Telefon sind dann leer, Land, Region, Ort und Postleitzahl bleiben erhalten (die Postleitzahl manchmal gekürzt). Die vollständige Adresse gibt es erst nach der Bestätigung über PaymentResponse.shippingAddress. Mit toJSON() machst du daraus ein einfaches Objekt, das du zum Server schicken kannst.

Parameter

Name	Typ	Default	Beschreibung
$addressLine	string[]	[]	Schreibgeschützt. Array mit den Adresszeilen, z. B. Straße, Hausnummer, Adresszusatz.
$city	string	""	Schreibgeschützt. Ort bzw. Stadt.
$country	string	""	Schreibgeschützt. Ländercode nach ISO 3166-1 Alpha-2, z. B. `"DE"`.
$dependentLocality	string	""	Schreibgeschützt. Ortsteil oder Stadtbezirk (in einigen Ländern relevant).
$organization	string	""	Schreibgeschützt. Firmen- oder Organisationsname.
$phone	string	""	Schreibgeschützt. Telefonnummer des Empfängers, meist im E.164-Format.
$postalCode	string	""	Schreibgeschützt. Postleitzahl.
$recipient	string	""	Schreibgeschützt. Name des Empfängers.
$region	string	""	Schreibgeschützt. Bundesland, Kanton oder Provinz.
$sortingCode	string	""	Schreibgeschützt. Sortiercode, z. B. CEDEX in Frankreich.
$toJSON()	function		Methode. Liefert ein einfaches Objekt mit allen oben genannten Eigenschaften, z. B. für `JSON.stringify()`.

Rückgabewert

Typ

PaymentAddress

Beschreibung

Kommt nicht aus einem Konstruktor, sondern vom Browser: über PaymentRequest.shippingAddress oder PaymentResponse.shippingAddress. Ohne Adresse ist der Wert null.

Beispiele

Versandadresse anfordern und nach der Zahlung auslesen

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

const checkout = async () => {
  const request = new PaymentRequest(methods, details, { requestShipping: true });
  const response = await request.show();

  const addr = response.shippingAddress; // PaymentAddress
  console.log(addr.recipient);
  console.log(addr.addressLine.join(', '));
  console.log(`${addr.postalCode} ${addr.city} (${addr.country})`);

  await response.complete('success');
};

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

Erika Mustermann Musterstraße 1 10115 Berlin (DE)

Versandkosten bei Adressänderung neu berechnen

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

request.addEventListener('shippingaddresschange', (event) => {
  const { country } = request.shippingAddress; // meist geschwärzt: nur Land/Ort/PLZ
  const shippingCost = country === 'DE' ? '4.90' : '12.90';

  event.updateWith({
    total: {
      label: 'Summe',
      amount: { currency: 'EUR', value: (45 + Number(shippingCost)).toFixed(2) }
    },
    shippingOptions: [{
      id: 'standard',
      label: country === 'DE' ? 'Standard (DE)' : 'International',
      amount: { currency: 'EUR', value: shippingCost },
      selected: true
    }]
  });
});

Adresse mit toJSON() an den Server senden

const sendOrder = async (response) => {
  const payload = {
    methodName: response.methodName,
    details: response.details,
    shipping: response.shippingAddress?.toJSON() ?? null
  };

  const res = await fetch('/api/orders', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });

  await response.complete(res.ok ? 'success' : 'fail');
};

// Wichtig · Fallstricke

Veraltet: In der aktuellen Spezifikation heißt das Interface ContactAddress. Auch die Adressfunktionen der Payment Request API (requestShipping, shippingaddresschange) gelten als veraltet oder stehen zur Entfernung an. Für neue Projekte empfiehlt sich, Adressen mit eigenen Formularen und autocomplete-Attributen zu erfassen.
Browser-Unterstützung: Vor allem Chromium-Browser (Chrome, Edge, Samsung Internet). Safari unterstützt die Adressfunktionen nur eingeschränkt (Apple Pay). Firefox hat die Payment Request API nie standardmäßig ausgeliefert. Prüfe die Verfügbarkeit vorher mit 'PaymentRequest' in window.
Nur in sicheren Kontexten (HTTPS) verfügbar. Der Dialog öffnet sich nur nach einer Nutzeraktion, etwa einem Klick.
Geschwärzte Daten: Im Ereignis shippingaddresschange sind addressLine, recipient, organization und phone in der Regel leer. Die vollständige Adresse gibt es erst über PaymentResponse.
Die früheren Eigenschaften regionCode und languageCode wurden entfernt. Verlass dich nicht auf sie.
Serverseitig prüfen: Die Adressdaten stammen vom Nutzer. Prüfe sie auf dem Server und maskiere sie vor der Ausgabe im HTML, damit keine XSS-Lücke entsteht.

Siehe auch

PaymentRequest ContactAddress PaymentManager PaymentResponse GamepadEvent