Checkify
Entwicklerdokumentation

Überprüfen Sie in Ihrem Backend

Nachdem die Browser-Einbettung abgeschlossen ist, muss Ihr Server das Ergebnis mit einem Site-API-Schlüssel überprüfen, bevor er die Anmeldung, den Checkout oder eine geschützte Aktion zulässt.

Serververifizierung in 5 Minuten

  1. Fügen Sie das Checkify Browser-Einbettungsmodul zu Ihrer Seite hinzu.
  2. Der Embed startet die Checkify-Sitzung und schreibt die Verifizierungsreferenz in Ihr Formular.
  3. Ihr Backend liest den Wert des versteckten Feldes.
  4. Ihr Backend sendet diesen Wert als request_id an POST /v1/qr/results/verify.
  5. Wenn die erforderlichen Ansprüche genehmigt werden, gestatten Sie die geschützte Handlung.
  6. Vertrauen Sie niemals allein dem Frontend-Status.

Das versteckte Formularfeld kann zwar den Namen checkify_token tragen, sein Wert ist jedoch die Checkify request_id.

End-to-End-Ablauf

1. Erstellen Sie einen Site-API-Schlüssel

Öffnen Sie in Ihrem Unternehmens-Dashboard Entwickler und erstellen Sie einen Site-API-Schlüssel für die Site, die Sie integrieren. Speichern Sie es nur in Serverumgebungsvariablen – senden Sie es niemals an den Browser.

Verwendung des Frontends SDK?

Sie müssen GET /v1/qr/pass/{PASS_ID}/start nicht manuell aufrufen. Die Checkify JavaScript-Einbettung startet die Sitzung, empfängt die request_id und schreibt sie automatisch in Ihr Formular.

Ihr Backend muss lediglich Folgendes leisten:

2. Empfangen Sie die request_id auf Ihrem Server.

Das Frontend SDK schreibt die Checkify-Anfrage-ID nach Abschluss der Benutzerverifizierung in ein verstecktes Formularfeld. Der Standardfeldname lautet checkify_token – dies ist der Feldname, kein separater Token-Typ. Senden Sie den Feldwert als Anfrage-ID an den Verifizierungsendpunkt.

Bei der Übergabe einer mobilen App kann die URL `checkify_request_id` enthalten. SDK liest diese beim Laden der Seite aus; Ihr Server überprüft weiterhin denselben Wert für `request_id`.

Formular POST von Ihrem Frontend

{
  "email": "user@example.com",
  "checkify_token": "56a57761-ff5b-42f0-9c97-6c13e223e017"
}

Überprüfen Sie die Anfrage von Ihrem Backend.

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "required_fields": [],
  "consume": true
}

Nur manuelle Frontend-Integration

3. Manuelles Testen mit cURL

Backend-Entwickler rufen `/start` normalerweise nicht auf. Verwenden Sie diesen Abschnitt nur beim Erstellen eines benutzerdefinierten Frontends oder beim Testen ohne Einbettung. Setzen Sie URLs in zsh/bash in Anführungszeichen, damit das Fragezeichen nicht als Glob interpretiert wird.

Für /start wird der Origin-Header benötigt.

Der Befehl „Pass start“ funktioniert nur von einer registrierten Website-Domain. Browser senden den Ursprung automatisch; cURL hingegen nicht. Senden Sie den Ursprung (oder die X-Checkify-Site-Url) mit einem Hostnamen, der unter „Websites → Zulässige Domains“ aufgeführt ist. Der Hostname muss exakt übereinstimmen – checkify.me und www.checkify.me sind unterschiedlich.

Häufigstes Testproblem

Wenn /start den HTTP-Statuscode 403 zurückgibt, ist Ihre Pass-ID möglicherweise trotzdem gültig. Die übliche Ursache ist, dass die angeforderte Domain nicht in der Liste der zulässigen Domains aufgeführt ist oder dass www.example.com zwar registriert, aber example.com verwendet wurde (oder umgekehrt).

Verwenden Sie eine dedizierte Testumgebung und geben Sie „Pass“ in Ihrem Checkify-Dashboard für Integrationstests ein. Site-API-Schlüssel verwenden das Präfix „csk_“; es gibt kein separates Testschlüsselformat. Testen Sie erst dann mit der Produktionsumgebung, wenn Sie sowohl erfolgreiche als auch fehlerhafte Abläufe bestätigt haben.

# Step A — start a session (replace PASS_ID and YOUR_REGISTERED_DOMAIN)
curl -sS \
  -H "Accept: application/json" \
  -H "Origin: https://YOUR_REGISTERED_DOMAIN" \
  "https://checkify.me/v1/qr/pass/chk_live_YOUR_PASS_ID/start?request_type=human"

# Response includes request_id and qr_url — open qr_url and complete verification

