Cycle de vie des sessions KYB : statuts et webhooks (FR-1)

Une vérification KYB n'est pas une simple réponse oui/non — c'est un processus avec des éléments en mouvement. La recherche dans le registre peut être approuvée instantanément tandis que la vérification de documents est en attente d'une nouvelle soumission et que l'AML de l'entité est en cours d'examen en attente d'un analyste. Pour intégrer KYB de manière propre, vous devez savoir exactement dans quel état se trouve chaque partie d'une vérification, et vos systèmes doivent se mettre à jour dès que l'un de ces états change. C'est à cela que servent le cycle de vie de la session et les webhooks.

L'API de vérification d'entreprise de Didit expose la machine d'état complète : un statut sur la session globale, un statut sur chaque fonctionnalité, un ensemble distinct de statuts pour l'entité commerciale une fois qu'elle est gérée, et des webhooks qui se déclenchent à chaque changement. La vérification complète de l'entreprise coûte 2,00 $, et ce guide décrit l'intégralité du cycle de vie — chaque statut, chaque webhook et l'API de gestion qui les relie.

Points clés à retenir

• Trois couches d'état. Une vérification KYB a un statut de session, des statuts par fonctionnalité, et — une fois gérée — un statut d'entité commerciale.
• Huit statuts de session. NOT_STARTED (non démarré), IN_PROGRESS (en cours), APPROVED (approuvé), DECLINED (refusé), IN_REVIEW (en révision), RESUBMITTED (resoumis), ABANDONED (abandonné), EXPIRED (expiré).
• Six statuts de fonctionnalité pour chacune des quatre fonctionnalités KYB : NOT_FINISHED (non terminé), APPROVED (approuvé), DECLINED (refusé), IN_REVIEW (en révision), RESUB_REQUESTED (resoumission demandée), AWAITING_USER (en attente de l'utilisateur).
• Trois statuts d'entité sous gestion : ACTIVE (actif), FLAGGED (signalé), BLOCKED (bloqué).
• Des webhooks sur tout. status.updated et data.updated (avec session_kind: business) pour les sessions ; business.status.updated et business.data.updated pour les entités gérées.
• Une API de gestion complète — POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, PATCH .../update-status/.

Ce que couvre le cycle de vie KYB

Une vérification KYB produit un état à trois niveaux, et chacun répond à une question différente :

• La session répond à la question « comment se déroule la vérification dans l'ensemble ? »
• Chaque fonctionnalité répond à la question « où en est le registre / l'AML de l'entreprise / les documents / la vérification des personnes clés ? »
• L'entité commerciale répond à la question « quel est le statut opérationnel de cette entreprise dans notre système actuellement ? »

Vous lisez les trois, et vous les maintenez synchronisés avec des webhooks plutôt qu'avec du polling. Une vérification commence comme une session, résout ses fonctionnalités, aboutit à un résultat global, puis — une fois que vous commencez à gérer l'entreprise — porte un statut d'entité commerciale que vous contrôlez à mesure que les circonstances changent.

Pourquoi c'est important

Sans un état granulaire, l'intégration KYB se dégrade en conjectures : un simple drapeau « en attente » ne vous dit rien sur quelle vérification retarde les choses ou quelle action la débloquerait. Avec des statuts par fonctionnalité, vous pouvez acheminer précisément — demander au demandeur de resoumettre un document, mettre en file d'attente une correspondance AML d'entité pour examen par un analyste, inviter un UBO à terminer son KYC — au lieu d'échouer toute la vérification.

Les webhooks sont importants car le KYB est asynchrone. Les données de registre, l'OCR de documents et les résultats de filtrage arrivent à des moments différents, et l'examen humain prend encore plus de temps. Le polling des changements est inefficace et lent ; les webhooks poussent le changement au moment où il se produit, de sorte que vos enregistrements reflètent la réalité sans qu'une tâche cron ne martèle l'API.

Détails techniques

Une session KYB est créée via l'API unifiée /v3/ et signale son état de cycle de vie.

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"
  }'

Un webhook status.updated contient le statut de la session et les statuts par fonctionnalité :

{
  "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"
  }
}

Statuts de session. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.

Statuts des fonctionnalités. Chacun des kyb_registry, kyb_company_aml, kyb_documents et kyb_key_people rapporte l'un des statuts suivants : NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.

Webhooks. Pour les sessions : status.updated (changements de cycle de vie) et data.updated (données enrichies), tous deux portant session_kind: "business". Pour les entités gérées : business.status.updated et business.data.updated.

Prix. 2,00 $ par vérification d'entreprise.

