• Eine Sitzung ist ab Erstellung 15 Minuten gültig. Das ist ein zusammenhängendes Zeitfenster für das Öffnen des Links, Dokumentprüfungen, Überprüfung und Freigabe; es beginnt nach MRZ, NFC oder Selfie nicht erneut.
• Wenn die mobile Verifikation eine Sicherheitsabfrage benötigt, ist sie bis zu 10 Minuten gültig, aber nie über den Sitzungsablauf hinaus. iOS und Android verwenden dieselbe vom Backend ausgegebene Ablaufzeit und eine Sicherheitsmarge von 15 Sekunden.
• Erstelle eine neue Sitzung, wenn expires_at erreicht ist. Verwende keine abgelaufene Launch-URL, keinen QR-Code und kein Callback-Token erneut.

• app: Anzeigename der Partner-App in Verihop (max. 80 Zeichen).
• header: kurzer Verifikationstitel für den Nutzer (max. 120 Zeichen).
• fields: angefragte Feldtokens; leer/fehlend fällt auf legalName und over18 zurück.
• callback: Basis-Rücksprung-URL aus POST /v1/sessions. Verihop öffnet sie nach Abschluss und ergänzt session_id, result_token (Success Path) und optional callback_jwt; erforderlich und gegen deine Produktions-Allowlist validiert.

• Authorization: Partner-API-Key im Bearer-Format.
• Content-Type: nutze application/json für Request-Body-Parsing.
• Idempotency-Key: Retry-Key für Create-Session-Dedupe; sende UUID v4/v7 und nutze ihn nur für Retries derselben Payload.

{
  "session_id": "sess_123",
  "expires_at": 1730000000,
  "launch_url": "https://www.verihop.com/verify.html?session_id=sess_123&token=h_abc123",
  "app_clip_url": "https://appclip.apple.com/id?p=KycBox.VerifyBox.Clip&session_id=sess_123&token=h_abc123",
  "qr_url": "https://www.verihop.com/verify.html?session_id=sess_123&token=h_abc123",
  "status_url": "https://api.verihop.com/v1/sessions/sess_123"
}

• session_id: eindeutige Session-ID für Tracking und Ergebnisabruf.
• expires_at: Ablaufzeit der Session (Unix Epoch Seconds).
• launch_url: primäre URL für Web, Android, QR-Codes, E-Mail, SMS und allgemeine Handoffs.
• app_clip_url: direkte native App-Clip-URL für iOS-Partnerapps. Öffne sie exakt wie zurückgegeben und rekonstruiere sie nicht.
• qr_url: QR-sichere URL; aktuell identisch mit launch_url.
• status_url: Session-Status-Endpunkt für serverseitiges Polling.

• 401 missing_bearer_token, 401 invalid_api_key
• 403 customer_inactive
• 400 missing_callback_url, invalid_callback_url, callback_host_not_allowed
• 400 field_not_allowed, invalid_field_token, request_too_large
• 409 idempotency_key_conflict, idempotency_key_in_progress
• 429 rate_limit_exceeded, daily_quota_exceeded

{
  "session_id": "sess_123",
  "status": "issued",
  "issued_at": 1730000000,
  "expires_at": 1730000300,
  "last_status": null,
  "last_status_at": null,
  "opened_at": null,
  "result_available": false,
  "result_token_expires_at": null
}

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "kid_2025_01",
      "alg": "RS256",
      "use": "sig",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

{
  "session_id": "sess_123",
  "status": "success",
  "result": {
    "legalName": "Jane Doe",
    "over18": "yes"
  }
}

• 401 missing_bearer_token, invalid_api_key, missing_result_token
• 403 customer_mismatch, invalid_result_token
• 410 result_token_expired
• 409 result_token_used
• 404 result_not_available, session_not_found

legalName, dateOfBirth, over18, over21, passport, idCard, documentNumber, documentExpiry, documentCountry, documentNationality

Das Ergebnis enthält nur die angefragten unterstützten Felder, die der Nutzer freigegeben hat. Anforderungen an Dokumentarten wie passport und idCard schließen nicht automatisch jedes Dokumentattribut ein.

