Transaction monitoring

Send each transaction or customer activity when it happens. Toden connects it to the customer, evaluates the relevant controls and returns an explainable allow, review or block decision.

Have past transactions to assess? Preview a historical batch before submitting it through this same endpoint.

Choose the correct endpoint

Use a secret sk_ key with the same base URL and authentication as the Identity Hub. Use the v1 endpoints for new integrations.

Complete value reference

The tables below are the complete closed-value fields accepted by the v1 transaction, activity and outcome contracts. Values are lowercase and case-sensitive in requests. If a value is not listed here, the API rejects it rather than guessing.

Request enum values

The response decision values are allow, review and block. Use them as machine values and show your own customer-facing copy separately.

Open string fields

These fields are intentionally not enums: channel, transaction.transactionType, transaction.status, transaction.paymentMethod, transaction.blockchain, currency, metadata keys and customAttributes keys. Send stable, documented values from your own system. Toden stores them as evidence and may use them in authorised custom controls, but does not silently translate them into another value.

POST /api/identity/events is a compatibility endpoint, so its type is also an open string. Recognised names containing transaction, payment, transfer, login, sign-in, sign-up, register, password reset, beneficiary added, profile change, device change, payout or withdrawal are routed into the canonical assessment pipeline. New integrations should use the closed v1 activity types above.

Send a complete transaction

POST /api/v1/transactions

The subject is your customer. The parties array describes who sent and received the funds. Add each bank account, wallet, card or other payment method to the party that used it.

Outbound bank transfer

{
  "externalActivityId": "activity_txn_10001",
  "subject": {
    "type": "individual",
    "externalUserId": "user_42"
  },
  "occurredAt": "2026-08-16T09:30:00.000Z",
  "channel": "bank_transfer",
  "deviceRef": "device_7f53",
  "ipAddress": "102.89.12.34",
  "country": "NG",
  "location": {
    "city": "Lagos",
    "region": "Lagos",
    "latitude": 6.5244,
    "longitude": 3.3792,
    "accuracyRadiusKm": 10
  },
  "transaction": {
    "externalTransactionId": "txn_10001",
    "assetClass": "fiat",
    "direction": "outbound",
    "amount": "48000.00",
    "currency": "NGN",
    "transactionType": "bank_transfer",
    "status": "pending",
    "channel": "bank_transfer",
    "paymentMethod": "bank_account",
    "parties": [
      {
        "role": "sender",
        "externalUserId": "user_42",
        "type": "individual",
        "displayName": "Sample customer",
        "country": "NG",
        "deviceRef": "device_7f53",
        "instruments": [
          {
            "type": "bank_account",
            "externalInstrumentId": "customer_account_01",
            "identifier": "0123456789",
            "institutionName": "Sample Bank",
            "country": "NG",
            "currency": "NGN",
            "verified": true
          }
        ]
      },
      {
        "role": "recipient",
        "externalPartyId": "beneficiary_998877",
        "type": "individual",
        "displayName": "Amina Bello",
        "country": "NG",
        "instruments": [
          {
            "type": "bank_account",
            "externalInstrumentId": "beneficiary_account_998877",
            "identifier": "9988776655",
            "institutionName": "Recipient Bank",
            "country": "NG",
            "currency": "NGN"
          }
        ]
      }
    ],
    "metadata": {
      "paymentPurpose": "supplier_payment",
      "customerReference": "invoice_2026_104"
    }
  }
}

This appears as Sample customer → Amina Bello throughout the dashboard. For an inbound transaction, the customer is the recipient and the title appears as Sample customer ← sender name.

Inbound crypto transfer

