Avvisi e codici di rischio della verifica telefonica

La funzionalità Verifica telefonica emette avvisi ogni volta che si attiva un segnale di rischio sul flusso OTP o sul numero stesso: un numero noto come non valido o a rischio, una linea VoIP o usa e getta, il superamento del limite di tentativi OTP o una corrispondenza con la sessione di un altro utente. Questa pagina elenca ciascun codice, cosa lo attiva e come configurare la risposta del workflow.

Panoramica

Gli avvisi sono contrassegnati con la funzionalità PHONE. Compaiono sotto phone_verifications[].warnings[] in GET /v3/session/{sessionId}/decision/ e seguono la struttura standard dell’oggetto avviso (feature, risk, additional_data, log_type, short_description, long_description, node_id). Ciascun avviso viene inoltre instradato nel registro per sessione in modo da comparire nella Business Console nella sezione Telefono. Alcuni avvisi sono trigger di rifiuto automatico vincolante: impostano sempre lo stato della funzionalità su Declined. Altri sono mappati su un’azione configurabile (DECLINE, REVIEW o NO_ACTION, a seconda dell’impostazione) definita nelle impostazioni del workflow, in modo che lo stesso codice di rischio possa rifiutare un workflow e limitarsi a segnalarne un altro.

Condizioni di rifiuto automatico

I seguenti avvisi rifiutano sempre il passaggio di Verifica telefonica indipendentemente dalla configurazione e presentano sempre log_type: "error":

VERIFICATION_CODE_ATTEMPTS_EXCEEDED: l’utente ha esaurito il limite di tentativi OTP: per impostazione predefinita 2 invii di codice errati (phone_max_check_attempts) o più di 2 invii OTP (phone_max_retries), entrambi regolabili per nodo del workflow. L’API standalone per la verifica telefonica consente 3 tentativi di inserimento del codice.
PHONE_NUMBER_IN_BLOCKLIST: il numero è presente nella tua blocklist gestita tramite l’API Lists oppure corrisponde a una sessione inserita in blocklist.

HIGH_RISK_PHONE_NUMBER: il livello antifrode del provider di consegna rifiuta di inviare l’OTP (invio Blocked): il blocco comporta il rifiuto per impostazione predefinita ma non è più incondizionato: consulta high_risk_phone_action più avanti.

Rischi configurabili

Ciascuno dei seguenti rischi è associato a un’impostazione del workflow che puoi configurare su DECLINE, REVIEW o NO_ACTION (il valore predefinito: l’avviso viene registrato senza influire sullo stato). L’azione configurata imposta anche il log_type dell’avviso: DECLINE → error, REVIEW → warning, NO_ACTION → information.

Impostazione	Codice di rischio	Si attiva quando
`voip_number_action`	`VOIP_NUMBER_DETECTED`	Il carrier identifica la linea come di tipo `voip`, `isp` o `vpn`.
`disposable_number_action`	`DISPOSABLE_NUMBER_DETECTED`	La verifica individua il numero come appartenente a un provider temporaneo o usa e getta.
`duplicated_phone_number_action`	`DUPLICATED_PHONE_NUMBER`	Il numero corrisponde a un’altra sessione di qualunque stato appartenente a un utente finale diverso. Ignorato quando il numero è inserito nella allowlist.

Il rilevamento dei duplicati viene eseguito all’interno della tua applicazione per le verifiche telefoniche KYC, KYB e tramite API standalone, e raggruppa le sessioni per vendor_data: le sessioni che condividono lo stesso vendor_data vengono trattate come un unico utente finale e sono escluse dai risultati delle corrispondenze. Se lasci vuoto vendor_data, ogni sessione viene considerata come un utente distinto.

Invii bloccati

HIGH_RISK_PHONE_NUMBER segue lo stesso schema con un insieme di opzioni più ristretto, poiché un invio rifiutato dal provider non può essere approvato:

Impostazione	Codice di rischio	Si attiva quando
`high_risk_phone_action`	`HIGH_RISK_PHONE_NUMBER`	Il livello antifrode del provider di consegna ha rifiutato di inviare l’OTP (invio `Blocked`). Accetta solo `DECLINE` o `REVIEW` e il valore predefinito è `DECLINE`.

L’impostazione viene applicata solo quando ogni blocco ad alto rischio sul passaggio presenta in additional_data.risk_factors esattamente ["device_attribute"]: il segnale del provider “questo dispositivo appare sospetto”, ovvero ciò che si attiva sulle normali linee mobili. Qualsiasi altro fattore di rischio, qualsiasi combinazione che si limiti a includere device_attribute o un blocco privo di fattori di rischio comporta il rifiuto a prescindere dall’impostazione. Il motivo del blocco (repeated_attempts, suspicious o spam) è un campo separato, restituito in additional_data.blocked_reason. Indipendentemente dall’impostazione, un numero presente in una allowlist telefonica creata tramite l’API Lists non viene mai rifiutato automaticamente per un invio bloccato: il passaggio passa a In revisione, l’avviso presenta log_type: "warning" e additional_data.phone_number_in_allowlist è true.

Limiti dei tentativi di verifica

La funzionalità Verifica telefonica applica un limite massimo rigido sui tentativi di OTP per prevenire abusi:

