> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Statuts de vérification : cycle de vie et codes de session

> Tous les statuts de session Didit expliqués : approuvé, refusé, en cours d'examen, expiré, soumis à nouveau, abandonné, KYC expiré. Gérez décisions et webhooks.

Chaque session de vérification passe par une série de statuts. Les comprendre vous aide à suivre la progression de l'utilisateur, à automatiser les décisions de conformité et à optimiser le taux de conversion.

Cette énumération est la source unique de vérité pour les chaînes renvoyées par `GET /v3/session/<id>/decision/` et par chaque webhook Didit.

***

## Toutes les valeurs de statut

> [!NOTE]
>
> Chaque statut est une **chaîne exacte** renvoyée par l'API et les webhooks Didit. Utilisez toujours une comparaison stricte des chaînes (par exemple `=== "In Review"`) dans votre code : ces valeurs sont sensibles à la casse et contiennent des espaces. La valeur `Kyc Expired` utilise également un seul `K` majuscule (et non `KYC`).

| Statut | Valeur de chaîne | Description |
| - | - | - |
| Non démarré | `"Not Started"` | Session créée, l'utilisateur n'a pas encore ouvert le lien |
| En cours | `"In Progress"` | L'utilisateur effectue activement la vérification |
| Approuvé | `"Approved"` | Tous les contrôles ont été passés avec succès : identité vérifiée |
| Refusé | `"Declined"` | Un ou plusieurs contrôles ont échoué |
| En cours d'examen | `"In Review"` | Signalé pour un examen manuel de conformité |
| En attente de l'utilisateur | `"Awaiting User"` | En attente qu'une ou plusieurs parties terminent leur vérification (KYB) |
| Soumis à nouveau | `"Resubmitted"` | L'utilisateur a demandé à refaire certaines étapes spécifiques |
| Expiré | `"Expired"` | La session a expiré avant que l'utilisateur n'ouvre le lien |
| Abandonné | `"Abandoned"` | L'utilisateur a commencé mais n'a pas terminé à temps |
| KYC expiré | `"Kyc Expired"` | Session précédemment approuvée dont le document vérifié a dépassé sa date d'expiration |

***

## Statuts des sessions

> [accordion] Non démarré — "Not Started"
>
> **Valeur API :** `"Not Started"`
>
> La session a été créée via l'API, mais l'utilisateur **n'a pas encore ouvert le lien de vérification**.
>
> * **Action à mener :** Attendez que l'utilisateur commence, ou envoyez un rappel si le délai est trop long.
> * **Transitions vers :** `"In Progress"`, `"Expired"`

> [accordion] En cours — "In Progress"
>
> **Valeur API :** `"In Progress"`
>
> L'utilisateur a ouvert le lien et **effectue activement les étapes de vérification** (capture du document, détection du vivant, etc.).
>
> * **Action à mener :** Aucune action requise, l'utilisateur est en train de suivre le parcours.
> * **Transitions vers :** `"Approved"`, `"Declined"`, `"In Review"`, `"Abandoned"`

