PaymentResponse.retry() — Methode · JavaScript-Referenz

Signatur

PaymentResponse.prototype.retry(errorFields)

Beschreibung

Mit retry() kann eine Web-Anwendung auf eine bereits abgesendete, aber ungültige oder abgelehnte Zahlung reagieren, ohne den ganzen Bezahlvorgang abzubrechen. Das zugehörige Zahlungsfenster des Browsers bleibt offen (bzw. wird wieder aktiviert) und zeigt die übergebenen Fehlermeldungen direkt an den betroffenen Feldern an, zum Beispiel an einer ungültigen E-Mail-Adresse oder einer Lieferadresse, an die nicht geliefert werden kann.

Man übergibt ein Objekt vom Typ PaymentValidationErrors. Darin stehen eine allgemeine Fehlermeldung (error) sowie feldbezogene Meldungen für payer (name, email, phone), shippingAddress (z. B. addressLine, city, postalCode, country) und paymentMethod. Das zurückgegebene Promise wird erfüllt, sobald der Benutzer die korrigierten Daten erneut absendet. Anschließend enthält dasselbe PaymentResponse-Objekt die aktualisierten Werte. Die Anwendung prüft diese Werte dann noch einmal und ruft entweder erneut retry() oder zum Schluss complete() auf.

Typischerweise baut man um die Prüfung eine Schleife: Man prüft die Antwort (clientseitig oder beim Server), ruft retry() mit den Fehlern auf, solange es noch Fehler gibt, und schließt den Vorgang am Ende mit complete("success") oder complete("fail") ab.

Parameter

Name	Typ	Default	Beschreibung
$errorFields	PaymentValidationErrors	{}	Objekt mit Fehlermeldungen: `error` (allgemeine Meldung, `string`), `payer` (`{ name, email, phone }`), `shippingAddress` (`{ addressLine, city, country, dependentLocality, organization, phone, postalCode, recipient, region, sortingCode }`) sowie `paymentMethod` (von der jeweiligen Zahlungsart abhängiges Objekt). Alle Werte sind für den Benutzer lesbare Texte.

Rückgabewert

Typ

Promise<void>

Beschreibung

Wird erfüllt, sobald der Benutzer die korrigierten Daten erneut absendet. Das PaymentResponse-Objekt enthält dann die neuen Werte. Wird mit AbortError abgelehnt, wenn der Benutzer abbricht, und mit InvalidStateError, wenn complete() schon aufgerufen wurde oder bereits ein retry() läuft.

Beispiele

Ungültige E-Mail-Adresse korrigieren lassen

const methods = [{ supportedMethods: 'https://bobbucks.dev/pay' }];
const details = {
  total: { label: 'Summe', amount: { currency: 'EUR', value: '19.99' } }
};

const checkout = async () => {
  const request = new PaymentRequest(methods, details, { requestPayerEmail: true });
  const response = await request.show();

  // So lange wiederholen, bis die E-Mail gültig ist
  while (!response.payerEmail?.includes('@')) {
    await response.retry({
      payer: { email: 'Bitte gib eine gültige E-Mail-Adresse ein.' }
    });
  }

  await response.complete('success');
  console.log('Bezahlt von', response.payerEmail);
};

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

Bezahlt von kunde@example.com

Serverseitige Prüfung mit Wiederholungsschleife

// Server liefert z. B. { ok: false, errors: { shippingAddress: { postalCode: '…' } } }
const validateOnServer = async (response) => {
  const res = await fetch('/api/payments/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(response.toJSON())
  });
  return res.json();
};

const processPayment = async (request) => {
  const response = await request.show();
  try {
    let result = await validateOnServer(response);
    while (!result.ok) {
      await response.retry(result.errors);
      result = await validateOnServer(response);
    }
    await response.complete('success');
  } catch (err) {
    if (err.name === 'AbortError') {
      console.log('Benutzer hat die Zahlung abgebrochen.');
    } else {
      await response.complete('fail');
      console.error(err);
    }
  }
};

Lieferadresse und allgemeine Meldung kombinieren

const response = await request.show();

if (response.shippingAddress?.country !== 'DE') {
  await response.retry({
    error: 'Wir liefern derzeit nur innerhalb Deutschlands.',
    shippingAddress: {
      country: 'Bitte wähle eine Adresse in Deutschland.'
    }
  });
}

await response.complete('success');

// Wichtig · Fallstricke

Reihenfolge beachten: retry() geht nur vor complete(). Danach führt der Aufruf zu einem InvalidStateError. Auch ein zweiter retry()-Aufruf, bevor das erste Promise erfüllt ist, ist nicht erlaubt.
Abbruch abfangen: Schließt der Benutzer das Zahlungsfenster, wird das Promise mit AbortError abgelehnt. Diesen Fall immer mit try/catch behandeln.
Die Fehlertexte werden dem Benutzer direkt angezeigt. Sie sollten verständlich und lokalisiert sein und keine internen Details wie Stacktraces oder Fehlercodes des Zahlungsdienstleisters enthalten.
Die clientseitige Prüfung ersetzt nicht die Prüfung auf dem Server. Die endgültige Prüfung der Zahlung muss immer auf dem Server stattfinden.
Ändert der Benutzer beim erneuten Versuch seine Kontaktdaten, löst PaymentResponse das Event payerdetailchange aus.
Kompatibilität: Die Methode funktioniert nur in sicheren Kontexten (HTTPS). Chromium-Browser und Safari unterstützen sie, Firefox standardmäßig nicht. Vorher mit 'retry' in PaymentResponse.prototype prüfen, ob sie vorhanden ist, und sonst mit complete('fail') und einem neuen PaymentRequest weitermachen.

Siehe auch

new IntersectionObserverEntry() PaymentResponse.toJSON() PaymentResponse.complete() PaymentRequest.abort() PaymentRequest.show()