PaymentResponse.complete() — Methode · JavaScript-Referenz

Signatur

PaymentResponse.prototype.complete(result)

Beschreibung

complete() ist der letzte Schritt eines Ablaufs mit der Payment Request API. Nachdem PaymentRequest.show() mit einer PaymentResponse erfüllt wurde, schickt die Seite die Zahlungsdaten meist an den eigenen Server oder an einen Zahlungsdienstleister. Sobald das Ergebnis vorliegt, ruft man complete() auf. Damit weiß der Browser, dass die Interaktion vorbei ist, und schließt noch geöffnete Zahlungsdialoge.

Mit dem Parameter result kann der Browser Erfolg oder Misserfolg anzeigen, etwa mit einer kurzen Bestätigung oder einer Fehlermeldung. Wie das genau aussieht, hängt vom Browser ab. Manche Browser zeigen gar keinen Unterschied an.

Die Methode gibt ein Promise zurück. Es wird erfüllt, sobald die Oberfläche geschlossen ist. Erst dann sollte man auf eine Bestätigungsseite weiterleiten oder die eigene Oberfläche aktualisieren. Pro PaymentResponse darf complete() nur einmal aufgerufen werden.

Parameter

Name	Typ	Default	Beschreibung
$result	"success" \| "fail" \| "unknown"	"unknown"	Ergebnis der Zahlungsverarbeitung. `"success"`: Zahlung erfolgreich. `"fail"`: Zahlung fehlgeschlagen, der Browser kann einen Fehler anzeigen. `"unknown"`: kein Status angegeben, der Browser zeigt keinen Hinweis an.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald die Zahlungsoberfläche geschlossen ist. Es wird mit einer DOMException abgelehnt, z. B. mit InvalidStateError, wenn die Zahlung schon abgeschlossen ist oder retry() gerade läuft, oder mit AbortError, wenn die Anfrage abgebrochen wurde.

Beispiele

Einfacher Bezahlablauf mit Server-Prüfung

const methods = [{ supportedMethods: 'https://google.com/pay', data: { /* Konfiguration */ } }];
const details = {
  total: { label: 'Gesamt', amount: { currency: 'EUR', value: '19.99' } }
};

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

  try {
    const res = await fetch('/api/pay', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(response.toJSON())
    });
    // Status an die Zahlungsoberfläche melden
    await response.complete(res.ok ? 'success' : 'fail');
    if (res.ok) location.href = '/danke';
  } catch (err) {
    await response.complete('fail');
    console.error('Zahlung fehlgeschlagen:', err);
  }
};

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

Erst retry() bei ungültigen Daten, dann complete()

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

  // Ungültige Daten korrigieren lassen, solange nötig
  while (!response.payerEmail?.includes('@')) {
    await response.retry({ payer: { email: 'Bitte eine gültige E-Mail-Adresse angeben.' } });
  }

  const ok = await sendToServer(response);
  await response.complete(ok ? 'success' : 'fail');
  return ok;
};

const sendToServer = async (response) => {
  const res = await fetch('/api/pay', {
    method: 'POST',
    body: JSON.stringify(response.toJSON())
  });
  return res.ok;
};

Doppelten Aufruf erkennen

const finish = async (response) => {
  await response.complete('success');
  try {
    await response.complete('success'); // zweiter Aufruf
  } catch (err) {
    console.log(err.name);
  }
};

InvalidStateError

// Wichtig · Fallstricke

Zeitlimit: Wenn complete() nach show() zu lange nicht aufgerufen wird, kann der Browser die Oberfläche selbst schließen. Die Server-Anfrage sollte daher zügig beantwortet werden.
Nur einmal aufrufbar: Ein zweiter Aufruf oder ein Aufruf während eines laufenden retry() führt zu InvalidStateError.
Keine Garantie für die Anzeige: \"success\" und \"fail\" sind nur Hinweise an den Browser. Eigene Rückmeldungen auf der Seite sind trotzdem nötig.
Sicherheit: Ob eine Zahlung erfolgreich war, muss immer der Server beim Zahlungsdienstleister prüfen. Der Status in complete() dient nur der Anzeige.
Kompatibilität: Die API funktioniert nur über HTTPS. Chromium-Browser und Safari unterstützen sie, Firefox nicht standardmäßig. Vorher mit 'PaymentRequest' in window prüfen und einen herkömmlichen Checkout als Ausweichlösung anbieten.

Siehe auch

new PaymentMethodChangeEvent() PaymentResponse.retry() PaymentResponse.toJSON() PaymentRequest.abort() Response.clone()