Invio transazioni API: payload e modello dei dati

Invia le transazioni a Didit tramite l’API Crea transazione. Ogni transazione include dati strutturati su parti, pagamento e contesto, che il motore di regole valuta in tempo reale.

Quando la transazione nasce sul dispositivo di un utente finale, ad esempio un prelievo crypto o un pagamento in app, valuta l’uso della trasmissione della transazione tramite SDK: un token con ambito limitato sostituisce la chiave API, le informazioni sul dispositivo vengono raccolte automaticamente e le azioni richieste all’utente (prova di proprietà del wallet, verifica rafforzata) si avviano sul momento.

Categorie di transazione

Ogni transazione ha un transaction_category che determina come la trattano regole e analisi:

Categoria	Descrizione
`finance`	Transazione finanziaria standard (deposito, prelievo, trasferimento)
`kyc`	Evento legato alla verifica dell’identità
`travel_rule`	Trasferimento di asset virtuali che richiede la conformità alla Travel Rule
`user_event`	Evento personalizzato della piattaforma (accesso, modifica del profilo, ecc.)
`gambling_bet`	Scommessa o puntata di gioco
`gambling_limit_change`	Modifica del limite di deposito, perdita o puntata di un giocatore
`gambling_bonus_change`	Assegnazione, riscatto o perdita di un bonus
`audit_trail_event`	Evento di audit di sistema o di compliance

Dettagli della transazione

L’oggetto transaction_details contiene i dati finanziari:

Campo	Tipo	Descrizione
`direction`	string	`inbound` oppure `outbound`
`amount`	string	Valore della transazione come stringa decimale (ad esempio `"1500.50"`)
`currency`	string	Codice valuta ISO (ad esempio `USD`, `EUR`, `BTC`)
`currency_kind`	string	`fiat` oppure `crypto` (alias `currencyType`); determina se lo screening crypto viene attivato
`action_type`	string	Etichetta dell’azione definita dal fornitore (ad esempio `deposit`, `withdrawal`, `purchase`)
`payment_details`	string	Descrizione libera del pagamento (ad esempio `"Bank transfer from ABC Corp"`)
`payment_reference_id`	string	Identificativo di riferimento esterno del pagamento. Per lo screening crypto successivo al trasferimento, usa l’hash della transazione sulla blockchain.

Soggetto e controparte

Ogni transazione ha un soggetto (obbligatorio) e una controparte (facoltativa). Entrambi usano lo stesso modello di parte:

Campo	Tipo	Descrizione
`entity_type`	string	`person` oppure `company`
`vendor_data`	string	Il tuo identificativo per questa parte: collega la transazione a un utente o a un profilo aziendale
`full_name`	string	Nome completo della parte
`first_name`	string	Nome di battesimo
`last_name`	string	Cognome
`date_of_birth`	string	Data ISO (ad esempio `1990-01-15`)
`country_code`	string	Codice paese ISO 3166-1 alpha-2
`address`	object o string	Indirizzo strutturato con `street`, `city`, `state`, `country`, `postal_code`. Accetta anche una stringa semplice, come un indirizzo per una controparte crypto: Didit la memorizza invariata nella parte.

Quando address è un oggetto, Didit ricava il country_code della parte da address.country. Quando address è una stringa, il country_code di quella parte viene restituito come null. Quando vendor_data corrisponde a un utente o a un’azienda esistente, Didit collega automaticamente la transazione al profilo di quell’entità, abilitando la valutazione delle regole tra sessioni diverse e i controlli di velocità. Nella risposta, entrambe le parti vengono restituite nell’array parties con i ruoli APPLICANT e COUNTERPARTY.

Metodi di pagamento

Allega un payment_method a ciascuna parte per descrivere lo strumento di quel lato:

Campo	Tipo	Descrizione
`method_type`	string	`bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet` oppure `other` (alias `type`); `ewallet`, `card` e `crypto` sono accettati come alias, e un valore non riconosciuto viene memorizzato come `other`
`account_id`	string	Numero di conto, indirizzo wallet o token della carta
`issuing_country`	string	Paese che ha emesso lo strumento di pagamento

Nelle transazioni travelRule, un metodo di pagamento della controparte con method_type: "unhosted_wallet" (alias type) dichiara il wallet della controparte come wallet in autocustodia. Quando la Travel Rule è attiva e l’importo, nella valuta predefinita della tua applicazione, non è inferiore a threshold_amount, il trasferimento passa direttamente a UNCONFIRMED_OWNERSHIP e al flusso di prova di proprietà: vedi Wallet in autocustodia dichiarati. Per le transazioni crypto, includi gli indirizzi wallet in account_id e imposta currency_kind su crypto, così lo screening blockchain può essere eseguito automaticamente. La direzione controlla quale wallet viene sottoposto a screening: lo screening inbound prima del trasferimento usa il wallet mittente in counterparty.payment_method.account_id; lo screening outbound usa il wallet di destinazione in counterparty.payment_method.account_id. Se invii un hash blockchain in transaction_details.payment_reference_id, lo screening inbound della transazione richiede l’indirizzo di deposito del tuo servizio in subject.payment_method.account_id, mentre lo screening outbound della transazione richiede il wallet di destinazione in counterparty.payment_method.account_id.

