PaymentAddress.postalCode — Eigenschaft · JavaScript-Referenz

Signatur

PaymentAddress.postalCode

Beschreibung

Die schreibgeschützte Eigenschaft postalCode des Interfaces PaymentAddress gibt eine Zeichenkette mit dem Code zurück, den ein Land oder eine Region für die Postzustellung nutzt. Das ist zum Beispiel die fünfstellige PLZ in Deutschland ("10115"), der ZIP-Code in den USA ("94043" oder "94043-1351") oder der alphanumerische Postcode in Großbritannien ("SW1A 1AA").

Ein PaymentAddress-Objekt bekommst du in der Regel über PaymentResponse.shippingAddress, nachdem der Nutzer eine Zahlung über die Payment Request API bestätigt hat. Du kannst es auch während des Bezahlvorgangs über PaymentRequest.shippingAddress im Handler des Events shippingaddresschange auslesen. Typische Einsätze sind die Berechnung von Versandkosten, das Prüfen des Liefergebiets und das Vorbefüllen von Bestellformularen.

Gibt es in einem Land kein Postleitzahlensystem (etwa in Teilen Irlands vor Eircode oder in einigen afrikanischen Staaten), ist der Wert eine leere Zeichenkette. Während eines shippingaddresschange-Events kann der Browser die Adresse aus Datenschutzgründen gekürzt übergeben. Die Postleitzahl ist dann manchmal nur teilweise vorhanden, zum Beispiel ohne die ZIP+4-Erweiterung.

Rückgabewert

Typ

string

Beschreibung

Die Postleitzahl im landesüblichen Format oder eine leere Zeichenkette "", wenn keine vorhanden ist oder der Browser sie nicht übergibt.

Beispiele

Postleitzahl nach abgeschlossener Zahlung auslesen

const methods = [{ supportedMethods: 'https://example.com/pay' }];
const details = {
  total: { label: 'Gesamt', amount: { currency: 'EUR', value: '49.90' } }
};

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

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

Lieferung an: 10115 Berlin (DE)

Versandkosten abhängig von der PLZ berechnen

const baseDetails = {
  total: { label: 'Gesamt', amount: { currency: 'EUR', value: '20.00' } }
};

const shippingFor = (postalCode) =>
  // Inseln (PLZ 18565, 25845–25999, 26465–26579) kosten Aufschlag
  /^(18565|259\d\d|2584[5-9]|26[45]\d\d)$/.test(postalCode) ? '9.90' : '4.90';

const request = new PaymentRequest(
  [{ supportedMethods: 'https://example.com/pay' }],
  baseDetails,
  { requestShipping: true }
);

request.addEventListener('shippingaddresschange', (event) => {
  const { postalCode } = request.shippingAddress;
  const cost = shippingFor(postalCode);
  event.updateWith({
    total: {
      label: 'Gesamt',
      amount: { currency: 'EUR', value: (20 + Number(cost)).toFixed(2) }
    },
    shippingOptions: [{
      id: 'standard', label: 'Standardversand', selected: true,
      amount: { currency: 'EUR', value: cost }
    }]
  });
});

PLZ-Format prüfen und Fehler melden

const isValidGermanZip = (zip) => /^\d{5}$/.test(zip);

const validateAddress = (address) => {
  if (address.country === 'DE' && !isValidGermanZip(address.postalCode)) {
    return { shippingAddressErrors: { postalCode: 'Bitte eine gültige fünfstellige PLZ angeben.' } };
  }
  return {};
};

// Beispiel mit einem Adress-ähnlichen Objekt
console.log(validateAddress({ country: 'DE', postalCode: '1011' }));
console.log(validateAddress({ country: 'DE', postalCode: '10115' }));

{ shippingAddressErrors: { postalCode: 'Bitte eine gültige fünfstellige PLZ angeben.' } } {}

// Wichtig · Fallstricke

Veraltet: PaymentAddress und die Lieferadress-Funktionen wurden aus der Payment-Request-Spezifikation entfernt. Die Browser unterstützen sie unterschiedlich gut: Chrome kennt die Eigenschaft noch, Firefox hat die API nie standardmäßig aktiviert. Prüfe deshalb vor der Nutzung, ob 'PaymentRequest' in window gilt, und halte ein normales Adressformular als Rückfall bereit.

Der Wert ist immer eine Zeichenkette und nie eine Zahl. Wandle PLZ nicht mit Number() um, sonst gehen führende Nullen verloren ("01067" Dresden würde zu 1067) und alphanumerische Codes wie in Großbritannien oder Kanada funktionieren nicht.
Das Format ist von Land zu Land verschieden. Prüfe die PLZ immer zusammen mit country.
Im Event shippingaddresschange kann die Adresse aus Datenschutzgründen gekürzt sein. Die vollständige Adresse ist erst nach show() über PaymentResponse.shippingAddress sicher verfügbar.
Die API funktioniert nur in einem sicheren Kontext (HTTPS).
Prüfe Adressdaten zusätzlich auf dem Server, denn Werte aus dem Client sind nicht vertrauenswürdig.

Siehe auch

PaymentAddress.sortingCode PaymentAddress.phone PaymentAddress.city PaymentAddress.country PaymentAddress.region