Der KYB-Sitzungslebenszyklus: Status und Webhooks (DE)

Eine KYB-Verifizierung ist keine einfache Ja/Nein-Antwort – sie ist ein Prozess mit vielen beweglichen Teilen. Die Registerprüfung kann sofort genehmigt werden, während die Dokumentenprüfung auf eine erneute Einreichung wartet und die AML-Prüfung der Entität in der Überprüfung durch einen Analysten hängen bleibt. Um KYB sauber zu integrieren, müssen Sie genau wissen, in welchem Zustand sich jeder Teil einer Verifizierung befindet, und Ihre eigenen Systeme müssen sich sofort aktualisieren, wenn sich einer dieser Zustände ändert. Dafür sind der Sitzungslebenszyklus und die Webhooks da.

Die Business Verification API von Didit legt den vollständigen Zustandsautomaten offen: einen Status der gesamten Sitzung, einen Status für jede Funktion, einen separaten Satz von Status für die Geschäftseinheit, sobald sie verwaltet wird, und Webhooks, die bei jeder Änderung ausgelöst werden. Die vollständige Unternehmensüberprüfung kostet 2,00 $, und dieser Leitfaden bildet den gesamten Lebenszyklus ab – jeden Status, jeden Webhook und die Management-API, die alles miteinander verbindet.

Wichtige Erkenntnisse

• Drei Status-Ebenen. Eine KYB-Verifizierung hat einen Sitzungsstatus, funktionsspezifische Status und – sobald verwaltet – einen Status der Geschäftseinheit.
• Acht Sitzungsstatus. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.
• Sechs Funktionsstatus für jede der vier KYB-Funktionen: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.
• Drei Entitätsstatus unter Verwaltung: ACTIVE, FLAGGED, BLOCKED.
• Webhooks für alles. status.updated und data.updated (mit session_kind: business) für Sitzungen; business.status.updated und business.data.updated für verwaltete Entitäten.
• Eine vollständige Management-API — POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, PATCH .../update-status/.

Was der KYB-Lebenszyklus abdeckt

Eine KYB-Verifizierung erzeugt Status auf drei Ebenen, und jede beantwortet eine andere Frage:

• Die Sitzung beantwortet „wie läuft die Verifizierung insgesamt ab?“
• Jede Funktion beantwortet „wo steht die Registerprüfung / Unternehmens-AML / Dokumente / Prüfung der Schlüsselpersonen?“
• Die Geschäftseinheit beantwortet „wie ist der operative Status dieses Unternehmens in unserem System derzeit?“

Sie lesen alle drei und halten sie mit Webhooks statt durch Polling synchron. Eine Verifizierung beginnt als Sitzung, löst ihre Funktionen auf, führt zu einem Gesamtergebnis und trägt dann – sobald Sie das Unternehmen verwalten – einen Status der Geschäftseinheit, den Sie bei sich ändernden Umständen kontrollieren können.

Warum es wichtig ist

Ohne detaillierten Status artet die KYB-Integration in Rätselraten aus: Eine einzige "ausstehend"-Markierung sagt Ihnen nichts darüber, welche Prüfung die Dinge aufhält oder welche Maßnahme sie freigeben würde. Mit funktionsspezifischen Status können Sie präzise steuern – den Antragsteller bitten, ein Dokument erneut einzureichen, eine Entitäts-AML-Übereinstimmung zur Überprüfung durch einen Analysten in die Warteschlange stellen, einen UBO auffordern, sein KYC abzuschließen – anstatt die gesamte Verifizierung scheitern zu lassen.

Webhooks sind wichtig, weil KYB asynchron ist. Registerdaten, Dokumenten-OCR und Screening-Ergebnisse kommen zu unterschiedlichen Zeiten an, und die menschliche Überprüfung dauert noch länger. Das Abfragen von Änderungen ist verschwenderisch und langsam; Webhooks pushen die Änderung sofort, wenn sie eintritt, sodass Ihre Aufzeichnungen die Realität widerspiegeln, ohne dass ein Cron-Job die API belastet.

Technische Details

Eine KYB-Sitzung wird über die vereinheitlichte /v3/ API erstellt und meldet ihren Lebenszyklusstatus zurück.

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "your_kyb_workflow_id",
    "vendor_data": "merchant_6601",
    "callback": "https://yourapp.com/kyb/callback"
  }'

Ein status.updated Webhook enthält den Sitzungsstatus und die Status pro Funktion:

{
  "event": "status.updated",
  "session_kind": "business",
  "session_id": "kyb_3a90f1c2",
  "vendor_data": "merchant_6601",
  "status": "IN_REVIEW",
  "features": {
    "kyb_registry": "APPROVED",
    "kyb_company_aml": "IN_REVIEW",
    "kyb_documents": "RESUB_REQUESTED",
    "kyb_key_people": "APPROVED"
  }
}

Sitzungsstatus. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.

Funktionsstatus. Jede von kyb_registry, kyb_company_aml, kyb_documents und kyb_key_people meldet einen der folgenden Status: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED oder AWAITING_USER.

Webhooks. Für Sitzungen: status.updated (Lebenszyklusänderungen) und data.updated (angereicherte Daten), beide mit session_kind: "business". Für verwaltete Entitäten: business.status.updated und business.data.updated.

