new PaymentRequest() — Methode · JavaScript-Referenz

Signatur

new PaymentRequest(methodData, details, options)

Beschreibung

Der Konstruktor PaymentRequest() ist der Einstiegspunkt der Payment Request API. Du übergibst ihm, welche Zahlungsarten dein Shop akzeptiert (methodData), was bezahlt werden soll (details mit Gesamtbetrag, Einzelposten und Versandoptionen) und optional, welche Kundendaten du zusätzlich brauchst (options, z. B. Name, E-Mail oder Lieferadresse).

Beim Erzeugen des Objekts erscheint noch kein Dialog. Erst ein Aufruf von request.show() öffnet die Bezahloberfläche des Browsers bzw. der Zahlungs-App (z. B. Google Pay oder Apple Pay). Das zurückgegebene Promise liefert eine PaymentResponse, deren Daten du an deinen Server bzw. Zahlungsdienstleister weitergibst. Danach schließt du den Vorgang mit response.complete("success") oder "fail" ab.

Der Konstruktor prüft seine Argumente sofort und wirft einen Fehler, wenn sie ungültig sind, etwa bei einem leeren methodData-Array, einem ungültigen Währungscode oder einem negativen Gesamtbetrag. Mit request.canMakePayment() kannst du vorab prüfen, ob überhaupt eine passende Zahlungsart verfügbar ist. So zeigst du den Bezahl-Button nur an, wenn es auch funktioniert.

Parameter

Name	Typ	Default	Beschreibung
$methodData Pflicht	Array<{supportedMethods: string, data?: object}>		Liste der akzeptierten Zahlungsarten. `supportedMethods` ist ein Bezeichner wie `"https://google.com/pay"` oder `"https://apple.com/apple-pay"`. In `data` stehen die Einstellungen, die die jeweilige Zahlungsart erwartet. Das Array darf nicht leer sein.
$details Pflicht	PaymentDetailsInit		Angaben zur Transaktion: `total` (Pflicht, `{label, amount: {currency, value}}`), optional `displayItems` (Einzelposten), `shippingOptions`, `modifiers` und `id`. Beträge werden als String angegeben, z. B. `"19.99"`.
$options	PaymentOptions	{}	Legt fest, welche Kundendaten abgefragt werden: `requestPayerName`, `requestPayerEmail`, `requestPayerPhone`, `requestShipping` (alle `boolean`, Standard `false`) sowie `shippingType` (`"shipping"`, `"delivery"` oder `"pickup"`).

Rückgabewert

Typ

PaymentRequest

Beschreibung

Ein neues PaymentRequest-Objekt. Den Bezahldialog öffnest du anschließend mit show().

Beispiele

Einfache Zahlung mit Google Pay

const methodData = [{
  supportedMethods: 'https://google.com/pay',
  data: {
    environment: 'TEST',
    apiVersion: 2,
    apiVersionMinor: 0,
    merchantInfo: { merchantName: 'Beispiel-Shop' },
    allowedPaymentMethods: [{
      type: 'CARD',
      parameters: {
        allowedAuthMethods: ['PAN_ONLY'],
        allowedCardNetworks: ['VISA', 'MASTERCARD']
      },
      tokenizationSpecification: {
        type: 'PAYMENT_GATEWAY',
        parameters: { gateway: 'example', gatewayMerchantId: 'abc123' }
      }
    }]
  }
}];

const details = {
  total: { label: 'Gesamtsumme', amount: { currency: 'EUR', value: '24.90' } }
};

const request = new PaymentRequest(methodData, details);
console.log(request instanceof PaymentRequest);

true

Vollständiger Checkout mit Posten, Kundendaten und Abschluss

const payButton = document.querySelector('#pay');

payButton.addEventListener('click', async () => {
  const request = new PaymentRequest(
    [{ supportedMethods: 'https://google.com/pay', data: { /* Konfiguration wie oben */ } }],
    {
      id: 'bestellung-1042',
      displayItems: [
        { label: 'T-Shirt', amount: { currency: 'EUR', value: '19.90' } },
        { label: 'Versand', amount: { currency: 'EUR', value: '5.00' } }
      ],
      total: { label: 'Gesamt', amount: { currency: 'EUR', value: '24.90' } }
    },
    { requestPayerName: true, requestPayerEmail: true }
  );

  try {
    const response = await request.show();
    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) {
    // AbortError, wenn der Nutzer den Dialog schließt
    console.warn('Abgebrochen:', err.name);
  }
});

Zahlung erfolgreich

Unterstützung prüfen und Konstruktorfehler abfangen

const supportsPayments = async () => {
  if (!('PaymentRequest' in window)) return false;
  try {
    const req = new PaymentRequest(
      [{ supportedMethods: 'https://google.com/pay', data: {} }],
      { total: { label: 'Test', amount: { currency: 'EUR', value: '0.00' } } }
    );
    return await req.canMakePayment();
  } catch (err) {
    console.error(err.name, err.message);
    return false;
  }
};

// Ungültiger Aufruf: leeres methodData
try {
  new PaymentRequest([], { total: { label: 'X', amount: { currency: 'EUR', value: '1.00' } } });
} catch (err) {
  console.log(err.name);
}

supportsPayments().then((ok) => console.log('Bezahlen möglich:', ok));

TypeError Bezahlen möglich: true (oder false, je nach Browser)

// Wichtig · Fallstricke

Sicherer Kontext: Die API funktioniert nur über HTTPS. In <iframe>-Elementen braucht sie zusätzlich allow="payment".
Nutzeraktion erforderlich: show() muss durch eine Nutzeraktion wie einen Klick ausgelöst werden, sonst wird das Promise mit SecurityError abgelehnt. Pro Seite darf außerdem nur ein Bezahldialog gleichzeitig offen sein.
Fehler im Konstruktor: Bei ungültigen Argumenten wirft der Konstruktor einen TypeError, etwa bei leerem methodData, ungültigem Währungscode, falsch formatiertem value oder negativem total. Ungültige Zahlungsart-Bezeichner lösen einen RangeError aus.
Beträge als Strings: Gib value immer als Dezimal-String an ("19.90"), nicht als Zahl. So vermeidest du Rundungsfehler. Der Browser rechnet die displayItems nicht nach. Für eine korrekte Summe in total bist du selbst verantwortlich.
Browser-Unterstützung: Chromium-Browser unterstützen die API am vollständigsten. Safari akzeptiert nur Apple Pay ("https://apple.com/apple-pay"). In Firefox ist sie standardmäßig nicht aktiviert. Die frühere Methode "basic-card" wurde entfernt. Biete deshalb immer einen klassischen Checkout als Ausweichlösung an.
Sicherheit: Prüfe Beträge und Zahlungstoken immer auf dem Server. Die Werte aus dem Client können manipuliert sein.

Siehe auch

new PaymentRequestEvent() new Request() new XMLHttpRequest() new GamepadEvent() new PointerEvent()