PaymentAddress.region — Eigenschaft · JavaScript-Referenz

Signatur

PaymentAddress.region

Beschreibung

Die schreibgeschützte Eigenschaft region eines PaymentAddress-Objekts enthält die oberste Verwaltungseinheit unterhalb der Landesebene. Je nach Land ist das ein Bundesstaat (USA: "CA"), eine Provinz (Kanada: "QC"), eine Präfektur (Japan), ein Kanton (Schweiz) oder ein Bundesland. In vielen Ländern wird dieses Feld in Postadressen nicht verwendet. Dann ist der Wert ein leerer String.

Ein PaymentAddress bekommst du über die Payment Request API: als PaymentResponse.shippingAddress, wenn du die Anfrage mit requestShipping: true gestellt hast, oder als PaymentRequest.shippingAddress innerhalb des Events shippingaddresschange. Typische Anwendungsfälle sind die Berechnung von Steuern (z. B. US-Sales-Tax je Bundesstaat), regional unterschiedliche Versandkosten und die Prüfung, ob an diese Region überhaupt geliefert wird.

Das Format des Werts ist nicht einheitlich festgelegt. Manche Browser liefern eine Abkürzung ("NY"), andere den ausgeschriebenen Namen ("New York"). Werte deshalb vor dem Vergleich normalisieren (Groß- und Kleinschreibung, Leerzeichen) und am besten zusammen mit country auswerten.

Rückgabewert

Typ

string

Beschreibung

Die oberste Verwaltungseinheit der Adresse, z. B. "CA", "QC" oder "Bayern". Ein leerer String, wenn es für das Land keine Region gibt oder keine angegeben wurde.

Beispiele

Region der Lieferadresse nach dem Bezahlvorgang auslesen

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

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

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

Lieferung nach San Francisco, CA, US

Sales-Tax je US-Bundesstaat im shippingaddresschange-Event berechnen

const TAX_RATES = { CA: 0.0725, NY: 0.04, TX: 0.0625 };
const NET = 100;

const request = new PaymentRequest(methods, {
  total: { label: 'Gesamt', amount: { currency: 'USD', value: NET.toFixed(2) } }
}, { requestShipping: true });

request.addEventListener('shippingaddresschange', (event) => {
  const { country, region } = request.shippingAddress;
  const code = region.trim().toUpperCase();
  const rate = country === 'US' ? (TAX_RATES[code] ?? 0) : 0;
  const tax = NET * rate;

  event.updateWith({
    displayItems: [
      { label: 'Zwischensumme', amount: { currency: 'USD', value: NET.toFixed(2) } },
      { label: `Steuer (${code || '–'})`, amount: { currency: 'USD', value: tax.toFixed(2) } }
    ],
    total: { label: 'Gesamt', amount: { currency: 'USD', value: (NET + tax).toFixed(2) } }
  });
});

Für region = "CA": Steuer (CA) 7.25, Gesamt 107.25

Lieferung in bestimmte Regionen ablehnen

const BLOCKED = new Set(['HI', 'AK']); // z. B. kein Versand nach Hawaii/Alaska

request.addEventListener('shippingaddresschange', (event) => {
  const region = request.shippingAddress.region.toUpperCase();
  if (BLOCKED.has(region)) {
    event.updateWith({
      error: 'Leider liefern wir nicht in diese Region.',
      shippingAddressErrors: { region: 'Region wird nicht beliefert.' }
    });
    return;
  }
  event.updateWith({});
});

// Wichtig · Fallstricke

Veraltet: PaymentAddress wurde in der Spezifikation durch ContactAddress ersetzt. Die Eigenschaft region gibt es dort weiterhin. Firefox hat die Payment Request API nie standardmäßig aktiviert. Prüfe die Unterstützung vorher mit 'PaymentRequest' in window.
Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung, und show() muss durch eine Benutzeraktion ausgelöst werden.
Datenschutz: Im Event shippingaddresschange geben Browser die Adresse oft nur teilweise weiter (z. B. ohne Straße und Namen). region, country und postalCode sind aber in der Regel vorhanden. Die vollständige Adresse gibt es erst in der PaymentResponse.
Das Format ist uneinheitlich: Abkürzung oder voller Name, je nach Browser und Land. Rechne auch mit einem leeren String, etwa bei deutschen Adressen, in denen das Bundesland meist fehlt.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert bzw. löst im Strict Mode einen TypeError aus.
Eine steuerrelevante Region gehört immer auch serverseitig geprüft. Clientseitige Werte sind nicht vertrauenswürdig.

Siehe auch

PaymentAddress.city PaymentAddress.phone PaymentAddress.recipient PaymentAddress.country PaymentAddress.addressLine