PaymentRequest.shippingOption — Eigenschaft · JavaScript-Referenz

Signatur

PaymentRequest.shippingOption

Beschreibung

Die Eigenschaft shippingOption der Schnittstelle PaymentRequest enthält die id der Versandoption, die gerade ausgewählt ist. Die möglichen Optionen legt man im Feld details.shippingOptions des Konstruktors new PaymentRequest(methodData, details, options) fest. Ist dort eine Option mit selected: true markiert, steht deren id schon vor dem Öffnen des Bezahldialogs in shippingOption. Ist keine vorausgewählt, ist der Wert null.

Wählt der Benutzer im Bezahldialog eine andere Versandart, aktualisiert der Browser shippingOption und löst anschließend das Ereignis shippingoptionchange aus. In dessen Handler liest man den neuen Wert aus und reicht über event.updateWith() neue Zahlungsdetails (z. B. geänderte Versandkosten und Gesamtsumme) zurück.

Einen sinnvollen Wert hat die Eigenschaft nur, wenn in den Optionen requestShipping: true gesetzt wurde. Nach Abschluss des Dialogs steht die gewählte Option auch in PaymentResponse.shippingOption zur Verfügung. Diesen Wert sollte man für die Bestellung auf dem Server verwenden.

Rückgabewert

Typ

string | null

Beschreibung

Die id der ausgewählten Versandoption aus details.shippingOptions oder null, wenn keine Option ausgewählt ist.

Beispiele

Vorausgewählte Versandoption auslesen

const methodData = [{ supportedMethods: 'https://example.com/pay' }];
const details = {
  total: { label: 'Gesamt', amount: { currency: 'EUR', value: '24.90' } },
  shippingOptions: [
    { id: 'standard', label: 'Standard (3–5 Tage)', amount: { currency: 'EUR', value: '4.90' }, selected: true },
    { id: 'express', label: 'Express (1 Tag)', amount: { currency: 'EUR', value: '9.90' } }
  ]
};

const request = new PaymentRequest(methodData, details, { requestShipping: true });
console.log(request.shippingOption);

standard

Versandkosten bei Wechsel der Option neu berechnen

const basePrice = 20;
const shippingCosts = { standard: 4.9, express: 9.9 };

const buildDetails = (selectedId) => {
  const shipping = shippingCosts[selectedId] ?? 0;
  return {
    total: { label: 'Gesamt', amount: { currency: 'EUR', value: (basePrice + shipping).toFixed(2) } },
    shippingOptions: Object.entries(shippingCosts).map(([id, cost]) => ({
      id,
      label: id === 'express' ? 'Express' : 'Standard',
      amount: { currency: 'EUR', value: cost.toFixed(2) },
      selected: id === selectedId
    }))
  };
};

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

request.addEventListener('shippingoptionchange', (event) => {
  // request.shippingOption enthält jetzt die neue Auswahl
  console.log('Neue Versandart:', request.shippingOption);
  event.updateWith(buildDetails(request.shippingOption));
});

const pay = async () => {
  const response = await request.show();
  console.log('Bestellt mit:', response.shippingOption);
  await response.complete('success');
};

Neue Versandart: express Bestellt mit: express

Ohne Vorauswahl ist der Wert null

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

console.log(request.shippingOption === null);

true

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an request.shippingOption hat keine Wirkung. Die Auswahl ändert man nur, indem man in event.updateWith() oder show(detailsPromise) neue shippingOptions mit selected: true übergibt.
Mehrfach-Auswahl: Sind mehrere Optionen mit selected: true markiert, gilt die letzte davon. Doppelte id-Werte führen dazu, dass der Browser alle Versandoptionen verwirft.
Ohne requestShipping: true werden Versandoptionen ignoriert und der Wert bleibt null.
Sicherheit: Versandkosten immer auf dem Server anhand der übermittelten id neu berechnen. Werte vom Client dürfen nicht als verbindlicher Preis gelten.
Kompatibilität: Die Payment Request API gibt es nur in sicheren Kontexten (HTTPS). Versandfunktionen (requestShipping, shippingOption, shippingoptionchange) laufen vor allem in Chromium-Browsern. Safari und Firefox unterstützen sie nicht oder nicht mehr, und die Spezifikation stuft sie inzwischen zurück. Deshalb vorher mit 'PaymentRequest' in window prüfen und eine eigene Formular-Lösung als Ersatz bereithalten.

Siehe auch

PaymentAddress.organization PaymentRequest.shippingType PaymentRequest.shippingAddress PaymentRequest.id PaymentRequest.payerName