Preis. 2,00 $ pro Unternehmensverifizierung.

Verwaltung der Geschäftseinheit

Sobald ein Unternehmen verifiziert ist, wird es zu einer Entität, die Sie über die Businesses API verwalten:

• POST /v3/businesses/create/ – eine Geschäftseinheit registrieren.
• GET /v3/businesses/ – verwaltete Unternehmen auflisten.
• GET /v3/businesses/{vendor_data}/ – ein Unternehmen anhand seiner vendor_data-Referenz abrufen.
• PATCH .../update-status/ – den Entitätsstatus ändern.

Die Entität trägt ihren eigenen Status, unabhängig von der Verifizierungssitzung: ACTIVE (in gutem Zustand), FLAGGED (unter Überprüfung wegen eines Risikosignals) oder BLOCKED (gesperrt). Dies ist die operative Ebene – ein Unternehmen kann eine APPROVED Sitzung abschließen und später FLAGGED werden, weil die Überwachung etwas aufgedeckt hat. Änderungen an der Entität senden business.status.updated und business.data.updated, damit nachgeschaltete Systeme auf dem neuesten Stand bleiben.

Der Lebenszyklus, von Anfang bis Ende

Eine typische Verifizierung durchläuft die Ebenen in der richtigen Reihenfolge. Die Sitzung beginnt mit NOT_STARTED, wechselt zu IN_PROGRESS, während die Funktionen ausgeführt werden, und jede Funktion wird aufgelöst – Register APPROVED, Dokumente vielleicht RESUB_REQUESTED, bis ein sauberer Upload eintrifft, Firmen-AML IN_REVIEW, bis ein Analyst eine Übereinstimmung freigibt, Schlüsselpersonen APPROVED. Wenn alle Funktionen abgeschlossen sind, landet die Sitzung bei APPROVED, DECLINED oder IN_REVIEW. Von dort aus wird das Unternehmen als ACTIVE Entität in die Verwaltung aufgenommen, und sein Status kann später zu FLAGGED oder BLOCKED wechseln, je nachdem, was die laufende Überwachung vorschreibt – jeder Übergang wird Ihnen per Webhook mitgeteilt.

Anwendungsfälle

• Marktplätze leiten Verkäufer präzise: ein Dokument erneut einreichen, das KYC eines UBO abschließen oder eine Übereinstimmung mit der Unternehmens-AML festlegen – ohne das gesamte Onboarding zu scheitern.
• Fintech- und Banking-Plattformen halten Unternehmens-Kontodatensätze mit Webhooks synchron, anstatt zu pollen, und markieren oder blockieren Entitäten, wenn sich das Risiko ändert.
• Kreditgeber verfolgen den Status jeder Underwriting-Prüfung und aktualisieren den Status des Kreditnehmers über die Management-API.
• Krypto B2B-Plattformen pflegen einen auditierbaren Lebenszyklus jeder Gegenparteientität von der Verifizierung bis zum laufenden Status.

So integrieren Sie sich in Didit

1. Workflow erstellen. Erstellen Sie in der Business Console einen KYB-Workflow mit den benötigten Funktionen.
2. Sitzung erstellen. POST /v3/session/ mit Ihrer KYB workflow_id und einer vendor_data Referenz.
3. Webhooks abonnieren. Behandeln Sie status.updated und data.updated (session_kind: business) für Sitzungen sowie business.status.updated / business.data.updated für verwaltete Entitäten.
4. Entitäten verwalten. Verwenden Sie POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/ und PATCH .../update-status/, um jedes Unternehmen ACTIVE, FLAGGED oder BLOCKED zu halten.

Da alles auf der vereinheitlichten /v3/ API basiert, gilt dasselbe Lebenszyklusmodell für KYC, Überwachung und KYB – ein konsistenter Zustandsautomat für die gesamte Identitäts- und Betrugsplattform.

Häufig gestellte Fragen

Was sind die KYB-Sitzungsstatus?

NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED und EXPIRED.

Welche Status melden einzelne Funktionen?

Jede der Funktionen kyb_registry, kyb_company_aml, kyb_documents und kyb_key_people meldet NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED oder AWAITING_USER.

Welche Webhooks sollte ich abonnieren?

Für Sitzungen: status.updated und data.updated (mit session_kind: business). Für verwaltete Geschäftsentitäten: business.status.updated und business.data.updated.

Wie ändere ich den Status eines Unternehmens nach der Verifizierung?

Verwenden Sie die Management-API – PATCH .../update-status/ – um die Entität auf ACTIVE, FLAGGED oder BLOCKED zu setzen.

Was kostet eine KYB-Verifizierung?

2,00 $ pro Unternehmen für die vollständige Verifizierung – Register, UBO, Verantwortliche und Unternehmens-AML.

Bereit, loszulegen?

Lesen Sie die Übersicht zur Unternehmensverifizierung in den Docs, sehen Sie, wie sie sich in den Rest der Plattform auf der Produktseite zur Unternehmensverifizierung einfügt, und prüfen Sie die transparenten Preise pro Anruf auf der Preisseite. Wenn Sie bereit sind, starten Sie kostenlos – 500 kostenlose KYC-Prüfungen jeden Monat und Unternehmensverifizierung für 2,00 $ pro Unternehmen.