Skip to main content
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:
CategoryDescription
financeStandard financial transaction (deposit, withdrawal, transfer)
kycIdentity verification-related event
travel_ruleVirtual asset transfer requiring travel rule compliance
user_platform_eventCustom platform event (login, profile change, etc.)
gambling_betGambling wager or bet placement
gambling_limit_changeChange to a player’s deposit, loss, or wager limit
gambling_bonus_changeBonus grant, redemption, or forfeiture
audit_trail_eventSystem or compliance audit event

​
Transaction details

The transaction_details object carries the financial data:
FieldTypeDescription
directionstringINBOUND or OUTBOUND
amountstringTransaction value as a decimal string (e.g., "1500.50")
currencystringISO currency code (e.g., USD, EUR, BTC)
currency_kindstringfiat or crypto — determines whether AML blockchain screening triggers
action_typestringVendor-defined action label (e.g., deposit, withdrawal, purchase)
payment_detailsstringFree-text description of the payment (e.g., "Bank transfer from ABC Corp")
payment_reference_idstringExternal payment reference identifier

​
Subject and counterparty

Each transaction has a subject (required) and an optional counterparty. Both use the same party model:
FieldTypeDescription
rolestringapplicant, counterparty, remitter, or beneficiary
entity_typestringindividual, company, external, or unhosted_wallet
vendor_datastringYour identifier for this party — links the transaction to a user or business profile
full_namestringFull name of the party
first_namestringGiven name
last_namestringFamily name
date_of_birthstringISO date (e.g., 1990-01-15)
country_codestringISO 3166-1 alpha-2 country code
addressobjectStructured 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:
FieldTypeDescription
rolestringsource, destination, funding, or beneficiary
payment_method_typestringbank_card, bank_account, ewallet, crypto_wallet, unhosted_wallet, or other
account_idstringAccount number, wallet address, or card token
issuing_countrystringCountry that issued the payment instrument
owner_namestringName of the account holder
fingerprintstringUnique fingerprint for the payment instrument
For crypto transactions, include the wallet address in account_id and set the chain details so AML blockchain screening can run automatically.

​
Device context

Include device information on the subject party to power device intelligence rules:
FieldTypeDescription
device.fingerprintstringUnique device fingerprint
device.user_agentstringBrowser or app user agent string
device.network_context.ip_addressstringClient IP address
device.network_context.ip_country_codestringGeo-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": "ABC Trading Ltd",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'

​
Response

The API returns the created transaction with its initial evaluation results:
FieldTypeDescription
uuidstringDidit’s unique transaction identifier
txn_idstringYour provided transaction ID
statusstringAPPROVED, IN_REVIEW, DECLINED, or AWAITING_USER
scorenumberCumulative risk score from all matched rules
severitystringHighest severity of matched rules (LOW, MEDIUM, HIGH, CRITICAL)
decision_reason_codestringMachine-readable reason for the status decision
decision_reason_labelstringHuman-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.

AML blockchain 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.