Guide d'intégration KYB : architecture et modèles

Ce guide complète le démarrage rapide. Il couvre l’architecture, chaque décision d’intégration et les modèles opérationnels qui rendent la KYB fiable en production.

Architecture

Authentification

Toutes les requêtes exigent l’en-tête x-api-key avec la clé API de votre application. Consultez authentification API pour la rotation des clés, la séparation des environnements et les scopes.

Création de session

Un seul endpoint : POST /v3/session/. Le type du workflow détermine si la session est KYC ou KYB, sans qu’un indicateur « entreprise » explicite soit nécessaire. Champs recommandés à la création :

Champ	Rôle
`workflow_id`	Obligatoire : référence votre workflow KYB.
`vendor_data`	Votre identifiant de l’entreprise. Lie la session à une entité Business.
`callback_url`	Facultatif : URL vers laquelle rediriger l’utilisateur une fois le parcours terminé.
`expected_details`	Facultatif : `{ company_name, registry_country, registration_number }`. Pré-remplit la recherche dans le registre des sociétés : le pays de constitution est présélectionné et verrouillé (`registry_country` au format `XX`, ou `XX-YY` pour les registres à l’échelle des États, par exemple `US-CA`), les champs du nom de l’entreprise et du numéro d’immatriculation sont pré-remplis, et la recherche déclarée s’exécute automatiquement, en combinant les deux identifiants lorsque les deux sont présents. Pré-remplissage uniquement : les écarts ne génèrent pas d’avertissements.
`metadata`	Facultatif : JSON attaché à la session.

Schéma complet : créer une session.

Transmission du lien hébergé

La réponse url est un lien de vérification hébergé. Options de transmission :

Envoyez-le par e-mail depuis votre propre plateforme.
Intégrez-le à votre interface d’onboarding sous forme de lien.
Ouvrez-le dans une webview intégrée à l’application (iOS / Android / React Native).

Vous pouvez personnaliser l’expérience hébergée (logo, couleur, domaine, modèles d’e-mails) via Marque blanche.

Interrogation ou webhooks

Les webhooks constituent le modèle recommandé. Didit envoie les événements de fin de traitement, par requête POST, à l’endpoint auquel vous êtes abonné dès que le traitement se termine. L’interrogation (polling) est prise en charge pour le développement, ou lorsque votre endpoint de webhook est injoignable :

Interrogez GET /v3/session/{id}/decision/ avec un backoff exponentiel (toutes les 10 s au départ, jusqu’à 60 s).
Arrêtez l’interrogation lorsque status prend l’une des valeurs suivantes : "Approved", "Declined", "In Review".

L’interrogation à haute fréquence peut atteindre les limites de débit. Privilégiez toujours les webhooks en production.

Traitement des webhooks

Abonnez-vous aux événements qui vous intéressent : les mêmes événements couvrent les KYC et les KYB, avec session_kind: "business" dans le payload pour identifier les événements des sessions d’entreprise :

status.updated : le statut de la session a changé. Filtrez sur session_kind === "business" pour les sessions KYB.
data.updated : un relecteur a modifié les données du registre ou les personnes clés dans la console, ou le registre a signalé un changement. Cet événement n’est pas envoyé lorsque le candidat téléverse un document ou soumet les personnes clés : suivez status.updated dans ce cas. Le même filtre session_kind s’applique.
business.status.updated / business.data.updated : l’entité Business liée a changé.

Catalogue complet des événements : webhooks KYB. Vérification des signatures et comportement des nouvelles tentatives : référence des webhooks.

Gestion des décisions

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;
}

Consultez les statuts KYB pour la machine à états complète, et les avertissements KYB pour les tags qui expliquent une décision.

Flux de nouvelle soumission

Lorsqu’une session de Vérification d’entreprise (KYB) passe à Resubmitted (ou qu’une fonctionnalité est marquée pour nouvelle soumission), l’entreprise doit téléverser des données corrigées ou complémentaires. Vous pouvez :

Renvoyer la même url : le parcours hébergé reprend là où la nouvelle soumission est nécessaire.
Réémettre un lien de personne clé devenu invalide : une partie dont la session KYC enfant a été supprimée, ou a expiré avant que la personne ne la démarre, reçoit une nouvelle session via Régénérer la session KYC des personnes clés.
Ouvrir un dossier dans la Business Console pour suivre les allers-retours en interne.

Exécuter les étapes depuis votre propre interface

Les étapes des documents et des personnes clés peuvent aussi être pilotées depuis votre serveur, avec votre clé API : vous conservez l’interface utilisateur, et Didit conserve la vérification et la décision. Chaque appel est limité à la session KYB, nécessite la permission write:businesses (la lecture des parties extraites accepte aussi read:businesses ou read:sessions), et exécute les mêmes contrôles, la même facturation et la même progression d’étape que la page hébergée.

