Ablauf einer Verifikation

Stand: 18. August 2026

Eine Verifikation ist eine einzelne Frage an eine einzelne Wallet, mit begrenzter Lebensdauer. Sie gehört zu deinem Konto, trägt deine eigene Referenz und endet in genau einem Zustand.

Die vier Schritte

  1. Dein Server erstellt die Verifikation. Er nennt das Prüfprofil und optional eine eigene Referenz. Zurück kommen ID, Einweg-Token, Deeplink und Ablaufzeitpunkt.
  2. Deine Seite zeigt QR-Code oder Wallet-Button. Sie arbeitet nur mit ID und Einweg-Token, nie mit deinem API-Schlüssel.
  3. Die Kundin bestätigt in der Wallet. Sie sieht vorher, was abgefragt wird, und kann ablehnen.
  4. Dein Server holt das Ergebnis – per Statusabfrage oder Webhook – und gibt die Bestellung frei.

Schritt 4 ist der einzige, der zählt. Die Anzeige in Schritt 2 kann man manipulieren; sie dient dem Menschen vor dem Bildschirm, nicht deiner Entscheidung.

Die vier Zustände

Status Bedeutung
PENDING Erstellt, noch nicht beantwortet. Ausgangszustand.
SUCCESS Die Wallet hat geantwortet und der Nachweis war gültig.
FAILED Die Prüfung ist gescheitert – abgelehnt, ungültig oder nicht erfüllt.
EXPIRED Niemand hat innerhalb der Lebensdauer geantwortet.

Ein Endzustand ist endgültig. Eine abgelaufene Prüfung wird nicht wieder PENDING, und ein zweiter Versuch ist eine neue Verifikation mit neuer ID.

Status und Ergebnis sind zwei Dinge

status beschreibt den Verlauf, satisfied das Ergebnis:

  • SUCCESS + satisfied: true – die Bedingung ist erfüllt. Nur hier gibst du frei.
  • SUCCESS + satisfied: false – die Wallet hat sauber geantwortet, aber die Bedingung ist nicht erfüllt. Technisch fehlerfrei, inhaltlich ein Nein.
  • FAILED – satisfied ist false oder null; in failure_reason steht, woran es lag.
  • PENDING, EXPIRED – satisfied ist null.

Frag deshalb immer beide Felder ab. Der häufigste Integrationsfehler ist, nur auf status zu schauen.

Lebensdauer

Eine Verifikation läuft nach kurzer Zeit ab. Das ist Absicht: ein Deeplink, der tagelang gültig bleibt, ist ein Deeplink, den man weitergeben kann.

Daraus folgt eine Regel für die Einbindung: erstelle die Verifikation erst, wenn die Kundin sie braucht – also beim Öffnen des Prüfdialogs, nicht beim Aufbau der Kassenseite. Wer sie zu früh erstellt, hat sie bei einem langsam ausgefüllten Formular schon verloren, bevor jemand den QR-Code ansieht. Das Widget nimmt dafür einen createSession-Rückruf; siehe Widget.

Die eigene Referenz

client_reference ist ein freies Textfeld, das unverändert zurückkommt – dein Haken, um eine Prüfung deiner Bestellung zuzuordnen. Eine Bestellnummer ist richtig, eine E-Mail-Adresse falsch.

Setz dort keine Personendaten hinein. Der Rest des Systems ist darauf ausgelegt, keine zu kennen; dieses Feld ist die einzige Stelle, an der du welche hineintragen könntest, und dann stünden sie in unserer Datenbank. Siehe Datensparsamkeit.