PaymentAddress.city — Eigenschaft · JavaScript-Referenz

Signatur

PaymentAddress.city

Beschreibung

Die schreibgeschützte Eigenschaft city gehört zum Interface PaymentAddress der Payment Request API. Sie liefert den Stadt- oder Gemeindeteil einer Adresse als String, zum Beispiel "Berlin" oder "München".

Ein PaymentAddress-Objekt bekommt man nicht über einen Konstruktor. Der Browser stellt es bereit, und zwar in zwei Fällen:

über PaymentRequest.shippingAddress, während der Nutzer die Lieferadresse auswählt (Event shippingaddresschange),
über PaymentResponse.shippingAddress, nachdem der Bezahlvorgang mit PaymentRequest.show() abgeschlossen wurde.

Voraussetzung ist in beiden Fällen, dass beim Erzeugen des PaymentRequest die Option requestShipping: true gesetzt war. Typische Anwendungsfälle sind die Berechnung von Versandkosten, die Prüfung, ob in eine Region geliefert wird, und das Speichern der Lieferadresse in der Bestellung.

Gibt es in einem Land keine Stadtangabe oder hat der Nutzer keine angegeben, ist der Wert ein leerer String "" und nicht null.

Rückgabewert

Typ

string

Beschreibung

Name der Stadt bzw. Gemeinde oder ein leerer String "", wenn keiner vorhanden ist.

Beispiele

Versandkosten abhängig von der Stadt berechnen

const methods = [{ supportedMethods: 'https://example.com/pay' }];
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 { city, country } = request.shippingAddress;
  const lokal = country === 'DE' && city.trim().toLowerCase() === 'berlin';

  event.updateWith({
    ...details,
    shippingOptions: [{
      id: lokal ? 'kurier' : 'standard',
      label: lokal ? 'Kurier (Berlin)' : 'Standardversand',
      amount: { currency: 'EUR', value: lokal ? '2.90' : '4.90' },
      selected: true
    }]
  });
});

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

Stadt aus der fertigen Zahlungsantwort lesen

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

try {
  const response = await request.show();
  const address = response.shippingAddress;
  console.log(`Lieferung nach: ${address.postalCode} ${address.city}`);
  await response.complete('success');
} catch (err) {
  console.error('Zahlung abgebrochen:', err.name);
}

Lieferung nach: 10115 Berlin

Liefergebiet prüfen mit Fallback für leere Werte

const LIEFERSTAEDTE = new Set(['berlin', 'hamburg', 'münchen']);

const istLieferbar = (address) => {
  const city = (address?.city ?? '').trim().toLocaleLowerCase('de');
  return city !== '' && LIEFERSTAEDTE.has(city);
};

request.addEventListener('shippingaddresschange', (event) => {
  if (!istLieferbar(request.shippingAddress)) {
    event.updateWith({
      error: 'In diese Stadt liefern wir leider nicht.',
      shippingAddressErrors: { city: 'Nicht im Liefergebiet' }
    });
    return;
  }
  event.updateWith({});
});

// Wichtig · Fallstricke

Veraltet: PaymentAddress wurde in der Spezifikation in ContactAddress umbenannt. Chromium stellt das Objekt unter diesem Namen bereit, city funktioniert gleich. Die Unterstützung für Lieferadressen wurde zudem aus der Payment-Request-Spezifikation entfernt. Für neue Projekte ist das deshalb nicht zu empfehlen.
Browserunterstützung: Nur Chromium-Browser und Safari (Apple Pay). Firefox hat die API nie standardmäßig aktiviert. Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung. Prüfen Sie die Verfügbarkeit mit 'PaymentRequest' in window.
Datenschutz/Schwärzung: Während des Events shippingaddresschange geben Browser die Adresse gekürzt weiter. Straße, Empfänger, Telefon und Organisation können dabei leer sein. city, postalCode und country sind in der Regel vorhanden. Die vollständige Adresse gibt es erst in PaymentResponse.shippingAddress.
Keine Normalisierung: Der Wert ist Freitext aus der Eingabe des Nutzers. Groß- und Kleinschreibung, Leerzeichen und Schreibweisen (z. B. „Muenchen“ statt „München“) können abweichen. Vor Vergleichen deshalb normalisieren und serverseitig validieren.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert bzw. wirft im Strict Mode einen TypeError.

Siehe auch

PaymentAddress.country PaymentAddress.phone PaymentAddress.region PaymentAddress.recipient PaymentAddress.postalCode