Vai al contenuto principale
POST
curl

Autorizzazioni

x-api-key
string
header
obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Corpo

application/json
transaction_id
string
obbligatorio

Il tuo identificatore univoco per questa transazione (massimo 128 caratteri).

Esempio:

"your-txn-2026-05-17-001"

transaction_category
enum<string>
obbligatorio

Categoria della transazione. Sono accettati anche alias CamelCase (travelRule, userPlatformEvent, gamblingBet, …); il valore memorizzato/restituito è in camelCase per le categorie composte da più parole.

Opzioni disponibili:
finance,
kyc,
travel_rule,
user_event,
audit_trail_event,
gambling_bet,
gambling_limit_change,
gambling_bonus_change,
travelRule
Esempio:

"finance"

transaction_details
object
obbligatorio

Dettagli finanziari principali della transazione.

subject
object
obbligatorio

Il soggetto (richiedente) della transazione.

transaction_at
string<date-time>

Quando è avvenuta la transazione. Se omesso, il valore predefinito è adesso.

time_zone
string

Identificatore di fuso orario IANA, ad es. Europe/Madrid.

counterparty
object

La controparte della transazione (opzionale).

custom_properties
object

Coppie chiave-valore arbitrarie allegate alla transazione. Ciascuna chiave può essere richiamata nelle condizioni delle regole con il percorso di campo custom_values.<key>.

Esempio:
travel_rule_details
object

Dati Travel Rule. Quando Travel Rule è abilitata e transaction_category è travel_rule, Didit gestisce lo scambio direttamente: ignora status, protocol, required e obligations_count e utilizza originator_data, beneficiary_data e metadata. Altrimenti Didit memorizza questi valori come record Travel Rule passivo. Quando Travel Rule è attiva, un trasferimento in uscita pari o superiore alla soglia deve includere quanto richiesto dal relativo regime (TFR UE o Raccomandazione 16 del GAFI), verificato sulle parti inviate: un campo mancante restituisce 400 sotto travel_rule_details.originator_data o travel_rule_details.beneficiary_data, ad esempio "Il TFR UE richiede il nome dell'ordinante."

network_snapshot
object

Istantanea precalcolata del grafo di rete.

include_crypto_screening
boolean | null

Sostituzione per singola transazione per lo screening di analisi della blockchain crypto. Quando è true, lo screening crypto viene eseguito indipendentemente dal valore predefinito dell'applicazione. Quando è false, lo screening crypto viene saltato anche se abilitato nelle impostazioni dell'applicazione. Se omesso o null, viene utilizzato il valore predefinito a livello di applicazione configurato nella Console. Lo screening crypto richiede transaction_details.direction, currency_kind: "crypto", una blockchain/valuta e l'indirizzo del wallet selezionato in base alla direzione: lo screening in entrata pre-trasferimento utilizza counterparty.payment_method.account_id, lo screening in entrata con hash di transazione utilizza subject.payment_method.account_id, e lo screening in uscita utilizza counterparty.payment_method.account_id. Quando transaction_details.payment_reference_id contiene l'hash di una transazione blockchain, Didit esegue lo screening della transazione e restituisce l'arricchimento del riepilogo della transazione quando disponibile.

Risposta

Transazione inviata e monitorata. Il corpo contiene il dettaglio completo della transazione (stessa struttura di GET /v3/transactions/{transaction_id}/), che riflette gli esiti delle regole già applicati.

Record di monitoraggio completo per una transazione, come restituito da GET /v3/transactions/{transaction_id}/ e POST /v3/transactions/.

uuid
string<uuid>

Identificativo della transazione stabile di Didit. Utilizzalo come {transaction_id} per le chiamate successive.

environment
enum<string>

Ambiente dell'applicazione proprietaria della transazione. Una transazione in sandbox viene archiviata ma non viene mai valutata, sottoposta a screening, notificata o fatturata; pertanto, il valore vuoto di rule_runs indica "non valutata".

Opzioni disponibili:
live,
sandbox
transaction_number
integer

Numero sequenziale della transazione con ambito limitato all'applicazione mostrato nella Console (es. 4123).

txn_id
string

Il transaction_id fornito al momento della creazione (max 128 caratteri). Univoco per applicazione.

txn_date
string<date-time>

