PaymentRequest.payerName — Eigenschaft · JavaScript-Referenz

Signatur

PaymentResponse.payerName

Beschreibung

payerName gehört eigentlich zum Interface PaymentResponse, nicht zu PaymentRequest. Die Eigenschaft ist aber nur im Zusammenspiel mit einem PaymentRequest sinnvoll: Man erhält die PaymentResponse als aufgelösten Wert von PaymentRequest.prototype.show(). Die Eigenschaft enthält den Namen, den der Nutzer im nativen Zahlungsdialog des Browsers eingegeben oder aus seinem gespeicherten Profil ausgewählt hat.

Einen Wert gibt es nur, wenn beim Erzeugen des Requests im Optionsobjekt requestPayerName: true gesetzt war. Andernfalls ist payerName immer null. Das ist bewusst so gestaltet: Der Browser gibt personenbezogene Daten nur heraus, wenn die Website ausdrücklich danach fragt und der Nutzer dem Dialog zustimmt.

Typische Einsatzfälle sind Bestellbestätigungen, Rechnungsadressierung oder das Anlegen eines Gastkontos ohne eigenes Formular. Oft wird die Eigenschaft zusammen mit payerEmail und payerPhone abgefragt. Wenn der Name nicht passt (zum Beispiel leer oder nur ein Wort, obwohl Vor- und Nachname nötig sind), kann man mit PaymentResponse.prototype.retry() und payerErrors.name eine Korrektur verlangen. Ändert der Nutzer daraufhin seine Angaben, wird das Ereignis payerdetailchange ausgelöst.

Rückgabewert

Typ

string | null

Beschreibung

Der vom Zahlenden angegebene Name als Freitext, zum Beispiel "Erika Mustermann". null, wenn requestPayerName nicht auf true gesetzt war.

Beispiele

Namen des Zahlenden anfordern und auslesen

const methods = [{ supportedMethods: 'https://google.com/pay', data: { /* Konfiguration des Anbieters */ } }];
const details = {
  total: { label: 'Gesamt', amount: { currency: 'EUR', value: '49.90' } }
};
// Ohne requestPayerName bleibt payerName null
const options = { requestPayerName: true, requestPayerEmail: true };

const buyButton = document.querySelector('#buy');
buyButton.addEventListener('click', async () => {
  const request = new PaymentRequest(methods, details, options);
  try {
    const response = await request.show();
    console.log(`Zahlung von: ${response.payerName}`);
    // ... Zahlung auf dem Server verarbeiten ...
    await response.complete('success');
  } catch (err) {
    console.error('Zahlung abgebrochen:', err.name);
  }
});

Zahlung von: Erika Mustermann

Namen prüfen und mit retry() korrigieren lassen

const isFullName = (name) => typeof name === 'string' && name.trim().split(/\s+/).length >= 2;

const validatePayer = async (response) => {
  while (!isFullName(response.payerName)) {
    // Der Browser zeigt den Fehler im Dialog an und wartet auf eine Korrektur
    await response.retry({
      payer: { name: 'Bitte Vor- und Nachnamen angeben.' }
    });
  }
  return response.payerName;
};

const request = new PaymentRequest(methods, details, { requestPayerName: true });
const response = await request.show();
const name = await validatePayer(response);
console.log('Gültiger Name:', name);
await response.complete('success');

Gültiger Name: Erika Mustermann

Auf Namensänderungen per payerdetailchange reagieren

const response = await request.show();

const onPayerChange = (event) => {
  // event.target ist die PaymentResponse
  console.log('Neuer Name:', event.target.payerName);
};

// Variante 1: addEventListener
response.addEventListener('payerdetailchange', onPayerChange);

// Variante 2: on-Property
// response.onpayerdetailchange = onPayerChange;

await response.retry({ payer: { name: 'Name unvollständig.' } });
response.removeEventListener('payerdetailchange', onPayerChange);
await response.complete('success');

Neuer Name: Erika Mustermann

// Wichtig · Fallstricke

Falsches Interface im Titel: Die Eigenschaft gibt es nur an PaymentResponse. request.payerName an einem PaymentRequest ist undefined.
Nur mit Optin: Ohne requestPayerName: true ist der Wert immer null. Prüfe deshalb vor der Weiterverarbeitung auf null.
Freitext ohne feste Struktur: Der Name ist nicht in Vor- und Nachname aufgeteilt und wird nicht geprüft. Vor dem Speichern bereinigen und beim Ausgeben im DOM mit textContent statt innerHTML einsetzen, um XSS zu vermeiden. Auf dem Server muss der Wert zusätzlich validiert werden.
Datenschutz: Es handelt sich um personenbezogene Daten. Frage sie nur ab, wenn du sie wirklich brauchst, und beachte die DSGVO.
Kompatibilität: Die Payment Request API ist nur in sicheren Kontexten (HTTPS) verfügbar. Chromium-Browser und Safari unterstützen sie. Firefox hat sie nicht standardmäßig aktiviert. Prüfe die Unterstützung vorab mit 'PaymentRequest' in window und biete ein normales Formular als Ausweichlösung an. In iframes ist zusätzlich das Attribut allow=\"payment\" nötig.

Siehe auch

PaymentRequest.id PaymentRequest.shippingType PaymentRequest.shippingAddress PaymentRequest.shippingOption PaymentResponse.payerEmail