# Step B — verify on your server (after the user completes verification)
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "PASTE_request_id_FROM_STEP_A",
    "required_claims": ["human_verified"],
    "consume": true
  }'

Verwenden Sie Ihren API-Schlüssel ausschließlich beim Verifizierungsanruf. Schließen Sie die Verifizierung in der App ab, bevor Sie den Verifizierungsanruf tätigen – andernfalls erhalten Sie den Status „Ausstehend“.

Erforderliche Ansprüche pro Anwendungsfall

Legen Sie die erforderlichen Ansprüche so fest, dass sie dem Nachweis entsprechen, den Ihre geschützte Aktion benötigt. Die Anspruchsnamen müssen mit den von Checkify für diese Verifizierungssitzung genehmigten Namen übereinstimmen. Altersprüfungen verwenden age_over_{N} (z. B. age_over_18). Dynamische Schwellenwerte von 10 bis 110 werden unterstützt, wenn die Einbettung den entsprechenden Anfragetyp anfordert.

Anwendungsfall Vorgeschlagene erforderliche Ansprüche Anmerkungen
Bot / CAPTCHA Ersatz ["human_verified"] Bestätigt, dass ein echter Benutzer den Checkify-Workflow abgeschlossen hat.
Inhalte ab 13 Jahren oder Produkte für Jugendliche ["age_over_13"] Verwenden Sie diese Option, wenn Ihr Pass ein Alter über 13 Jahren erfordert.
Inhalte ab 16 Jahren oder regionale Altersbestimmungen ["age_over_16"] Verwenden Sie diese Option, wenn Ihr Pass eine Altersangabe über 16 Jahren erfordert.
Vape, Alkohol oder Kasse für Artikel ab 18 Jahren ["age_over_18"] Passen Sie die Altersgrenze an Ihr Produkt und Ihren Markt an.
Produkte, die nur für Personen ab 21 Jahren geeignet sind (sofern zutreffend). ["age_over_21"] Verwenden Sie diese Option, wenn Ihr Pass ein Alter über 21 Jahren erfordert.
Herausforderung 25 oder strengere Einzelhandelspolitik ["age_over_25"] Verwenden Sie diese Option, wenn Ihr Pass eine Altersangabe über 25 Jahren erfordert.
Benutzerdefinierte Altersgrenze ["age_over_N"] Verwenden Sie age_over_N, wobei N zwischen 10 und 110 liegt, entsprechend Ihrem Einbettungsanforderungstyp.

Einbettungsanfragetyp → Serveranspruch

Der Browser-Anfragetyp muss mit der serverseitig überprüften Behauptung übereinstimmen.

Einbettungsanfragetyperforderliche Ansprüche
human["human_verified"]
age_over_13["age_over_13"]
age_over_16["age_over_16"]
age_over_18["age_over_18"]
age_over_21["age_over_21"]
age_over_25["age_over_25"]
age_over_N["age_over_N"] (N = 10–110)

Optionale Pflichtfelder

Neben required_claims können Sie bestimmte genehmigte Identitätsfelder verlangen (z. B. Land oder Altersband), wenn Ihre Integration sie erfasst hat. Übergeben Sie Feldnamen in required_fields — fehlen sie im genehmigten Ergebnis, liefert verify missing_required_fields mit missing_fields in error.details.

4. Rufen Sie den Anruf auf Ihrem Server an, um die Anrufbestätigung zu erhalten.

Rufen Sie POST /v1/qr/results/verify mit Ihrem API-Schlüssel auf, bevor Sie Zugriff gewähren. Behandeln Sie die Browserreferenz (request_id oder Legacy-Poll-Token) als nicht vertrauenswürdig, bis Checkify das Ergebnis bestätigt hat.

POST https://checkify.me/v1/qr/results/verify
Authorization: Bearer YOUR_SITE_API_KEY
Content-Type: application/json

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "consume": true
}

Sie können auch senden token anstatt request_id. Der Schlüssel API ist auf Ihre Checkify-Site beschränkt – Sie senden die site_id nicht im Anfragetext.

Implementierungsbeispiele

# checkify_token from your form POST is sent as request_id
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
    "required_claims": ["human_verified"],
    "consume": true
  }'

Wann sollte man verbrauchen?

Verwenden Sie consume: true für endgültige geschützte Aktionen — Bezahlvorgang, Registrierung, Passwort zurücksetzen, Kauf mit Altersbeschränkung, Zugriff auf geschützte Inhalte

Verwenden Sie consume: false nur für — Testen, Debuggen oder nicht finale Prüfungen, bei denen das Ergebnis später erneut überprüft werden muss.

Bei regulierten oder risikoreichen Aktionen sollte „consume: true“ bevorzugt werden, damit dasselbe Verifizierungsergebnis nicht für mehrere geschützte Entscheidungen wiederverwendet werden kann.

