Integrazione del Monitoraggio delle transazioni: API KYT

Questa guida copre l’intero ambito di integrazione del Monitoraggio delle transazioni. La guida rapida ti permette di iniziare; questa pagina ti accompagna fino all’ambiente di produzione.

Architettura

Autenticazione

Intestazione standard x-api-key. Le stesse chiavi sono usate per sessioni ed entità. Vedi autenticazione API.

Invio di una transazione

Endpoint unico: POST /v3/transactions/. Vedi invio delle transazioni per lo schema completo. Payload minimo:

{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}

Payload più ricco con metodi di pagamento, contesto del dispositivo e proprietà personalizzate:

{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}

Gli alias in camelCase sono accettati per ogni campo di primo livello (txnId, txnDate, type, info, applicant, props, travelRule, includeCryptoScreening): il formato wire dell’SDK e il formato snake_case vengono interpretati allo stesso modo.

Modellazione delle parti

Ogni transazione ha un subject obbligatorio (il tuo cliente, cioè la parte che monitori) e un counterparty facoltativo (l’altra parte). Ciascuno ha il proprio payment_method e un contesto device facoltativo. Nella risposta, le parti arrivano nell’array parties con i ruoli APPLICANT e COUNTERPARTY; una parte senza vendor_data viene memorizzata come snapshot esterno (kind: EXTERNAL), senza entità collegata. Vedi payload delle transazioni per i campi delle parti.

Idempotenza

txn_id (il transaction_id che invii) è univoco per applicazione. Reinviare un transaction_id già esistente restituisce 400 con A transaction with this transaction_id already exists. nel campo transaction_id; quando due richieste identiche arrivano in concorrenza, la seconda riceve 409. Nessuna delle due risposte restituisce la transazione esistente. In caso di 400 o 409 per un transaction_id duplicato, cerca la transazione esistente invece di reinviarla: leggila con GET /v3/transactions/{uuid}/ usando l’uuid della prima risposta, oppure usa il transaction_id (l’uuid Didit) che il webhook transaction.created riporta accanto al tuo txn_id. Genera sempre txn_id dal tuo lato prima dell’invio; non fare affidamento su un ID generato da Didit per l’idempotenza. Usa l’ID del tuo database, un UUID o un hash dei campi della transazione.

Tempo reale vs batch

Tempo reale: consigliato per la maggior parte dei casi d’uso. Invia la transazione nel momento in cui avviene nel tuo sistema. Le regole vengono valutate in modo sincrono e restituiscono la decisione.
Batch / backfill: per l’importazione dello storico, passa txn_date nel passato. Le regole vengono comunque eseguite e possono attivare webhook. Per evitare che le regole si attivino durante il backfill, usa l’importazione CSV della console con il flag “dry ingest”.

Importazione dello storico

Quando stai migrando da un altro sistema di monitoraggio delle transazioni:

Esporta le transazioni storiche in un CSV.
Usa Transactions → Import history nella console (oppure invia tramite API in un ciclo) con txn_date nel passato.
Attiva le regole solo dopo il termine dell’importazione, oppure usa dry ingest per saltare la valutazione delle regole.

Fai attenzione alla valutazione storica delle regole. Far passare 6 mesi di storico attraverso una regola “20 trasferimenti in 30 giorni” genererà migliaia di alert in una sola volta.

Webhook

Iscriviti a:

transaction.created: ogni transazione inviata.
transaction.status.updated: cambi di stato (ad esempio l’analista passa da IN_REVIEW ad APPROVED, oppure un controllo AML asincrono aggiorna il punteggio).

Dettagli completi: webhook TM.

app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});

Gestione degli stati

Stato	Cosa fare
`APPROVED`	Elabora la transazione normalmente.
`IN_REVIEW`	Trattieni la transazione finché la revisione dell’analista o il nuovo controllo automatico non si conclude.
`DECLINED`	Rifiuta la transazione. Mostra all’utente un errore generico.
`AWAITING_USER`	L’utente deve agire prima che la transazione possa essere regolata: leggi il blocco `action_required` e invia il suo `url` all’utente (gli SDK possono gestire questo passaggio automaticamente).

Vedi stati TM.

Collegamento delle transazioni alle entità

Passa vendor_data su ogni parte. Vantaggi:

Ogni transazione confluisce nel profilo Utente o Azienda.
Le regole di frequenza e quelle comportamentali hanno a disposizione la cronologia completa su cui basare la valutazione.
Il blocco di un’entità si propaga automaticamente alle transazioni future.

L’assenza di vendor_data non è un errore bloccante: la transazione viene memorizzata come snapshot esterno, ma perdi l’aggregazione a livello di entità.

