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)
workflow_id: ti servirà nel passaggio successivo.2
Crea una sessione di Verifica aziendale (KYB) tramite l'API
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.6
Agisci in base alla decisione
In base a
status:"Approved": avvia l’onboarding dell’azienda."Declined": rifiuta l’azienda e registra i tagwarnings[]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.