PaymentAddress.country — Eigenschaft · JavaScript-Referenz

Signatur

PaymentAddress.country

Beschreibung

Die Eigenschaft country eines PaymentAddress-Objekts enthält den Ländercode der Adresse, die der Nutzer im Zahlungsdialog der Payment Request API ausgewählt hat. Der Wert ist ein zweistelliger Code in Großbuchstaben nach ISO 3166-1 alpha-2, etwa "DE" für Deutschland, "AT" für Österreich oder "CH" für die Schweiz.

An ein PaymentAddress-Objekt kommt man über PaymentResponse.shippingAddress (nach request.show()) oder über PaymentRequest.shippingAddress im Handler des Ereignisses shippingaddresschange. Den Ländercode braucht man vor allem, um Versandkosten, Steuersätze oder verfügbare Versandarten vom Zielland abhängig zu machen und bestimmte Lieferländer zu sperren.

Die Eigenschaft ist schreibgeschützt. Kann das Land nicht ermittelt werden oder hat der Browser es aus Datenschutzgründen entfernt, ist der Wert ein leerer String (""). Vor dem Abschluss der Zahlung liefert der Browser im shippingaddresschange-Ereignis oft nur eine gekürzte Adresse. Das Land ist dabei aber in der Regel enthalten, weil es für die Berechnung der Versandkosten gebraucht wird.

Rückgabewert

Typ

string

Beschreibung

Zweistelliger Ländercode nach ISO 3166-1 alpha-2 in Großbuchstaben (z. B. "DE") oder ein leerer String, wenn kein Land bekannt ist.

Beispiele

Lieferland 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 country = response.shippingAddress?.country ?? '';
  console.log(`Lieferland: ${country}`);
  await response.complete('success');
};

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

Lieferland: DE

Versandkosten je nach Land beim Adresswechsel anpassen

const versand = { DE: '4.90', AT: '7.90', CH: '12.90' };

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

request.addEventListener('shippingaddresschange', (event) => {
  const { country } = request.shippingAddress;
  const kosten = versand[country];

  if (!kosten) {
    // Land wird nicht beliefert – Fehler im Dialog anzeigen
    event.updateWith({
      error: `Leider liefern wir nicht nach ${country || 'dieses Land'}.`,
      shippingOptions: []
    });
    return;
  }

  const summe = (49.90 + Number(kosten)).toFixed(2);
  event.updateWith({
    total: { label: 'Gesamt', amount: { currency: 'EUR', value: summe } },
    shippingOptions: [{
      id: 'standard', label: `Standardversand (${country})`,
      amount: { currency: 'EUR', value: kosten }, selected: true
    }]
  });
});

Ländercode lesbar anzeigen mit Intl.DisplayNames

const laenderNamen = new Intl.DisplayNames(['de'], { type: 'region' });

const zeigeLand = (address) => {
  const code = address?.country;
  return code ? laenderNamen.of(code) : 'unbekannt';
};

// z. B. mit response.shippingAddress aufrufen
console.log(zeigeLand({ country: 'CH' }));

Schweiz

// Wichtig · Fallstricke

Veraltet: Die Schnittstelle PaymentAddress und das Anfordern von Adressen über die Payment Request API wurden aus der Spezifikation entfernt (requestShipping gilt als veraltet). Nur Chromium-basierte Browser unterstützen sie noch, Firefox und Safari nicht. Für neue Projekte besser die Adresse per eigenem Formular erfassen oder die Adressfunktionen des Zahlungsanbieters nutzen.
In neueren Chromium-Versionen heißt das Objekt ContactAddress. Die Eigenschaft country funktioniert dort gleich.
Der Wert kann ein leerer String sein. Immer auf "" prüfen, bevor er als Schlüssel für Versandtabellen dient.
Es gibt nur zweistellige Alpha-2-Codes, keine Alpha-3-Codes ("DEU") und keine Ländernamen. Für eine lesbare Anzeige Intl.DisplayNames verwenden.
Verfügbar nur in sicheren Kontexten (HTTPS). Werte aus dem Client immer serverseitig prüfen, bevor Preise oder Steuern endgültig berechnet werden.

Siehe auch

ContactAddress.city PaymentAddress.city PaymentAddress.phone PaymentAddress.region PaymentAddress.recipient