Ja. Dein Backend erstellt eine Sitzung mit POST /v1/sessions und rendert die zurückgegebene qr_url als QR-Code auf der Desktopseite. Der Nutzer scannt den QR-Code mit dem Telefon und Verihop öffnet die bestmögliche Erfahrung.

Die beste UX ist ein direkter Start: Kodiere die zurückgegebene qr_url. Sie ist dieselbe universelle HTTPS-Übergabe wie launch_url und unterstützt App-, schlanke und Web-Fallbackpfade.

Verwende launch_url auf Android und für allgemeine Web-Handoffs. Eine iOS-Partnerapp, die die native App-Clip-Karte anzeigen möchte, öffnet die zurückgegebene app_clip_url. Die Callback-Struktur bleibt gleich: Verihop ergänzt session_id, im Erfolgsfall result_token und optional callback_jwt.

Erstelle die Session auf deinem Backend und sende die zurückgegebene app_clip_url an deine iOS-App. Öffne diese URL unter iOS 17 oder neuer mit SwiftUI Link oder UIApplication.open. Parse launch_url nicht, kopiere den Token nicht und hardcode die App-Clip-Bundle-ID von Verihop nicht. Ist die vollständige Verihop-App installiert, öffnet iOS stattdessen diese mit derselben Session.

Wenn du einen Custom Callback wie ridenow://verified nutzt, muss die Android-Partnerapp einen Intent Filter für dieses Scheme und diesen Host deklarieren. Wenn du für Desktop- oder Web-gestartete Flows einen https:// Callback nutzt, behandle ihn als Backend-Endpunkt, außer deine Android-App besitzt diese Domain über verifizierte App Links.

Nutze einen https:// Callback-Endpunkt auf deinem Backend. Nach Abschluss durch Verihop erhält dein Server session_id und result_token und ruft anschließend GET /v1/sessions/{id}/result serverseitig ab.

Nein. Dieser Token ist für Verihop bestimmt. Partner behandeln ihn als opaque Transportdaten und nutzen launch_url, um Verihop zu starten.

Callback-Queryparameter sind nur Transportmetadaten. Verifizierte personenbezogene Daten werden bewusst nicht in Callback-URLs gesendet. Dein Backend muss den einmaligen result_token austauschen, um die result Payload sicher abzurufen. Falls aktiviert, kann callback_jwt über JWKS zur Callback-Authentizität verifiziert werden.

Ja, auf dem Partnerbackend, wenn vorhanden. Verifiziere Signatur und Claims mit Verihop JWKS unter GET /.well-known/jwks.json. Prüfe Issuer, Audience und Expiry und stelle sicher, dass JWT-Claims zu den Callback-Querywerten passen.

Nein. API-Keys bleiben serverseitig und Ergebnisse werden nur über dein Backend abgerufen. Der Frontend/Web-Client sollte nur UI anzeigen und State an deine Backend-Session weitergeben.

Erstelle eine neue Session, wenn eine Session abläuft oder der Nutzer den Flow abbricht. result_token ist kurzlebig und einmalig verwendbar; wenn er verwendet wurde oder abgelaufen ist, starte mit einem neuen POST /v1/sessions neu.

Stelle hinter deinem QR-Flow eine Fallback-Seite bereit, die erklärt, wie Verihop installiert oder geöffnet wird und wie es danach weitergeht. Erstelle nach der Installation eine neue Session und zeige einen frischen QR-Code; verwende keine veralteten Sessions erneut.

POST /v1/sessions unterstützt Idempotency-Key für retry-sichere Create-Session-Aufrufe: gleicher Key plus gleiche Payload spielt die ursprüngliche Antwort erneut aus, während gleicher Key plus andere Payload 409 idempotency_key_conflict zurückgibt. Missbrauch wird zusätzlich durch API-Key-Auth, Callback-Allowlist, Field-Allowlist-Prüfungen, kundenspezifische Rate Limits/Quota, kurze Session-TTL und einmalige result_token begrenzt.