workflow_id.
Il tuo backend avvia la verifica e ne recupera il risultato; la tua interfaccia guida la persona attraverso l’autenticazione richiesta dal wallet.
Un’integrazione API richiede comunque che la persona si autentichi e approvi la condivisione della propria identità.
Non è possibile verificare una persona inviando il suo identificativo personale senza questa interazione.
Come funziona la verifica
- Il tuo backend consulta il catalogo dei wallet, quindi chiama l’endpoint di avvio di un wallet disponibile usando la chiave API della tua applicazione.
- Didit restituisce un riferimento di verifica e l’azione che la persona deve compiere.
- La tua applicazione apre la pagina di autenticazione o mostra le istruzioni di approvazione del wallet.
- La persona si autentica con il proprio wallet.
- Il tuo backend recupera il risultato verificato e gestisce le notifiche di completamento.
Integrazione backend
Usa Elenco dei wallet di identità digitale per ottenere gli endpoint attuali, i campi obbligatori e la disponibilità per la tua applicazione. Conserva la tuax-api-key sul backend.
Non inserirla in un bundle del browser o in un’applicazione mobile.
Usa un Idempotency-Key distinto per ogni nuovo tentativo di verifica e riutilizza quella chiave quando ripeti la stessa richiesta di avvio.
Modificare la richiesta riutilizzando la stessa chiave è un conflitto, non un nuovo tentativo di verifica.
Ogni wallet ha un proprio URL di avvio, ad esempio /v3/id-verification/wallets/ftn/ per Finnish Trust Network.
Il request_id identifica la verifica autonoma per le operazioni successive.
Usa vendor_data come riferimento interno, fino a 2.000 byte UTF-8, e metadata per un oggetto JSON facoltativo.
Entrambi vengono restituiti con il risultato e con il webhook di completamento.
Queste operazioni usano la chiave API dell’applicazione che ha avviato la verifica.
La disponibilità del polling e dell’autenticazione dipende dal wallet selezionato.
Un annullamento rifiuta una verifica in attesa senza addebitarla e restituisce invariata una verifica completata.
Per Smart-ID e Mobile-ID, un annullamento che arriva mentre un polling sta controllando l’approvazione attende alcuni secondi che il polling termini.
Quindi rifiuta la verifica oppure la restituisce come
verified se la persona aveva già approvato.
Una verifica che la persona sta completando in quel momento non può essere annullata: la risposta è 409 con error: "verification_in_progress" e un header Retry-After.
Riprova dopo quel numero di secondi per leggere il risultato completato.
Registra la tua destinazione di ritorno
I wallet con reindirizzamento riportano la persona alla tua applicazione dopo l’autenticazione. Registra l’hostname esatto prima di avviare una verifica:return_url HTTPS, ad esempio https://app.example.com/identity/complete.
Usa hostname semplici in allowed_return_hosts, senza schema, percorso o wildcard.
Registra separatamente ogni sottodominio che usi, fino a 20 hostname.
L’aggiornamento di allowed_return_hosts sostituisce l’elenco registrato, quindi includi ogni hostname che vuoi conservare.
GET /v3/webhook/ restituisce l’elenco attuale; vedi Configurazione webhook.
Per registrare una destinazione di ritorno non serve un workflow né un dominio White label.
La destinazione è una pagina di ritorno del browser; configura i webhook di completamento separatamente per il tuo backend.
Esempio: Finnish Trust Network
Dopo aver registrato l’hostname di ritorno, avvia una verifica Finnish Trust Network:request_id restituito e invia il browser della persona a wallet_verification.next_action.url quando il suo type è redirect.
Dopo che la persona torna, recupera il risultato dal tuo backend:
wallet_verification.outcome:
Usa l’identità solo quando l’esito è
verified e simulated è false per un controllo d’identità reale.
Una risposta in attesa può contenere un’azione successiva; le risposte finali non hanno un’azione successiva.
Autenticazione
I wallet con reindirizzamento restituiscono un URL di autenticazione. Apri quell’URL nel browser della persona, lascia che completi il processo di autenticazione del wallet e riportala alla destinazione registrata. Leggi il risultato dal tuo backend invece di considerare un parametro dell’URL di ritorno come prova di identità. Smart-ID e Mobile-ID usano una richiesta di approvazione sul telefono della persona. La tua interfaccia raccoglie l’identificativo personale richiesto; Mobile-ID richiede anche il numero di telefono associato. Mostra il codice di confronto e chiedi alla persona di approvare solo se corrisponde al codice presente sul suo telefono. Il PIN va inserito nel prompt del wallet o del telefono, mai nel tuo modulo o in una richiesta API. Interroga il tuo backend con l’intervallo indicato inpoll_interval_seconds per ricevere un riscontro sulla richiesta.
Didit controlla anche in background le approvazioni telefoniche in attesa, quindi il completamento può arrivare al tuo webhook dopo che la persona ha chiuso la tua pagina.
Google Wallet viene richiesto dalla tua pagina o dalla tua app tramite la Digital Credentials API, senza reindirizzamento; vedi Wallet con credenziali digitali (Google Wallet).
L’interazione disponibile dipende dal wallet selezionato.
Non dare per scontato che ogni wallet supporti un modulo incorporato, un codice QR o l’autenticazione senza browser.
Wallet con credenziali digitali (Google Wallet)
Google Wallet viene richiesto direttamente dalla tua pagina web o dalla tua app Android, usando la W3C Digital Credentials API. Non c’è alcun reindirizzamento, nessuna pagina ospitata da Didit e nessun codice QR di Didit. È disponibile in produzione e in sandbox. Le applicazioni sandbox non richiedono alcuna registrazione; ogni applicazione di produzione si registra una sola volta dalla console (passaggio di verifica dell’ID, riga Google Wallet, Registra con Google) prima di poter usare Google Wallet. Consulta L’elenco dei wallet di identità digitale per vedere cosa può avviare subito la tua applicazione.1
Inizia dall'origine
Il tuo backend chiama
POST /v3/id-verification/wallets/google-wallet/ con il country della persona (USA, GBR, BRA, SGP o TWN) e l’origin da cui verrà effettuata la richiesta al wallet.
La origin è l’origine HTTPS della tua pagina, come https://app.example.com, il cui host deve essere uno dei tuoi nomi host di ritorno registrati o il tuo dominio white label.
Per un’app Android è android:apk-key-hash: seguito dal SHA-256 in base64 del certificato di firma della tua app, senza padding.
Il wallet rifiuta una richiesta effettuata da qualsiasi altra origine.
Non esiste alcun return_url.2
Richiedi il wallet all'interno di un gesto dell'utente
La risposta contiene
wallet_verification.interaction = "digital_credentials" e next_action.type = "request_digital_credential".
Passa next_action.digital_credentials.request al browser o all’Android Credential Manager, da un tocco o un clic sulla origin con cui hai avviato la richiesta.
Su desktop il browser mostra il proprio codice QR quando il wallet si trova su un altro dispositivo.3
Invia ciò che il wallet ha restituito
Invia
{protocol, data} restituiti al tuo backend e da lì a POST /v3/id-verification/wallets/verifications/{request_id}/response/ come {"response": {...}}.
La richiesta può essere inviata una sola volta; un secondo invio restituisce la verifica già decisa.4
Leggi l'esito
La risposta all’invio è la verifica decisa.
Puoi anche leggerla con
GET /v3/id-verification/wallets/verifications/{request_id}/ oppure riceverla nel webhook di completamento."DigitalCredential" in window è true.
navigator.credentials.get deve essere eseguito in un gesto dell’utente, quindi chiamalo dal gestore del clic e non dopo un passaggio asincrono.
Su Android, usa Jetpack Credential Manager (androidx.credentials 1.5.0 o successiva) con la stessa richiesta:
Una credenziale che non supera la verifica è una verifica decisa con esito
failed, non una risposta di errore.
Dal wallet escono solo i campi richiesti dalla verifica, e il risultato contiene gli attributi di identità restituiti dal wallet.
Un pass ID di Google Wallet o una patente di guida mobile di uno stato USA non restituisce una fotografia.
In un’applicazione sandbox il flusso viene simulato con gli stessi passaggi e restituisce simulated: true.
Qualsiasi risposta inviata decide la verifica in base a sandbox_scenario, così puoi costruire l’intero percorso nel browser o nell’app senza una credenziale reale.
Webhook di completamento
Configura una destinazione webhook dell’applicazione perstatus.updated seguendo la guida all’integrazione dei webhook.
Usa webhook_version: "v3" per la struttura della decisione descritta qui.
Verifica la firma del webhook nel tuo backend prima di elaborarlo.
Il session_id del webhook corrisponde al request_id restituito dall’API del wallet.
Un’identità completata tramite wallet compare nell’array decision.id_verifications del webhook con verification_method: "wallet".
Puoi anche usare l’identificativo per recuperare il risultato dedicato dell’API del wallet.
Gestisci le notifiche di approvazione e rifiuto, incluse le verifiche annullate e scadute.
Rendi idempotente il gestore del webhook, perché le consegne non riuscite vengono sottoposte a un nuovo tentativo.
Il ritorno dal browser non è un webhook di completamento e i suoi parametri di query non sono una prova di identità.
Identità restituita
Usa i campi di identità normalizzati per nomi e date di nascita quando vengono restituiti. Gli attributi specifici del wallet descrivono le informazioni di identità condivise dal wallet selezionato. Gli attributi disponibili variano in base al wallet e al paese. Un’identità autenticata non implica che siano disponibili un ritratto, un indirizzo o ogni altro attributo richiesto.Test nella sandbox
Un’applicazione in modalità sandbox di Didit simula la verifica del wallet senza contattare un fornitore di wallet e senza addebitare crediti. La risposta identifica queste richieste conwallet_verification.simulated: true.
Un’approvazione simulata si basa su dati di esempio, non su un’identità reale verificata.
Per un wallet con reindirizzamento, segui l’URL restituito per testare il callback e tornare alla tua applicazione.
Per Smart-ID o Mobile-ID, usa l’endpoint di polling per completare l’approvazione simulata; nessuna notifica viene inviata a un telefono.
Per testare la gestione degli errori, imposta sandbox_scenario su wallet_cancelled, wallet_timeout o wallet_provider_error quando avvii una richiesta.
Le applicazioni in ambiente di produzione rifiutano sandbox_scenario.
La simulazione nella sandbox di Didit è separata dai test eseguiti nell’ambiente di test del fornitore.
Una simulazione riuscita non stabilisce l’accesso live presso il fornitore né la disponibilità in produzione.
Sandbox del provider ConnectID
La sandbox del provider ConnectID utilizza banche di test ed è separata dalla simulazione nella sandbox di Didit. Quando l’accesso alla sandbox del provider è configurato per la tua integrazione, passa l’authorisation_server_id della banca selezionata all’endpoint di avvio di ConnectID.
Usa l’ID restituito dal selettore banche di ConnectID; non inviare un URL della banca né un emittente arbitrario.
Se ometti il campo, viene selezionata la banca di test predefinita.
Il campo è specifico per ConnectID e non modifica gli attributi di identità richiesti.
Il pacchetto iniziale richiede nome, cognome e data di nascita.
Segui il next_action restituito per autenticarti, quindi recupera o interroga il risultato della verifica.
Solo un risultato completato con stato approvato conferma che la verifica è riuscita; il ritorno alla tua applicazione non lo conferma.
ConnectID rimane Prossimamente in produzione mentre vengono completati l’onboarding e la certificazione.