Create Transaction - Didit Documentation

curl

curl -X POST 'https://verification.didit.me/v3/transactions/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_id": "your-txn-2026-05-17-001",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": 1500,
      "currency": "EUR",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user-12345",
      "full_name": "Maria Garcia"
    }
  }'

{
  "uuid": "abcdef12-3456-4890-abcd-ef1234567890",
  "transaction_number": 4123,
  "txn_id": "your-txn-2026-05-17-001",
  "txn_date": "2026-05-17T08:42:00Z",
  "zone_id": "Europe/Madrid",
  "transaction_type": "finance",
  "action_type": "withdrawal",
  "direction": "OUTBOUND",
  "status": "APPROVED",
  "amount": "1500",
  "currency": "EUR",
  "currency_type": "fiat",
  "amount_in_default_currency": "1620.45",
  "default_currency_code": "USD",
  "preferred_currency_amount": "1620.45",
  "preferred_currency_code": "USD",
  "payment_details": "Withdrawal to crypto wallet",
  "payment_txn_id": null,
  "score": 0,
  "severity": null,
  "decision_reason_code": null,
  "decision_reason_label": null,
  "vendor_data": "user-12345",
  "metadata": {
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user-12345",
      "full_name": "Maria Garcia",
      "address": {},
      "institution_details": {},
      "device_context": {}
    },
    "counterparty": {}
  },
  "props": {},
  "tags": [],
  "parties": [
    {
      "uuid": "b1111111-2222-4333-8444-555555555555",
      "role": "APPLICANT",
      "entity_type": "individual",
      "kind": "USER",
      "vendor_data": "user-12345",
      "full_name": "Maria Garcia",
      "first_name": null,
      "last_name": null,
      "country_code": null,
      "dob": null,
      "address": {},
      "institution_info": {},
      "device": {},
      "external_party_snapshot": null
    }
  ],
  "payment_methods": [],
  "activities": [
    {
      "uuid": "d4e5f6a7-8901-4bcd-9ef0-123456789abc",
      "activity_type": "TRANSACTION_CREATED",
      "source": "TRANSACTION",
      "status": "APPROVED",
      "title": "withdrawal",
      "description": "Transaction recorded.",
      "metadata": {},
      "occurred_at": "2026-05-17T08:42:11Z"
    }
  ],
  "alerts": [],
  "rule_runs": [],
  "provider_results": [],
  "travel_rule": null,
  "network_snapshot": null,
  "remediation": null,
  "cost_breakdown": null
}

POST

transactions

curl

curl -X POST 'https://verification.didit.me/v3/transactions/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_id": "your-txn-2026-05-17-001",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": 1500,
      "currency": "EUR",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user-12345",
      "full_name": "Maria Garcia"
    }
  }'

{
  "uuid": "abcdef12-3456-4890-abcd-ef1234567890",
  "transaction_number": 4123,
  "txn_id": "your-txn-2026-05-17-001",
  "txn_date": "2026-05-17T08:42:00Z",
  "zone_id": "Europe/Madrid",
  "transaction_type": "finance",
  "action_type": "withdrawal",
  "direction": "OUTBOUND",
  "status": "APPROVED",
  "amount": "1500",
  "currency": "EUR",
  "currency_type": "fiat",
  "amount_in_default_currency": "1620.45",
  "default_currency_code": "USD",
  "preferred_currency_amount": "1620.45",
  "preferred_currency_code": "USD",
  "payment_details": "Withdrawal to crypto wallet",
  "payment_txn_id": null,
  "score": 0,
  "severity": null,
  "decision_reason_code": null,
  "decision_reason_label": null,
  "vendor_data": "user-12345",
  "metadata": {
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user-12345",
      "full_name": "Maria Garcia",
      "address": {},
      "institution_details": {},
      "device_context": {}
    },
    "counterparty": {}
  },
  "props": {},
  "tags": [],
  "parties": [
    {
      "uuid": "b1111111-2222-4333-8444-555555555555",
      "role": "APPLICANT",
      "entity_type": "individual",
      "kind": "USER",
      "vendor_data": "user-12345",
      "full_name": "Maria Garcia",
      "first_name": null,
      "last_name": null,
      "country_code": null,
      "dob": null,
      "address": {},
      "institution_info": {},
      "device": {},
      "external_party_snapshot": null
    }
  ],
  "payment_methods": [],
  "activities": [
    {
      "uuid": "d4e5f6a7-8901-4bcd-9ef0-123456789abc",
      "activity_type": "TRANSACTION_CREATED",
      "source": "TRANSACTION",
      "status": "APPROVED",
      "title": "withdrawal",
      "description": "Transaction recorded.",
      "metadata": {},
      "occurred_at": "2026-05-17T08:42:11Z"
    }
  ],
  "alerts": [],
  "rule_runs": [],
  "provider_results": [],
  "travel_rule": null,
  "network_snapshot": null,
  "remediation": null,
  "cost_breakdown": null
}

