PaymentResponse: payerdetailchange — Ereignis · JavaScript-Referenz

Signatur

paymentResponse.addEventListener("payerdetailchange", handler)

Beschreibung

Das Ereignis payerdetailchange gehört zur Payment Request API. Der Browser löst es an einem PaymentResponse-Objekt aus, wenn der Benutzer im Zahlungsdialog seine persönlichen Angaben ändert, also payerName, payerEmail oder payerPhone. Wenn der Handler läuft, enthalten diese Eigenschaften bereits die neuen Werte.

Das Ereignis ist vor allem im Zusammenspiel mit PaymentResponse.retry() wichtig. Stellt der Server fest, dass z. B. die E-Mail-Adresse ungültig ist, ruft man retry() mit einem Fehlerobjekt auf. Das öffnet den Dialog erneut und zeigt die Fehlermeldungen an. Korrigiert der Benutzer seine Angaben, wird payerdetailchange ausgelöst. So kann man die Eingaben schon prüfen, bevor der Benutzer erneut bestätigt.

Einen Handler registriert man mit addEventListener("payerdetailchange", handler) oder über die Eigenschaft onpayerdetailchange. Das Ereignisobjekt ist ein PaymentRequestUpdateEvent. Der Browser löst das Ereignis nur für Angaben aus, die beim Erstellen des PaymentRequest über requestPayerName, requestPayerEmail oder requestPayerPhone angefordert wurden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"payerdetailchange"`.
$handler Pflicht	(event: PaymentRequestUpdateEvent) => void		Die Rückruffunktion. Über `event.target` erreicht man das `PaymentResponse`-Objekt mit den aktualisierten Werten in `payerName`, `payerEmail` und `payerPhone`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen für den Listener, z. B. `{ once: true }` oder `{ signal }` zum späteren Entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Den Rückgabewert des Handlers ignoriert der Browser.

Beispiele

Geänderte Angaben mit addEventListener protokollieren

const methods = [{ supportedMethods: 'https://example.com/pay' }];
const details = { total: { label: 'Summe', amount: { currency: 'EUR', value: '19.99' } } };
const options = { requestPayerName: true, requestPayerEmail: true, requestPayerPhone: true };

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

  response.addEventListener('payerdetailchange', (event) => {
    const { payerName, payerEmail, payerPhone } = event.target;
    console.log('Neue Angaben:', payerName, payerEmail, payerPhone);
  });

  // Beispiel: Server lehnt E-Mail ab -> Benutzer soll korrigieren
  await response.retry({ payer: { email: 'Bitte eine gültige E-Mail-Adresse angeben.' } });
  await response.complete('success');
};

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

Neue Angaben: Max Mustermann max@example.com +49301234567

Eingaben während retry() live prüfen (onpayerdetailchange)

const isValidEmail = (mail) => /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(mail ?? '');

const handlePayment = async (response) => {
  response.onpayerdetailchange = async () => {
    const errors = {};
    if (!isValidEmail(response.payerEmail)) {
      errors.email = 'Die E-Mail-Adresse ist ungültig.';
    }
    if (!response.payerPhone?.startsWith('+')) {
      errors.phone = 'Bitte die Telefonnummer mit Ländervorwahl angeben.';
    }
    if (Object.keys(errors).length > 0) {
      // Dialog erneut mit Fehlermeldungen anzeigen
      await response.retry({ payer: errors });
    }
  };

  if (!isValidEmail(response.payerEmail)) {
    await response.retry({ payer: { email: 'Die E-Mail-Adresse ist ungültig.' } });
  }
  await response.complete('success');
  response.onpayerdetailchange = null; // Handler entfernen
};

Listener per AbortController wieder entfernen

const watchPayer = (response) => {
  const controller = new AbortController();

  response.addEventListener('payerdetailchange', () => {
    console.log('Name geändert auf:', response.payerName);
  }, { signal: controller.signal });

  // Später, z. B. nach complete(): Listener entfernen
  return () => controller.abort();
};

// Nutzung:
// const stop = watchPayer(response);
// await response.complete('success');
// stop();

Name geändert auf: Erika Musterfrau

// Wichtig · Fallstricke

Browser-Unterstützung: Die Payment Request API wird nicht überall unterstützt. Chromium-Browser und Safari unterstützen sie, Firefox nur hinter einem Flag. Das Ereignis selbst ist noch uneinheitlicher umgesetzt. Die Unterstützung vorher prüfen, z. B. mit 'onpayerdetailchange' in PaymentResponse.prototype, und immer einen normalen Bezahlablauf als Ausweichlösung anbieten.
Sicherer Kontext: Die API funktioniert nur über HTTPS (bzw. localhost). Ohne Weiteres ist sie auch nicht in iframes nutzbar, dafür braucht es allow=\"payment\".
Das Ereignis wird nur für angeforderte Angaben ausgelöst (requestPayerName, requestPayerEmail, requestPayerPhone). Nicht angeforderte Eigenschaften sind null.
In der Praxis wird das Ereignis fast nur während eines laufenden retry() ausgelöst. Nach complete() kommt es nicht mehr.
Eine Prüfung im Browser ersetzt nicht die Prüfung auf dem Server. Angaben zum Zahler sind Benutzereingaben und müssen auf dem Server erneut geprüft werden.
Nicht verwechseln: Änderungen an Adresse oder Versandoption lösen shippingaddresschange bzw. shippingoptionchange am PaymentRequest aus, nicht am PaymentResponse.

Siehe auch

PaymentRequest: paymentmethodchange PaymentRequest: shippingoptionchange PaymentRequest: shippingaddresschange AudioSession: statechange BatteryManager: levelchange