Risoluzione dei problemi KYT: errori comuni e soluzioni

Un riferimento dei problemi più comuni di Monitoraggio delle transazioni, con sintomo, causa e soluzione.

​

Errore txn_id duplicato

Sintomo. L’invio di una transazione restituisce 400 con A transaction with this transaction_id already exists. sul campo transaction_id, oppure 409 quando due richieste identiche si sovrappongono. Causa. txn_id (il transaction_id che invii) è univoco per applicazione. Didit rifiuta una seconda transazione con lo stesso transaction_id e non restituisce il record esistente. Soluzione.

• Genera txn_id in modo deterministico dal tuo lato (ad esempio usando l’ID della tua tabella delle transazioni).
• In caso di 400 o 409 per un transaction_id duplicato durante un nuovo tentativo, cerca la transazione esistente invece di inviarla di nuovo: leggila con GET /v3/transactions/{uuid}/ usando l’uuid della prima risposta, oppure usa il transaction_id (l’uuid di Didit) che il webhook transaction.created riporta accanto al tuo txn_id.
• Se la richiesta non era un nuovo tentativo, assegna alla nuova transazione un proprio transaction_id.

​

La regola non si attiva

Sintomo. Hai creato una regola che dovrebbe corrispondere, ma nessuna transazione la mostra in rule_runs[] con matched: true. Cause e soluzioni.

• L’applicazione è in modalità sandbox: un’applicazione sandbox salta la valutazione delle regole, lo screening AML, la fatturazione e i webhook transaction.created e transaction.status.updated. Gli scambi Travel Rule vengono comunque eseguiti quando sono abilitati, verso il Didit Test VASP, e inviano webhook travel_rule.status.updated contrassegnati con environment: sandbox. rule_runs torna vuoto e il punteggio resta 0, qualunque sia la modalità delle tue regole, e la transazione resta APPROVED a meno che un trasferimento Travel Rule in scadenza non applichi il tuo timeout_outcome. Controlla environment nella risposta della transazione: "sandbox" significa che non è mai stata valutata. Consulta Transaction Monitoring in sandbox per capire come validare una regola prima che vada in produzione.
• La modalità della regola è DISABLED o TEST: controlla Rules → [rule] → Mode. Solo le regole ACTIVE contribuiscono al punteggio; le regole TEST vengono valutate ma non influiscono sullo stato.
• Il filtro di ambito esclude la transazione: ad esempio, uno scope impostato su transaction_type = finance non corrisponde alle transazioni travelRule.
• La finestra di aggregazione è più corta del necessario: una regola “20 transazioni in 30 giorni” non si attiva dopo sole 15 transazioni.
• Il campo della condizione è null: ad esempio, la tua regola verifica counterparty.country_code ma non hai inviato una controparte.
• Conversione valutaria: la regola usa come soglia amount_in_default_currency; se la valuta predefinita della tua applicazione è diversa dalla valuta della transazione, l’importo convertito potrebbe risultare sotto la soglia.

Usa la funzione Rules → [rule] → Backtest per rieseguire una transazione passata e capire perché la regola si è attivata o no.

​

La regola si attiva su tutto

Sintomo. Una regola si attiva sul 90%+ delle transazioni: la tua coda di revisione è sommersa. Causa. Le condizioni sono troppo ampie oppure le soglie sono troppo basse. Soluzione.

• Aggiungi filtri scope per restringere l’applicabilità (ad esempio solo transazioni in uscita, solo determinati tipi di transazione).
• Alza le soglie (importi, numero di operazioni nel periodo).
• Imposta la regola in modalità TEST per una settimana: analizza i rule_runs per vedere il tasso di corrispondenza e restringi le condizioni prima di riattivarla.

​

Timeout dello screening crypto

Sintomo. La transazione è completata con status: APPROVED, ma l’array provider_results[] mostra status: FAILED per un wallet, un hash di transazione o un provider di screening crypto. Cause.

• L’API del provider è stata brevemente non disponibile.
• La query è scaduta (in genere dopo circa 10 s).

Soluzione.

• Le transazioni non falliscono mai a causa dei provider: l’arricchimento viene eseguito al meglio delle possibilità.
• Se un provider specifico fallisce ripetutamente, controlla la sua pagina di stato o apri un ticket di supporto.
• Valuta di configurare le preferenze dei provider in Settings → Transaction Monitoring → Providers per instradare le richieste verso provider alternativi.

​

Arricchimento IP mancante

Sintomo. applicant.ip_enrichment di una transazione è assente o parziale. Cause.