Fehler aufgrund regulierter Aktionen geschlossen

Falls Ihr Backend Checkify nicht erreichen kann, erlauben Sie keine altersbeschränkten Bezahlvorgänge, keinen Zugriff auf Glücksspiele, keinen Zugriff auf Inhalte für Erwachsene, keinen Kauf von E-Zigaretten oder Alkohol oder andere geschützte Aktionen ohne ein bestätigtes serverseitiges Ergebnis.

Verwenden Sie kurze HTTP-Timeouts (z. B. 10 Sekunden). Versuchen Sie bei vorübergehenden 5xx-Fehlern oder Netzwerkfehlern ein- bis zweimal, den Zugriff zu verweigern und protokollieren Sie Vorfälle serverseitig mit benutzerfreundlichen Meldungen. Geben Sie interne GLO_6-Fehlerdetails nicht an Kunden weiter.

try {
  const verdict = await verifyCheckifyResult(requestId);

  if (!verdict.allow) {
    return res.status(403).json({ error: "Verification required" });
  }

  // Continue protected action
} catch (err) {
  console.error("Checkify verification unavailable", err);

  return res.status(403).json({
    error: "Verification is temporarily unavailable. Please try again.",
  });
}

Server SDKs und Tools

The Checkify monorepo includes @checkify/server (Node.js) and checkify-server (Python) packages for server-side verify calls. There is no published OpenAPI spec or Postman collection yet — use the examples on this page and POST /v1/qr/results/verify directly.

@checkify/server v1.0.0 ist auf npm veröffentlicht. Das Python-Paket checkify-server ist im Checkify SDK Monorepo enthalten.

Ablaufdatum des Ergebnisses

Abgeschlossene Verifizierungen verfallen nach QR_RESULT_MAX_AGE_SECONDS (standardmäßig 900 Sekunden / 15 Minuten). Nach Ablauf dieser Frist gibt die Überprüfung „result_expired“ zurück und fordert den Benutzer zur erneuten Verifizierung auf.

Statusabfrage-Endpunkte (benutzerdefinierte Frontends)

Die Klassen JavaScript und SDK verwalten den Sitzungsstatus für Standard-Einbettungen. Verwenden Sie diese nur, wenn Sie ein benutzerdefiniertes Frontend erstellen, das manuell GET /v1/qr/pass/{pass_id}/start aufruft.

Antwortverarbeitung

Bei Erfolg gibt Checkify den HTTP-Statuscode 200 mit success: true und status: completed zurück. Der Zugriff wird nur gewährt, wenn die erforderlichen Angaben vorhanden sind (z. B. human_verified: true).

{
  "success": true,
  "status": "completed",
  "message": "Verification result confirmed",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "site_id": "YOUR_SITE_ID",
  "business_id": "YOUR_BUSINESS_ID",
  "approved_claims": {
    "human_verified": true
  },
  "approved_fields": [],
  "signed_result": {
    "payload": { "...": "..." },
    "signature": "...",
    "signature_algorithm": "EdDSA",
    "key_id": "checkify:default"
  }
}

Signiertes Ergebnis

Das Objekt signed_result ermöglicht Ihrem Backend einen manipulationssicheren Audit-Eintrag, dass Checkify den erforderlichen Claim zum Verifizierungszeitpunkt genehmigt hat. Die meisten Integrationen benötigen nur approved_claims. Regulierte oder risikoreiche Unternehmen können signed_result zusätzlich speichern. Verschachteltes proof_metadata kann kryptografische oder operative Nachweise enthalten (z. B. Assurance-Metadaten, Evidence-Typen oder Consent-Hashes) — keine Ausweisdokumente und kein rohes Geburtsdatum. Behandeln Sie verschachtelte Assurance-Felder nicht als Zertifizierung oder Vertrauensgarantie; prüfen Sie certification_status und Ihre eigene Richtlinie. Speichern Sie nicht mehr personenbezogene Daten als nötig.

Wenn der Kunde die Anwendung noch nicht abgeschlossen hat, gibt Checkify den HTTP-Statuscode 200 mit „success: false“ und „status: pending“ zurück. Geschützte Aktionen werden verweigert und der Benutzer zur Verifizierung aufgefordert.

{
  "success": false,
  "status": "pending",
  "message": "Verification is not completed yet",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "approved_claims": {},
  "signed_result": null
}
FeldBedeutung
successtrue wenn die Verifizierung abgeschlossen ist und Anforderungen senden übereinstimmend
statuscompleted oder pending
approved_claimsAnsprüche Checkify genehmigt, z.B. human_verified: true
signed_resultOptional signierte Nutzlast für Audit-Trails

JSON Fehlernutzlasten