Quando è avvenuta la transazione (da transaction_at; il valore predefinito è il momento dell'invio).

zone_id
string | null

Identificatore di fuso orario IANA fornito al momento della creazione.

transaction_type
string

Categoria di primo livello così come memorizzata: finance, kyc, travelRule, userPlatformEvent, gamblingBet, gamblingLimitChange, gamblingBonusChange, auditTrailEvent. Nota che i valori composti da più parole vengono restituiti in camelCase anche se inviati in snake_case.

action_type
string

Sottotipo all'interno della categoria (ad es. deposit, withdrawal, transfer). Se non specificato, il valore predefinito coincide con la categoria.

direction
enum<string>

Direzione rispetto al soggetto. Memorizzato in maiuscolo indipendentemente dal formato inviato (in/out/inbound/outbound sono accettati in input).

Opzioni disponibili:
INBOUND,
OUTBOUND
status
enum<string>

Verdetto di monitoraggio attuale. Le transazioni vengono create come APPROVED; le regole possono modificarle in IN_REVIEW/DECLINED in modo sincrono.

Opzioni disponibili:
APPROVED,
IN_REVIEW,
DECLINED,
AWAITING_USER
source
enum<string>

In che modo ha avuto origine il record: LIVE per le transazioni inviate tramite API o SDK, IMPORTED per le transazioni caricate tramite l'importazione da console.

Opzioni disponibili:
LIVE,
IMPORTED
amount
string

Importo della transazione come stringa decimale senza zeri finali (es. "1500", "0.5", "0.123456789012345678"). Fino a 18 cifre decimali.

currency
string

Codice valuta di amount. Viene accettato qualsiasi codice alfabetico ISO 4217 (ad es. EUR, USD, NGN), così come il simbolo di un asset crypto (ad es. BTC). È preferibile utilizzare un codice attualmente in circolazione. Non tutti i codici accettati hanno un tasso di cambio: quando non ne è disponibile alcuno per il codice (ad esempio l'unità di conto ISO XSU o un simbolo crypto di cui Didit non calcola il prezzo), la conversione automatica non riesce e preferred_currency_amount viene restituito null a meno che la richiesta non abbia fornito un amount_in_default_currency pre-convertito.

currency_type
string | null

fiat o crypto, come inviato in currency_kind.

amount_in_default_currency
string | null

Importo pre-convertito fornito dall'utente, come stringa decimale priva di zeri finali.

default_currency_code
string | null
preferred_currency_amount
string | null

amount convertito nella valuta preferita dell'applicazione, se disponibile.

preferred_currency_code
string | null
payment_details
string | null

Riferimento di pagamento o promemoria in formato testo libero derivante dall'invio.

payment_txn_id
string | null

Riferimento del sistema di pagamento esterno (ad es. hash della transazione blockchain) da payment_reference_id.

score
integer

Punteggio di rischio accumulato dalle regole (in genere 0–100). Più alto = più rischioso.

severity
enum<string> | null

Gravità categoriale del rischio impostata da regole/provider (UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL). null finché non viene impostata.

Opzioni disponibili:
UNKNOWN,
LOW,
MEDIUM,
HIGH,
CRITICAL
decision_reason_code
string | null

Motivo leggibile dalla macchina per il status attuale.

decision_reason_label
string | null

Etichetta di facile lettura per decision_reason_code.

vendor_data
string | null

Copia per comodità di vendor_data del richiedente.

metadata
object

Istantanea dei payload di subject e counterparty così come inviati al momento della creazione.

props
object

Le custom_properties fornite al momento della creazione. Ciascuna chiave è accessibile nelle condizioni delle regole come custom_values.<key>.

tags
object[]

Tag associati alla transazione (manualmente o tramite regole).

parties
object[]

Parti della transazione (richiedente, controparte).

payment_methods
object[]

Metodi di pagamento collegati alla transazione.

documents
object[]

File allegati alla transazione dalla console. [] se non ce ne sono.

activities
object[]

Voci del registro delle attività (creazione, note, revisioni manuali, modifiche di stato).

alerts
object[]

Attualmente sempre vuoto. Un alert aperto è una transazione con stato IN_REVIEW o AWAITING_USER.

rule_runs
object[]

Risultati dell'esecuzione per regola: quale regola è scattata, con quale impatto sul punteggio.

provider_results
object[]

Payload non elaborati del provider (screening AML, analisi blockchain, ecc.).

travel_rule
object | null

Trasferimento o controllo Travel Rule. Valorizzato quando travel_rule_details è stato inviato e anche quando Travel Rule è abilitata e la transazione è stata creata con transaction_category: travelRule (Didit avvia lo scambio direttamente, anche senza travel_rule_details). null quando non esiste alcun trasferimento o controllo. In un trasferimento in entrata, originator_data e beneficiary_data della controparte rimangono mascherati (data_masked: true) finché non viene confermato l'assetto proprietario del wallet.

network_snapshot
object | null

Snapshot del grafo delle transazioni/parti correlate utilizzato dal motore di regole. È il network_snapshot inviato con la transazione oppure il grafo che Didit crea da uno Screening AML del wallet riuscito (che sostituisce quello inviato). null quando nessuno dei due è presente.

remediation
object | null

Sessione di remediation offerta all'utente quando è richiesta una nuova verifica. Sostituita da action_required, che costituisce il blocco canonico; mantenuta per retrocompatibilità.

action_required
Verification session · object

Azione richiesta all'utente finale e ancora in sospeso per completare questa transazione, oppure null quando non ce n'è alcuna. Gli SDK di Didit avviano automaticamente l'azione per impostazione predefinita e aggiornano la transazione al termine. Due varianti, distinte da type: verification_session (una sessione di verifica ospitata creata da un'azione di una regola) e wallet_ownership (una sessione del widget di proprietà del wallet generata automaticamente per un trasferimento Travel Rule che richiede la prova di controllo del wallet, regolata dall'impostazione Travel Rule auto_wallet_verification). Quando potrebbero essere applicate entrambe, wallet_ownership ha la precedenza perché blocca lo scambio Travel Rule.

cost_breakdown
object | null

Costo di questa transazione: total_price e items, uno per ogni addebito, ciascuno con usage_type, price, details e created_at. Un nuovo screening della stessa transazione costituisce una nuova voce.

Ultima modifica il 7 novembre 2026