{
  "externalActivityId": "activity_crypto_10002",
  "subject": {
    "type": "individual",
    "externalUserId": "user_42"
  },
  "occurredAt": "2026-08-16T10:05:00.000Z",
  "channel": "blockchain",
  "country": "NG",
  "transaction": {
    "externalTransactionId": "crypto_10002",
    "assetClass": "crypto",
    "direction": "inbound",
    "amount": "0.25",
    "currency": "USDT",
    "transactionType": "transfer",
    "blockchain": "ethereum",
    "parties": [
      {
        "role": "sender",
        "externalPartyId": "crypto_sender_01",
        "type": "individual",
        "displayName": "Charles Okafor",
        "country": "NG",
        "instruments": [
          {
            "type": "crypto_wallet",
            "externalInstrumentId": "sender_wallet_01",
            "identifier": "0x8ba1f109551bd432803012645ac136ddd64dba72",
            "network": "ethereum",
            "currency": "USDT"
          }
        ]
      },
      {
        "role": "recipient",
        "externalUserId": "user_42",
        "type": "individual",
        "displayName": "Sample customer",
        "country": "NG",
        "instruments": [
          {
            "type": "crypto_wallet",
            "externalInstrumentId": "customer_wallet_01",
            "identifier": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
            "network": "ethereum",
            "currency": "USDT",
            "verified": true
          }
        ]
      }
    ]
  }
}

This appears as Sample customer ← Charles Okafor. Toden screens the sender’s crypto wallet before producing the transaction decision.

How directional screening works

The transaction direction is always from the perspective of your customer.

Crypto counterparties use the same Wallet Intelligence engine as Spot Checks and the direct API. A post-settlement hash remains in Toden’s transaction record; the wallet provider receives the counterparty address only. The internal wallet check is part of the transaction assessment and does not create a second customer wallet charge. A result without wallet evidence requires review; it is never treated as clean.

Individuals are checked for sanctions, PEP and adverse media. Businesses are checked for sanctions and adverse media. If the required target name or wallet address is missing, Toden returns a review decision with an insufficient-data reason rather than treating the transaction as clear.

Transaction fields

Request envelope

transaction

Party fields

Every party needs at least one stable reference: externalUserId, entityId or externalPartyId.

Instrument fields

Each instrument needs externalInstrumentId, identifier or fingerprint. Toden derives a tenant-scoped fingerprint and keeps only safe display evidence.

Transaction assessment response

The response wraps the persisted decision in assessment. Read summary first:

{
  "assessment": {
    "activityId": "act_01j9ghi000",
    "transactionId": "atx_01j9ghi001",
    "decisionId": "dec_01j9ghi002",
    "decision": "review",
    "summary": {
      "outcome": "review",
      "title": "Review required",
      "reason": "New beneficiary with value matched.",
      "score": 72,
      "riskLevel": "high",
      "matchedRules": 1,
      "nextAction": {
        "type": "review_activity",
        "label": "Review transaction"
      }
    },
    "alertId": "alt_01j9ghi003",
    "assessedAt": "2026-08-16T09:30:00.284Z"
  }
}

Use summary.outcome to gate your flow and summary.nextAction to continue it. The complete response also retains matched rules, screening, billing, signals and processing evidence when you need to audit or investigate the result.

Wallet verification & screening

For crypto, each assessment.screening.attempts[] contains a walletScreenings array. Each item is the exact saved counterparty wallet check: id, status, wallet, risk, profile, provider and screenedAt. Multiple screened wallets remain separate items. Read risk.score and risk.level for wallet risk; the transaction’s decision remains the overall Toden decision.

The address overview fields include the analytics provider (Merkle Science when returned), address, blockchain, owner and user attribution, their types and subtypes, first/latest transaction times and provider date added. They have the same names and meaning as standalone wallet results. Missing fields remain null. Name-screening attempts and attempts without linked wallet evidence have an empty array. If walletEvidenceUnavailable is history_limit_exceeded, the evidence read exceeded its bound (100 wallet attempts or 1,000 saved wallets). No partial list is presented; do not interpret that empty array as clean or complete evidence. Create, exact replay and GET /api/v1/transactions/{id} return the same saved wallet evidence without another provider call. The response excludes raw provider data and credentials.