Téléversez les documents de la société pendant que la session se trouve à l’étape Documents KYB.
Lisez les parties nommées dans les documents, y compris les actionnaires et les pourcentages de détention, et présentez-les à votre candidat.
Créez, modifiez et supprimez des brouillons de parties. Un brouillon n’est pas déclaré et ne coûte rien.
Soumettez les brouillons. Didit détermine quelles parties doivent être vérifiées, crée une session KYC pour chacune et renvoie son kyc_session_url à transmettre ou à intégrer.
Lisez la décision consolidée depuis la session, comme pour le parcours hébergé.

Un appel effectué pendant que la session se trouve à une autre étape renvoie 409 kyb_step_mismatch avec l’étape en cours, et une session terminée renvoie 409 kyb_session_not_writable.

Agrégation du profil d’entreprise

Si vous transmettez vendor_data à la création de la session, Didit agrège toutes les sessions de cette entreprise dans une seule entité Business. Utilisez la carte features de l’entité pour savoir si cette entreprise est entièrement vérifiée actuellement, sans parcourir les sessions. Avantages :

Les flux de KYB périodiques (re-KYB) s’ajoutent au même profil.
Les transactions surveillées avec le même vendor_data portent le contexte de risque de l’entreprise.
Les UBO et dirigeants liés à des entités utilisateur alimentent les relations entre entités.

Bonnes pratiques

Pratique	Pourquoi
Transmettez toujours `vendor_data`	Sans lui, la session est orpheline et ne peut pas être agrégée.
Utilisez les webhooks plutôt que le polling	Latence plus faible, et aucune pression sur la limite de débit.
Vérifiez les signatures des webhooks	Empêche l’usurpation des événements.
Stockez le `session_id` de votre côté	Nécessaire pour récupérer la décision et générer les PDF.
Étiquetez les sessions avec `metadata`	Simplifie les rapports et le débogage.
Configurez un workflow de test	Utilisez un workflow sandbox pour les tests d’intégration avant la production.

Gestion des erreurs

Scénario	Réponse
`workflow_id` invalide	`400 Bad Request`
Session en double avec le même `vendor_data`	Crée une nouvelle session. C’est voulu, car une revérification est attendue.
Pays de l’entreprise hors des pays autorisés par le workflow	La vérification dans le registre déclenche l’avertissement `KYB_COUNTRY_RESTRICTED`.
Panne du fournisseur de registre pendant la recherche d’entreprise	`POST /v3/kyb/search/` renvoie `502` avec `code: "kyb_registry_provider_unavailable"`. La requête n’est pas facturée. Réessayez, ou traitez le `code` pour proposer la saisie manuelle de l’entreprise. Dans le parcours hébergé de Didit, l’entreprise est automatiquement dirigée vers la saisie manuelle, au lieu de renvoyer uniquement une erreur nécessitant une nouvelle tentative. Voir Recherche dans le registre KYB.
Limite de débit	`429 Too Many Requests` avec l’en-tête `Retry-After`.

Référence complète sur la limitation du débit.

Étapes suivantes

Webhooks

Chaque événement KYB et son payload.

Statuts

Référence de la machine à états.

Schéma de réponse

Décodage de la décision KYB.

Prise en main

Fonctionnalités

Profils d'entreprise

Référence

Console

Guide d'intégration KYB : architecture et modèles

Architecture

Authentification

Création de session

Transmission du lien hébergé

Interrogation ou webhooks

Traitement des webhooks

Gestion des décisions

Flux de nouvelle soumission

Exécuter les étapes depuis votre propre interface

Agrégation du profil d’entreprise

Bonnes pratiques

Gestion des erreurs

Étapes suivantes

Webhooks

Statuts

Schéma de réponse

​Architecture

​Authentification

​Création de session

​Transmission du lien hébergé

​Interrogation ou webhooks

​Traitement des webhooks

​Gestion des décisions

​Flux de nouvelle soumission

​Exécuter les étapes depuis votre propre interface

​Agrégation du profil d’entreprise

​Bonnes pratiques

​Gestion des erreurs

​Étapes suivantes

Webhooks

Statuts

Schéma de réponse

Architecture

Authentification

Création de session

Transmission du lien hébergé

Interrogation ou webhooks

Traitement des webhooks

Gestion des décisions

Flux de nouvelle soumission

Exécuter les étapes depuis votre propre interface

Agrégation du profil d’entreprise

Bonnes pratiques

Gestion des erreurs

Étapes suivantes