Fraud Detection Overview
Synchronous fraud verdicts, deterministic rules, and an immutable decision trail — the control plane for fraud-resistant infrastructure.
The PlatformXe Fraud Detection Engine renders synchronous risk verdicts on every action your application protects, with a clear reason chain, immutable audit trail, and tenant-controlled rule logic.
What it does
- Decide in real time —
POST /api/v1/fraud/decidereturns one ofallow,review,step_up, orblockfor any subject + action + resource tuple, in milliseconds. - Explain every verdict — every response includes a structured
reasons[]chain so reviewers and customers can always trace why an action was flagged. - Reproduce any past decision — every rendered verdict is recorded in
fraud_decisions(append-only, 90-day default retention) and exposed underfraud:audit. - Validate rules safely —
shadow-decideruns a verdict without enforcement, so you can publish rules with confidence. - Stay deterministic — verdicts are produced by rules and signals you control, not a black-box model.
The control-plane principle
PlatformXe is the fraud control plane — the layer between your application and the action it protects. The engine never decides whether to commit a transaction, freeze an account, or send a wire. The tenant is always the decision authority of record. Every decide response carries a mandatory notice field reminding callers of this boundary; the full liability framing lives in the Fraud Detection Terms.
The verdict is informational. Your app keeps full control over what action is taken on the basis of it.
What ships in each phase
| Phase | Capability | Status |
|---|---|---|
| 6A | Decision spine — decide, shadow-decide, decision audit, scopes, events | Live |
| 6B | Velocity rules engine + ABAC-shape rule DSL | Live |
| 6C | Sanctions / PEP screening + tenant lists + multi-provider fallback | Live |
| 6C2 | Per-source list fetchers (OFAC / UN / EU / UK HMT / NFIU) wired to daily refresh cron | Live |
| 6D | Device fingerprint registry + IP intelligence + 4 built-in signals | Live |
| 6E | Cases workflow + auto-open on block + SLA cron | Live |
| 6F | Nigerian KYC: BVN, NIN, liveness, face-match, account-name + KMS-encrypted audit trail | Live |
| 6F.5 | Identity Resilience: country plugins, per-(country, provider) circuit breakers, provider health endpoint | Live |
| 6F.5b | DLQ + replay endpoints, hedging primitive, latency observations, KE / GH / ZA country plugins | Live |
| 6G | Federated rule + tenant list push for ENTERPRISE multi-org tenants | Live |
| 6H | Liability T&Cs + click-through gate (/legal/fraud-detection-terms) | Live |
Plan & access
The Fraud Detection Engine is a Detection Pack addon to the flat tier. It is available to both Pro and Enterprise organizations, with Enterprise unlocking federation push and commercial-screening volume tiers.
| Capability | Pro | Enterprise |
|---|---|---|
fraud:decide quota included | 10,000 / month | 100,000 / month |
| Detection Pack base | ₦40,000 / month | included |
| Per-call overage above quota | ₦8 / call | ₦5 / call |
API scopes
| Scope | Endpoints |
|---|---|
fraud:decide | /decide, /shadow-decide, /devices/seen |
fraud:screen | /screen (Phase 6C) |
fraud:manage | /rules, /lists (Phase 6B–6C) |
fraud:audit | /decisions, /decisions/:id |
fraud:cases | /cases (Phase 6E) |
Endpoints (Phases 6A–6E — live)
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/fraud/decide | Render a synchronous verdict |
| POST | /api/v1/fraud/shadow-decide | Dry-run a decision (no enforcement, no metering) |
| GET | /api/v1/fraud/decisions | Audit query — list rendered decisions |
| GET | /api/v1/fraud/decisions/:id | Fetch a single decision by id |
| GET | /api/v1/fraud/rules | List tenant rules |
| POST | /api/v1/fraud/rules | Create a rule (always draft) |
| GET | /api/v1/fraud/rules/:id | Fetch one rule |
| PATCH | /api/v1/fraud/rules/:id | Update a draft or shadow rule |
| DELETE | /api/v1/fraud/rules/:id | Soft-archive |
| POST | /api/v1/fraud/rules/:id/transition | Lifecycle transition |
| GET | /api/v1/fraud/rules/:id/shadow-report | Trigger-rate metrics |
| POST | /api/v1/fraud/screen | Sanctions / PEP / adverse-media / tenant-list screening |
| GET / POST | /api/v1/fraud/lists | Tenant lists CRUD (allowlists / blocklists) |
| GET / PATCH / DELETE | /api/v1/fraud/lists/:id | Single list operations |
| GET / POST | /api/v1/fraud/lists/:id/entries | List entry CRUD (bulk add ≤ 1,000) |
| DELETE | /api/v1/fraud/lists/:id/entries/:entryId | Remove a single entry |
| POST | /api/v1/fraud/devices/seen | Register a device fingerprint observation |
| GET / POST | /api/v1/fraud/cases | List or open cases |
| GET / PATCH | /api/v1/fraud/cases/:id | Fetch or update a case |
| POST | /api/v1/fraud/cases/:id/transition | State-machine transition (open / triaging / escalated / resolved) |
| POST | /api/v1/identity/verify-bvn | Verify BVN + match against expected name |
| POST | /api/v1/identity/verify-nin | Verify NIN + match against expected name |
| POST | /api/v1/identity/liveness | Liveness detection on a selfie image |
| POST | /api/v1/identity/face-match | Selfie ↔ ID-document similarity |
| POST | /api/v1/identity/verify-account | Bank-account-name verification (NIBSS-equivalent) |
| GET | /api/v1/identity/providers/health | Provider circuit-breaker rollup (per country) |
Performance contract
| Operation | p50 | p95 | p99 |
|---|---|---|---|
POST /v1/fraud/decide | 15ms | 60ms | 120ms |
The hot path is Redis-only on the engine side; the durable fraud_decisions write is fanned out asynchronously via Inngest so it never blocks the verdict.
Next steps
- Quickstart — your first verdict
- Decision API reference
- Audit trail
- Rules — DSL, lifecycle, and shadow reports
- Screening — sanctions / PEP with multi-provider fallback
- Tenant lists — allowlists and blocklists
- Device registry — fingerprint signals + IP intelligence
- Cases — reviewer workflow with SLA escalation
- Identity verification — BVN, NIN, liveness, face-match, account-name
- Identity resilience — country plugins, circuit breakers, provider health