Vai al contenuto principale
Questa pagina descrive il payload completo restituito da POST /v3/transactions/ e GET /v3/transactions/{transaction_id}/. Entrambi gli endpoint restituiscono lo stesso oggetto TransactionDetail; il riferimento API riporta lo schema campo per campo, mentre questa pagina ne illustra la struttura.

​
Struttura di primo livello

Due identificatori descrivono la stessa transazione. uuid è l’identificatore stabile di Didit e va indicato nel percorso di GET /v3/transactions/{transaction_id}/; txn_id è il transaction_id che hai fornito al momento della creazione. transaction_number è il numero sequenziale, valido nell’ambito dell’applicazione, che la console mostra. Il soggetto e la controparte che hai inviato non compaiono come chiavi di primo livello. Sono le voci dell’array parties, distinte dal campo role, mentre vendor_data di primo livello è una copia di comodo del vendor_data dell’utente.

​
Campi principali

​
Campi finanziari

  • amount / currency: importo della transazione così come inviato. amount è una stringa decimale senza zeri finali ("1500", "0.5"), con fino a 18 cifre decimali.
  • currency_type: fiat o crypto, come inviato in currency_kind; null se omesso.
  • amount_in_default_currency / default_currency_code: l’importo già convertito che hai fornito nella richiesta, restituito così com’è; null se non lo hai inviato.
  • preferred_currency_amount / preferred_currency_code: amount convertito nella valuta preferita della tua applicazione. null quando non è disponibile un tasso di cambio per currency e non hai inviato amount_in_default_currency.
  • payment_details / payment_txn_id: il riferimento di pagamento in testo libero e il riferimento esterno del pagamento (ad esempio un hash di transazione blockchain) presenti nella richiesta.

​
Campi di stato

  • status: APPROVED, IN_REVIEW, DECLINED, AWAITING_USER. Le transazioni vengono create come APPROVED; le regole possono cambiarle in modo sincrono.
  • score: punteggio di rischio intero accumulato dalle regole. Un valore più alto indica un rischio maggiore.
  • severity: UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL, oppure null finché una regola o un provider non lo imposta.
  • decision_reason_code / decision_reason_label: motivo strutturato e motivo leggibile dello stato attuale.
  • environment: live o sandbox, in base all’applicazione a cui appartiene la transazione. Una transazione sandbox viene memorizzata ma non viene mai valutata, quindi il suo rule_runs vuoto significa “non valutata” e non “nessuna corrispondenza”. Vedi Monitoraggio delle transazioni in sandbox.
  • source: LIVE per le transazioni inviate tramite API o SDK, IMPORTED per le transazioni caricate tramite importazione CSV dalla console.

​
Parti

Ogni parte della transazione è una voce di parties. L’endpoint di creazione registra il soggetto come APPLICANT e la controparte facoltativa come COUNTERPARTY; l’enum role include anche REMITTER e BENEFICIARY. Tutte le voci hanno la stessa struttura.
  • role: APPLICANT, COUNTERPARTY, REMITTER, BENEFICIARY. Filtra su questo campo per trovare il soggetto.
  • entity_type: individual, company, external, unhostedWallet, come inviato.
  • kind: USER o BUSINESS quando la parte è collegata a un utente o a un’azienda di Didit tramite vendor_data; EXTERNAL in caso contrario.
  • country_code / dob: dal campo address.country e da date_of_birth inviati.
  • address / institution_info: gli oggetti così come inviati; {} se omessi.
  • external_party_snapshot: copia congelata dei dati della parte per le parti EXTERNAL; null finché la parte è collegata a un utente o a un’azienda di Didit.

​
device

device è il device_context che hai inviato per quella parte, normalizzato in snake_case, con l’arricchimento IP lato server. È {} quando la richiesta non conteneva alcun contesto del dispositivo, quindi tratta sempre ogni chiave come facoltativa. Non esiste un oggetto di arricchimento separato. Quando la parte include un network_context.ip_address pubblico, Didit lo risolve direttamente e scrive i campi arricchiti nello stesso oggetto network_context, compilando solo le chiavi che non hai fornito. Le chiavi per cui il resolver ha restituito valori vuoti vengono omesse, quindi un network_context completamente arricchito contiene le quattro chiavi inviate (ip_address, ip_country_code, latitude, longitude) più quelle tra ip_country, ip_state, ip_city, isp, organization, is_vpn_or_tor, is_data_center, time_zone, time_zone_offset, asn_number, asn_organization, connection_type, carrier e proxy_type che sono state risolte. is_vpn_or_tor e is_data_center sono sempre presenti dopo una risoluzione riuscita. L’arricchimento viene saltato e network_context viene restituito esattamente come inviato quando l’IP manca o non è instradabile, quando l’applicazione è in sandbox o quando la risoluzione non è riuscita. ip_country_code è un codice ISO 3166-1 alpha-2 quando Didit lo ha risolto, altrimenti è il valore che hai inviato; le condizioni delle regole normalizzano entrambe le forme prima del confronto.