Wenn die Verifizierung fehlschlägt, gibt Checkify einen HTTP-4xx/5xx-Fehler mit einem strukturierten JSON-Body zurück. Prüfen Sie den Fehlercode und protokollieren Sie die Fehlerdetails serverseitig. Geben Sie allgemeine Fehlermeldungen an die Endbenutzer zurück.

{
  "success": false,
  "error": {
    "code": "verification_failed",
    "message": "The verification did not include all required claims.",
    "details": {
      "missing_claims": ["age_over_18"]
    }
  }
}
Code HTTP Bedeutung Empfohlene Maßnahmen
missing_authorization401Es wurde kein Autorisierungsheader gesendet.Send Authorization: Bearer YOUR_SITE_API_KEY ausschließlich vom serverseitigen Code.
invalid_token401Bearer-Token fehlt, ist fehlerhaft oder kein gültiger Site-API-Schlüssel.Überprüfen Sie den Schlüssel in Ihrem Business-Dashboard und speichern Sie ihn in den Umgebungsvariablen.
expired_token401Der Website-Schlüssel API wurde widerrufen.Erstellen Sie einen neuen Site-Schlüssel API und wechseln Sie ihn regelmäßig auf Ihren Servern.
missing_required_field400 / 422Im JSON-Body fehlt die request_id oder das Token.Übergeben Sie die request_id aus Ihrem versteckten Formularfeld oder das Poll-Token, falls Ihre Integration dieses noch verwendet.
invalid_request_id400Die Referenz konnte nicht analysiert werden oder ist nach der Normalisierung leer.Stellen Sie sicher, dass Ihr Frontend die Checkify request_id unverändert übermittelt.
result_not_found404Für diese Referenz existiert keine Verifizierungsanfrage.Die Aktion wird abgelehnt. Der Benutzer hat möglicherweise das versteckte Feld manipuliert oder eine alte Sitzung übermittelt.
result_expired410Die Überprüfung ist zu lange her, um dieser Maßnahme noch vertrauen zu können.Bitten Sie den Benutzer, erneut zu scannen und die Überprüfung mit der neuen request_id aufzurufen.
verification_failed403 / 409Site-/Business-Mismatch, bereits verbrauchtes Ergebnis (HTTP 409) oder ein allgemeiner Verifizierungsfehler.Zugriff verweigern. error.details prüfen. Bei Claim-/Feldlücken siehe missing_required_claims und missing_required_fields.
missing_required_claims403developers_server.err_missing_required_claims_meaningdevelopers_server.err_missing_required_claims_action
missing_required_fields403developers_server.err_missing_required_fields_meaningdevelopers_server.err_missing_required_fields_action
unknown_required_attributes400developers_server.err_unknown_required_attributes_meaningdevelopers_server.err_unknown_required_attributes_action
business_not_operational403Das Geschäftskonto ist gesperrt, archiviert oder nicht betriebsbereit.Wenden Sie sich an den Geschäftsinhaber oder den GLO_6-Support. Geschützte Aktionen sind erst nach der Aktivierung des Kontos zulässig.
validation_errors422Der JSON-Body konnte das Schema nicht validieren (HTTP 422).Prüfen Sie error.details.validation_errors auf Meldungen auf Feldebene. Korrigieren Sie die Datentypen request_id, required_claims oder required_fields, bevor Sie es erneut versuchen.
rate_limited429Zu viele Verifizierungsanrufe in einem kurzen Zeitraum.Wiederholen mit exponentiellem Backoff. Überprüfung nur bei geschützten Aktionen, nicht bei jedem Seitenaufruf.
server_error500+Die Überprüfung durch Checkify konnte aufgrund eines vorübergehenden Serverproblems nicht abgeschlossen werden.Versuchen Sie es ein- oder zweimal erneut, schließen Sie dann den Fehler und protokollieren Sie den Vorfall.

Webhooks und asynchrone Verifizierung

Die Serververifizierung erfolgt heute synchron: Ihr Backend überprüft die request_id, sobald der Nutzer die geschützte Aktion absendet. Dies ist die empfohlene Vorgehensweise für Checkout-, Registrierungs- und Zugriffskontrollprozesse. Allgemeine Verifizierungs-Webhooks sind für Standardintegrationen nicht erforderlich. GoHighLevel und andere Partnerintegrationen können separate ausgehende Webhook-Konfigurationen im Business-Dashboard verwenden.

Häufige Fehler

Sicherheitserinnerung

Behandeln Sie das ausgeblendete Feld als nicht vertrauenswürdige Referenz, nicht als Beweis. Überprüfen Sie immer den API-Schlüssel Ihrer Website auf dem Server, bevor Sie Zugriff gewähren. Verwenden consume: true für einmalige Aktionen wie Anmeldung oder Passwort-Zurücksetzung.

Nächste Schritte