Skip to main content
This page documents the full payload returned by POST /v3/transactions/ and GET /v3/transactions/{transaction_id}/. Both endpoints return the same TransactionDetail object; the API reference carries the field-by-field schema and this page walks through it.

​
Top-level structure

Two identifiers describe the same transaction. uuid is the Didit-stable identifier and is what GET /v3/transactions/{transaction_id}/ expects in its path; txn_id is the transaction_id you supplied at create time. transaction_number is the application-scoped sequential number the console shows. The subject and counterparty you submitted do not come back as top-level keys. They are the entries of the parties array, distinguished by role, and vendor_data at the top level is a convenience copy of the applicant’s vendor_data.

​
Key fields

​
Financial fields

  • amount / currency — transaction amount as submitted. amount is a decimal string with trailing zeros stripped ("1500", "0.5"), with up to 18 decimal places.
  • currency_type — fiat or crypto, as submitted in currency_kind; null when omitted.
  • amount_in_default_currency / default_currency_code — the pre-converted amount you supplied on the request, echoed back; null when you did not send one.
  • preferred_currency_amount / preferred_currency_code — amount converted to your application’s preferred currency. null when no exchange rate is available for currency and you did not supply amount_in_default_currency.
  • payment_details / payment_txn_id — the free-text payment reference and the external payment reference (for example a blockchain transaction hash) from the request.

​
Status fields

  • status — APPROVED, IN_REVIEW, DECLINED, AWAITING_USER. Transactions are created APPROVED; rules may flip them synchronously.
  • score — integer risk score accumulated by rules. Higher is riskier.
  • severity — UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL, or null until a rule or provider sets it.
  • decision_reason_code / decision_reason_label — structured + human reason for the current status.
  • environment - live or sandbox, from the application that owns the transaction. A sandbox transaction is stored but never evaluated, so its empty rule_runs means “not evaluated” rather than “nothing matched”. See Transaction Monitoring in sandbox.
  • source - LIVE for transactions submitted through the API or SDK, IMPORTED for transactions loaded through the console CSV import.

​
Parties

Every party on the transaction is an entry in parties. The create endpoint records the subject as APPLICANT and the optional counterparty as COUNTERPARTY; the role enum also includes REMITTER and BENEFICIARY. All entries share one shape.
  • role — APPLICANT, COUNTERPARTY, REMITTER, BENEFICIARY. Filter on it to find the subject.
  • entity_type — individual, company, external, unhostedWallet, as submitted.
  • kind — USER or BUSINESS when the party links to a Didit user or business through vendor_data; EXTERNAL otherwise.
  • country_code / dob — from the submitted address.country and date_of_birth.
  • address / institution_info — the objects as submitted; {} when omitted.
  • external_party_snapshot — frozen copy of the party data for EXTERNAL parties; null while the party is linked to a Didit user or business.

​
device

device is the device_context you submitted for that party, normalized to snake_case, plus server-side IP enrichment. It is {} when the request carried no device context, so always treat every key as optional. There is no separate enrichment object. When the party carried a public network_context.ip_address, Didit resolves it inline and writes the enriched fields into the same network_context object, filling only the keys you did not supply. Keys the resolver returned empty are omitted, so a fully enriched network_context holds the four submitted keys (ip_address, ip_country_code, latitude, longitude) plus whichever of 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 and proxy_type were resolved. is_vpn_or_tor and is_data_center are always present after a successful resolution. Enrichment is skipped, and network_context is returned exactly as submitted, when the IP is missing or non-routable, when the application is in sandbox, or when resolution failed. ip_country_code is an ISO 3166-1 alpha-2 code when Didit resolved it and whatever you submitted otherwise; rule conditions normalize both forms before comparing.

​
Payment methods

  • role — SOURCE, DESTINATION, FUNDING, BENEFICIARY. The create endpoint assigns SOURCE / DESTINATION from direction: on an outbound transaction the subject’s method is the SOURCE and the counterparty’s the DESTINATION; inbound is the reverse.
  • payment_method_type — bank_card, bank_account, e_wallet, crypto_wallet, unhosted_wallet, other.
  • fingerprint — SHA-256 over type:account_id:issuing_country, stable across transactions so you can correlate reuse of the same instrument. null when no account_id was submitted.
  • owner_kind / vendor_data / owner_name — who owns the instrument, following the same USER / BUSINESS / EXTERNAL convention as parties.
  • details — the raw payment_method object as submitted.