​
Metodi di pagamento

  • role: SOURCE, DESTINATION, FUNDING, BENEFICIARY. L’endpoint di creazione assegna SOURCE / DESTINATION in base a direction: in una transazione in uscita il metodo del soggetto è SOURCE e quello della controparte è DESTINATION; in una transazione in entrata è l’inverso.
  • payment_method_type: bank_card, bank_account, e_wallet, crypto_wallet, unhosted_wallet, other.
  • fingerprint: SHA-256 calcolato su type:account_id:issuing_country, stabile tra le transazioni, così puoi correlare il riutilizzo dello stesso strumento. null quando non è stato inviato alcun account_id.
  • owner_kind / vendor_data / owner_name: chi è il proprietario dello strumento, con la stessa convenzione USER / BUSINESS / EXTERNAL usata per le parti.
  • details: l’oggetto payment_method grezzo così come inviato.

​
Esecuzioni delle regole

  • rule: UUID della regola eseguita; rule_title, rule_description, rule_category vengono copiati da essa.
  • matched: un’esecuzione viene registrata solo quando le condizioni della regola sono soddisfatte, quindi le valutazioni live riportano sempre matched: true. Le regole valutate senza corrispondenza non lasciano alcuna voce. I dati di esempio possono includere righe con matched: false.
  • is_test / mode: true e TEST quando la regola è stata eseguita in modalità test; un’esecuzione di test viene registrata ma non ha effetti su status, score o severity.
  • score_delta / status_target / severity: il contributo di questa esecuzione. status_target viene impostato quando è stata eseguita un’azione change_status oppure quando il punteggio aggiunto ha superato una soglia.
  • action_summary: riepilogo testuale delle azioni eseguite dalla regola, unite con ; (score +30, change_status:IN_REVIEW, add_tag:<name>, add_note, add_to_list, open_case); null quando la regola non ha eseguito alcuna azione.
  • metadata: il dettaglio della valutazione: scope_match, più conditions[] e aggregations[]. Le due liste usano chiavi di valore diverse:
    • conditions[]: una voce per condizione, con field, operator, expected_value, il current_value letto dalla transazione, matched, group_index e group_logic. field_source è sempre null nelle esecuzioni delle regole sulle transazioni; viene classificato solo per gli eventi di monitoraggio.
    • aggregations[]: una voce per ogni aggregazione di frequenza, conteggio o somma, con metric, field, operator, expected_value, il computed_value risultante dalla valutazione dell’aggregazione, window, filters, matched e sample_references. Le aggregazioni che possono essere calcolate solo in modo asincrono riportano computed_value: null e deferred: true.

​
Alert

alerts è oggi sempre un array vuoto. Un alert aperto corrisponde a una transazione trattenuta, quindi leggi invece status (IN_REVIEW o AWAITING_USER). Vedi Alert.

​
Attività

Il registro delle attività della transazione: creazione, note, revisioni manuali e modifiche di stato.
Le note dell’analista compaiono qui come voci TRANSACTION_NOTE_ADDED; non esiste un array notes separato.

​
Documenti

File allegati alla transazione dalla console. [] se non ce ne sono.
file_url è un URL firmato a breve scadenza; recuperalo quando ti serve invece di memorizzarlo.

​
Risultati dei provider

Output di provider esterni (screening dell’hash della transazione, screening dei wallet, monitoraggio fiat, screening delle sanzioni).
result_type: FIAT_MONITORING, WALLET_SCREENING, TRANSACTION_SCREENING, TRAVEL_RULE, NETWORK_GRAPH, CUSTOM. payload.risk_factors è la spiegazione ordinata di score: indica cosa ha prodotto il verdetto, prima i fattori ad alto rischio e poi in base al valore trasferito. Un score alto senza alcuna voce is_high_risk significa che il provider ha valutato l’entità con il proprio modello di esposizione senza segnalare una corrispondenza con sanzioni o con un’entità attribuita; summary lo dichiara esplicitamente. Riferimento campo per campo: Fattori di rischio. I risultati sottoposti a screening prima dell’introduzione di questo campo non includono la chiave. Per lo screening crittografico dell’hash delle transazioni, transaction_flows è popolato quando è disponibile l’arricchimento on-chain. Normalizza l’attività della catena in modo che la console possa mostrare sia la panoramica della transazione sia il grafo di visualizzazione a partire dallo stesso payload di risposta. Fonti di arricchimento supportate:
  • Le catene EVM usano Blockscout per normalizzare la transazione principale, le chiamate interne e i trasferimenti di token.
  • Bitcoin usa mempool.space per normalizzare input e output della transazione.
  • Solana usa Helius per normalizzare i trasferimenti nativi di SOL, i trasferimenti di token SPL e il contesto disponibile per gli eventi NFT.
