> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Transaction

> Submit a transaction for synchronous AML/risk monitoring. The transaction is created `APPROVED`, then your rules (and crypto screening, when applicable) run inline and may flip the returned `status` to `IN_REVIEW` or `DECLINED`. **`transaction_id` is your idempotency key** (max 128 chars, unique per app); reusing it returns 400. A `transaction.created` webhook is dispatched on success (sandbox applications are not billed and do not emit webhooks).

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Create Transaction API Prompt"
  prompt={`Submit a transaction for Didit monitoring through the Management API.

Endpoint:
POST https://verification.didit.me/v3/transactions/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
- Submit a transaction for KYT (transaction monitoring). Didit runs the configured rules engine, blockchain analytics, AML screening, and optional Travel Rule checks synchronously and returns the verdict in the response. The full detail (parties, rule runs, provider results, remediation links) is also returned.

When to call:
- At payment authorization, before fanning out funds, to decide allow / hold / decline based on status, score, severity.
- On post-trade events (gambling bets, audit-trail events, KYC events) for long-running monitoring without a per-transaction decision.
- On crypto deposits / withdrawals — set transaction_details.currency_kind = "crypto" and provide the relevant wallet address in payment_method.account_id.
- For Travel Rule — include travel_rule_details with originator/beneficiary VASP metadata.

Identifiers:
- transaction_id is YOUR identifier (max 128 chars), unique per application. It becomes txn_id on subsequent calls. Reusing the same transaction_id returns 400.
- The returned uuid is Didit's stable identifier — use it in GET /v3/transactions/{transaction_id}/.

Linking to entities:
- subject.vendor_data (and optionally counterparty.vendor_data) are your internal user/business identifiers. They link the transaction to the long-lived User / Business entity assembled from prior verification sessions. Use the SAME vendor_data you supplied when creating the KYC session.

Minimum request body (application/json):
{
"transaction_id": "your-txn-2026-05-17-001",
"transaction_category": "finance",   // finance | kyc | travel_rule | user_event | audit_trail_event | gambling_bet | gambling_limit_change | gambling_bonus_change
"transaction_details": {
"direction": "outbound",            // "inbound" | "outbound"
"amount": 1500,                     // number, up to 18 decimal places
"currency": "EUR",
"currency_kind": "fiat",            // "fiat" | "crypto" (optional)
"action_type": "withdrawal"         // optional, e.g. deposit/withdrawal/transfer
},
"subject": {                          // APPLICANT party
"entity_type": "individual",        // "individual" | "company"
"vendor_data": "user-12345",        // required
"full_name": "Maria Garcia",        // required
"address": { "country": "ESP" }     // optional
},
"counterparty": { ... },              // optional COUNTERPARTY party (same shape as subject)
"transaction_at": "2026-05-17T08:42:00Z",  // optional, defaults to now
"travel_rule_details": { ... }        // optional, for crypto Travel Rule
}

Example call:
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"}
}'

What to read from the response:
- uuid — Didit transaction id, use for GET /v3/transactions/{transaction_id}/.
- status — APPROVED | IN_REVIEW | DECLINED (live verdict).
- score (0–100, higher = riskier) and severity (LOW | MEDIUM | HIGH | CRITICAL).
- decision_reason_code / decision_reason_label — machine + human verdict reason.
- parties (APPLICANT, COUNTERPARTY, EXTERNAL), cost_breakdown, rule_runs, wallet_screening / network snapshots (for crypto).

Webhooks:
- transaction.created fires after this call succeeds.
- transaction.status.updated fires whenever the verdict changes (manual review, async screening, rule re-runs). Subscribe a destination via POST /v3/webhook/destinations/.

Failure modes:
- 400 — duplicate transaction_id, missing required field, invalid currency/direction/category enum, or malformed party object.
- 401 — missing or malformed x-api-key.
- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.
- 429 — rate limited; back off and retry.

Side effects:
- Creates the transaction record and runs the synchronous rules + screening pipeline.
- Links the transaction to the User / Business entity that shares the subject.vendor_data.

For the full integration shape, see /integration/integration-prompt.`}
/>


## OpenAPI

