PaymentRequest.securePaymentConfirmationAvailability() — Methode · JavaScript-Referenz

Signatur

PaymentRequest.securePaymentConfirmationAvailability()

Beschreibung

PaymentRequest.securePaymentConfirmationAvailability() ist eine statische Methode. Sie wird direkt auf PaymentRequest aufgerufen, nicht auf einer Instanz. Sie meldet, ob der Browser Secure Payment Confirmation (SPC) im aktuellen Dokument nutzen kann. SPC ist ein Verfahren für die starke Kundenauthentifizierung (SCA, etwa für 3-D Secure oder PSD2). Es baut auf WebAuthn auf: Der Nutzer bestätigt eine Zahlung in einem Browser-Dialog mit Biometrie oder Geräte-PIN.

Das zurückgegebene Promise wird mit einem der folgenden Strings erfüllt:

"available": SPC kann verwendet werden.
"unavailable-feature-not-enabled": Die Funktion ist im Browser deaktiviert oder wird nicht unterstützt.
"unavailable-no-permission-policy": Die Permissions Policy payment erlaubt SPC nicht, zum Beispiel in einem <iframe> ohne allow="payment".
"unavailable-no-user-verifying-platform-authenticator": Das Gerät hat keinen Plattform-Authenticator mit Nutzerverifikation, etwa Touch ID, Windows Hello oder einen Android-Fingerabdrucksensor.
"unavailable-unknown-reason": SPC ist aus einem anderen Grund nicht verfügbar. Browser dürfen diesen Wert auch aus Datenschutzgründen melden.

Rufen Sie die Methode auf, bevor Sie einen PaymentRequest mit supportedMethods: "secure-payment-confirmation" erzeugen. So können Sie gleich auf einen anderen Ablauf ausweichen, zum Beispiel eine klassische 3-D-Secure-Challenge oder ein Einmalpasswort per SMS, und müssen nicht erst auf eine fehlgeschlagene show()-Anzeige warten. Früher prüfte man die Verfügbarkeit über canMakePayment() auf einer SPC-Anfrage. Die neue Methode ist genauer, weil sie den Grund für die Nichtverfügbarkeit nennt.

Rückgabewert

Typ

Promise<string>

Beschreibung

Ein Promise, das mit einem der Werte "available", "unavailable-unknown-reason", "unavailable-feature-not-enabled", "unavailable-no-permission-policy" oder "unavailable-no-user-verifying-platform-authenticator" erfüllt wird.

Beispiele

Einfache Verfügbarkeitsprüfung mit Feature-Erkennung

const pruefeSpc = async () => {
  // Methode existiert nur in Browsern mit SPC-Unterstützung
  if (typeof PaymentRequest?.securePaymentConfirmationAvailability !== 'function') {
    return 'unavailable-feature-not-enabled';
  }
  return PaymentRequest.securePaymentConfirmationAvailability();
};

const status = await pruefeSpc();
console.log(`SPC-Status: ${status}`);

SPC-Status: available

Checkout: SPC nutzen oder auf 3-D-Secure-Challenge ausweichen

const authentifiziereZahlung = async ({ credentialId, challenge, betrag }) => {
  const status = typeof PaymentRequest?.securePaymentConfirmationAvailability === 'function'
    ? await PaymentRequest.securePaymentConfirmationAvailability()
    : 'unavailable-feature-not-enabled';

  if (status !== 'available') {
    console.warn(`SPC nicht nutzbar (${status}) – Fallback auf OTP-Challenge`);
    return { methode: 'otp' };
  }

  const request = new PaymentRequest(
    [{
      supportedMethods: 'secure-payment-confirmation',
      data: {
        credentialIds: [credentialId],
        challenge,
        rpId: 'bank.example',
        instrument: {
          displayName: 'Visa •••• 4242',
          icon: 'https://bank.example/card.png'
        },
        timeout: 60000
      }
    }],
    { total: { label: 'Gesamt', amount: { currency: 'EUR', value: betrag } } }
  );

  const response = await request.show();
  await response.complete('success');
  // Assertion zur Prüfung an den Server senden
  return { methode: 'spc', assertion: response.details };
};

SPC nicht nutzbar (unavailable-no-user-verifying-platform-authenticator) – Fallback auf OTP-Challenge

Gründe gezielt auswerten (z. B. im iframe)

const meldungen = {
  'available': 'Zahlung per Fingerabdruck/Gesichtserkennung möglich.',
  'unavailable-no-permission-policy': 'iframe benötigt allow="payment".',
  'unavailable-no-user-verifying-platform-authenticator': 'Kein Plattform-Authenticator auf diesem Gerät.',
  'unavailable-feature-not-enabled': 'Browser unterstützt SPC nicht.',
  'unavailable-unknown-reason': 'SPC derzeit nicht verfügbar.'
};

const status = await PaymentRequest.securePaymentConfirmationAvailability();
console.log(meldungen[status] ?? `Unbekannter Status: ${status}`);

iframe benötigt allow="payment".

// Wichtig · Fallstricke

Experimentell und eingeschränkt verfügbar: Die Methode gibt es derzeit nur in Chromium-basierten Browsern (in neueren Versionen). Firefox und Safari unterstützen SPC nicht. Prüfen Sie deshalb immer zuerst mit typeof PaymentRequest?.securePaymentConfirmationAvailability === 'function', ob sie existiert, sonst gibt es einen TypeError.
Sicherer Kontext: Die Payment Request API steht nur über HTTPS (oder localhost) zur Verfügung.
iframes: In eingebetteten Frames, etwa beim 3-D-Secure-Frame eines Zahlungsdienstleisters, muss das <iframe> das Attribut allow="payment" tragen. Sonst lautet das Ergebnis "unavailable-no-permission-policy".
"available" ist keine Erfolgsgarantie: Der Wert bedeutet nicht, dass für den Nutzer passende Zugangsdaten registriert sind. Die Anfrage mit show() kann trotzdem fehlschlagen, zum Beispiel mit NotAllowedError, wenn keine passende credentialId vorhanden ist oder der Nutzer abbricht. Planen Sie immer einen Fallback ein.
Datenschutz: Browser können aus Schutz vor Fingerprinting "unavailable-unknown-reason" melden, obwohl ein konkreterer Grund vorliegt. Verlassen Sie sich nicht auf einen bestimmten Grund-String.
Sicherheit: Die kryptografische Assertion aus der SPC-Antwort muss immer serverseitig geprüft werden: Challenge, Herkunft (Origin), Betrag und Signatur. Die Prüfung im Client reicht nicht aus.

Siehe auch

PaymentRequest.abort() PaymentRequest.getSecurePaymentConfirmationCapabilities() PaymentRequest.canMakePayment() PaymentRequest.show() PaymentRequestEvent.respondWith()