> ## 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.

# Verifica degli utenti: percorso e UX del flusso KYC

> UX di verifica Didit: acquisizione ID, vitalità biometrica, nuovi tentativi e feedback in tempo reale per massimizzare i tassi di completamento.



Prompt per il ciclo di vita della sessione
        Copia il prompt negli appunti



      
      

\<pre>

\````# Goal — drive a user through a full verification session

The session is the unit you build against. One `POST /v3/session/` returns a hosted URL; your user opens it; Didit runs the workflow; you receive a webhook with the decision.

For the complete recipe (SDK pick per platform, HMAC signature pipeline, decision parsing, every status), copy the canonical prompt at:

https://docs.didit.me/integration/integration-prompt

\## Session lifecycle at a glance

\| Phase | Trigger | What happens |
\|---|---|---|
\| Create | `POST https://verification.didit.me/v3/session/` | Returns `session_id`, `url`, `session_token`. Status = `Not Started`. |
\| User opens `url` | SDK / iframe / redirect | Status flips to `In Progress`. The hosted flow handles country, ID capture, liveness, retries. |
\| Processing | Didit backend | OCR, liveness, face match, AML, etc. run; per-feature plural arrays populate on the decision. |
\| Decision | `status.updated` webhook | One of `Approved`, `Declined`, `In Review`, `Awaiting User` (KYB resub), `Resubmitted`, `Abandoned`, `Expired`, `Kyc Expired`. |

\## Create a session

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "$WORKFLOW_ID",
"vendor_data": "user-42",
"callback": "https://myapp.com/kyc/return"
}'
\```

Always pass `vendor_data` — it is the linking key that binds the session to the persistent [User entity](/entities/users/overview). Without it the session is orphaned.

\## Receive the decision

Webhook (recommended) — register a destination with `webhook_version: "v3"` subscribed to `status.updated` and `data.updated`. Verify the `X-Signature-V2` header (HMAC-SHA256 of canonical JSON).

Polling fallback —
\```bash
curl https://verification.didit.me/v3/session/$SESSION_ID/decision/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

The V3 decision returns plural arrays for every feature: `id_verifications[]`, `liveness_checks[]`, `face_matches[]`, `aml_screenings[]`, `nfc_verifications[]`, `proof_of_address_checks[]`, etc. Never assume V2 singular fields.

\## Failure modes

\- Missing API key → `403 {"detail": "You do not have permission to perform this action."}`. Wrong, revoked or expired key → `401`.
\- Invalid `workflow_id` → `400`.
\- User abandons the flow → status becomes `Abandoned`.
\- Workflow asks for resubmit → status `Resubmitted`, payload includes `resubmit_info`; re-deliver the same `url`.

\## Sources of truth

\- /sessions-api/create-session — request body schema
\- /sessions-api/retrieve-session — V3 decision schema
\- /integration/verification-statuses — literal status strings
\- /integration/webhooks — signature verification, retries
\- /reference/data-models — per-feature decision shape
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Incolla in

Questa guida spiega l'esperienza di un tipico utente finale durante una sessione di **Controllo del documento d'identità + Test di vitalità** ed evidenzia le ottimizzazioni UX che favoriscono tassi di completamento elevati.Questa lezione della Didit Academy segue il flusso ospitato esattamente come lo vede un utente: la prima schermata, l'acquisizione del documento, il selfie per la vitalità e ogni schermata di esito, da approvata a rifiutata.[Cosa vedono effettivamente i tuoi utenti — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?rel=0\&playsinline=1)## Panoramica del flusso![Percorso utente di verifica dell'identità Didit dalla schermata iniziale all'acquisizione di documento e selfie fino al risultato](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/user-verification-flow.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=cc77846e25a476c7e91281295f079e80)**1. Schermata iniziale**L'utente atterra su una schermata semplice con il branding che definisce le aspettative (ad es. "Avrai bisogno del tuo documento e del tuo volto"). Questo riduce l'abbandono eliminando le incertezze.**2. Selezione di paese e documento**L'utente seleziona il proprio paese e il tipo di documento (passaporto, carta d'identità, ecc.).> [!NOTE]
>
> Se il tuo workflow è configurato per un **singolo tipo di documento**, questa schermata viene **saltata automaticamente**, portando l'utente direttamente all'acquisizione.**3. Acquisizione del documento con nuovi tentativi intelligenti**L'utente fotografa il fronte del proprio documento.
**Controllo di qualità sul dispositivo** — Prima dell'invio, l'SDK verifica la presenza di riflessi, sfocature e bordi tagliati. Se viene rilevato un problema, all'utente viene richiesto di scattare nuovamente la foto.**Validazione backend con nuovo tentativo guidato** — Una volta inviato:- **Superato** → si procede al Rilevamento della vitalità
- **Non superato** → l'utente visualizza istruzioni specifiche (ad es. "Documento scaduto", "MRZ illeggibile — riprova con una luce più forte") anziché un errore genericoQuesto ciclo di nuovi tentativi in autonomia aumenta notevolmente i tassi di superamento. Consulta l'elenco completo degli esiti di validazione in [Avvisi di verifica dell'identità](https://docs.didit.me/it/core-technology/id-verification/warnings-id-verification.md).**4. Rilevamento della vitalità + Confronto facciale**Un controllo di vitalità tramite selfie garantisce che l'utente sia fisicamente presente e previene attacchi di tipo replay o deepfake. Se l'utente non risponde in tempo, il processo **ritenta automaticamente una volta** invece di fallire definitivamente.**5. Esito finale**Al termine di tutti i controlli, l'utente visualizza uno dei tre risultati:| Risultato | Descrizione |
| - | - |
| **Approvata** | Tutti i controlli sono stati superati. I dati vengono estratti e resi disponibili tramite API/webhook. |
| **Rifiutata** | Il sistema ha stabilito che la verifica non può essere approvata. |
| **In revisione** | I controlli automatizzati non sono stati conclusivi — è necessaria una revisione manuale. |Il tuo workflow decide quali ulteriori passaggi vede l'utente, nell'ordine che hai impostato.
Ad esempio:- [Verifica telefonica](https://docs.didit.me/it/core-technology/phone-verification/overview.md) e [verifica email](https://docs.didit.me/it/core-technology/email-verification/overview.md)
- [Questionari](https://docs.didit.me/it/core-technology/questionnaires/overview.md)
- [Prova di residenza](https://docs.didit.me/it/core-technology/proof-of-address/overview.md)
- [Consenso biometrico](https://docs.didit.me/it/getting-started/biometric-consent.md)
- [Firma dei documenti](https://docs.didit.me/it/core-technology/electronic-signature/overview.md)Combinando una UX intelligente, validazione progressiva, feedback concreto e utilizzabile e nuovi tentativi gestiti in modo fluido, il percorso di verifica Didit fa avanzare gli utenti legittimi ed esclude i malintenzionati, senza alcun intervento manuale.


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