PaymentRequest.show() — Methode · JavaScript-Referenz

Signatur

PaymentRequest.prototype.show(detailsPromise)

Beschreibung

show() weist den Browser an, die native Bezahloberfläche anzuzeigen. Dort wählt der Nutzer eine Zahlungsmethode (z. B. Google Pay, Apple Pay oder eine gespeicherte Karte) und gibt bei Bedarf eine Lieferadresse und Kontaktdaten an. Hat der Nutzer die Zahlung bestätigt, wird das zurückgegebene Promise mit einem PaymentResponse-Objekt erfüllt. Darin stecken die Zahlungsdaten, die Sie an Ihren Zahlungsdienstleister weitergeben.

Die Methode darf nur als Reaktion auf eine Nutzeraktion aufgerufen werden, etwa einen Klick. Dafür ist eine transiente Nutzeraktivierung nötig. Außerdem kann jede PaymentRequest-Instanz nur einmal angezeigt werden. Für einen neuen Versuch erzeugen Sie eine neue Instanz.

Über den optionalen Parameter detailsPromise können Sie die Oberfläche sofort öffnen und die endgültigen Preisdetails erst danach nachreichen, etwa wenn Versandkosten oder Steuern noch vom Server berechnet werden. Bis das Promise erfüllt ist, zeigt der Browser einen Ladezustand an.

Nach erfolgreicher Verarbeitung müssen Sie PaymentResponse.complete() aufrufen. Damit schließt sich die Oberfläche, und der Nutzer sieht, ob die Zahlung geklappt hat.

Parameter

Name	Typ	Default	Beschreibung
$detailsPromise	Promise<PaymentDetailsUpdate>		Optionales Promise, das mit aktualisierten Zahlungsdetails erfüllt wird (`total`, `displayItems`, `shippingOptions`, `modifiers`, `error`). Die Oberfläche bleibt im Ladezustand, bis das Promise erfüllt ist.

Rückgabewert

Typ

Promise<PaymentResponse>

Beschreibung

Wird mit einer PaymentResponse erfüllt, sobald der Nutzer die Zahlung bestätigt. Abgelehnt wird es u. a. mit AbortError (Nutzer bricht ab oder abort() wurde aufgerufen), InvalidStateError (Anfrage wurde bereits angezeigt oder es läuft schon eine andere), NotSupportedError (keine unterstützte Zahlungsmethode), SecurityError (kein sicherer Kontext, keine Nutzeraktivierung oder Einsatz im iframe ohne Berechtigung).

Beispiele

Einfacher Bezahlvorgang per Button-Klick

const methods = [{
  supportedMethods: 'https://google.com/pay',
  data: { /* Google-Pay-Konfiguration */ }
}];

const details = {
  total: { label: 'Gesamt', amount: { currency: 'EUR', value: '49.90' } }
};

document.querySelector('#pay').addEventListener('click', async () => {
  const request = new PaymentRequest(methods, details);
  try {
    const response = await request.show();
    // Zahlungsdaten an den eigenen Server senden
    const res = await fetch('/api/pay', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(response.toJSON())
    });
    await response.complete(res.ok ? 'success' : 'fail');
    console.log(res.ok ? 'Zahlung erfolgreich' : 'Zahlung fehlgeschlagen');
  } catch (err) {
    console.log(`Abgebrochen: ${err.name}`);
  }
});

Zahlung erfolgreich // oder bei Abbruch durch den Nutzer: Abgebrochen: AbortError

Vorab prüfen, ob eine Zahlung möglich ist

const pay = async () => {
  if (!('PaymentRequest' in window)) {
    console.log('Payment Request API nicht verfügbar – Formular anzeigen');
    return;
  }
  const request = new PaymentRequest(
    [{ supportedMethods: 'https://google.com/pay', data: {} }],
    { total: { label: 'Abo', amount: { currency: 'EUR', value: '9.99' } } }
  );
  if (!(await request.canMakePayment())) {
    console.log('Keine passende Zahlungsmethode – Alternative anbieten');
    return;
  }
  const response = await request.show();
  await response.complete('success');
};

document.querySelector('#abo').addEventListener('click', pay);

Preisdetails asynchron nachreichen (detailsPromise)

const methods = [{ supportedMethods: 'https://google.com/pay', data: {} }];
const initial = {
  total: { label: 'Gesamt', amount: { currency: 'EUR', value: '0.00' } }
};

document.querySelector('#checkout').addEventListener('click', async () => {
  const request = new PaymentRequest(methods, initial);

  // Oberfläche sofort öffnen, Preise erst vom Server holen
  const detailsPromise = fetch('/api/cart/total')
    .then((r) => r.json())
    .then(({ total, items }) => ({
      total: { label: 'Gesamt', amount: { currency: 'EUR', value: total } },
      displayItems: items
    }));

  try {
    const response = await request.show(detailsPromise);
    await response.complete('success');
  } catch (err) {
    console.error(err.name, err.message);
  }
});

// Wichtig · Fallstricke

Nur mit Nutzeraktivierung: Ruft man show() ohne vorherige Nutzeraktion auf (z. B. beim Laden der Seite oder nach langem await), wird das Promise mit SecurityError abgelehnt. Vor show() sollten Sie daher keine langsamen Netzwerkanfragen abwarten. Dafür ist detailsPromise gedacht.
Nur einmal pro Instanz: Ein zweiter Aufruf von show() auf derselben Instanz führt zu InvalidStateError. Außerdem kann pro Browser nur eine Bezahloberfläche gleichzeitig offen sein.
Sicherer Kontext: Die API steht nur über HTTPS zur Verfügung. In iframes ist sie nur nutzbar, wenn das iframe die Berechtigung hat, z. B. über allow="payment".
Immer complete() aufrufen: Sonst bleibt die Oberfläche im Ladezustand. Nach einer Zeitüberschreitung schließt der Browser sie von selbst.
Sicherheit: Prüfen Sie Betrag und Zahlungsdaten immer auf dem Server. Werte aus dem Client können manipuliert sein.
Kompatibilität: Unterstützt in Chromium-Browsern (Chrome, Edge) und Safari (dort vor allem für Apple Pay). In Firefox ist die API nicht standardmäßig aktiviert. Welche Zahlungsmethoden unterstützt werden, hängt stark von Browser und Plattform ab. Sehen Sie deshalb immer einen Ersatz-Bezahlweg vor.

Siehe auch

PannerNode.setPosition() PaymentRequest.abort() PaymentRequest.canMakePayment() PaymentRequest.securePaymentConfirmationAvailability() PaymentRequest.getSecurePaymentConfirmationCapabilities()