Tentativi di inserimento del codice — Valore predefinito di 2 invii errati (phone_max_check_attempts) prima che il passaggio si concluda come Declined con VERIFICATION_CODE_ATTEMPTS_EXCEEDED. L’API telefonica autonoma consente 3 tentativi di inserimento del codice per verifica.
Tentativi di invio — Valore predefinito di 2 invii totali (phone_max_retries): l’invio iniziale più un reinvio. Un’ulteriore richiesta di invio conclude il passaggio e genera VERIFICATION_CODE_ATTEMPTS_EXCEEDED.
Validità dell’OTP — Un OTP in attesa è valido per 5 minuti dal primo invio; i nuovi tentativi non estendono questa finestra.

Entrambi i limiti sono configurabili per nodo del workflow. Indipendentemente da questi limiti, il livello antifrode del provider di consegna può bloccare direttamente un invio (motivo repeated_attempts, suspicious o spam): questo genera HIGH_RISK_PHONE_NUMBER, non l’avviso relativo ai tentativi.

Avvisi generati

Tag	`log_type`	Descrizione
`VERIFICATION_CODE_ATTEMPTS_EXCEEDED`	`error` (sempre)	L’utente ha superato il limite di inserimento del codice OTP o di invio. Rifiuto automatico.
`HIGH_RISK_PHONE_NUMBER`	Segue `high_risk_phone_action`, o `warning` se in allowlist	Il provider di consegna ha bloccato l’invio dell’OTP. Viene rifiutata per impostazione predefinita; imposta `high_risk_phone_action` su `REVIEW` per indirizzare invece un blocco basato solo sui segnali del dispositivo allo stato in revisione (vedi Invii bloccati). Anche un numero presente in una allowlist telefonica passa allo stato in revisione. `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`.
`PHONE_NUMBER_IN_BLOCKLIST`	`error` (sempre)	Il numero è presente in una blocklist creata tramite l’API Lists o corrisponde a una sessione inserita in blocklist. Rifiuto automatico. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (tutti `null` per una corrispondenza diretta nella lista).
`PHONE_NUMBER_IN_ALLOWLIST`	`information`	Il numero corrispondeva ad altre sessioni ma è presente in una allowlist creata tramite l’API Lists, quindi le azioni per numero duplicato vengono ignorate. `additional_data`: `{ phone_number }`.
`DISPOSABLE_NUMBER_DETECTED`	Segue `disposable_number_action`	Il numero appartiene a un provider temporaneo o usa e getta, spesso utilizzato per eludere la tracciabilità.
`VOIP_NUMBER_DETECTED`	Segue `voip_number_action`	Il numero corrisponde a una linea `voip`, `isp` o `vpn` anziché a una linea mobile o fissa standard.
`DUPLICATED_PHONE_NUMBER`	Segue `duplicated_phone_number_action`	Il numero corrisponde a un’altra sessione — di qualsiasi stato — appartenente a un utente finale diverso (raggruppate in base a `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`.

Corrispondenze tra sessioni

Quando un numero viene rilevato in altre sessioni o nella tua blocklist, tali corrispondenze compaiono anche in phone_verifications[].matches[] (con un limite massimo di 5 voci). Ciascuna corrispondenza include session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service e un campo source con valore session (un’altra sessione con lo stesso numero, di qualsiasi stato) o list_entry (una corrispondenza sintetica della blocklist anteposta all’array). Se il numero corrente è presente nella tua allowlist telefonica, Didit conserva l’evidenza della corrispondenza ma genera PHONE_NUMBER_IN_ALLOWLIST anziché applicare l’azione per numero duplicato. Consulta il report di Verifica telefonica per lo schema completo delle corrispondenze.

Esempio

Un invio bloccato (HIGH_RISK_PHONE_NUMBER) su un numero VoIP, con voip_number_action configurato su REVIEW:

{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}

Tipi di avviso

A ciascun rischio viene assegnata una gravità in base alla configurazione della tua applicazione. I livelli di gravità si suddividono in tre categorie:

Correlati

Panoramica sulla Verifica telefonica — comportamento della funzionalità, prezzi, canali supportati.
Report di Verifica telefonica — struttura completa della risposta inclusi lifecycle[] e matches[].
Modelli di dati — verifica telefonica — schema canonico campo per campo.
API di gestione — Liste — gestione della blocklist telefonica utilizzata da PHONE_NUMBER_IN_BLOCKLIST.

Autenticazione

Verifica

Monitoraggio

Piattaforma

Avvisi e codici di rischio della verifica telefonica

Panoramica

Condizioni di rifiuto automatico

Rischi configurabili

Invii bloccati

Limiti dei tentativi di verifica

Avvisi generati

Corrispondenze tra sessioni

Esempio

Tipi di avviso

Correlati

​Panoramica

​Condizioni di rifiuto automatico

​Rischi configurabili

​Invii bloccati

​Limiti dei tentativi di verifica

​Avvisi generati

​Corrispondenze tra sessioni

​Esempio

​Tipi di avviso

​Correlati

Panoramica

Condizioni di rifiuto automatico

Rischi configurabili

Invii bloccati

Limiti dei tentativi di verifica

Avvisi generati

Corrispondenze tra sessioni

Esempio

Tipi di avviso

Correlati