> [accordion] Approuvé — "Approved"
>
> **Valeur API :** `"Approved"`
>
> Toutes les vérifications ont abouti avec succès. L'identité de l'utilisateur a été vérifiée.
>
> * **Action à mener :** Accordez à l'utilisateur l'accès, mettez à jour son profil et conservez les données de la décision.
> * **Le webhook inclut :** L'objet `decision` complet avec les résultats de toutes les fonctionnalités.
> * **Transitions vers :** `"Kyc Expired"` (lorsque la date d'expiration du document vérifié est dépassée ; comportement par défaut, sauf si **Expiration mode** est réglé sur **Allow expired** pour ce pays et ce type de document). Un réviseur ou l'endpoint de mise à jour du statut peut également la faire passer à `"Declined"` ou `"Resubmitted"`.

> [accordion] Refusé — "Declined"
>
> **Valeur API :** `"Declined"`
>
> Une ou plusieurs vérifications ont échoué. L'utilisateur n'a pas réussi la vérification.
>
> * **Action à mener :** Informez l'utilisateur. Vous pouvez éventuellement demander une nouvelle soumission si le problème peut être corrigé.
> * **Le webhook inclut :** L'objet `decision` complet avec les avertissements expliquant l'échec.
> * **Transitions vers :** `"Resubmitted"` (si un réviseur la demande). Un réviseur ou l'endpoint de mise à jour du statut peut aussi la faire passer à `"Approved"`.

> [accordion] En cours d’examen — "In Review"
>
> **Valeur API :** `"In Review"`
>
> Les contrôles automatiques ont signalé des **avertissements nécessitant un examen humain**. Un réviseur chargé de la conformité doit prendre la décision finale.
>
> * **Action à mener :** Un réviseur doit ouvrir la session dans la Console, puis approuver, refuser ou demander une nouvelle soumission.
> * **Le webhook inclut :** L'objet `decision` complet avec les avertissements.
> * **Transitions vers :** `"Approved"`, `"Declined"`, `"Resubmitted"`

> [accordion] En attente de l’utilisateur — "Awaiting User"
>
> **Valeur API :** `"Awaiting User"`
>
> Utilisé dans les **sessions KYB (vérification d'entreprise)** lorsque l'étape Personnes clés a soumis la liste des parties et généré des sessions KYC ou KYB enfants. La session parente attend que **toutes les parties requises aient terminé leur vérification individuelle**.
>
> * **Action à mener :** Surveillez les statuts des sessions KYC enfants. Une fois que toutes les parties requises ont terminé leur vérification (avec une session approuvée, refusée ou expirée), la session parente recalcule automatiquement son statut final.
> * **Le webhook inclut :** La liste actuelle des parties et les statuts de leurs sessions enfants.
> * **Transitions vers :** `"Approved"`, `"Declined"`, `"In Review"` (une fois que toutes les sessions enfants sont terminales)
> * **Transitions depuis :** `"In Progress"` (après soumission de l'étape Personnes clés)
> * **Remarque :** Si une session KYC enfant est soumise à nouveau, la session parente revient à `"Awaiting User"` jusqu'à ce que la session soumise à nouveau soit terminée. Un KYB Registry Check en statut `"Declined"` prime sur `"Awaiting User"`.

> [accordion] Nouvelle soumission demandée — "Resubmitted"
>
> **Valeur API :** `"Resubmitted"`
>
> Un réviseur a demandé que l'utilisateur **refasse certaines étapes de vérification** (par exemple, reprendre une photo de document floue).
>
> * **Action à mener :** Attendez que l'utilisateur termine les étapes à refaire. Le système réévaluera automatiquement la session.
> * **Le webhook inclut :** L'objet `resubmit_info` avec la liste des fonctionnalités à refaire et les motifs.
> * **Transitions vers :** `"Approved"`, `"Declined"`, `"In Review"`, ou `"Abandoned"` lorsque la fenêtre de la session se termine avant que la personne ait refait les étapes.

> [accordion] Expiré — "Expired"
>
> **Valeur API :** `"Expired"`
>
> La session a expiré avant que l'utilisateur ouvre le lien de vérification.
>
> * **Action à mener :** Créez une nouvelle session et envoyez à l'utilisateur un nouveau lien.
> * **Statut terminal** : aucune transition ultérieure.

> [accordion] Abandonné — "Abandoned"
>
> **Valeur API :** `"Abandoned"`
>
> L'utilisateur a **commencé sans terminer** la vérification dans le délai imparti.
>
> * **Action à mener :** Envoyez un rappel ou créez une nouvelle session.
> * **Aucune transition automatique.** Un réviseur, ou `PATCH /v3/session/{sessionId}/update-status/`, peut encore la faire passer à `"Approved"`, `"Declined"` ou `"Resubmitted"`.

> [accordion] KYC expiré — "Kyc Expired"
>
> **Valeur API :** `"Kyc Expired"`
>
> Le document vérifié pendant la session a **dépassé sa propre date d'expiration**. Le déclencheur est cette date, et non une période mesurée à partir de l'approbation ; aucun avertissement n'est envoyé au préalable.
>
> * **Action à mener :** Demandez à l'utilisateur de refaire la vérification avec une nouvelle session. `status.updated` transmet la transition, et le résultat de la vérification d'identité comporte un avertissement `DOCUMENT_EXPIRED`.
> * **Contrôlé par :** le paramètre **Expiration mode** pour le pays et le type de document concernés dans *ID verification → Additional settings by country & document type* : **Reject expired** (par défaut) surveille le document, tandis que **Allow expired** signifie que la session ne passe jamais à ce statut.
> * **Aucune transition automatique.** Un réviseur, ou `PATCH /v3/session/{sessionId}/update-status/`, peut encore la faire passer à `"Approved"`, `"Declined"` ou `"Resubmitted"`.

***

## Transitions de statut

| De | Vers | Déclencheur |
| - | - | - |
| `"Not Started"` | `"In Progress"` | L'utilisateur ouvre le lien de vérification |
| `"Not Started"` | `"Expired"` | La durée de vie (TTL) de la session expire avant que l'utilisateur n'ouvre le lien |
| `"In Progress"` | `"Approved"` | Tous les contrôles automatisés réussissent |
| `"In Progress"` | `"Declined"` | Un ou plusieurs contrôles échouent |
| `"In Progress"` | `"In Review"` | Les contrôles signalent des avertissements nécessitant une vérification humaine |
| `"In Progress"` | `"Awaiting User"` | L'étape KYB des personnes clés est soumise ; le parent attend les parties KYC enfants |
| `"In Progress"` | `"Abandoned"` | L'utilisateur ne termine pas dans le délai imparti |
| `"Awaiting User"` | `"Approved"` | Toutes les parties KYB requises terminent et les contrôles agrégés réussissent |
| `"Awaiting User"` | `"Declined"` | Une partie requise est refusée ou la vérification du registre KYB échoue |
| `"Awaiting User"` | `"In Review"` | Le résultat KYB agrégé nécessite un examen manuel |
| `"In Review"` | `"Approved"` | Le réviseur approuve manuellement |
| `"In Review"` | `"Declined"` | Le réviseur refuse manuellement |
| `"In Review"` | `"Resubmitted"` | Le réviseur demande de refaire des étapes précises |
| `"Declined"` | `"Resubmitted"` | Le réviseur demande de refaire des étapes précises |
| `"Approved"` | `"Resubmitted"` | Le réviseur demande de refaire des étapes précises |
| `"Approved"` | `"Declined"` | Le réviseur ou l'API définit l'autre décision |
| `"Declined"` | `"Approved"` | Le réviseur ou l'API définit l'autre décision |
| `"Abandoned"`, `"Kyc Expired"` | `"Approved"`, `"Declined"`, `"Resubmitted"` | Le réviseur ou l'API décide d'une session terminée sans décision |
| `"Resubmitted"` | `"Abandoned"` | La fenêtre de la session se termine avant que la personne ne refasse les étapes |
| `"Resubmitted"` | `"Approved"` | Les étapes resoumises réussissent tous les contrôles |
| `"Resubmitted"` | `"Declined"` | Les étapes resoumises échouent |
| `"Resubmitted"` | `"In Review"` | Les étapes resoumises signalent de nouveaux avertissements |
| `"Resubmitted"` (enfant KYB) | `"Awaiting User"` (parent KYB) | Le parent retourne en attente jusqu'à ce que l'enfant termine |
| `"Approved"` | `"Kyc Expired"` | La date d'expiration du document vérifié est dépassée (le mode d'expiration est **Reject expired**) |

### Diagramme du cycle de vie

```mermaid theme={null}
flowchart LR
    NS["Not Started"] --> IP["In Progress"]
    NS --> EX["Expired"]
    IP --> AP["Approved"]
    IP --> DC["Declined"]
    IP --> IR["In Review"]
    IP --> AU["Awaiting User<br/>(KYB only)"]
    IP --> AB["Abandoned"]
    AU --> AP
    AU --> DC
    AU --> IR
    IR --> AP
    IR --> DC
    IR --> RS["Resubmitted"]
    DC --> RS
    AP --> RS
    AP <--> DC
    AB --> AP
    AB --> DC
    AB --> RS
    KE --> AP
    KE --> DC
    KE --> RS
    RS --> AB
    RS --> AP
    RS --> DC
    RS --> IR
    AP --> KE["Kyc Expired"]
```

***

## Terminaux et non terminaux

| Catégorie | Statuts | Signification |
| - | - | - |
| **Décidé** | `"Approved"`, `"Declined"`, `"Kyc Expired"` | Les contrôles ont produit une décision, et rien ne la modifie de lui-même, sauf le passage de `"Approved"` à `"Kyc Expired"` lorsque la date d'expiration du document vérifié est dépassée. Un réviseur ou l'endpoint de mise à jour du statut peut toujours modifier la décision. |
| **Non terminal** | `"Not Started"`, `"In Progress"`, `"Resubmitted"`, `"Awaiting User"` | Les statuts sont toujours actifs : en attente d'une action de l'utilisateur, de sessions enfants ou d'un traitement. |
| **Actionnable** | `"In Review"` | Nécessite une intervention manuelle de votre équipe. |
| **Inactif** | `"Expired"`, `"Abandoned"` | Terminé sans décision de vérification. `"Expired"` ne change jamais ; un réviseur peut encore décider d'une session `"Abandoned"`. |

***

## Gérer les statuts dans votre code

Utilisez les webhooks ou l'[API de récupération de session](https://docs.didit.me/fr/sessions-api/retrieve-session.md) pour réagir aux changements de statut.

> [!WARNING]
>
> Les statuts sont des **chaînes exactes, sensibles à la casse et contenant des espaces**. Par exemple, `"In Review"` (et non `"in_review"` ou `"IN_REVIEW"`). Utilisez toujours l'égalité stricte (`===`) lors de la comparaison.

```javascript theme={null}
// All ten possible status string values (StatusChoices, source of truth):
// "Not Started"  | "In Progress" | "Approved"     | "Declined" |
// "In Review"    | "Resubmitted" | "Awaiting User"|
// "Expired"      | "Abandoned"   | "Kyc Expired"

async function handleWebhook(webhook) {
  const { status, vendor_data: vendorData } = webhook;

  switch (status) {
    case "Not Started":
      // Session created but user hasn't opened the link yet
      break;

    case "In Progress":
      // User is actively completing verification steps
      break;

    case "Approved":
      // All checks passed — grant access
      await db.users.update(vendorData, {
        verified: true,
        verifiedAt: new Date(),
        decision: webhook.decision,
      });
      break;

    case "Declined":
      // Verification failed — notify user
      await db.users.update(vendorData, {
        verificationStatus: "declined",
        declineReasons: webhook.decision?.warnings,
      });
      break;

    case "In Review":
      // Needs manual review by compliance team
      await db.users.update(vendorData, {
        verificationStatus: "pending_review",
      });
      break;

    case "Awaiting User":
      // KYB parent waiting for all child KYC parties to finish
      await db.users.update(vendorData, {
        verificationStatus: "awaiting_kyb_parties",
      });
      break;

    case "Resubmitted":
      // User will redo specific steps
      await db.users.update(vendorData, {
        verificationStatus: "resubmission_pending",
        resubmitInfo: webhook.resubmit_info,
      });
      break;

    case "Abandoned":
      // User started but didn't finish — send reminder
      await sendReminderEmail(vendorData);
      break;

    case "Expired":
    case "Kyc Expired":
      // Session expired — create a new one
      await createNewSession(vendorData);
      break;
  }
}
```

***

## Resoumission

Le statut **Resubmitted** permet à votre équipe de conformité de donner une seconde chance aux utilisateurs sans créer de nouvelle session.

**1. Le réviseur lance la resoumission**

Depuis la Console, ouvrez une session `In Review` ou `Declined` et cliquez sur **Demander une resoumission**. Sélectionnez les étapes à refaire.

**2. Les données précédentes sont archivées**

Le système réinitialise les fonctionnalités sélectionnées et marque les données précédentes comme `previous_attempt`, en préservant la piste d'audit complète.

**3. L'utilisateur est notifié**

Si un e-mail est disponible, l'utilisateur reçoit un e-mail localisé avec un lien direct pour reprendre.

**4. L'utilisateur refait des étapes précises**

L'utilisateur ne répète que les étapes signalées, et non la vérification complète.

**5. Le système réévalue**

Une fois terminée, la session passe automatiquement à `"Approved"`, `"Declined"` ou `"In Review"`.

### Charge utile du webhook de resoumission

```json theme={null}
{
  "session_id": "uuid-of-the-session",
  "status": "Resubmitted",
  "resubmit_info": {
    "nodes_to_resubmit": [
      { "node_id": "feature_ocr", "feature": "OCR" },
      { "node_id": "feature_liveness", "feature": "LIVENESS" }
    ],
    "reasons": {
      "feature_ocr": "DOCUMENT_EXPIRED",
      "feature_liveness": "LOW_LIVENESS_SCORE"
    }
  }
}
```

`reasons` associe chaque `node_id` resoumis au code d'avertissement du journal le plus pertinent pour cette étape (les mêmes codes que ceux rapportés par la [décision](https://docs.didit.me/fr/reference/data-models.md)), afin que vous puissiez le mettre en correspondance avec vos propres textes. C'est aussi le code que l'écran de resoumission du flux hébergé et l'e-mail de resoumission localisent pour l'utilisateur, sauf pour les avertissements qui révéleraient un signal de filtrage ou de fraude (doublons, AML, liste de blocage, vérifications inter-organisations, intégrité de la localisation géographique et similaires) : dans ces cas, la personne voit un motif générique, et `resubmit_info.reasons` dans votre webhook contient toujours le code réel. Une étape sans avertissement enregistré n'a pas d'entrée.

### Fonctionnalités pouvant être resoumises

Toute fonctionnalité au statut non approuvé : **Declined**, **In Review**, **Not Finished**, **Not Started** ou **Expired**.

> [!TIP]
>
> Vous pouvez demander une resoumission plusieurs fois pour la même session. Chaque cycle archive les données de la tentative précédente, ce qui vous donne une visibilité complète sur l'historique de vérification de l'utilisateur.

***

## Meilleures pratiques

> [card] Surveiller les sessions en cours d'examen
>
> Configurez des alertes (e-mail ou Slack) dans votre Didit Console pour être averti lorsque des sessions nécessitent un examen manuel.

> [card] Privilégier la nouvelle soumission
>
> Si le problème est corrigeable (photo floue, mauvais côté du document), demandez une nouvelle soumission au lieu de refuser. Cela améliore le taux de conversion.

> [card] Suivre les abandons
>
> Des taux élevés de sessions abandonnées ou expirées peuvent indiquer des frictions dans l'expérience utilisateur. Envisagez d'ajuster le TTL de session ou d'améliorer les instructions données à l'utilisateur.

> [card] Gestionnaires idempotents
>
> Les webhooks peuvent être réessayés. Utilisez `session_id` comme clé unique pour vous assurer de ne traiter chaque changement de statut qu'une seule fois.

> [!WARNING]
>
> Vérifiez toujours les signatures des webhooks avant de traiter les payloads. Didit propose trois méthodes : `X-Signature`, `X-Signature-V2` (recommandée) et `X-Signature-Simple`, obsolète, qui n'authentifie que l'enveloppe et jamais le corps `decision`. Consultez [Webhooks](https://docs.didit.me/fr/integration/webhooks.md#vérification-de-la-signature) pour plus de détails.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.