Ogni elemento transaction_flows[] include campi normalizzati stabili (flow_type, from_address, to_address, amount, amount_usd, currency, token_name, token_address, transaction_hash, block_timestamp, index, success) più metadata specifici del provider. Esempi comuni di metadata:
metadata può contenere campi aggiuntivi e varia in base al provider. Non costruire integrazioni critiche che richiedano la presenza di ogni chiave per ogni catena.

​
Travel Rule

null quando la transazione non ha alcun trasferimento o controllo Travel Rule. Viene popolato quando invii travel_rule_details, e anche quando Travel Rule è abilitata per l’applicazione e la transazione è stata creata con transaction_category: "travelRule": in tal caso Didit avvia lo scambio autonomamente, con o senza travel_rule_details, e ne riporta qui lo status. Leggi questo campo invece della richiesta che hai inviato. Su un trasferimento in entrata, i dati originator_data e beneficiary_data della controparte restano mascherati (data_masked: true) finché non viene confermata la proprietà del wallet (vedi Dati della controparte mascherati).
direction, rail, counterparty_vasp, delivery, discovery, reason e next_actions hanno la stessa struttura dell’endpoint dei trasferimenti. reason e next_actions indicano perché un trasferimento con COUNTERPARTY_VASP_NOT_FOUND o COUNTERPARTY_VASP_NOT_REACHABLE è bloccato e cosa lo fa proseguire; valgono "" e [] per qualsiasi altro stato: vedi Perché un trasferimento è bloccato. Ogni riga di GET /v3/transactions/ contiene lo stesso blocco. Vedi Travel Rule.

​
Snapshot della rete

Il grafo memorizzato stesso, non un riferimento ad esso. Proviene da una delle due fonti:
  • un network_snapshot che hai inviato con la transazione, oppure
  • il grafo che Didit costruisce quando lo Screening AML dei wallet va a buon fine per una transazione crypto, anche se la richiesta non conteneva alcun network_snapshot. Un grafo costruito dallo screening sostituisce quello inviato, e un nuovo screening asincrono lo aggiorna.
null quando non esiste nessuno dei due:
La pagina di dettaglio della transazione nella console mostra lo stesso grafo.

​
Tag, metadata, props

  • tags[]: tag associati (tramite un’azione di una regola o da un analista): { "uuid", "name", "color", "description", "source" }, dove source è didit per un tag predefinito e custom per uno dei tuoi.
  • metadata: uno snapshot dei payload subject e counterparty esattamente come li hai inviati al momento della creazione, sotto queste due chiavi.
  • props: i custom_properties forniti al momento della creazione. Ogni chiave è indirizzabile nelle condizioni delle regole come custom_values.<key>.

​
Rimedio

Quando una regola attiva AWAITING_USER, Didit crea la sessione di verifica collegata e la restituisce in due campi:
  • remediation: la sessione collegata: { "session_id", "session_token", "url", "status" }. Resta popolato per tutta la durata della transazione, così puoi sempre vedere come si è conclusa l’azione dell’utente.
  • action_required: l’azione che l’utente deve compiere ora, oppure null quando non c’è nulla in sospeso: { "type": "verification_session", "url", "session_id", "session_token", "status" }. Reindirizza l’utente a url, oppure passa session_token a un SDK di Didit. Le azioni relative all’assetto proprietario del wallet della Travel Rule usano { "type": "wallet_ownership", "url", "widget_session_id", "expires_at" } e hanno la precedenza quando potrebbero applicarsi entrambe. Quando un’azione relativa all’assetto proprietario del wallet è in sospeso e la controparte del trasferimento non è stata trovata, lo stesso blocco contiene anche reason e next_actions (vedi individuazione della controparte).
Gli stessi due campi sono presenti nei payload dei webhook transaction.created e transaction.status.updated (action_required): vedi webhook.

​
Dettaglio dei costi

null finché non viene eseguita una funzionalità fatturabile per la transazione. Altrimenti { "total_price", "items": [ { "usage_type", "price", "details" } ] }, con un elemento per ogni funzionalità a consumo (screening, arricchimento e così via).

​
Conversione di valuta

preferred_currency_amount è amount convertito nella valuta preferita della tua applicazione, ai tassi di cambio medi di mercato, a meno che tu non abbia fornito amount_in_default_currency; in tal caso viene usato così com’è quel valore già convertito. Le condizioni delle regole su amount confrontano l’importo nella valuta originale; usa preferred_currency_amount nelle condizioni quando ti serve un’unica soglia valida per valute diverse.

​
Prossimi passi

Invia transazioni

Schema completo della richiesta.

Stati

Il significato di ciascuno stato.

Punteggio di rischio

Come viene calcolato il punteggio.
Ultima modifica il 7 novembre 2026