````yaml POST /v3/transactions/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/transactions/:
    post:
      tags:
        - Transactions
      summary: Create transaction
      description: >-
        Submit a transaction for synchronous AML/risk monitoring. The
        transaction is created `APPROVED`, then your rules (and crypto
        screening, when applicable) run inline and may flip the returned
        `status` to `IN_REVIEW` or `DECLINED`. **`transaction_id` is your
        idempotency key** (max 128 chars, unique per app); reusing it returns
        400. A `transaction.created` webhook is dispatched on success (sandbox
        applications are not billed and do not emit webhooks).
      operationId: createTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction_id:
                  type: string
                  description: >-
                    Your unique identifier for this transaction (max 128
                    characters).
                  example: your-txn-2026-05-17-001
                transaction_at:
                  type: string
                  format: date-time
                  description: When the transaction occurred. Defaults to now if omitted.
                time_zone:
                  type: string
                  description: IANA time zone identifier, e.g. `Europe/Madrid`.
                transaction_category:
                  type: string
                  description: >-
                    Category of the transaction. CamelCase aliases
                    (`travelRule`, `userPlatformEvent`, `gamblingBet`, …) are
                    also accepted; the stored/echoed value is camelCase for
                    multi-word categories.
                  example: finance
                  enum:
                    - finance
                    - kyc
                    - travel_rule
                    - user_event
                    - audit_trail_event
                    - gambling_bet
                    - gambling_limit_change
                    - gambling_bonus_change
                transaction_details:
                  type: object
                  description: Core financial details of the transaction.
                  required:
                    - direction
                    - amount
                    - currency
                  properties:
                    direction:
                      type: string
                      description: >-
                        Direction of the transaction relative to the subject.
                        Case-insensitive; `in`/`out` are accepted as aliases.
                        Echoed back uppercase (`INBOUND`/`OUTBOUND`).
                      example: outbound
                      enum:
                        - inbound
                        - outbound
                        - in
                        - out
                    amount:
                      type: number
                      description: Transaction amount (up to 18 decimal places).
                      example: 1500
                    currency:
                      type: string
                      description: Currency code, e.g. `EUR`, `USD`, `BTC`.
                      example: EUR
                    currency_kind:
                      type: string
                      description: Whether the currency is `fiat` or `crypto`.
                    amount_in_default_currency:
                      type: number
                      nullable: true
                      description: >-
                        Pre-converted amount in the default currency. If
                        omitted, automatic FX conversion is attempted.
                    default_currency:
                      type: string
                      description: The default currency code for the converted amount.
                    payment_details:
                      type: string
                      nullable: true
                      description: Free-text payment reference or memo.
                    payment_reference_id:
                      type: string
                      nullable: true
                      description: >-
                        External payment system reference. For crypto AML
                        transaction-hash screening, send the blockchain
                        transaction hash and also provide
                        `subject.payment_method.account_id` with the related
                        address.
                    action_type:
                      type: string
                      nullable: true
                      description: >-
                        Sub-type of the transaction, e.g. `deposit`,
                        `withdrawal`, `transfer`.
                subject:
                  type: object
                  description: The subject (applicant) of the transaction.
                  required:
                    - vendor_data
                    - full_name
                  properties:
                    entity_type:
                      type: string
                      description: 'Entity type: `individual` or `company`.'
                    vendor_data:
                      type: string
                      description: Your internal user/business identifier.
                      example: user-12345
                    full_name:
                      type: string
                      description: Full name of the subject.
                      example: Maria Garcia
                    first_name:
                      type: string
                      description: First name of the subject.
                    last_name:
                      type: string
                      description: Last name of the subject.
                    date_of_birth:
                      type: string
                      format: date
                      description: Date of birth (YYYY-MM-DD).
                    address:
                      type: object
                      description: Address object.
                      properties:
                        country:
                          type: string
                          description: >-
                            Country code (ISO 3166-1 alpha-3 recommended).
                            Copied to the party's `country_code`.
                        town:
                          type: string
                        state:
                          type: string
                        street:
                          type: string
                        post_code:
                          type: string
                    institution_details:
                      type: object
                      description: Institution details (for institutional subjects).
                      properties:
                        name:
                          type: string
                        code:
                          type: string
                        address:
                          type: object
                    device_context:
                      type: object
                      description: Device context captured at transaction time.
                    payment_method:
                      type: object
                      description: Payment method used by the subject.
                      properties:
                        method_type:
                          type: string
                          description: >-
                            Type of payment method: `bank_card`, `bank_account`,
                            `crypto_wallet`, `ewallet`, `unhosted_wallet`,
                            `other`.
                        account_id:
                          type: string
                          description: >-
                            Account identifier (e.g. IBAN, wallet address). For
                            crypto screening, this should contain the wallet
                            address for this participant. Inbound
                            transaction-hash screening requires the
                            service/customer deposit address on the subject.
                            Outbound screening uses the destination wallet on
                            the counterparty.
                        issuing_country:
                          type: string
                          description: ISO 3166-1 alpha-3 country code of the issuer.
                counterparty:
                  type: object
                  description: The counterparty of the transaction (optional).
                  properties:
                    entity_type:
                      type: string
                      description: 'Entity type: `individual` or `company`.'
                    vendor_data:
                      type: string
                      description: Your internal identifier for the counterparty.
                    full_name:
                      type: string
                      description: Full name of the counterparty.
                    first_name:
                      type: string
                    last_name:
                      type: string
                    date_of_birth:
                      type: string
                      format: date
                    address:
                      type: object
                      description: Address object with `country` (ISO 3166-1 alpha-3).
                    institution_details:
                      type: object
                    device_context:
                      type: object
                    payment_method:
                      type: object
                      description: Payment method used by the counterparty.
                      properties:
                        method_type:
                          type: string
                        account_id:
                          type: string
                        issuing_country:
                          type: string
                custom_properties:
                  type: object
                  description: >-
                    Arbitrary key-value pairs attached to the transaction. Each
                    key can be referenced in rule conditions with the field path
                    `custom_values.<key>`.
                  additionalProperties: true
                  example:
                    merchant_id: test
                    bank_name: test_2
                travel_rule_details:
                  type: object
                  description: Travel Rule compliance metadata.
                  required:
                    - status
                  properties:
                    status:
                      type: string
                    protocol:
                      type: string
                    required:
                      type: boolean
                    obligations_count:
                      type: integer
                    originator_data:
                      type: object
                    beneficiary_data:
                      type: object
                    metadata:
                      type: object
                network_snapshot:
                  type: object
                  description: Pre-computed network graph snapshot.
                  properties:
                    nodes:
                      type: array
                      items:
                        type: object
                    edges:
                      type: array
                      items:
                        type: object
                    metrics:
                      type: object
                include_crypto_screening:
                  type: boolean
                  nullable: true
                  description: >-
                    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.
              required:
                - transaction_id
                - transaction_category
                - transaction_details
                - subject
            examples:
              Minimal fiat withdrawal:
                summary: Smallest acceptable payload for a fiat outbound transfer
                value:
                  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
              Crypto outbound with screening:
                summary: >-
                  Outbound crypto withdrawal to an unhosted wallet, opt-in
                  screening
                value:
                  transaction_id: your-txn-2026-05-17-002
                  transaction_category: finance
                  include_crypto_screening: true
                  transaction_details:
                    direction: outbound
                    amount: 0.5
                    currency: BTC
                    currency_kind: crypto
                    amount_in_default_currency: 32500
                    default_currency: USD
                    action_type: withdrawal
                  subject:
                    entity_type: individual
                    vendor_data: user-12345
                    full_name: Maria Garcia
                    payment_method:
                      method_type: crypto_wallet
                      account_id: bc1qexampleexchangewalletaddressxyz
                      issuing_country: ESP
                  counterparty:
                    entity_type: individual
                    payment_method:
                      method_type: unhosted_wallet
                      account_id: bc1qexampleexternalwalletaddressabc
              Travel Rule transfer:
                summary: >-
                  Outbound crypto transfer with Travel Rule
                  originator/beneficiary data
                value:
                  transaction_id: your-txn-2026-05-17-003
                  transaction_category: travel_rule
                  transaction_details:
                    direction: outbound
                    amount: 25000
                    currency: USDT
                    currency_kind: crypto
                    payment_reference_id: '0xabcdef1234567890'
                    action_type: transfer
                  subject:
                    entity_type: individual
                    vendor_data: user-12345
                    full_name: Maria Garcia
                    date_of_birth: '1992-03-14'
                    address:
                      country: ESP
                      town: Madrid
                      street: Calle Mayor 1
                      post_code: '28013'
                  counterparty:
                    entity_type: individual
                    full_name: John Beneficiary
                    institution_details:
                      name: Beneficiary VASP, Inc.
                      code: BVASP-US
                  travel_rule_details:
                    status: PENDING
                    protocol: IVMS101
                    required: true
                    originator_data:
                      name: Maria Garcia
                    beneficiary_data:
                      name: John Beneficiary
      responses:
        '201':
          description: >-
            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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDetail'
              examples:
                Approved with no rule hits:
                  value:
                    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
                Flagged for review:
                  value:
                    uuid: abcdef12-3456-4890-abcd-ef1234567891
                    transaction_number: 4124
                    txn_id: your-txn-2026-05-17-002
                    txn_date: '2026-05-17T08:42:00Z'
                    zone_id: Europe/Madrid
                    transaction_type: finance
                    action_type: withdrawal
                    direction: OUTBOUND
                    status: IN_REVIEW
                    amount: '0.5'
                    currency: BTC
                    currency_type: crypto
                    amount_in_default_currency: '32500'
                    default_currency_code: USD
                    preferred_currency_amount: '32500'
                    preferred_currency_code: USD
                    payment_details: Withdrawal to crypto wallet
                    payment_txn_id: null
                    score: 78
                    severity: HIGH
                    decision_reason_code: WALLET_HIGH_RISK
                    decision_reason_label: Destination wallet flagged as high risk
                    vendor_data: user-12345
                    metadata:
                      subject:
                        entity_type: individual
                        vendor_data: user-12345
                        full_name: Maria Garcia
                        address: {}
                        institution_details: {}
                        device_context: {}
                      counterparty: {}
                    props:
                      order_id: ord-9988
                    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: []
                    alerts:
                      - uuid: a7b8c9d0-1234-4abc-9def-567890abcdef
                        title: Destination wallet flagged as high risk
                        description: Provider risk score exceeded the configured threshold.
                        severity: HIGH
                        status: OPEN
                        source: RULE
                        metadata: {}
                        created_at: '2026-05-17T08:42:12Z'
                        due_at: null
                    rule_runs:
                      - uuid: e5f6a7b8-9012-4cde-af01-23456789abcd
                        rule: f6a7b8c9-0123-4def-b012-3456789abcde
                        rule_title: High-risk wallet screening
                        rule_description: null
                        rule_category: crypto
                        matched: true
                        is_test: false
                        mode: ACTIVE
                        severity: HIGH
                        score_delta: 78
                        status_target: IN_REVIEW
                        action_summary:
                          add_score: 78
                          change_status: IN_REVIEW
                        metadata: {}
                        created_at: '2026-05-17T08:42:12Z'
                    provider_results: []
                    travel_rule: null
                    network_snapshot: null
                    remediation: null
                    cost_breakdown: null
        '400':
          description: >-
            Validation failed (missing required fields, duplicate
            `transaction_id`, unknown enum value, invalid currency, etc.).
          content:
            application/json:
              examples:
                Missing required field:
                  value:
                    transaction_details:
                      amount:
                        - This field is required.
                Duplicate transaction_id:
                  value:
                    transaction_id:
                      - A transaction with this transaction_id already exists.
                Invalid category:
                  value:
                    non_field_errors:
                      - Unsupported transaction category.
                Missing subject identity:
                  value:
                    subject:
                      - subject.vendor_data and subject.full_name are required.
                Blocklisted participant:
                  value:
                    vendor_data:
                      - >-
                        The individual 'user-12345' is in the blocklist and
                        cannot participate in transactions.
        '403':
          description: >-
            Missing, invalid, or revoked API key, or the key cannot submit
            transactions for this application. This endpoint returns `403`
            (never `401`) for authentication failures, including requests with
            no credentials at all.
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: >-
            Rate limit exceeded; back off and retry after the interval indicated
            in `Retry-After`.
          content:
            application/json:
              examples:
                Throttled:
                  value:
                    detail: Request was throttled. Expected available in 30 seconds.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            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"
                }
              }'
        - lang: python
          label: Python
          source: |-
            import os

            import requests

            resp = requests.post(
                'https://verification.didit.me/v3/transactions/',
                headers={
                    'x-api-key': os.environ['DIDIT_API_KEY'],
                    'Content-Type': 'application/json',
                },
                json={
                    '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',
                    },
                },
                timeout=15,
            )
            resp.raise_for_status()
            tx = resp.json()
            print(tx['txn_id'], '->', tx['status'], tx['severity'])
        - lang: javascript
          label: JavaScript
          source: >-
            const resp = await
            fetch('https://verification.didit.me/v3/transactions/', {
              method: 'POST',
              headers: {
                'x-api-key': process.env.DIDIT_API_KEY,
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({
                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',
                },
              }),
            });

            if (!resp.ok) throw new Error(await resp.text());

            const tx = await resp.json();

            console.log(tx.txn_id, tx.status, tx.severity);