• Nell’invio manca applicant.device.ip.
• L’IP è privato o riservato (non instradabile).
• Tutti i provider di arricchimento erano temporaneamente non disponibili.

Soluzione.

• Acquisisci l’IP di chi invia nel tuo client o server e passalo in ogni transazione.
• Usa solo IP instradabili: Didit ignora silenziosamente gli intervalli privati.
• Controlla lo stato dei provider in Settings → Status nella console.

​

Mancata corrispondenza della firma del webhook

Sintomo. Il tuo endpoint rifiuta gli eventi perché la firma non corrisponde. Cause.

• Il corpo grezzo è stato modificato (JSON serializzato di nuovo con spaziatura diversa).
• Segreto errato.
• Più destinazioni webhook con lo stesso URL: le firme sono diverse per ogni destinazione.

Soluzione.

• Calcola la firma sul corpo grezzo della richiesta, non sul JSON analizzato. Molti framework espongono un middleware per il corpo grezzo.
• Ruota il segreto se è compromesso: Webhook destinations → [destination] → Rotate secret.
• Mantieni una sola destinazione per URL, per evitare confusione tra i segreti.

​

Il webhook non arriva

Sintomo. Le transazioni vengono create, ma i webhook non arrivano mai. Cause.

• enabled della destinazione è false.
• L’URL non è raggiungibile pubblicamente.
• La destinazione webhook è stata disattivata automaticamente dopo ripetuti errori.
• L’evento non è incluso in subscribed_events.

Soluzione.

• Invia un evento di test: Webhook destinations → [destination] → Send test.
• Controlla le consegne recenti: Webhooks → [destination] → Deliveries. Vedrai le risposte 4xx/5xx con corpo e intestazioni.
• Riattiva le destinazioni webhook disattivate.

​

La conversione valutaria sembra errata

Sintomo. amount_in_default_currency non corrisponde al tasso che ti aspetti. Cause.

• Il tasso di cambio è il tasso medio di mercato alla data txn_date.
• Le transazioni retrodatate usano il tasso storico di quella data.
• Alcune valute (valute esotiche) hanno intervalli di aggiornamento più ampi.

Soluzione.

• Usa amount e currency (valuta originale) per la visualizzazione.
• Usa amount_in_default_currency solo per le soglie delle regole interne.
• Ai fini di audit, il record della transazione conserva il tasso di conversione utilizzato al momento della valutazione.

​

Controparte non corrispondente alla mia blocklist

Sintomo. Hai inserito in blocklist un’azienda tramite vendor_data, ma una transazione con quella controparte è comunque andata a buon fine. Cause.

• La controparte nel payload della transazione non ha vendor_data: è memorizzata come snapshot esterno.
• Il vendor_data differisce per maiuscole e minuscole.

Soluzione.

• Passa sempre counterparty.vendor_data quando la controparte è un’entità presente sulla tua piattaforma.
• Usa la stessa combinazione di maiuscole e minuscole ovunque: vendor_data distingue tra maiuscole e minuscole.

​

Transazioni AWAITING_USER bloccate

Sintomo. Le transazioni restano bloccate in AWAITING_USER perché l’utente non completa mai la sessione di rimedio. Cause.

• L’utente non ha aperto l’URL della sessione di rimedio.
• La sessione di rimedio è scaduta.
• La transazione è un trasferimento Travel Rule che una regola della libreria, come travel-rule-pending-action, ha spostato in AWAITING_USER: Didit non crea la sessione di rimedio predefinita per una transazione Travel Rule, quindi, a meno che la regola non indichi un proprio workflow di rimedio, non esiste alcun link da inviare.

Soluzione.

• Il remediation_session_url nella risposta della transazione è il link da inviare. Invialo di nuovo all’utente.
• Per una transazione Travel Rule, risolvi il trasferimento dalla scheda Travel Rule, poi modifica tu lo stato della transazione, perché la risoluzione del trasferimento non sposta da sola la transazione fuori da AWAITING_USER.
• Le sessioni di rimedio seguono lo stesso schema della guida rapida KYC: sottoscrivi i webhook di completamento.
• Imposta nel tuo sistema un timeout per far scadere le transazioni ferme se il rimedio non viene mai completato.

​

Limite di frequenza sulla creazione

Sintomo. 429 Too Many Requests durante picchi di volume elevato. Soluzione.

• Rispetta l’intestazione Retry-After.
• Limita il ritmo delle richieste lato client durante i picchi di traffico.
• Contatta il supporto per limiti più alti, in base a un volume di produzione comprovato.

Vedi limitazione della frequenza.

​

Prossimi passi