Authorizations

x-api-key

string

header

required

Body

application/json

transaction_id

string

required

Your unique identifier for this transaction (max 128 characters).

Example:

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

transaction_category

enum<string>

required

Category of the transaction. CamelCase aliases (travelRule, userPlatformEvent, gamblingBet, …) are also accepted; the stored/echoed value is camelCase for multi-word categories.

Available options:

finance,

kyc,

travel_rule,

user_event,

audit_trail_event,

gambling_bet,

gambling_limit_change,

gambling_bonus_change

Example:

"finance"

transaction_details

object

required

Core financial details of the transaction.

Show child attributes

subject

object

required

The subject (applicant) of the transaction.

Show child attributes

transaction_at

string<date-time>

When the transaction occurred. Defaults to now if omitted.

time_zone

string

IANA time zone identifier, e.g. Europe/Madrid.

counterparty

object

The counterparty of the transaction (optional).

Show child attributes

custom_properties

object

Arbitrary key-value pairs attached to the transaction. Each key can be referenced in rule conditions with the field path custom_values.<key>.

Example:

{
  "merchant_id": "test",
  "bank_name": "test_2"
}

travel_rule_details

object

Travel Rule compliance metadata.

Show child attributes

network_snapshot

object

Pre-computed network graph snapshot.

Show child attributes

include_crypto_screening

boolean | null

Per-transaction override for crypto blockchain analytics screening. When true, crypto screening is performed regardless of the application default. When false, crypto screening is skipped even if enabled in the application settings. When omitted or null, the application-level default configured in the Console is used. Crypto screening requires transaction_details.direction, currency_kind: "crypto", a chain/currency, and the wallet address selected by the direction: inbound pre-transfer screening uses counterparty.payment_method.account_id, inbound transaction-hash screening uses subject.payment_method.account_id, and outbound screening uses counterparty.payment_method.account_id. When transaction_details.payment_reference_id contains a blockchain transaction hash, Didit performs transaction screening and returns transaction summary enrichment when available.

Response

Transaction submitted and monitored. The body is the full transaction detail (same shape as GET /v3/transactions/{transaction_id}/), reflecting any rule outcomes already applied.

Full monitoring record for one transaction, as returned by GET /v3/transactions/{transaction_id}/ and POST /v3/transactions/.

uuid

string<uuid>

Didit-stable transaction identifier. Use as {transaction_id} for follow-up calls.

transaction_number

integer

Application-scoped sequential transaction number shown in Console (e.g. 4123).

txn_id

string

The transaction_id you supplied at create time (max 128 chars). Unique per application.

txn_date

string<date-time>

When the transaction occurred (from transaction_at; defaults to submission time).

zone_id

string | null

IANA time zone identifier provided at create time.

transaction_type

string

Top-level category as stored: finance, kyc, travelRule, userPlatformEvent, gamblingBet, gamblingLimitChange, gamblingBonusChange, auditTrailEvent. Note multi-word values are echoed back in camelCase even when submitted in snake_case.

action_type

string

Sub-type within the category (e.g. deposit, withdrawal, transfer). Defaults to the category when not supplied.

direction

enum<string>

Direction relative to the subject. Stored uppercase regardless of the casing submitted (in/out/inbound/outbound are accepted on input).

Available options:

INBOUND,

OUTBOUND

status

enum<string>

Current monitoring verdict. Transactions are created APPROVED; rules may flip them to IN_REVIEW/DECLINED synchronously.

Available options:

APPROVED,

IN_REVIEW,

DECLINED,

AWAITING_USER

amount

string

Transaction amount as a decimal string with trailing zeros stripped (e.g. "1500", "0.5", "0.123456789012345678"). Up to 18 decimal places.

currency

string

Currency code of amount (e.g. EUR, USD, BTC).

currency_type

string | null

fiat or crypto, as submitted in currency_kind.

amount_in_default_currency

string | null

Pre-converted amount you supplied, as a decimal string with trailing zeros stripped.

default_currency_code

string | null

preferred_currency_amount

string | null

amount converted to the application's preferred currency, when available.

preferred_currency_code

string | null

payment_details

string | null

Free-text payment reference or memo from the submission.

payment_txn_id

string | null

External payment system reference (e.g. blockchain transaction hash) from payment_reference_id.

score

integer

Risk score accumulated by rules (typically 0–100). Higher = riskier.

severity

enum<string> | null

Categorical risk severity set by rules/providers (UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL). null until something sets it.

Available options:

UNKNOWN,

LOW,

MEDIUM,

HIGH,

CRITICAL

decision_reason_code

string | null

Machine-readable reason for the current status.

decision_reason_label

string | null

Human-readable label for decision_reason_code.

vendor_data

string | null

Convenience copy of the applicant's vendor_data.

metadata

object

Snapshot of the subject and counterparty payloads as submitted at create time.

props

object

The custom_properties you supplied at create time. Each key is addressable in rule conditions as custom_values.<key>.