Production billing uses the component prices configured for your organisation. A transaction can contain a fraud-assessment line and one or more screening lines. Sandbox requests are non-billable. Invalid input is rejected before usage is reserved, and service failures are not treated as successful billable assessments.

Send behaviour activity

POST /api/v1/activities

Use this endpoint for non-transaction customer behaviour. The example below connects a login to the customer, device, IP and location used at the time.

{
  "externalActivityId": "login_10001",
  "subject": {
    "type": "individual",
    "externalUserId": "user_42"
  },
  "type": "login",
  "occurredAt": "2026-08-16T09:30:00.000Z",
  "channel": "mobile_app",
  "deviceRef": "device_7f53",
  "ipAddress": "102.89.12.34",
  "country": "NG",
  "location": {
    "city": "Lagos",
    "region": "Lagos",
    "latitude": 6.5244,
    "longitude": 3.3792,
    "accuracyRadiusKm": 10
  },
  "metadata": {
    "authenticationMethod": "password",
    "sessionReference": "session_20001"
  },
  "customAttributes": {
    "trustedDevice": false,
    "failedAttemptsBeforeSuccess": 2
  }
}

Supported behaviour types

Use POST /api/v1/transactions when money movement has sender, recipient, account or wallet evidence. Do not send a transaction through the generic activity endpoint.

Each accepted activity updates the customer’s Behaviour intelligence with the evidence supplied, evaluates active risk-scoring rules, and records the resulting decision. Location observations appear under Connected records → Locations & IPs. Device references contribute to device history and relationship evidence.

Location and IP evidence

Send only evidence you actually collected. ipAddress must be a valid IPv4 or IPv6 address, country uses a two-letter code, and latitude and longitude must be supplied together. accuracyRadiusKm is optional and is accepted only with coordinates.

If you send both location and IP evidence, your supplied location remains primary. IP enrichment fills only missing fields. Replaying the same logical activity does not create a duplicate location observation.

Location capture happens before billable fraud assessment. Invalid activity input does not create a location record or an assessment charge. A temporary location-enrichment failure does not turn otherwise valid activity into a chargeable failure.

Idempotency and freshness

• Use one externalActivityId per logical assessment and keep it stable across retries.
• Use one externalTransactionId per customer transaction.
• Replaying the same request returns the existing assessment with replayed: true and does not score or bill it again.
• Reusing either identifier with different immutable transaction data returns a conflict.
• Send the original occurredAt. Toden retains both the occurrence time and receipt time so late events remain visible and do not distort the audit trail.

Webhooks

Subscribe to fraud.transaction.assessed for every transaction decision and fraud.activity.assessed for every behaviour decision. Transaction webhooks include the subject, external activity and transaction references, structured parties, masked instruments, screening evidence and billing breakdown. Use event.flagged only as a compatibility alias for non-allow decisions.

See Transaction Monitoring webhooks and Event Monitoring webhooks for delivery contracts and retry guidance.

Compatibility event endpoint

POST /api/identity/events remains available for existing integrations:

{
  "externalUserId": "user_42",
  "externalEventId": "txn_10001",
  "type": "transaction.transfer",
  "data": {
    "amount": 48000,
    "currency": "NGN",
    "country": "NG",
    "counterparty": "beneficiary_998877",
    "direction": "outbound",
    "channel": "bank_transfer",
    "ipAddress": "102.89.12.34",
    "location": {
      "city": "Lagos",
      "region": "Lagos",
      "latitude": 6.5244,
      "longitude": 3.3792,
      "accuracyRadiusKm": 10
    }
  }
}

This reduced shape can store and score a simple event, but it cannot submit structured sender and recipient profiles or attach instruments to each party. Migrate transaction integrations to POST /api/v1/transactions to receive complete relationship intelligence, directional screening, billing evidence and human-readable transaction titles.

Errors

Next steps

• Fraud rules: install or build controls for transactions, logins and other activity.
• Ongoing monitoring: configure recurring customer review.
• Investigations and reporting: investigate review and block decisions.
• Webhooks: receive lifecycle events without polling.