KYB-Integration: Architektur, Muster und Leitfaden

Dieser Leitfaden ergänzt die Schnellstartanleitung. Er beschreibt die Architektur, alle Integrationsentscheidungen und die betrieblichen Muster, mit denen KYB in der Produktion zuverlässig läuft.

Architektur

Authentifizierung

Alle Anfragen benötigen den Header x-api-key mit dem API-Schlüssel Ihrer Anwendung. Informationen zur Schlüsselrotation, zur Trennung der Umgebungen und zu Scopes finden Sie unter API-Authentifizierung.

Sitzung erstellen

Es gibt einen einzigen Endpoint: POST /v3/session/. Der Typ des Workflows bestimmt, ob es sich um eine KYC- oder eine KYB-Sitzung handelt. Ein eigenes Flag „business“ ist nicht erforderlich. Empfohlene Felder beim Erstellen:

Feld	Zweck
`workflow_id`	Erforderlich. Verweist auf Ihren KYB-Workflow.
`vendor_data`	Ihre Kennung für das Unternehmen. Verknüpft die Sitzung mit einer Unternehmens-Entität.
`callback_url`	Optional. Ziel, an das der Benutzer nach Abschluss weitergeleitet wird.
`expected_details`	Optional. `{ company_name, registry_country, registration_number }`. Befüllt die Suche im Unternehmensregister vor: Das Gründungsland wird vorausgewählt und gesperrt (`registry_country` als `XX` oder `XX-YY` für Register auf Bundesstaatsebene, z. B. `US-CA`), die Felder für Firmenname und Registernummer werden vorausgefüllt, und die vorgegebene Suche läuft automatisch. Sind beide Kennungen vorhanden, werden sie kombiniert. Es handelt sich nur um eine Vorausfüllung. Abweichungen erzeugen keine Warnungen.
`metadata`	Optional. JSON-Daten, die der Sitzung angehängt werden.

Vollständiges Schema: Sitzung erstellen.

Gehosteten Link bereitstellen

Die Antwort url ist ein gehosteter Verifizierungslink. Für die Zustellung stehen folgende Möglichkeiten zur Verfügung:

Senden Sie ihn von Ihrer eigenen Plattform per E-Mail.
Betten Sie ihn als Link in Ihre Onboarding-Oberfläche ein.
Öffnen Sie ihn in einer In-App-WebView (iOS, Android oder React Native).

Sie können die gehostete Erfahrung anpassen, also Logo, Farbe, Domain und E-Mail-Vorlagen, über White-Label.

Polling oder Webhooks

Webhooks sind das empfohlene Muster. Didit sendet Abschlussereignisse per POST an Ihren abonnierten Endpoint, sobald die Verarbeitung abgeschlossen ist. Polling wird während der Entwicklung oder dann unterstützt, wenn Ihr Webhook-Endpoint nicht erreichbar ist:

Fragen Sie GET /v3/session/{id}/decision/ mit exponentiellem Backoff ab (zunächst alle 10 Sekunden, maximal alle 60 Sekunden).
Beenden Sie das Polling, sobald status einen der Werte "Approved", "Declined" oder "In Review" hat.

Polling mit hoher Frequenz kann die Rate-Limits auslösen. Verwenden Sie in der Produktion immer Webhooks.

Webhook-Verarbeitung

Abonnieren Sie die Ereignisse, die für Sie relevant sind. Dieselben Ereignisse gelten für KYC und KYB. Im Payload kennzeichnet session_kind: "business" die Ereignisse von Unternehmenssitzungen:

status.updated: Der Status der Sitzung hat sich geändert. Filtern Sie nach session_kind === "business" für KYB-Sitzungen.
data.updated: Ein Prüfer hat Registerdaten oder Schlüsselpersonen in der Business Console bearbeitet, oder das Register hat eine Änderung gemeldet. Dieses Ereignis wird nicht gesendet, wenn der Antragsteller ein Dokument hochlädt oder Schlüsselpersonen einreicht. Verwenden Sie dafür status.updated. Derselbe Filter für session_kind gilt.
business.status.updated und business.data.updated: Die verknüpfte Unternehmens-Entität hat sich geändert.

