PaymentResponse — Schnittstelle · JavaScript-Referenz

Signatur

interface PaymentResponse extends EventTarget

Beschreibung

PaymentResponse ist das Objekt, mit dem das Promise von PaymentRequest.prototype.show() erfüllt wird. Das passiert, sobald der Benutzer im nativen Zahlungsdialog des Browsers eine Zahlungsmethode gewählt und die Zahlung bestätigt hat. Das Objekt enthält alle Daten, die dein Server für die eigentliche Abbuchung braucht, zum Beispiel ein Token des Zahlungsanbieters oder Kartendaten.

Wichtige Eigenschaften (alle schreibgeschützt):

requestId: die ID der zugehörigen Anfrage (aus details.id oder automatisch erzeugt)
methodName: Kennung der gewählten Zahlungsmethode, z. B. "https://google.com/pay" oder "https://apple.com/apple-pay"
details: methodenspezifisches Objekt mit den Zahlungsdaten, das du an den Server weitergibst
payerName, payerEmail, payerPhone: Käuferangaben. Sie werden nur befüllt, wenn du sie über requestPayerName usw. angefordert hast, sonst ist der Wert null.
shippingAddress, shippingOption: Lieferadresse und Versandart, wenn requestShipping gesetzt war

Wichtige Methoden:

complete(result): Schließt den Zahlungsdialog. result ist "success", "fail" oder "unknown". Die Methode gibt ein Promise<void> zurück.
retry(errorFields): Bittet den Benutzer, fehlerhafte Angaben zu korrigieren, etwa eine ungültige E-Mail-Adresse. Die Methode gibt ein Promise<void> zurück, das erfüllt wird, sobald der Benutzer erneut bestätigt hat.
toJSON(): Wandelt die Antwort in ein serialisierbares Objekt um. So lässt sie sich direkt per JSON.stringify() an den Server schicken.

Über das Ereignis payerdetailchange erfährst du, wenn der Benutzer während eines retry()-Durchlaufs Name, E-Mail-Adresse oder Telefonnummer ändert. Du kannst es mit addEventListener("payerdetailchange", …) oder über die Eigenschaft onpayerdetailchange abonnieren. Der typische Ablauf sieht so aus:

show() aufrufen und die Antwort abwarten.
response.details zum Server schicken.
Je nach Ergebnis complete("success") oder complete("fail") aufrufen.

Rückgabewert

Typ

PaymentResponse

Beschreibung

Wird nicht per Konstruktor erzeugt, sondern ist der Erfüllungswert des Promise von PaymentRequest.prototype.show().

Beispiele

Zahlung anfordern und abschließen

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

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

const options = { requestPayerName: true, requestPayerEmail: true };

const bezahlen = async () => {
  const request = new PaymentRequest(methods, details, options);
  const response = await request.show(); // PaymentResponse

  console.log(response.requestId, response.methodName, response.payerEmail);

  try {
    const res = await fetch('/api/zahlung', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(response) // nutzt intern toJSON()
    });
    await response.complete(res.ok ? 'success' : 'fail');
  } catch (err) {
    await response.complete('fail');
  }
};

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

bestellung-4711 https://google.com/pay kunde@example.com

Fehlerhafte Käuferangaben mit retry() korrigieren lassen

const pruefeUndBezahle = async (request) => {
  const response = await request.show();

  // Solange die E-Mail-Adresse ungültig ist, den Benutzer korrigieren lassen
  while (!response.payerEmail?.endsWith('.de')) {
    await response.retry({
      payer: { email: 'Bitte eine deutsche E-Mail-Adresse (.de) angeben.' }
    });
  }

  await response.complete('success');
  return response;
};

Änderungen der Käuferdaten beobachten (payerdetailchange)

const beobachteKaeufer = (response) => {
  const onChange = (event) => {
    const r = event.target; // PaymentResponse
    console.log('Neue Daten:', r.payerName, r.payerEmail, r.payerPhone);
  };

  response.addEventListener('payerdetailchange', onChange);
  // Alternativ über die Eigenschaft:
  // response.onpayerdetailchange = onChange;

  // Später wieder abmelden
  return () => response.removeEventListener('payerdetailchange', onChange);
};

Neue Daten: Max Muster max@example.de +49301234567

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser (Chrome, Edge, Samsung Internet) und Safari (dort hauptsächlich Apple Pay) unterstützen die API. Firefox unterstützt sie nicht. Die API ist nur in einem sicheren Kontext (HTTPS) verfügbar und in einem iframe nur mit allow="payment".
complete() immer aufrufen: Ohne diesen Aufruf bleibt der Zahlungsdialog offen oder läuft in ein Zeitlimit. Du darfst complete() nur einmal aufrufen. Ein zweiter Aufruf oder ein Aufruf während eines laufenden retry() wirft einen InvalidStateError.
Sicherheit: Vertraue details clientseitig nie. Zahlungstoken müssen serverseitig beim Zahlungsanbieter geprüft und eingelöst werden. Rohe Kartendaten (basic-card) sind veraltet und fallen unter PCI-DSS. Nutze stattdessen tokenbasierte Methoden wie Google Pay oder Apple Pay.
shippingAddress und shippingOption sind in der aktuellen Spezifikation und in mehreren Browsern veraltet oder werden unterschiedlich unterstützt. Verlasse dich nicht darauf, dass sie überall verfügbar sind.
payerName, payerEmail und payerPhone sind null, wenn sie in den Optionen nicht angefordert wurden.

Siehe auch

PaymentRequest PaymentAddress Response GamepadPose PaymentManager