Sovrascrittura dello screening crypto

Usa include_crypto_screening al livello superiore della richiesta per sostituire il valore predefinito configurato in Transazioni > Impostazioni nella Console:

Valore	Descrizione
`true`	Forza lo screening crypto per questa transazione
`false`	Salta lo screening crypto per questa transazione
omesso o `null`	Usa il valore predefinito a livello di applicazione

Contesto del dispositivo

Includi le informazioni sul dispositivo nella parte relativa al soggetto (e, facoltativamente, in quella relativa alla controparte) per alimentare le regole di analisi del dispositivo. Il campo della richiesta è device_context su ciascuna parte; è accettato anche l’alias in camelCase device, che è quello usato dal formato di trasmissione dell’SDK. La risposta lo restituisce come device su ciascuna parte nell’array parties.

Campo	Tipo	Descrizione
`device_context.fingerprint`	stringa	Fingerprint univoco del dispositivo
`device_context.persistent_device_id`	stringa	Identificatore stabile del dispositivo tra sessioni diverse (schema di fingerprint v2)
`device_context.user_agent`	stringa	Stringa user agent del browser o dell’app
`device_context.browser_family`	stringa	Famiglia del browser (ad esempio `Chrome`, `Firefox`, `Safari`). Deve essere inviato esplicitamente: non viene ricavato da `user_agent`. Alimenta regole come `subject_browser_family`.
`device_context.browser_version`	stringa	Stringa della versione del browser (ad esempio `131.0`). Deve essere inviato esplicitamente.
`device_context.platform`	stringa	Identificatore della piattaforma (`web`, `ios`, `android`, `macos`, `windows`, `linux`). Deve essere inviato esplicitamente: non viene ricavato da `user_agent`. Alimenta regole come `subject_platform`.
`device_context.os_family`	stringa	Famiglia del sistema operativo (ad esempio `iOS`, `Android`, `Windows`)
`device_context.os_version`	stringa	Stringa della versione del sistema operativo
`device_context.accept_language`	stringa	Valore dell’intestazione Accept-Language (ad esempio `en-US,en;q=0.9`). Nel percorso SDK viene raccolto automaticamente.
`device_context.session_id`	stringa	Identificatore della sessione corrente dell’utente. Viene memorizzato nei metadati. Alias in camelCase: `sessionId`.
`device_context.session_age_ms`	numero	Durata della sessione dell’utente, in millisecondi, al momento della transazione. Alimenta regole come `subject_session_age_ms`.
`device_context.network_context.ip_address`	stringa	Indirizzo IP del client
`device_context.network_context.ip_country_code`	stringa	Paese dell’IP, risolto tramite geolocalizzazione (ISO 3166-1 alpha-3)
`device_context.network_context.latitude`	numero	Latitudine geografica dell’IP
`device_context.network_context.longitude`	numero	Longitudine geografica dell’IP

browser_family e platform non vengono ricavati da user_agent. Devono essere inviati come chiavi esplicite di primo livello all’interno di device_context, altrimenti le regole di analisi del dispositivo non si attivano. Se usi l’SDK di Didit, questi campi vengono raccolti automaticamente.

Sono accettati alias in camelCase per ogni campo: userAgent, browserFamily, browserVersion, osFamily, osVersion, acceptLang, sessionId, sessionAgeMs. L’oggetto network_context accetta gli alias ip / countryCode3 / lat / lon, e un blocco ipInfo di primo livello viene anch’esso unito a network_context. Il contesto del dispositivo abilita regole come il rilevamento del multi-account (stesso fingerprint su soggetti diversi), il rilevamento della combinazione di un nuovo browser e di un nuovo IP, i trasferimenti di valore elevato con una sessione di breve durata e il punteggio di rischio basato sulla posizione.

Proprietà personalizzate

Aggiungi qualsiasi altra coppia chiave-valore nell’oggetto custom_properties. Le regole possono fare riferimento a questi campi nelle loro condizioni: è utile per passare un contesto specifico dell’azienda, come la categoria di prodotto, l’ID dell’esercente o il canale.

"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}

Nelle condizioni delle regole, fai riferimento a ogni chiave con il percorso del campo custom_values.<key>: ad esempio, il payload sopra corrisponde a custom_values.product_category eq "electronics". Nel generatore di regole della Console, le chiavi viste nelle transazioni acquisite di recente compaiono nel selettore dei campi delle condizioni sotto Proprietà personalizzate, e Inserisci proprietà personalizzata nello stesso gruppo ti permette di digitare manualmente qualsiasi chiave (con distinzione tra maiuscole e minuscole). Vedi Regole e punteggio per i dettagli.

Esempio di richiesta

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'

Risposta

