Saltar al contingut principal
Aquesta pàgina documenta el payload complet que retornen 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

Hi ha dos identificadors que descriuen la mateixa transacció. 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 — fiat o crypto, tal com s’ha enviat a currency_kind; null si 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; null si no n’has enviat cap.
  • preferred_currency_amount / preferred_currency_code — amount convertit a la moneda preferida de la teva aplicació. null quan no hi ha cap tipus de canvi disponible per a currency i no has enviat amount_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 a APPROVED; 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, o null fins 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 - live o sandbox, des de l’aplicació que és propietària de la transacció. Una transacció sandbox s’emmagatzema però mai s’avalua, de manera que el seu rule_runs buit vol dir «no avaluada» i no «cap coincidència». Consulta Monitoratge de transaccions en sandbox.
  • source - LIVE per a les transaccions enviades mitjançant l’API o el SDK, IMPORTED per a les transaccions carregades mitjançant la importació CSV de la consola.

Parts

Cada part de la transacció és una entrada de parties. 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 — USER o BUSINESS quan la part està vinculada a un usuari o a una empresa de Didit mitjançant vendor_data; EXTERNAL en cas contrari.
  • country_code / dob — a partir de address.country i date_of_birth enviats.
  • 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 parts EXTERNAL; null mentre 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ó assigna SOURCE / DESTINATION a partir de direction: en una transacció de sortida, el mètode del subjecte és el SOURCE i el de la contrapart és el DESTINATION; 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 sobre type:account_id:issuing_country, estable entre transaccions perquè puguis correlacionar la reutilització del mateix instrument. null quan no s’ha enviat cap account_id.
  • owner_kind / vendor_data / owner_name — qui és el titular de l’instrument, seguint la mateixa convenció USER / BUSINESS / EXTERNAL que les parts.
  • details — l’objecte payment_method tal com s’ha enviat.

Execucions de regles

  • rule — UUID de la regla que s’ha executat; rule_title, rule_description i rule_category se 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 porten matched: true. Les regles que s’han avaluat sense coincidir no deixen cap entrada. Les dades de demostració poden incloure files amb matched: false.
  • is_test / mode — true i TEST quan la regla s’ha executat en mode de prova; una execució de prova es registra però no afecta status, score ni severity.
  • score_delta / status_target / severity — allò que ha aportat aquesta execució. status_target s’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); null quan la regla no ha executat cap acció.
  • metadata — el detall de l’avaluació: scope_match, així com conditions[] i aggregations[]. Les dues llistes fan servir claus de valor diferents:
    • conditions[] — una entrada per condició amb field, operator, expected_value, el current_value llegit de la transacció, matched, group_index i group_logic. field_source és sempre null a 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 amb metric, field, operator, expected_value, el computed_value que ha produït l’agregació, window, filters, matched i sample_references. Les agregacions que només es poden calcular de manera asíncrona porten computed_value: null i deferred: 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.
Les notes de l’analista apareixen aquí com a entrades 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.
Cada element de 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_snapshot que 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:
La pàgina de detall de la transacció a la consola mostra el mateix graf.

Etiquetes, metadades i propietats

  • tags[]: etiquetes adjuntades (per una acció d’una regla o per un analista): { "uuid", "name", "color", "description", "source" }, on source és didit per a una etiqueta predefinida i custom per a una de les teves.
  • metadata: una instantània dels payloads subject i counterparty exactament tal com els vas enviar en crear la transacció, sota aquestes dues claus.
  • props: els custom_properties que vas proporcionar en crear la transacció. Cada clau es pot referenciar a les condicions de les regles com a custom_values.<key>.

Remediació

Quan una regla activa AWAITING_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, o null quan ja no hi ha res pendent: { "type": "verification_session", "url", "session_id", "session_token", "status" }. Redirigeix l’usuari a url, o passa session_token a 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é inclou reason i next_actions (consulta descobriment de la contrapart).
Els mateixos dos camps viatgen als payloads dels webhooks 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ó.
Darrera modificació el 7 de novembre del 2026