Transaction Monitoring

Transaction Monitoring is an opt-in capability: the platform switches it on for your account. Every transaction the engine scores is billed once at your Transaction Monitoring rate (re-evaluations are free). All endpoints authenticate with your API key (X-API-Key or Authorization: Bearer).

The transaction payload

{
  "external_id": "TXN-2026-000123",
  "amount": "650000.00",
  "currency": "NPR",
  "direction": "debit",
  "type": "transfer_out",
  "channel": "mobile",
  "booked_at": "2026-10-22T10:15:00+05:45",
  "status": "posted",
  "account": {
    "external_id": "0123456789",
    "holder_name": "Sita Gurung",
    "product_type": "savings",
    "branch_id": "KTM-01",
    "opened_at": "2023-01-15",
    "customer": { "external_user_id": "cif-88213", "document_number": "12-01-70-01234", "phone": "9841000000" },
    "profile": { "occupation": "salaried", "monthly_income": 85000, "expected_monthly_volume": 300000, "source_of_funds": "salary" }
  },
  "counterparty": { "kind": "external_account", "identifier": "0987654321", "bank_code": "NABIL", "name": "Ram Bahadur", "country": "NP" },
  "narration": "Rent", "reference": "IPS-1182",
  "device_id": "a1b2c3", "ip_address": "27.34.10.10", "geo": { "country": "NP", "city": "Kathmandu" },
  "metadata": {}
}

• direction is credit (money arrives) or debit (money leaves); omit it and the engine infers it from type.
• type: cash_deposit, cash_withdrawal, transfer_in, transfer_out, remittance_in, remittance_out, card_purchase, bill_payment, merchant_payment, loan_disbursement, loan_repayment, salary, fx, fee, interest, other (common aliases such as deposit, p2p, qr, emi are accepted).
• channel: branch, atm, mobile, internet, pos, ips, wallet, swift, agent, api, other.
• account may be a plain string (the account id). customer links the account to the verified identity you onboarded: by your external_user_id, a document number, phone or email.
• fx_rate converts a foreign-currency amount to your base currency for thresholds.

Score a transaction before it goes

POST /v3/monitoring/decide/

Send the payload above (status defaults to pending). The response carries the decision and why. Post the booked transaction later with the same external_id and status: posted to finalise it without scoring it again. Add "dry_run": true to score without storing.

{
  "transaction_id": "…", "external_id": "TXN-2026-000123", "dry_run": false,
  "score": 78, "risk_level": "high", "decision": "challenge",
  "reasons": ["Large debit from a never-seen device: new_device; amount_base = 650,000 (≥ 500,000)"],
  "signals": [{ "detector": "rules", "key": "new_device_large_debit", "typology": "account_takeover",
                "severity": "high", "score": 75, "action": "challenge", "explanation": "…", "evidence": { "matched": [] } }],
  "latency_ms": 23, "alert_id": "…", "mode": "realtime"
}

Responses also include coverage and evaluation_latency_ms. coverage.checks records each check's status (complete, not_applicable, skipped, unavailable, stale, or error), reason, and shadow state. coverage.missing_required lists configured mandatory checks that did not complete. Configure Required checks and When required checks are incomplete in monitoring settings; the action can keep the scored decision, require review, or hold. It only escalates a decision. By default, no checks are mandatory, preserving existing tenant decision policies.

latency_ms remains scoring time. evaluation_latency_ms includes persistence, alerts, playbooks, billing, and event emission. The X-Monitoring-Request-Duration-Ms response header and Server-Timing: monitoring_request;dur=… measure the entire Django request through response rendering, including authentication and ingestion. Network transit and subsequent asynchronous delivery are excluded. The transaction detail stores this as request_latency_ms for its latest HTTP evaluation. Replays have their own request header but do not overwrite the original measurement.

Retries with the same economic facts replay the saved decision without charging again, including after credits are exhausted. Reusing an ID with a different amount, currency, account, beneficiary, or supplied device context returns 409 idempotency_conflict. Older pending/held lifecycle messages do not regress a posted or reversed transaction; contradictory terminal transitions return 409 invalid_status_transition. The original booking timestamp is retained on a replay.