L’API restituisce la transazione creata con i risultati della valutazione iniziale:

Campo	Tipo	Descrizione
`uuid`	stringa	Identificatore univoco della transazione in Didit
`txn_id`	stringa	L’ID della transazione che hai fornito
`status`	stringa	`APPROVED`, `IN_REVIEW`, `DECLINED` o `AWAITING_USER`
`score`	numero	Punteggio di rischio cumulativo di tutte le regole corrispondenti
`severity`	stringa	Gravità più alta tra le regole corrispondenti (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`decision_reason_code`	stringa	Motivo leggibile dalle macchine della decisione sullo stato
`decision_reason_label`	stringa	Descrizione leggibile della decisione

Consulta il Riferimento API per lo schema completo di richiesta e risposta, e il riferimento dedicato allo schema della risposta per una spiegazione annotata del payload.

Assegnare una transazione a un revisore

Assegna una transazione in attesa a un membro della tua applicazione, oppure rimuovi l’assegnazione, con una chiave API che ha il privilegio write:transactions. Ogni modifica viene registrata nella cronologia della transazione come TRANSACTION_ASSIGNED.

Chiamata	Uso
`POST /v3/transactions/{transaction_uuid}/assign/`	Assegna una transazione.
`POST /v3/transactions/assign/`	Assegna fino a 500 transazioni a un membro.

Entrambe le chiamate accettano assignee_email, l’email di un membro dell’applicazione che ha effettuato l’accesso a Didit. Invia null o una stringa vuota per rimuovere l’assegnazione. La chiamata multipla accetta anche transaction_ids, un elenco da 1 a 500 UUID di transazioni.

curl -X POST "https://verification.didit.me/v3/transactions/assign/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_ids": ["<transaction-uuid>"], "assignee_email": "analyst@example.com"}'

La chiamata singola restituisce uuid, transaction_number, assignee e changed (false se la transazione aveva già questo assegnatario), oppure 404 se la transazione non esiste nell’applicazione. La chiamata multipla restituisce transactions (una voce come quella sopra), updated_count e not_found_transaction_ids. Filtra l’elenco delle transazioni con assignee, un elenco separato da virgole in cui basta che un valore corrisponda: me, unassigned, rules (decisa solo dalle regole, senza intervento di un revisore) oppure l’email di un membro.

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. sul campo transaction_id, e due richieste identiche inviate contemporaneamente restituiscono alla seconda un 409. Nessuna delle due risposte restituisce la transazione esistente. Per ritentare in sicurezza, tratta un 400 o un 409 per un transaction_id duplicato come “già creata” e 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 di Didit) che il webhook transaction.created riporta accanto al tuo txn_id. Genera sempre txn_id sul tuo lato (ad esempio l’ID del tuo database delle transazioni, un UUID o un hash deterministico).

Caricamento storico

Passa un txn_date nel passato per importare transazioni storiche. Le regole vengono comunque valutate per impostazione predefinita: se durante i caricamenti storici in blocco vuoi saltare la valutazione delle regole, usa l’importazione CSV dalla console in modalità dry-ingest. Vedi la guida all’integrazione.

Passaggi successivi

Regole e punteggio

Come le transazioni inviate vengono valutate rispetto alle regole.

Schema della risposta

Payload completo della risposta, con annotazioni.

Screening crypto

Screening automatico di wallet e transazioni per le transazioni crypto.

Travel Rule

Allega i dati di conformità alla Travel Rule ai trasferimenti di asset virtuali.

Arricchimento IP

Contesto derivato dall’IP disponibile per le regole.

Riferimento API

Schema completo della richiesta per l’endpoint Create Transaction.

Primi passi

Funzionalità

Riferimento

Console

Invio transazioni API: payload e modello dei dati

Categorie di transazione

Dettagli della transazione

Soggetto e controparte

Metodi di pagamento

Sovrascrittura dello screening crypto

Contesto del dispositivo

Proprietà personalizzate

Esempio di richiesta

Risposta

Assegnare una transazione a un revisore

Idempotenza

Caricamento storico

Passaggi successivi

Regole e punteggio

Schema della risposta

Screening crypto

Travel Rule

Arricchimento IP

Riferimento API

​Categorie di transazione

​Dettagli della transazione

​Soggetto e controparte

​Metodi di pagamento

​Sovrascrittura dello screening crypto

​Contesto del dispositivo

​Proprietà personalizzate

​Esempio di richiesta

​Risposta

​Assegnare una transazione a un revisore

​Idempotenza

​Caricamento storico

​Passaggi successivi

Regole e punteggio

Schema della risposta

Screening crypto

Travel Rule

Arricchimento IP

Riferimento API

Categorie di transazione

Dettagli della transazione

Soggetto e controparte

Metodi di pagamento

Sovrascrittura dello screening crypto

Contesto del dispositivo

Proprietà personalizzate

Esempio di richiesta

Risposta

Assegnare una transazione a un revisore

Idempotenza

Caricamento storico

Passaggi successivi