Vollständiger Ereigniskatalog: KYB-Webhooks. Signaturprüfung und Wiederholungslogik: Webhook-Referenz.

Entscheidungen verarbeiten

switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}

Das vollständige Zustandsmodell finden Sie unter KYB-Status. Die Tags, die eine Entscheidung erklären, sind unter KYB-Warnungen beschrieben.

Ablauf bei erneuter Einreichung

Wenn eine Sitzung zur Unternehmensverifizierung (KYB) in den Status Resubmitted übergeht oder eine Funktion zur erneuten Einreichung markiert wird, muss das Unternehmen korrigierte oder zusätzliche Daten hochladen. Sie haben folgende Möglichkeiten:

Erneut übermitteln: Senden Sie dieselbe url noch einmal. Der gehostete Ablauf setzt dort an, wo eine erneute Einreichung nötig ist.
Ungültigen Link für eine Schlüsselperson neu ausstellen: Eine Person, deren untergeordnete KYC-Sitzung gelöscht wurde oder abgelaufen ist, bevor die Person sie begonnen hatte, erhält mit Schlüsselpersonen-KYC-Sitzung neu erzeugen eine neue Sitzung.
Einen Fall in der Business Console öffnen, um die Abstimmung intern nachzuverfolgen.

Schritte über Ihr eigenes Frontend ausführen

Die Schritte für Dokumente und Schlüsselpersonen lassen sich auch serverseitig mit Ihrem API-Schlüssel steuern. So behalten Sie die Benutzeroberfläche, und Didit übernimmt die Verifizierung und die Entscheidung. Jeder Aufruf bezieht sich auf die KYB-Sitzung und benötigt die Berechtigung write:businesses. Beim Lesen der ermittelten Beteiligten sind auch read:businesses oder read:sessions zulässig. Die Aufrufe führen dieselben Prüfungen und Abrechnungen durch und rücken den Workflow wie die gehostete Seite um denselben Schritt weiter.

Laden Sie die Unternehmensdokumente hoch, während sich die Sitzung im Schritt „KYB-Dokumente“ befindet.
Lesen Sie die Beteiligten aus den Dokumenten inklusive Gesellschafter und Eigentumsanteilen aus, und zeigen Sie sie Ihrem Antragsteller an.
Erstellen, bearbeiten und löschen Sie Entwürfe für Beteiligte. Ein Entwurf gilt nicht als gemeldet und verursacht keine Kosten.
Reichen Sie die Entwürfe ein. Didit entscheidet, welche Beteiligten verifiziert werden müssen, erstellt für jeden eine KYC-Sitzung und gibt deren kyc_session_url zurück, damit Sie sie senden oder einbetten können.
Lesen Sie die zusammengefasste Entscheidung aus der Sitzung aus, wie beim gehosteten Ablauf.

Ein Aufruf, während die Sitzung sich in einem anderen Schritt befindet, antwortet mit 409 kyb_step_mismatch und dem aktuellen Schritt. Eine abgeschlossene Sitzung liefert 409 kyb_session_not_writable zurück.

Aggregation des Unternehmensprofils

Wenn Sie beim Erstellen der Sitzung vendor_data übergeben, fasst Didit alle Sitzungen dieses Unternehmens in einer einzigen Unternehmens-Entität zusammen. Mit der Map features der Entität beantworten Sie die Frage „Ist dieses Unternehmen jetzt vollständig verifiziert?“, ohne Sitzungen durchlaufen zu müssen. Vorteile:

Periodische erneute KYB-Prüfungen werden demselben Profil hinzugefügt.
Transaktionen, die mit demselben vendor_data überwacht werden, enthalten den Risikokontext des Unternehmens.
UBOs und Organmitglieder, die mit Benutzer-Entitäten verknüpft sind, bilden Beziehungen über Entitäten hinweg ab.