​
Rule runs

  • rule — UUID of the rule that ran; rule_title, rule_description, rule_category are copied from it.
  • matched — a run is recorded only when the rule’s conditions matched, so live evaluations always carry matched: true. Rules that evaluated without matching leave no entry. Demo data can include matched: false rows.
  • is_test / mode — true and TEST when the rule ran in test mode; a test run is recorded but has no effect on status, score or severity.
  • score_delta / status_target / severity — what this run contributed. status_target is set when a change_status action ran, or when the added score crossed a threshold.
  • action_summary — a string summary of the actions the rule executed, joined with ; (score +30, change_status:IN_REVIEW, add_tag:<name>, add_note, add_to_list, open_case); null when the rule executed no action.
  • metadata — the evaluation detail: scope_match, plus conditions[] and aggregations[]. The two lists use different value keys:
    • conditions[] — one entry per condition with field, operator, expected_value, the current_value that was read from the transaction, matched, group_index and group_logic. field_source is always null on transaction rule runs; it is only classified for monitoring events.
    • aggregations[] — one entry per velocity / count / sum aggregation with metric, field, operator, expected_value, the computed_value that the aggregate evaluated to, window, filters, matched and sample_references. Aggregations that could only be computed asynchronously carry computed_value: null and deferred: true.

​
Alerts

status: OPEN, INVESTIGATING, AWAITING_USER, PENDING_SAR, SAR_FILED, RESOLVED, DISMISSED. source: RULE, PROVIDER, MANUAL. See Alerts.

​
Activities

The transaction’s activity log: creation, notes, manual reviews and status changes.
Analyst notes appear here as TRANSACTION_NOTE_ADDED entries; there is no separate notes array.

​
Documents

Files attached to the transaction from the console. [] when none.
file_url is a short-lived signed URL; fetch it when you need it rather than storing it.

​
Provider results

External provider outputs (transaction hash screening, wallet screening, fiat monitoring, sanctions screening).
result_type: FIAT_MONITORING, WALLET_SCREENING, TRANSACTION_SCREENING, TRAVEL_RULE, NETWORK_GRAPH, CUSTOM. payload.risk_factors is the ranked explanation of score — what produced the verdict, high-risk drivers first and then by value moved. A high score with no is_high_risk entry means the provider graded the entity on its own exposure model without reporting a sanctions or attributed-entity match; summary says so explicitly. Field-by-field reference: Risk factors. Results screened before this field existed omit the key. For crypto transaction-hash screening, transaction_flows is populated when on-chain enrichment is available. It normalizes chain activity so the console can render both the transaction overview and visualization graph from the same response payload. Supported enrichment sources:
  • EVM chains use Blockscout to normalize the main transaction, internal calls, and token transfers.
  • Bitcoin uses mempool.space to normalize transaction inputs and outputs.
  • Solana uses Helius to normalize native SOL transfers, SPL token transfers, and available NFT event context.
Each transaction_flows[] item includes stable normalized fields (flow_type, from_address, to_address, amount, amount_usd, currency, token_name, token_address, transaction_hash, block_timestamp, index, success) plus provider-specific metadata. Common metadata examples:
metadata is additive and provider-specific. Do not build critical integrations that require every key to be present for every chain.

​
Travel rule

null when the transaction has no Travel Rule transfer or check. It is populated when you submit travel_rule_details, and also when Travel Rule is enabled for the application and the transaction was created with transaction_category: "travelRule": Didit then initiates the exchange itself, with or without travel_rule_details, and reports its status here. Read this field rather than the request you sent.
See Travel rule.

​
Network snapshot

The stored graph itself, not a reference to it. It comes from either source:
  • a network_snapshot you submitted with the transaction, or
  • the graph Didit builds when AML wallet screening succeeds for a crypto transaction, even if the request carried no network_snapshot. A screening-built graph replaces a submitted one, and an asynchronous re-screen refreshes it.
null when neither exists:
The console transaction detail page renders the same graph.

​
Tags, metadata, props

  • tags[] — attached tags (either by rule action or by analyst): { "uuid", "name", "color", "description", "source" }, where source is didit for a preset tag and custom for one of yours.
  • metadata — a snapshot of the subject and counterparty payloads exactly as you submitted them at create time, under those two keys.
  • props — the custom_properties you supplied at create time. Each key is addressable in rule conditions as custom_values.<key>.

​
Remediation

When a rule triggers AWAITING_USER, Didit creates the linked verification session and returns it in two fields:
  • remediation — the linked session: { "session_id", "session_token", "url", "status" }. Stays populated for the life of the transaction, so you can always see how the user action ended.
  • action_required — the action the user must take right now, or null once nothing is pending: { "type": "verification_session", "url", "session_id", "session_token", "status" }. Redirect the user to url, or feed session_token to a Didit SDK. Travel Rule wallet-ownership actions use { "type": "wallet_ownership", "url", "widget_session_id", "expires_at" } and take precedence when both could apply.
The same two fields ride on the transaction.created and transaction.status.updated webhook payloads (action_required) - see webhooks.

​
Cost breakdown

null until a billable feature ran for the transaction. Otherwise { "total_price", "items": [ { "usage_type", "price", "details" } ] }, one item per metered feature (screening, enrichment, and so on).

​
Currency conversion

preferred_currency_amount is amount converted to your application’s preferred currency at mid-market rates, unless you supplied amount_in_default_currency, in which case that pre-converted value is used as is. Rule conditions on amount compare the native amount; use preferred_currency_amount in conditions when you need one threshold across currencies.

​
Next steps

Submit transactions

Full request schema.

Statuses

What each status means.

Risk scoring

How score is computed.