> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Invio transazioni API: payload e modello dei dati > Con Didit invii le transazioni per il monitoraggio in tempo reale: parti, pagamenti, dispositivo. 1,000 al mese incluse, poi $0.001 ciascuna. Invia le transazioni a Didit tramite l'API [Crea transazione](https://docs.didit.me/it/management-api/transactions/create.md). Ogni transazione include dati strutturati su parti, pagamento e contesto, che il motore di regole valuta in tempo reale. > [!TIP] > > 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](https://docs.didit.me/it/transaction-monitoring/sdk-transaction-submission.md): 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](https://docs.didit.me/it/management-api/users/list.md) o a un [profilo aziendale](https://docs.didit.me/it/business-verification/business-profiles.md) | | `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](https://docs.didit.me/it/transaction-monitoring/travel-rule.md#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 | > [!NOTE] > > `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. ```json theme={null} "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.`: 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](https://docs.didit.me/it/transaction-monitoring/rules.md#riferimento-alle-proprietà-personalizzate) per i dettagli. ## Esempio di richiesta ```bash theme={null} 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](https://docs.didit.me/it/management-api/transactions/create.md) per lo schema completo di richiesta e risposta, e il [riferimento dedicato allo schema della risposta](https://docs.didit.me/it/transaction-monitoring/response-schema.md) 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. ```bash theme={null} 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": [""], "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](https://docs.didit.me/it/management-api/transactions/list.md) 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}/`](https://docs.didit.me/it/management-api/transactions/get) 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](https://docs.didit.me/it/transaction-monitoring/integration-guide.md#importazione-dello-storico). ## Passaggi successivi > [card] [Regole e punteggio](https://docs.didit.me/it/transaction-monitoring/rules.md) > > Come le transazioni inviate vengono valutate rispetto alle regole. > [card] [Schema della risposta](https://docs.didit.me/it/transaction-monitoring/response-schema.md) > > Payload completo della risposta, con annotazioni. > [card] [Screening crypto](https://docs.didit.me/it/transaction-monitoring/aml-screening.md) > > Screening automatico di wallet e transazioni per le transazioni crypto. > [card] [Travel Rule](https://docs.didit.me/it/transaction-monitoring/travel-rule.md) > > Allega i dati di conformità alla Travel Rule ai trasferimenti di asset virtuali. > [card] [Arricchimento IP](https://docs.didit.me/it/transaction-monitoring/ip-enrichment.md) > > Contesto derivato dall'IP disponibile per le regole. > [card] [Riferimento API](https://docs.didit.me/it/management-api/transactions/create.md) > > Schema completo della richiesta per l'endpoint Create Transaction. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.