components:
  schemas:
    TransactionDetail:
      type: object
      description: >-
        Full monitoring record for one transaction, as returned by `GET
        /v3/transactions/{transaction_id}/` and `POST /v3/transactions/`.
      properties:
        uuid:
          type: string
          format: uuid
          description: >-
            Didit-stable transaction identifier. Use as `{transaction_id}` for
            follow-up calls.
        transaction_number:
          type: integer
          description: >-
            Application-scoped sequential transaction number shown in Console
            (e.g. `4123`).
        txn_id:
          type: string
          description: >-
            The `transaction_id` you supplied at create time (max 128 chars).
            Unique per application.
        txn_date:
          type: string
          format: date-time
          description: >-
            When the transaction occurred (from `transaction_at`; defaults to
            submission time).
        zone_id:
          type: string
          nullable: true
          description: IANA time zone identifier provided at create time.
        transaction_type:
          type: string
          description: >-
            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:
          type: string
          description: >-
            Sub-type within the category (e.g. `deposit`, `withdrawal`,
            `transfer`). Defaults to the category when not supplied.
        direction:
          type: string
          enum:
            - INBOUND
            - OUTBOUND
          description: >-
            Direction relative to the subject. Stored uppercase regardless of
            the casing submitted (`in`/`out`/`inbound`/`outbound` are accepted
            on input).
        status:
          type: string
          enum:
            - APPROVED
            - IN_REVIEW
            - DECLINED
            - AWAITING_USER
          description: >-
            Current monitoring verdict. Transactions are created `APPROVED`;
            rules may flip them to `IN_REVIEW`/`DECLINED` synchronously.
        amount:
          type: string
          description: >-
            Transaction amount as a decimal string with trailing zeros stripped
            (e.g. `"1500"`, `"0.5"`, `"0.123456789012345678"`). Up to 18 decimal
            places.
        currency:
          type: string
          description: Currency code of `amount` (e.g. `EUR`, `USD`, `BTC`).
        currency_type:
          type: string
          nullable: true
          description: '`fiat` or `crypto`, as submitted in `currency_kind`.'
        amount_in_default_currency:
          type: string
          nullable: true
          description: >-
            Pre-converted amount you supplied, as a decimal string with trailing
            zeros stripped.
        default_currency_code:
          type: string
          nullable: true
        preferred_currency_amount:
          type: string
          nullable: true
          description: >-
            `amount` converted to the application's preferred currency, when
            available.
        preferred_currency_code:
          type: string
          nullable: true
        payment_details:
          type: string
          nullable: true
          description: Free-text payment reference or memo from the submission.
        payment_txn_id:
          type: string
          nullable: true
          description: >-
            External payment system reference (e.g. blockchain transaction hash)
            from `payment_reference_id`.
        score:
          type: integer
          description: Risk score accumulated by rules (typically 0–100). Higher = riskier.
        severity:
          type: string
          nullable: true
          enum:
            - UNKNOWN
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
          description: >-
            Categorical risk severity set by rules/providers (`UNKNOWN`, `LOW`,
            `MEDIUM`, `HIGH`, `CRITICAL`). `null` until something sets it.
        decision_reason_code:
          type: string
          nullable: true
          description: Machine-readable reason for the current `status`.
        decision_reason_label:
          type: string
          nullable: true
          description: Human-readable label for `decision_reason_code`.
        vendor_data:
          type: string
          nullable: true
          description: Convenience copy of the applicant's `vendor_data`.
        metadata:
          type: object
          description: >-
            Snapshot of the `subject` and `counterparty` payloads as submitted
            at create time.
        props:
          type: object
          description: >-
            The `custom_properties` you supplied at create time. Each key is
            addressable in rule conditions as `custom_values.<key>`.
        tags:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                format: uuid
              name:
                type: string
              color:
                type: string
              description:
                type: string
                nullable: true
              source:
                type: string
                enum:
                  - didit
                  - custom
                description: Whether the tag is a Didit preset or a custom tag.
          description: Tags attached to the transaction (manually or by rules).
        parties:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                format: uuid
              role:
                type: string
                enum:
                  - APPLICANT
                  - REMITTER
                  - BENEFICIARY
                  - COUNTERPARTY
                description: >-
                  Party role. The create endpoint assigns `APPLICANT` (the
                  subject) and `COUNTERPARTY`.
              entity_type:
                type: string
                enum:
                  - individual
                  - company
                  - external
                  - unhostedWallet
              kind:
                type: string
                enum:
                  - USER
                  - BUSINESS
                  - EXTERNAL
                description: >-
                  `USER`/`BUSINESS` parties link back to a Didit-owned entity
                  via `vendor_data`. `EXTERNAL` parties have no Didit entity
                  behind them.
              vendor_data:
                type: string
                nullable: true
                description: Your internal user/business identifier.
              full_name:
                type: string
                nullable: true
              first_name:
                type: string
                nullable: true
              last_name:
                type: string
                nullable: true
              country_code:
                type: string
                nullable: true
                description: >-
                  Country code from the submitted `address.country` (typically
                  ISO 3166-1 alpha-3).
              dob:
                type: string
                format: date
                nullable: true
                description: Date of birth from the submitted `date_of_birth`.
              address:
                type: object
                description: Address object as submitted. `{}` when omitted.
              institution_info:
                type: object
                description: Institution details as submitted. `{}` when omitted.
              device:
                type: object
                description: >-
                  Normalized device context, including server-side IP enrichment
                  under `network_context` (geolocation, VPN/data-center flags)
                  when an IP was provided.
              external_party_snapshot:
                type: object
                nullable: true
                description: >-
                  Frozen copy of the party data for `EXTERNAL` parties (or after
                  the linked entity was deleted). `null` while linked to a live
                  entity.
          description: Transaction parties (applicant, counterparty).
        payment_methods:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                format: uuid
              payment_method_type:
                type: string
                enum:
                  - bank_card
                  - bank_account
                  - e_wallet
                  - crypto_wallet
                  - unhosted_wallet
                  - other
              label:
                type: string
                nullable: true
              fingerprint:
                type: string
                nullable: true
                description: >-
                  SHA-256 over `type:account_id:issuing_country` — stable
                  identifier to correlate reuse of the same instrument.
              account_id:
                type: string
                nullable: true
                description: Account identifier (IBAN, wallet address, card token, …).
              issuing_country:
                type: string
                nullable: true
              owner_kind:
                type: string
                enum:
                  - USER
                  - BUSINESS
                  - EXTERNAL
              vendor_data:
                type: string
                nullable: true
                description: Your identifier for the owning user/business.
              owner_name:
                type: string
                nullable: true
              institution_info:
                type: object
              details:
                type: object
                description: Raw `payment_method` object as submitted.
              external_owner_snapshot:
                type: object
                nullable: true
              role:
                type: string
                enum:
                  - SOURCE
                  - DESTINATION
                  - FUNDING
                  - BENEFICIARY
                description: >-
                  How this method was used in the transaction. The create
                  endpoint assigns `SOURCE`/`DESTINATION` from the direction
                  (outbound: subject = SOURCE; inbound: subject = DESTINATION).
          description: Payment methods linked to the transaction.
        activities:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                format: uuid
              activity_type:
                type: string
                description: >-
                  E.g. `TRANSACTION_CREATED`, `TRANSACTION_NOTE_ADDED`,
                  `TRANSACTION_STATUS_CHANGED`.
              source:
                type: string
              status:
                type: string
                nullable: true
              title:
                type: string
                nullable: true
              description:
                type: string
                nullable: true
              metadata:
                type: object
              occurred_at:
                type: string
                format: date-time
          description: >-
            Activity log entries (creation, notes, manual reviews, status
            changes).
        alerts:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                format: uuid
              title:
                type: string
              description:
                type: string
                nullable: true
              severity:
                type: string
                enum:
                  - UNKNOWN
                  - LOW
                  - MEDIUM
                  - HIGH
                  - CRITICAL
              status:
                type: string
                enum:
                  - OPEN
                  - INVESTIGATING
                  - AWAITING_USER
                  - PENDING_SAR
                  - SAR_FILED
                  - RESOLVED
                  - DISMISSED
              source:
                type: string
                enum:
                  - RULE
                  - PROVIDER
                  - MANUAL
              metadata:
                type: object
              created_at:
                type: string
                format: date-time
              due_at:
                type: string
                format: date-time
                nullable: true
          description: Alerts raised by rules and providers.
        rule_runs:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                format: uuid
              rule:
                type: string
                format: uuid
                description: UUID of the rule that ran.
              rule_title:
                type: string
              rule_description:
                type: string
                nullable: true
              rule_category:
                type: string
              matched:
                type: boolean
                description: Whether the rule's conditions matched this transaction.
              is_test:
                type: boolean
                description: >-
                  True when the rule ran in TEST mode (no effect on
                  status/score).
              mode:
                type: string
                enum:
                  - ACTIVE
                  - DISABLED
                  - TEST
              severity:
                type: string
                nullable: true
              score_delta:
                type: integer
                description: Score added by this rule's `add_score` actions.
              status_target:
                type: string
                nullable: true
                description: Status set by a `change_status` action, if any.
              action_summary:
                type: object
                description: Summary of the actions the rule executed.
              metadata:
                type: object
              created_at:
                type: string
                format: date-time
          description: >-
            Per-rule execution results — which rule fired, with what score
            impact.
        provider_results:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                format: uuid
              provider:
                type: string
              result_type:
                type: string
                enum:
                  - FIAT_MONITORING
                  - WALLET_SCREENING
                  - TRANSACTION_SCREENING
                  - TRAVEL_RULE
                  - NETWORK_GRAPH
                  - CUSTOM
              status:
                type: string
              severity:
                type: string
                nullable: true
              score:
                type: integer
              summary:
                type: string
                nullable: true
              payload:
                type: object
                description: Raw provider response payload.
              created_at:
                type: string
                format: date-time
          description: Raw provider payloads (AML screening, blockchain analytics, etc.).
        travel_rule:
          type: object
          nullable: true
          description: >-
            Travel Rule compliance check, present when `travel_rule_details` was
            submitted.
          properties:
            uuid:
              type: string
              format: uuid
            status:
              type: string
            protocol:
              type: string
              nullable: true
            required:
              type: boolean
            obligations_count:
              type: integer
            originator_data:
              type: object
            beneficiary_data:
              type: object
            metadata:
              type: object
        network_snapshot:
          type: object
          nullable: true
          description: >-
            Graph snapshot of related transactions/parties used by the rules
            engine, present when submitted.
          properties:
            uuid:
              type: string
              format: uuid
            nodes:
              type: array
              items:
                type: object
            edges:
              type: array
              items:
                type: object
            metrics:
              type: object
        remediation:
          type: object
          nullable: true
          description: >-
            Remediation session offered to the user when re-verification is
            required.
          properties:
            session_id:
              type: string
            session_token:
              type: string
            url:
              type: string
              format: uri
            status:
              type: string
        cost_breakdown:
          type: object
          nullable: true
          description: Per-feature credit cost breakdown for this transaction.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````