Vai al contenuto principale
This guide walks you through a complete KYB verification in under 10 minutes. You’ll create a workflow, start a session, deliver the hosted verification link to your business contact, wait for the webhook, and fetch the final decision.

Prerequisiti

  • Un’applicazione Didit con KYB abilitato. Creane una su business.didit.me, se necessario.
  • Una chiave API da Developer Settings → API Keys.
  • Un endpoint webhook raggiungibile da internet (per il webhook della decisione).

Passaggi

1

Crea un workflow KYB nella console

Vai a Workflows → Create workflow. Scegli Verifica aziendale come tipo di workflow.Attiva le funzionalità che ti servono:
  • Ricerca nel registro delle imprese (obbligatoria)
  • AML aziendale (consigliata)
  • persone chiave (obbligatoria per la maggior parte dei settori regolamentati)
  • Documenti (facoltativo: scegli i tipi di documento che richiederai)
Salva e copia il workflow_id: ti servirà nel passaggio successivo.
2

Crea una sessione di Verifica aziendale (KYB) tramite l'API

La risposta contiene session_id, session_number e url, cioè il link di verifica alla pagina di verifica ospitata che consegni al referente dell’azienda. Il tipo di workflow (KYB) contrassegna automaticamente la sessione come sessione aziendale.
3

Invia il link al referente dell'azienda

Invia il url all’amministratore dell’azienda tramite la tua email o chat. Apre il link, compila i dati del registro, aggiunge persone chiave e UBO e carica i documenti.Puoi personalizzare l’esperienza della pagina ospitata con branding, logo e dominio: vedi White label.
4

Ricevi il webhook dello stato

Quando l’azienda completa il flusso e l’elaborazione KYB raggiunge uno stato finale, Didit invia una richiesta POST con un evento status.updated al tuo endpoint webhook. Gli eventi delle sessioni aziendali contengono session_kind: "business" all’interno di data: filtra su questo valore per indirizzare l’evento al tuo gestore KYB.Verifica la firma HMAC X-Signature-V2 prima di considerare attendibile l’evento (vedi webhook), poi avvia la logica a valle. Salva il secret_shared_key della destinazione webhook (restituito quando registri il webhook) come DIDIT_WEBHOOK_SECRET nel tuo .env.Esempio di payload:
5

Recupera la decisione (facoltativo)

Il payload del webhook status.updated contiene già la decisione completa. Devi chiamare questo endpoint solo se non ti sei iscritto ai webhook, oppure se vuoi recuperare la decisione su richiesta in un secondo momento.
La decisione include i dati del registro, le persone chiave (UBO, azionisti, amministratori e rappresentanti), i riscontri AML, i documenti e i risultati per ciascuna funzionalità. Consulta lo schema della risposta per il riferimento completo del payload.
6

Agisci in base alla decisione

In base a status:
  • "Approved": avvia l’onboarding dell’azienda.
  • "Declined": rifiuta l’azienda e registra i tag warnings[] della decisione.
  • "In Review": attendi la decisione dell’analista; riceverai un altro webhook quando sarà risolta.

Esempio Node.js

Cosa succede automaticamente

  • Ricerca nel registro delle imprese in 190+ giurisdizioni.
  • Estrazione di UBO e amministratori dai dati del registro.
  • Screening AML a livello aziendale (sanzioni, PEP, notizie negative).
  • AML a livello di persona per ogni soggetto identificato.
  • OCR dei documenti e incrocio dei dati.
  • Creazione e aggregazione dei profili aziendali basate su vendor_data.

Prossimi passi

Guida all'integrazione

Architettura end-to-end, polling rispetto all’uso dei webhook, logica di retry.

Webhook KYB

Ogni evento KYB e la struttura del relativo payload.

Stati

Riferimento per gli stati di sessione, funzionalità e registro.

Schema della risposta

Il payload completo della decisione KYB.

Entità aziendali

Come i profili si aggregano tra le sessioni.
Ultima modifica il 7 novembre 2026