Sessioni di rimedio

Quando un’azione di una regola sposta una transazione in AWAITING_USER, Didit crea automaticamente una sessione di rimedio, ovvero una normale sessione di verifica ospitata per lo stesso vendor_data. Le regole personalizzate indicano sempre il workflow direttamente nell’azione; per le regole della libreria integrata, viene utilizzato il workflow di rimedio nelle impostazioni delle transazioni, poi il workflow di Autenticazione biometrica della tua applicazione (quando il soggetto ha un volto di riferimento memorizzato), e infine il workflow predefinito della tua applicazione. Le transazioni Travel Rule sono escluse da questo ricorso automatico: la loro azione in sospeso è la prova di titolarità del wallet. La transazione (la risposta, ogni lettura successiva e ogni webhook) riporta la sessione nel blocco canonico action_required:

{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}

remediation è mantenuto per compatibilità con le versioni precedenti; action_required è il blocco canonico (include anche le azioni wallet_ownership per i trasferimenti Travel Rule). Un’azione wallet_ownership non modifica da sola lo stato della transazione: la transazione mantiene lo stato assegnato dalle tue regole, spesso APPROVED, quindi controlla action_required in ogni risposta, non solo quando lo stato è AWAITING_USER. L’utente completa la verifica: per un workflow di Autenticazione biometrica, un selfie con controllo di vitalità confrontato con il volto acquisito durante l’onboarding KYC originale, il livello di autenticazione rafforzata più elevato per le transazioni di alto valore. Quando la sessione raggiunge una decisione, la transazione la segue automaticamente: APPROVED (decision_reason_code: user_action_approved), DECLINED (user_action_declined) o IN_REVIEW (user_action_in_review), e viene inviato un webhook transaction.status.updated.

È possibile selezionare qualsiasi tipo di workflow tranne KYB. I workflow di Autenticazione biometrica (e i workflow in cui il confronto facciale viene eseguito prima della verifica del documento d’identità) richiedono che il soggetto abbia già un volto di riferimento memorizzato da una verifica approvata; gli utenti che non ne hanno uno vengono indirizzati al workflow predefinito della tua applicazione, con una nota sulla transazione che registra la sostituzione.

Best practice

Pratica	Perché
Passa sempre `vendor_data`	Consente l’aggregazione.
Usa il tuo `txn_id`	Idempotenza.
Iscriviti sia a `transaction.created` sia a `transaction.status.updated`	Intercetta i cambiamenti di stato asincroni (ad esempio, gli esiti delle revisioni degli analisti).
Imposta le soglie delle regole in modo deliberato	Soglie basse = più alert; soglie alte = più rischi non rilevati. Vedi punteggio di rischio.
Monitora nella console il numero di esecuzioni delle regole	Individua le regole che non si attivano mai (configurate in modo errato) o che si attivano su tutto (troppo permissive).
Testa le regole in modalità TEST prima di andare in produzione	Vedi regole.

Limiti di frequenza

Vedi limitazione della frequenza. La creazione di transazioni è uno degli endpoint con il più alto throughput; i limiti tipici si attestano nell’ordine delle centinaia di richieste al secondo. Gestisci con cautela i picchi di richieste.

Prossimi passi

Transazioni

Riferimento completo del payload.

Regole

Come vengono valutate le regole.

Webhook

Catalogo degli eventi.

Risoluzione dei problemi

Problemi comuni di integrazione.

Primi passi

Funzionalità

Riferimento

Console

Integrazione del Monitoraggio delle transazioni: API KYT

Architettura

Autenticazione

Invio di una transazione

Modellazione delle parti

Idempotenza

Tempo reale vs batch

Importazione dello storico

Webhook

Gestione degli stati

Collegamento delle transazioni alle entità

Sessioni di rimedio

Best practice

Limiti di frequenza

Prossimi passi

Transazioni

Regole

Webhook

Risoluzione dei problemi

​Architettura

​Autenticazione

​Invio di una transazione

​Modellazione delle parti

​Idempotenza

​Tempo reale vs batch

​Importazione dello storico

​Webhook

​Gestione degli stati

​Collegamento delle transazioni alle entità

​Sessioni di rimedio

​Best practice

​Limiti di frequenza

​Prossimi passi

Transazioni

Regole

Webhook

Risoluzione dei problemi

Architettura

Autenticazione

Invio di una transazione

Modellazione delle parti

Idempotenza

Tempo reale vs batch

Importazione dello storico

Webhook

Gestione degli stati

Collegamento delle transazioni alle entità

Sessioni di rimedio

Best practice

Limiti di frequenza

Prossimi passi