POST /v3/transactions/ i GET /v3/transactions/{transaction_id}/. Tots dos endpoints retornen el mateix objecte TransactionDetail. La referència de l’API conté l’esquema camp per camp, i aquesta pàgina n’explica el contingut pas a pas.
Estructura de primer nivell
uuid és l’identificador estable de Didit i és el que GET /v3/transactions/{transaction_id}/ espera al camí de la URL. txn_id és el transaction_id que vas proporcionar en el moment de crear la transacció. transaction_number és el número seqüencial associat a l’aplicació que mostra la consola.
El subjecte i la contrapart que vas enviar no es retornen com a claus de primer nivell. Són les entrades de l’array parties, que es distingeixen pel role, i vendor_data de primer nivell és una còpia pràctica del vendor_data del sol·licitant.
Camps clau
Camps financers
amount/currency— import de la transacció tal com s’ha enviat.amountés una cadena decimal sense zeros finals ("1500","0.5"), amb fins a 18 decimals.currency_type—fiatocrypto, tal com s’ha enviat acurrency_kind;nullsi s’ha omès.amount_in_default_currency/default_currency_code— l’import prèviament convertit que has proporcionat a la sol·licitud, retornat tal com l’has enviat;nullsi no n’has enviat cap.preferred_currency_amount/preferred_currency_code—amountconvertit a la moneda preferida de la teva aplicació.nullquan no hi ha cap tipus de canvi disponible per acurrencyi no has enviatamount_in_default_currency.payment_details/payment_txn_id— la referència de pagament en text lliure i la referència externa de pagament (per exemple, un hash de transacció de blockchain) de la sol·licitud.
Camps d’estat
status—APPROVED,IN_REVIEW,DECLINED,AWAITING_USER. Les transaccions es creen com aAPPROVED; les regles poden canviar-ne l’estat de manera síncrona.score— puntuació de risc entera acumulada per les regles. Com més alta, més risc.severity—UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL, onullfins que una regla o un proveïdor la establisca.decision_reason_code/decision_reason_label— motiu estructurat i motiu llegible per a les persones de l’estat actual.environment-liveosandbox, des de l’aplicació que és propietària de la transacció. Una transacciósandboxs’emmagatzema però mai s’avalua, de manera que el seurule_runsbuit vol dir «no avaluada» i no «cap coincidència». Consulta Monitoratge de transaccions en sandbox.source-LIVEper a les transaccions enviades mitjançant l’API o el SDK,IMPORTEDper a les transaccions carregades mitjançant la importació CSV de la consola.
Parts
Cada part de la transacció és una entrada departies. L’endpoint de creació registra el subjecte com a APPLICANT i la contrapart opcional com a COUNTERPARTY; l’enumeració role també inclou REMITTER i BENEFICIARY. Totes les entrades comparteixen la mateixa estructura.
role—APPLICANT,COUNTERPARTY,REMITTER,BENEFICIARY. Filtra per aquest camp per trobar el subjecte.entity_type—individual,company,external,unhostedWallet, tal com s’ha enviat.kind—USERoBUSINESSquan la part està vinculada a un usuari o a una empresa de Didit mitjançantvendor_data;EXTERNALen cas contrari.country_code/dob— a partir deaddress.countryidate_of_birthenviats.address/institution_info— els objectes tal com s’han enviat;{}si s’han omès.external_party_snapshot— còpia congelada de les dades de la part per a les partsEXTERNAL;nullmentre la part estigui vinculada a un usuari o a una empresa de Didit.
device
device és el device_context que has enviat per a aquesta part, normalitzat a snake_case, més l’enriquiment de la IP fet al servidor. És {} quan la sol·licitud no contenia cap context de dispositiu, de manera que cal tractar sempre cada clau com a opcional.
No hi ha cap objecte d’enriquiment separat. Quan la part tenia un
network_context.ip_address públic, Didit el resol en línia i escriu els camps enriquits al mateix objecte network_context, omplint només les claus que no has proporcionat. Les claus que el resolutor ha retornat buides s’ometen, de manera que un network_context completament enriquit conté les quatre claus enviades (ip_address, ip_country_code, latitude, longitude) més les que s’hagin resolt entre 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 i proxy_type. is_vpn_or_tor i is_data_center sempre hi són després d’una resolució correcta.
L’enriquiment s’omet, i network_context es retorna exactament tal com s’ha enviat, quan falta la IP o no és encaminable, quan l’aplicació és a sandbox, o quan la resolució ha fallat. ip_country_code és un codi ISO 3166-1 alpha-2 quan Didit l’ha resolt, i el que hagis enviat en cas contrari; les condicions de les regles normalitzen les dues formes abans de comparar-les.
Mètodes de pagament
role—SOURCE,DESTINATION,FUNDING,BENEFICIARY. L’endpoint de creació assignaSOURCE/DESTINATIONa partir dedirection: en una transacció de sortida, el mètode del subjecte és elSOURCEi el de la contrapart és elDESTINATION; en una d’entrada, és a la inversa.payment_method_type—bank_card,bank_account,e_wallet,crypto_wallet,unhosted_wallet,other.fingerprint— SHA-256 sobretype:account_id:issuing_country, estable entre transaccions perquè puguis correlacionar la reutilització del mateix instrument.nullquan no s’ha enviat capaccount_id.owner_kind/vendor_data/owner_name— qui és el titular de l’instrument, seguint la mateixa convencióUSER/BUSINESS/EXTERNALque les parts.details— l’objectepayment_methodtal com s’ha enviat.
Execucions de regles
rule— UUID de la regla que s’ha executat;rule_title,rule_descriptionirule_categoryse n’han copiat.matched— només es registra una execució quan es compleixen les condicions de la regla, de manera que les avaluacions reals sempre portenmatched: true. Les regles que s’han avaluat sense coincidir no deixen cap entrada. Les dades de demostració poden incloure files ambmatched: false.is_test/mode—trueiTESTquan la regla s’ha executat en mode de prova; una execució de prova es registra però no afectastatus,scoreniseverity.score_delta/status_target/severity— allò que ha aportat aquesta execució.status_targets’estableix quan s’ha executat una accióchange_status, o quan la puntuació afegida ha superat un llindar.action_summary— un resum en text de les accions que ha executat la regla, unides amb;(score +30,change_status:IN_REVIEW,add_tag:<name>,add_note,add_to_list,open_case);nullquan la regla no ha executat cap acció.metadata— el detall de l’avaluació:scope_match, així comconditions[]iaggregations[]. Les dues llistes fan servir claus de valor diferents:conditions[]— una entrada per condició ambfield,operator,expected_value, elcurrent_valuellegit de la transacció,matched,group_indexigroup_logic.field_sourceés semprenulla les execucions de regles de transacció; només es classifica per als esdeveniments de monitoratge.aggregations[]— una entrada per cada agregació de velocitat, recompte o suma ambmetric,field,operator,expected_value, elcomputed_valueque ha produït l’agregació,window,filters,matchedisample_references. Les agregacions que només es poden calcular de manera asíncrona portencomputed_value: nullideferred: true.
Alertes
alerts és sempre un array buit actualment.
Una alerta oberta és una transacció retinguda, així que llegeix status (IN_REVIEW o AWAITING_USER) en el seu lloc. Consulta Alertes.
Activitats
El registre d’activitat de la transacció: creació, notes, revisions manuals i canvis d’estat.TRANSACTION_NOTE_ADDED; no hi ha cap array notes independent.
Documents
Fitxers adjuntats a la transacció des de la consola.[] quan no n’hi ha cap.
file_url és una URL signada de vida curta; obtén-la quan la necessitis en lloc d’emmagatzemar-la.
Resultats dels proveïdors
Resultats dels proveïdors externs (cribratge de hash de transaccions, cribratge de carteres, monitoratge fiat i cribratge de sancions).result_type: FIAT_MONITORING, WALLET_SCREENING, TRANSACTION_SCREENING, TRAVEL_RULE, NETWORK_GRAPH, CUSTOM.
payload.risk_factors és l’explicació ordenada de score: què ha produït el veredicte, primer els factors d’alt risc i després per valor mogut. Un score alt sense cap entrada is_high_risk vol dir que el proveïdor ha valorat l’entitat amb el seu propi model d’exposició sense informar de cap coincidència amb sancions ni amb una entitat atribuïda; summary ho indica explícitament. Referència camp per camp: Factors de risc. Els resultats cribats abans que existís aquest camp no contenen la clau.
Per al cribratge de hash de transaccions cripto, transaction_flows s’omple quan hi ha enriquiment on-chain disponible. Normalitza l’activitat de la cadena perquè la consola pugui mostrar tant el resum de la transacció com el graf de visualització a partir del mateix payload de resposta.
Fonts d’enriquiment compatibles:
- Les cadenes EVM utilitzen Blockscout per normalitzar la transacció principal, les crides internes i les transferències de tokens.
- Bitcoin utilitza mempool.space per normalitzar les entrades i sortides de la transacció.
- Solana utilitza Helius per normalitzar les transferències de SOL nadiu, les transferències de tokens SPL i el context dels esdeveniments NFT disponibles.
transaction_flows[] inclou camps normalitzats i estables (flow_type, from_address, to_address, amount, amount_usd, currency, token_name, token_address, transaction_hash, block_timestamp, index, success) més metadata específics del proveïdor.
Exemples habituals de metadata:
metadata és additiva i específica del proveïdor. No construeixis integracions crítiques que requereixin que totes les claus hi siguin per a cada cadena.
Travel Rule
null quan la transacció no té cap transferència ni comprovació de Travel Rule. S’omple quan envies travel_rule_details, i també quan Travel Rule està habilitada per a l’aplicació i la transacció s’ha creat amb transaction_category: "travelRule": en aquest cas Didit inicia l’intercanvi per si mateixa, amb o sense travel_rule_details, i informa del seu status aquí. Llegeix aquest camp en lloc de la sol·licitud que has enviat.
En una transferència entrant, originator_data i beneficiary_data de la contrapart continuen emmascarades (data_masked: true) fins que es confirmi la titularitat de la cartera (consulta Dades emmascarades de la contrapart).
direction, rail, counterparty_vasp, delivery, discovery, reason i next_actions tenen la mateixa estructura que a l’endpoint de transferència.
reason i next_actions indiquen per què una transferència COUNTERPARTY_VASP_NOT_FOUND o COUNTERPARTY_VASP_NOT_REACHABLE està bloquejada i què la fa avançar, i valen "" i [] per a qualsevol altre estat: consulta Per què una transferència està bloquejada.
Cada fila de GET /v3/transactions/ inclou el mateix bloc.
Consulta Travel Rule.
Instantània de la xarxa
El graf emmagatzemat en si mateix, no una referència a ell. Pot provenir de qualsevol de les dues fonts següents:- un
network_snapshotque has enviat amb la transacció, o - el graf que Didit construeix quan el cribratge AML de carteres acaba amb èxit per a una transacció cripto, fins i tot si la sol·licitud no portava cap
network_snapshot. Un graf generat pel cribratge substitueix un de enviat, i un nou cribratge asíncron l’actualitza.
null quan no existeix cap dels dos:
Etiquetes, metadades i propietats
tags[]: etiquetes adjuntades (per una acció d’una regla o per un analista):{ "uuid", "name", "color", "description", "source" }, onsourceésdiditper a una etiqueta predefinida icustomper a una de les teves.metadata: una instantània dels payloadssubjecticounterpartyexactament tal com els vas enviar en crear la transacció, sota aquestes dues claus.props: elscustom_propertiesque vas proporcionar en crear la transacció. Cada clau es pot referenciar a les condicions de les regles com acustom_values.<key>.
Remediació
Quan una regla activaAWAITING_USER, Didit crea la sessió de verificació vinculada i la retorna en dos camps:
remediation: la sessió vinculada:{ "session_id", "session_token", "url", "status" }. Es manté emplenat durant tota la vida de la transacció, de manera que sempre pots veure com va acabar l’acció de l’usuari.action_required: l’acció que l’usuari ha de fer ara mateix, onullquan ja no hi ha res pendent:{ "type": "verification_session", "url", "session_id", "session_token", "status" }. Redirigeix l’usuari aurl, o passasession_tokena un SDK de Didit. Les accions de titularitat de la cartera de Travel Rule utilitzen{ "type": "wallet_ownership", "url", "widget_session_id", "expires_at" }i tenen prioritat quan es podrien aplicar totes dues. Quan hi ha una acció de titularitat de cartera pendent i no s’ha pogut trobar la contrapart de la transferència, el mateix bloc també incloureasoninext_actions(consulta descobriment de la contrapart).
transaction.created i transaction.status.updated (action_required); consulta webhooks.
Desglossament de costos
null fins que s’hagi executat una funcionalitat facturable per a la transacció. En cas contrari, { "total_price", "items": [ { "usage_type", "price", "details" } ] }, amb un element per cada funcionalitat mesurada (cribratge, enriquiment, etc.).
Conversió de moneda
preferred_currency_amount és amount convertit a la moneda preferida de la teva aplicació segons els tipus de canvi mitjans del mercat, tret que hagis proporcionat amount_in_default_currency, cas en què s’utilitza aquest valor preconvertit tal com és. Les condicions de regla sobre amount comparen l’import original; utilitza preferred_currency_amount a les condicions quan necessitis un únic llindar per a totes les monedes.
Passos següents
Envia transaccions
Esquema complet de la sol·licitud.
Estats
Què significa cada estat.
Puntuació de risc
Com es calcula la puntuació.