Transaction Response Schema

This page documents the full payload returned by POST /v3/transactions/ and GET /v3/transactions/{id}/.

Top-level structure

{
  "transaction_id": "uuid",
  "txn_id": "tx-0001",
  "txn_date": "2026-04-16T12:00:00Z",
  "environment": "live",
  "direction": "OUTBOUND",
  "status": "IN_REVIEW",
  "score": 65,
  "amount": "12500.00",
  "currency": "USD",
  "amount_in_default_currency": "12500.00",
  "default_currency_code": "USD",
  "preferred_currency_amount": "12500.00",
  "transaction_type": "finance",
  "action_type": null,
  "rules_evaluated_count": 18,
  "rules_matched_count": 2,
  "decision_reason_code": "rule_score_threshold",
  "decision_reason_label": "Score above review threshold",
  "applicant": { ... },
  "remitter": null,
  "beneficiary": null,
  "counterparty": { ... },
  "payment_methods": [ ... ],
  "rule_runs": [ ... ],
  "alerts": [ ... ],
  "provider_results": [ ... ],
  "travel_rule": { ... } | null,
  "network_snapshot_id": null,
  "tags": [ ... ],
  "notes": [ ... ],
  "metadata": { },
  "custom_values": { },
  "session_id": null,
  "remediation": null,
  "action_required": null,
  "assigned_to": null,
  "created_at": "...",
  "updated_at": "..."
}

Key fields

Financial fields

amount / currency — transaction amount as submitted.
amount_in_default_currency / default_currency_code — amount converted to your app’s default currency (for cross-currency thresholding).
preferred_currency_amount — optional per-rule / per-app preferred reporting currency.

Status fields

status — APPROVED, IN_REVIEW, DECLINED, AWAITING_USER.
score — integer score.
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.

Parties

"applicant": {
  "uuid": "...",
  "vendor_data": "user-42",
  "full_name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "country_code": "USA",
  "date_of_birth": "1990-01-01",
  "address": { "line_1": "...", "city": "...", "country_code": "USA" },
  "institution_info": { "name": "...", "country_code": "..." },
  "device": {
    "fingerprint": "...",
    "persistent_device_id": "...",
    "user_agent": "...",
    "browser_family": "Chrome",
    "browser_version": "131.0",
    "platform": "web",
    "os_family": "Windows",
    "os_version": "10.0",
    "network_context": {
      "ip_address": "203.0.113.5",
      "ip_country_code": "USA"
    }
  },
  "ip_enrichment": {
    "ip_country_code": "USA",
    "is_vpn_or_tor": false,
    "is_data_center": false,
    "asn_number": 15169,
    "asn_organization": "Google LLC"
  }
}

Each party (applicant, remitter, beneficiary, counterparty) has the same shape. See IP enrichment for the enrichment fields.

Payment methods

"payment_methods": [
  {
    "uuid": "...",
    "role": "SOURCE",
    "type": "BANK_ACCOUNT",
    "label": "Chase checking ****1234",
    "fingerprint": "bank:us:chase:****1234",
    "account_id": "...",
    "issuing_country": "USA",
    "institution_info": { "name": "JP Morgan Chase", "country_code": "USA" },
    "details": { }
  }
]

role: SOURCE, DESTINATION, FUNDING, BENEFICIARY. type: BANK_CARD, BANK_ACCOUNT, EWALLET, CRYPTO_WALLET, UNHOSTED_WALLET.

Rule runs

"rule_runs": [
  {
    "rule_uuid": "...",
    "rule_name": "High-value outbound",
    "matched": true,
    "is_test": false,
    "mode": "ACTIVE",
    "score_delta": 30,
    "severity": null,
    "status_target": null,
    "action_summary": { "add_score": 30 },
    "considered_payload": { "amount": "12500.00", "direction": "OUTBOUND" },
    "matched_payload": { "amount": "12500.00" }
  },
  {
    "rule_uuid": "...",
    "rule_name": "High-risk jurisdiction counterparty",
    "matched": true,
    "score_delta": 35,
    "action_summary": { "add_score": 35, "add_tags": ["high_risk_country"] }
  }
]

Every rule that evaluated is included — matched: false rules appear too, so you can audit selectivity.

Alerts

"alerts": [
  {
    "uuid": "...",
    "status": "OPEN",
    "source": "RULE",
    "title": "High-value + high-risk jurisdiction",
    "severity": null,
    "created_at": "..."
  }
]

Provider results

External provider outputs (transaction hash screening, wallet screening, fiat monitoring, sanctions screening).