Gestion de l'entité commerciale

Une fois qu'une entreprise est vérifiée, elle devient une entité que vous gérez via l'API des entreprises :

• POST /v3/businesses/create/ — enregistrer une entité commerciale.
• GET /v3/businesses/ — lister les entreprises gérées.
• GET /v3/businesses/{vendor_data}/ — récupérer une entreprise par sa référence vendor_data.
• PATCH .../update-status/ — modifier le statut de l'entité.

L'entité porte son propre statut, indépendant de la session de vérification : ACTIVE (en règle), FLAGGED (en cours d'examen pour un signal de risque), ou BLOCKED (suspendue). C'est la couche opérationnelle — une entreprise peut compléter une session APPROVED et être ensuite FLAGGED parce que la surveillance a révélé quelque chose. Les changements apportés à l'entité émettent business.status.updated et business.data.updated afin que les systèmes en aval restent à jour.

Le cycle de vie, de bout en bout

Une vérification typique parcourt les couches dans l'ordre. La session s'ouvre à NOT_STARTED, passe à IN_PROGRESS à mesure que les fonctionnalités s'exécutent, et chaque fonctionnalité se résout — registre APPROVED, documents peut-être RESUB_REQUESTED jusqu'à ce qu'un téléchargement propre arrive, AML de l'entreprise IN_REVIEW jusqu'à ce qu'un analyste valide une correspondance, personnes clés APPROVED. Lorsque chaque fonctionnalité est réglée, la session aboutit à APPROVED, DECLINED ou IN_REVIEW. À partir de là, l'entreprise entre en gestion en tant qu'entité ACTIVE, et son statut peut ensuite passer à FLAGGED ou BLOCKED selon ce que dicte la surveillance continue — chaque transition vous est transmise par webhook.

Cas d'utilisation

• Les places de marché acheminent précisément les vendeurs : resoumettre un document, terminer le KYC d'un UBO, ou retenir une correspondance AML d'entité — sans faire échouer l'ensemble de l'intégration.
• Les plateformes de fintech et bancaires maintiennent les enregistrements de comptes d'entreprise synchronisés avec des webhooks au lieu de sonder, et signalent ou bloquent les entités à mesure que les risques changent.
• Les fournisseurs de prêts suivent le statut de chaque vérification de souscription et mettent à jour le statut de l'emprunteur via l'API de gestion.
• Les plateformes Crypto B2B maintiennent un cycle de vie auditable de chaque entité contrepartie, de la vérification à la situation actuelle.

Comment s'intégrer à Didit

1. Construire le workflow. Dans la console d'entreprise, créez un workflow KYB avec les fonctionnalités dont vous avez besoin.
2. Créer la session. POST /v3/session/ avec votre workflow_id KYB et une référence vendor_data.
3. S'abonner aux webhooks. Gérez status.updated et data.updated (session_kind: business) pour les sessions, et business.status.updated / business.data.updated pour les entités gérées.
4. Gérer les entités. Utilisez POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, et PATCH .../update-status/ pour maintenir chaque entreprise ACTIVE, FLAGGED ou BLOCKED.

Parce que tout est basé sur l'API unifiée /v3/, le même modèle de cycle de vie s'applique au KYC, au monitoring et au KYB — une machine d'état cohérente pour l'ensemble de la plateforme d'identité et de fraude.

Foire aux questions

Quels sont les statuts de session KYB ?

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

Quels statuts les fonctionnalités individuelles rapportent-elles ?

Chacune des fonctionnalités kyb_registry, kyb_company_aml, kyb_documents et kyb_key_people rapporte NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED ou AWAITING_USER.

À quels webhooks dois-je m'abonner ?

Pour les sessions, status.updated et data.updated (avec session_kind: business). Pour les entités commerciales gérées, business.status.updated et business.data.updated.

Comment modifier le statut d'une entreprise après vérification ?

Utilisez l'API de gestion — PATCH .../update-status/ — pour définir l'entité sur ACTIVE, FLAGGED ou BLOCKED.

Combien coûte une vérification KYB ?

2,00 $ par entreprise pour la vérification complète — registre, UBO, dirigeants et AML d'entité.

Prêt à commencer ?

Lisez l'aperçu de la vérification d'entreprise dans la documentation, voyez comment cela s'intègre au reste de la plateforme sur la page produit de la vérification d'entreprise, et consultez les tarifs transparents par appel sur la page des tarifs. Lorsque vous êtes prêt, commencez gratuitement — 500 vérifications KYC gratuites chaque mois, et vérification d'entreprise à 2,00 $ par entreprise.