Bewährte Vorgehensweisen

Praxis	Warum
Übergeben Sie immer `vendor_data`	Ohne dieses Feld ist die Sitzung verwaist und kann nicht aggregiert werden.
Verwenden Sie Webhooks statt Polling	Geringere Latenz, keine Belastung des Rate-Limits.
Prüfen Sie Webhook-Signaturen	Verhindert gefälschte Webhook-Ereignisse.
Speichern Sie die `session_id` auf Ihrer Seite	Sie wird benötigt, um die Entscheidung abzurufen und PDFs zu erzeugen.
Versehen Sie Sitzungen mit `metadata`	Vereinfacht Reporting und Fehlersuche.
Richten Sie einen Test-Workflow ein	Verwenden Sie vor dem Produktivbetrieb einen Sandbox-Workflow für Integrationstests.

Fehlerbehandlung

Szenario	Antwort
Ungültige `workflow_id`	`400 Bad Request`
Doppelte Sitzung mit demselben `vendor_data`	Erstellt eine neue Sitzung. Das ist so vorgesehen, da eine erneute Verifizierung erwartet wird.
Land des Unternehmens liegt außerhalb der im Workflow zulässigen Länder	Die Unternehmensregisterprüfung löst die Warnung `KYB_COUNTRY_RESTRICTED` aus.
Ausfall des Unternehmensregisteranbieters während der Unternehmenssuche	`POST /v3/kyb/search/` gibt `502` mit `code: "kyb_registry_provider_unavailable"` zurück. Nicht abgerechnet. Wiederholen Sie den Versuch oder verzweigen Sie anhand von `code`, um die manuelle Eingabe des Unternehmens anzubieten. Im gehosteten Ablauf von Didit wird das Unternehmen automatisch zur manuellen Eingabe weitergeleitet, anstatt eines Fehlers, der ausschließlich einen Wiederholungsversuch zulässt. Siehe KYB-Registersuche.
Rate-Limit	`429 Too Many Requests` mit `Retry-After`-Header.

Vollständige Referenz zu Rate-Limits.

Nächste Schritte

Webhooks

Alle KYB-Ereignisse und Payloads.

Status

Referenz zum Zustandsautomaten.

Antwortschema

Dekodierung der KYB-Entscheidung.

Erste Schritte

Funktionen

Unternehmensprofile

Referenz

Konsole

KYB-Integration: Architektur, Muster und Leitfaden

Architektur

Authentifizierung

Sitzung erstellen

Gehosteten Link bereitstellen

Polling oder Webhooks

Webhook-Verarbeitung

Entscheidungen verarbeiten

Ablauf bei erneuter Einreichung

Schritte über Ihr eigenes Frontend ausführen

Aggregation des Unternehmensprofils

Bewährte Vorgehensweisen

Fehlerbehandlung

Nächste Schritte

Webhooks

Status

Antwortschema

​Architektur

​Authentifizierung

​Sitzung erstellen

​Gehosteten Link bereitstellen

​Polling oder Webhooks

​Webhook-Verarbeitung

​Entscheidungen verarbeiten

​Ablauf bei erneuter Einreichung

​Schritte über Ihr eigenes Frontend ausführen

​Aggregation des Unternehmensprofils

​Bewährte Vorgehensweisen

​Fehlerbehandlung

​Nächste Schritte

Webhooks

Status

Antwortschema

Architektur

Authentifizierung

Sitzung erstellen

Gehosteten Link bereitstellen

Polling oder Webhooks

Webhook-Verarbeitung

Entscheidungen verarbeiten

Ablauf bei erneuter Einreichung

Schritte über Ihr eigenes Frontend ausführen

Aggregation des Unternehmensprofils

Bewährte Vorgehensweisen

Fehlerbehandlung

Nächste Schritte