"provider_results": [
  {
    "uuid": "...",
    "result_type": "TRANSACTION_SCREENING",
    "provider": "merklescience",
    "status": "SCREENED",
    "severity": "HIGH",
    "score": 82,
    "summary": "Merkle Science risk: High (4/5). Dominant risk: stolen_funds. Driven by: 50% direct incoming exposure to Theft / Hack (Stolen Funds)",
    "payload": {
      "provider": "merklescience",
      "screening_type": "TRANSACTION_SCREENING",
      "transaction_hash": "0x...",
      "wallet_address": null,
      "blockchain": "ETH",
      "block_timestamp": "2026-04-01T00:07:11Z",
      "total_value_usd": 2942.31,
      "fee_usd": 0.09,
      "transaction_flows": [
        {
          "flow_type": "token",
          "from_address": "0x...",
          "to_address": "0x...",
          "amount": 72.83039728,
          "amount_usd": 235.97,
          "currency": "UNI",
          "token_name": "Uniswap",
          "token_address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
          "transaction_hash": "0x...",
          "block_timestamp": "2026-04-01T00:07:11Z",
          "index": 460,
          "success": true,
          "metadata": {
            "provider": "blockscout",
            "token_type": "ERC-20",
            "token_icon_url": "https://...",
            "token_reputation": "ok",
            "token_holders_count": "410093",
            "from": {
              "label": "ravaga.eth",
              "tags": [{ "name": "Beacon Depositor", "type": "generic" }]
            },
            "to": {
              "label": "AirSwap: Spender",
              "is_contract": true,
              "is_verified": true
            }
          }
        }
      ],
      "source_of_funds": [
        {
          "category": "stolen_funds",
          "entity_name": "Stolen Funds",
          "entity_type": "Theft",
          "entity_subtype": "Hack",
          "exposure_direction": "incoming",
          "exposure_type": "direct",
          "is_direct": true,
          "amount_usd": 1471.16,
          "percentage": 50,
          "country": ""
        }
      ],
      "destination_of_funds": [],
      "counterparty_connections": [],
      "sanctions_hit": false,
      "risk_factors": [
        {
          "source": "exposure",
          "category": "stolen_funds",
          "label": "Theft / Hack",
          "entity_name": "Stolen Funds",
          "direction": "incoming",
          "exposure_type": "direct",
          "amount_usd": 1471.16,
          "percentage": 50,
          "is_high_risk": true,
          "description": "50% direct incoming exposure to Theft / Hack (Stolen Funds)"
        }
      ],
      "raw_response": { "...": "provider-specific details" }
    }
  }
]

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:

{
  "provider": "blockscout",
  "decoded_method_call": "swap(string aggregatorId, address tokenFrom, uint256 amount, bytes data)",
  "block_number": 23141214,
  "gas_used": "171843",
  "fee_native": 0.000342317619518133,
  "token_icon_url": "https://...",
  "token_reputation": "ok"
}

{
  "provider": "mempool",
  "role": "input",
  "previous_txid": "4c0c...",
  "previous_vout": 0,
  "scriptpubkey_type": "v0_p2wpkh",
  "fee_btc": 0.00000322,
  "block_height": 943130
}

{
  "provider": "helius",
  "source": "MAGIC_EDEN",
  "type": "NFT_BID",
  "description": "Wallet bid 2.5 SOL on an NFT.",
  "slot": 136658192,
  "fee_sol": 0.000005,
  "nft_event": {
    "type": "NFT_BID",
    "source": "MAGIC_EDEN",
    "nft_mints": ["3bUW..."]
  }
}

metadata is additive and provider-specific. Do not build critical integrations that require every key to be present for every chain.

Travel rule

Only present for virtual-asset transfers.

"travel_rule": {
  "status": "COMPLIANT",
  "required": true,
  "protocol": "TRP",
  "obligations_count": 2,
  "originator_data": { "name": "...", "wallet_address": "..." },
  "beneficiary_data": { "name": "...", "wallet_address": "..." }
}

See Travel rule.

Network snapshot

For crypto transactions, network_snapshot_id points to the stored network graph (nodes, edges, metrics). View the graph in the console transaction detail page.

Tags, notes, metadata

tags[] — attached tags (either by rule action or by analyst).
notes[] — analyst notes.
metadata — free-form JSON you submitted on the request.
custom_values — rule-engine-consumable JSON (typed fields you can reference in conditions).

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" } (Travel Rule wallet-ownership actions use "type": "wallet_ownership"). Redirect the user to url, or feed session_token to a Didit SDK.

The same two fields ride on the transaction.created and transaction.status.updated webhook payloads (action_required) - see webhooks.

Currency conversion

amount_in_default_currency uses mid-market rates from our FX provider at the transaction’s txn_date. Rules that threshold on “amount” operate on amount_in_default_currency by default; rules can opt into the native amount via rule scope.

Next steps

Submit transactions

Full request schema.

Statuses

What each status means.

Risk scoring

How score is computed.

Getting Started

Features

Reference

Console

Top-level structure

Key fields

Financial fields

Status fields

Parties

Payment methods

Rule runs

Alerts

Provider results

Travel rule

Network snapshot

Tags, notes, metadata

Remediation

Currency conversion

Next steps

Submit transactions

Statuses

Risk scoring

​Top-level structure

​Key fields

​Financial fields

​Status fields

​Parties

​Payment methods

​Rule runs

​Alerts

​Provider results

​Travel rule

​Network snapshot

​Tags, notes, metadata

​Remediation

​Currency conversion

​Next steps

Submit transactions

Statuses

Risk scoring

Top-level structure

Key fields

Financial fields

Status fields

Parties

Payment methods

Rule runs

Alerts

Provider results

Travel rule

Network snapshot

Tags, notes, metadata

Remediation

Currency conversion

Next steps