Ingest booked transactions

POST /v3/monitoring/transactions/ — one payload, or {"transactions": [...]} (up to 500). Batches of 25 or fewer are scored synchronously; larger ones return "evaluation": "queued" and go immediately to the evaluation queue, separate from training and imports. A two-minute sweep recovers missed work. Replays of an external_id return "status": "existing"; unevaluated replays are queued again, and the first committed evaluation wins. A multi-status batch answers 207 with per-row results and "status": "rejected" rows carrying error / field.

GET /v3/monitoring/transactions/?account=&since=&until=&decision=review,hold&min_score=60&page= and GET /v3/monitoring/transactions/{id or external_id}/ read them back with scores, reasons and signals.

Accounts

POST /v3/monitoring/accounts/ upserts one account (or {"accounts": [...]}) with the same account object as above — use it to push declared profiles and identity links ahead of traffic. GET /v3/monitoring/accounts/ and GET /v3/monitoring/accounts/{id or external_id}/ return the account, its baseline, recent transactions and open alerts.

Alerts

GET /v3/monitoring/alerts/?status=open,investigating&severity=high,critical&typology=structuring&account=&since= lists alerts; GET /v3/monitoring/alerts/{id}/ includes the signals, evidence, action trail and transactions. POST /v3/monitoring/alerts/{id}/action/ drives the lifecycle from your own case tool:

{ "action": "close", "disposition": "reported", "report_ref": "STR-2026-0142", "note": "Filed with FIU" }

Actions: assign (assignee), unassign, note (note), status (open / investigating / escalated), close (disposition one of true_positive, false_positive, inconclusive, reported + report_ref), reopen.

Response playbooks

Playbooks are configured in the console (Transaction Monitoring → Playbooks): when a scored transaction or a new alert matches a score band, decision, severity, typology or rule, they raise the decision, trigger a KYC workflow for the customer (the link goes out by SMS or email), tag the identity, move the account's risk tier, escalate or notify. Each firing is a run: GET /v3/monitoring/alerts/{id}/ returns playbook_runs with the triggered session and its outcome, and Connect emits playbook.fired / playbook.outcome.

Rules and features

GET /v3/monitoring/rules/ lists the typology rules in force with their human-readable conditions and the tenant variables they reference; GET /v3/monitoring/features/ lists the feature vector the rules can use. Rules are edited in the console.

Webhooks

Subscribe a Connect endpoint to transaction.decided, alert.created, alert.updated and alert.closed to receive decisions and alert lifecycle events.

Errors

Investigation narrative

Each alert can carry a drafted narrative (what happened, assessment, recommended action, questions for the customer, grounds for suspicion) that feeds the case file and the STR. Drafts are built from the alert's own evidence on the server; an optional AI-assisted draft exists but is switched off by default on the platform, so no customer data leaves the deployment unless your administrator enables it.

Regulatory reports

Filing with the FIU is a console feature (Transaction Monitoring → Alerts); there is no partner-API surface for it. From an alert an investigator can download:

• STR XML — a goAML-shaped Suspicious Transaction Report for the alert: the reporting entity and reporting person from Settings → Regulatory reporting, the reason (alert summary, each signal's explanation and the investigation narrative), the latest action, one <transaction> per transaction in the alert with the customer's account on your side and the counterparty on the other, and the rule keys as report indicators. The download needs a complete reporting identity (rentity_id, reporting person, address); it does not change the alert — record the filing with close → reported + report_ref as above.
• Case file PDF — the printable record of the alert: customer and account, why it fired (every signal with its matched evidence), the transactions, counterparty screening, playbooks and workflows triggered, the narrative and the full activity trail.

A TTR XML batch (Threshold Transaction Report) for every cash movement at or above the reporting threshold in a date range is available from the same place. The XML follows the goAML 4.x report layout; confirm FIU-Nepal's current XSD and code lists and validate the file before uploading it.