Le cycle de vie d'une session KYB : statuts et webhooks

Une vérification KYB n'est pas une simple réponse oui/non — c'est un processus avec des éléments évolutifs. La consultation du registre peut être approuvée instantanément tandis que la vérification des documents attend une nouvelle soumission et que l'AML de l'entité est en cours d'examen en attente d'un analyste. Pour intégrer proprement le KYB, vous devez connaître l'état exact de chaque partie d'une vérification, et vos propres 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 sous gestion, et des webhooks qui se déclenchent à chaque changement. La vérification complète de l'entreprise est de 2,00 $, et ce guide décrit l'ensemble du cycle de vie — chaque statut, chaque webhook et l'API de gestion qui les lie.

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, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.
• Six statuts de fonctionnalité sur chacune des quatre fonctions KYB : NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.
• Trois statuts d'entité sous gestion : ACTIVE, FLAGGED, BLOCKED.
• 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 à « comment se déroule la vérification dans l'ensemble ? »
• Chaque fonctionnalité répond à « où en est la vérification du registre / de l'AML de l'entreprise / des documents / des personnes clés ? »
• L'entité commerciale répond à « 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 au fur et à 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 bloque les choses ou quelle action pourrait la débloquer. Avec des statuts par fonctionnalité, vous pouvez acheminer précisément — demander au demandeur de soumettre à nouveau 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 de faire é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 pour les 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 rend compte de l'état de son 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 de fonctionnalité. 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 (sous examen pour un signal de risque), ou BLOCKED (suspendue). Il s'agit de la couche opérationnelle — une entreprise peut terminer une session APPROVED et être ensuite FLAGGED parce que la surveillance a détecté 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 au fur et à 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 toutes les fonctionnalités sont réglées, 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 par la suite passer à FLAGGED ou BLOCKED selon les exigences de la surveillance continue — chaque transition vous étant transmise par webhook.

Cas d'utilisation

• Les places de marché acheminent précisément les vendeurs : soumettre à nouveau 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 lorsque 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é de 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 sur l'API unifiée /v3/, le même modèle de cycle de vie s'applique au KYC, à la surveillance et au KYB — une machine d'état cohérente pour toute la plateforme d'identité et de fraude.

Questions fréquemment posées

Quels sont les statuts de session KYB ?

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

Quels statuts rapportent les fonctionnalités individuelles ?

Chacun des 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.

Quel est le coût d'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, découvrez comment cela s'intègre au reste de la plateforme sur la page produit de 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 la vérification d'entreprise à 2,00 $ par entreprise.