Submitting Transactions

Submit transactions to Didit via the Create Transaction API. Each transaction includes structured party, payment, and context data that the rules engine evaluates in real time.

Transaction categories

Every transaction has a transaction_category that determines how rules and analytics treat it:

Category	Description
`finance`	Standard financial transaction (deposit, withdrawal, transfer)
`kyc`	Identity verification-related event
`travel_rule`	Virtual asset transfer requiring travel rule compliance
`user_platform_event`	Custom platform event (login, profile change, etc.)
`gambling_bet`	Gambling wager or bet placement
`gambling_limit_change`	Change to a player’s deposit, loss, or wager limit
`gambling_bonus_change`	Bonus grant, redemption, or forfeiture
`audit_trail_event`	System or compliance audit event

Transaction details

The transaction_details object carries the financial data:

Field	Type	Description
`direction`	string	`INBOUND` or `OUTBOUND`
`amount`	string	Transaction value as a decimal string (e.g., `"1500.50"`)
`currency`	string	ISO currency code (e.g., `USD`, `EUR`, `BTC`)
`currency_kind`	string	`fiat` or `crypto` — determines whether crypto screening triggers
`action_type`	string	Vendor-defined action label (e.g., `deposit`, `withdrawal`, `purchase`)
`payment_details`	string	Free-text description of the payment (e.g., `"Bank transfer from ABC Corp"`)
`payment_reference_id`	string	External payment reference identifier. For post-transfer crypto screening, use the blockchain transaction hash.

Subject and counterparty

Each transaction has a subject (required) and an optional counterparty. Both use the same party model:

Field	Type	Description
`role`	string	`applicant`, `counterparty`, `remitter`, or `beneficiary`
`entity_type`	string	`individual`, `company`, `external`, or `unhosted_wallet`
`vendor_data`	string	Your identifier for this party — links the transaction to a user or business profile
`full_name`	string	Full name of the party
`first_name`	string	Given name
`last_name`	string	Family name
`date_of_birth`	string	ISO date (e.g., `1990-01-15`)
`country_code`	string	ISO 3166-1 alpha-2 country code
`address`	object	Structured address with `street`, `city`, `state`, `country`, `postal_code`

When vendor_data matches an existing user or business, Didit automatically links the transaction to that entity’s profile, enabling cross-session rule evaluation and velocity checks.

Payment methods

Attach one or more payment methods to describe the instruments used:

Field	Type	Description
`role`	string	`source`, `destination`, `funding`, or `beneficiary`
`payment_method_type`	string	`bank_card`, `bank_account`, `ewallet`, `crypto_wallet`, `unhosted_wallet`, or `other`
`account_id`	string	Account number, wallet address, or card token
`issuing_country`	string	Country that issued the payment instrument
`owner_name`	string	Name of the account holder
`fingerprint`	string	Unique fingerprint for the payment instrument

For crypto transactions, include wallet addresses in account_id and set currency_kind to crypto so blockchain screening can run automatically. Direction controls which wallet is screened: inbound pre-transfer screening uses the sender wallet in counterparty.payment_method.account_id; outbound screening uses the destination wallet in counterparty.payment_method.account_id. If you send a blockchain hash in transaction_details.payment_reference_id, inbound transaction screening requires your service deposit address in subject.payment_method.account_id, while outbound transaction screening requires the destination wallet in counterparty.payment_method.account_id.

Crypto screening override

Use include_crypto_screening at the top level of the request to override the default configured in Transactions > Settings in the Console:

Value	Description
`true`	Force crypto screening for this transaction
`false`	Skip crypto screening for this transaction
omitted or `null`	Use the application-level default

Device context

Include device information on the subject party to power device intelligence rules:

Field	Type	Description
`device.fingerprint`	string	Unique device fingerprint
`device.user_agent`	string	Browser or app user agent string
`device.network_context.ip_address`	string	Client IP address
`device.network_context.ip_country_code`	string	Geo-resolved country of the IP

Device context enables rules like multi-accounting detection (same fingerprint across different subjects) and location-based risk scoring.

Custom properties

Add any additional key-value pairs in the custom_properties object. Rules can reference these fields in their conditions — useful for passing business-specific context like product category, merchant ID, or channel.

"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}

Example request

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "OUTBOUND",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'

Response

The API returns the created transaction with its initial evaluation results:

Field	Type	Description
`uuid`	string	Didit’s unique transaction identifier
`txn_id`	string	Your provided transaction ID
`status`	string	`APPROVED`, `IN_REVIEW`, `DECLINED`, or `AWAITING_USER`
`score`	number	Cumulative risk score from all matched rules
`severity`	string	Highest severity of matched rules (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`decision_reason_code`	string	Machine-readable reason for the status decision
`decision_reason_label`	string	Human-readable description of the decision

See the API Reference for the full request and response schema, and the dedicated response schema reference for an annotated payload walkthrough.

Idempotency

txn_id is unique per application. Re-submitting the same txn_id returns the existing transaction rather than creating a duplicate — effectively idempotent for retries. Always generate txn_id on your side (e.g. your own transaction DB ID, UUID, or deterministic hash).

Historical backfill

Pass txn_date in the past to ingest historical transactions. Rules still evaluate by default — use the console CSV import with dry-ingest mode if you want to skip rule evaluation during bulk historical loads. See integration guide.

Next steps

Rules & scoring

How submitted transactions are evaluated against rules.

Response schema

Full annotated response payload.

Crypto screening

Automatic wallet and transaction screening for crypto transactions.

Travel rule

Attach travel rule compliance data to virtual asset transfers.

IP enrichment

IP-derived context available to rules.

API reference

Full request schema for the Create Transaction endpoint.

Getting Started

Features

Reference

Console

Transaction categories

Transaction details

Subject and counterparty

Payment methods

Crypto screening override

Device context

Custom properties

Example request

Response

Idempotency

Historical backfill

Next steps

Rules & scoring

Response schema

Crypto screening

Travel rule

IP enrichment

API reference

Getting Started

Features

Reference

Console

Documentation Index

​Transaction categories

​Transaction details

​Subject and counterparty

​Payment methods

​Crypto screening override

​Device context

​Custom properties

​Example request

​Response

​Idempotency

​Historical backfill

​Next steps

Rules & scoring

Response schema

Crypto screening

Travel rule

IP enrichment

API reference

Transaction categories

Transaction details

Subject and counterparty

Payment methods

Crypto screening override

Device context

Custom properties

Example request

Response

Idempotency

Historical backfill

Next steps