Risk Engine

The risk engine evaluates every transaction for fraud before routing. Configure antifraud plans, scoring rules, and block/allow lists to protect your merchants and control transaction risk.

Risk Pipeline

The risk check runs after limit checks and before routing in the payment pipeline:

Payment created --> Limit check --> Risk check --> 3DS decision --> Routing --> Attempt

The risk engine produces a signal that determines how the transaction proceeds:

Signal	Action
`allow`	Transaction proceeds to routing normally
`reject`	Transaction is declined immediately
`review`	Transaction is flagged for manual review (if approval queues are enabled)
`force_3ds`	3DS authentication is required regardless of other settings
`skip_3ds`	3DS is skipped for this transaction (e.g., trusted card)

When the risk engine produces multiple signals during evaluation (from list matches, individual scoring rules with direct signal overrides, and score thresholds), the highest-severity signal wins. The precedence order is:

reject > review > force_3ds > skip_3ds > allow

For example, if one scoring rule produces force_3ds and another produces reject, the final signal is reject. If a list match produces allow (via allowlist) but a scoring rule produces review, the final signal is review.

Antifraud Plans

An antifraud plan is a named risk profile that aggregates your risk configuration into a single assignable entity. Each plan references:

Block lists (blacklist groups) — values that should be blocked
Allow lists (whitelist groups) — values that should be trusted
Scoring rules — condition-based rules that contribute to the risk score

Test and Live Plans

A plan belongs to the mode it was created in: a plan created in test mode is a test plan, one created in live mode is a live plan. Scoring rules and list groups work the same way. A plan can reference only rules and groups of its own mode, and the Portal and the API show only the plans, rules and groups of the mode you are in.

A test plan never evaluates live payments, and a live plan never evaluates test payments. A sandbox merchant is a test merchant and takes a test plan; when it goes live, it needs a live plan (see Go-Live Checklist).

Creating an Antifraud Plan

Portal: Navigate to Risk > Antifraud Plans > Create, in the mode the plan is for.

Plan name: Give the plan a descriptive name (e.g., "Standard Risk Profile").
Description: Optional.
Scoring rules: Select which scoring rules to include.
Block/allow lists: Select which list groups to check. Whether a group blocks or allows is set on the group itself.

A new plan is created disabled. Open it and choose Enable to start evaluating it.

Assigning a Plan

A plan is assigned to a merchant: set Antifraud Plan when you create or edit the merchant, or choose the live plan when you approve it. Through the API, pass antifraudPlanId to merchant create, update or approve. The plan must be of the merchant's mode; any other plan answers 422 INVALID_ANTIFRAUD_PLAN_ID. The Portal offers only enabled plans.

One plan can serve many merchants, and enabling a plan does not change any other plan. A disabled plan stays assigned and is skipped: its merchants are not risk-checked until it is enabled again.

There is no tenant-level or terminal-level plan. A merchant without a plan, or with a plan of the other mode, is not risk-checked: the risk check returns allow and the payment proceeds to routing.

Deleting a Plan

Only the owner layer deletes plans. In the Portal, Delete appears on a plan once it is disabled. A plan that any merchant still names cannot be deleted (409 PLAN_IN_USE): assign those merchants another plan, or clear their plan, first. To stop a plan without deleting it, disable it.

Scoring Rules

Scoring rules evaluate transaction attributes and contribute to an aggregate risk score (0--100). When the score exceeds a threshold, the engine produces a reject or review signal.

How Scoring Works

Each rule defines conditions and a score impact (positive = more risky).
If a transaction matches a rule's conditions, the rule's score impact is added to the total.
After all rules are evaluated, the total score is compared against four configurable thresholds:

Threshold	Default	Signal produced
`allowBelow`	20	Score below this: `allow`
`force3dsAbove`	60	Score above this (but below reject): `force_3ds` — forces 3DS authentication even if merchant configuration says to skip it
`reviewAbove`	50	Score above this (but below reject): `review`
`rejectAbove`	80	Score above this: `reject`

The full score-to-signal mapping:

Score range	Signal
0 -- `allowBelow`	`allow`
`allowBelow` -- `reviewAbove`	`allow` (score visible to operators in pipeline trace)
`reviewAbove` -- `rejectAbove`	`review`
above `rejectAbove`	`reject`
above `force3dsAbove` and below `rejectAbove`	`force_3ds`

The force3dsAbove threshold is independent of the review/reject thresholds. When a score lands above force3dsAbove but below rejectAbove, the engine produces force_3ds. This ensures risky-but-not-blocked transactions get additional authentication. If force3dsAbove is not set, no score-based 3DS forcing occurs (you can still force 3DS via individual scoring rule signals).

Creating a Scoring Rule

Portal: Navigate to Risk > Scoring Rules > Create.

Name: Descriptive name (e.g., "High-amount card payment").
Conditions: Define when this rule applies. Available condition fields include:

Field	Description	Example
Amount	Transaction amount in minor units	Greater than 50000
Currency	Transaction currency	`USD`, `EUR`
Card brand	Card network	`visa`, `mastercard`
Card BIN	Card BIN prefix	`411111`
Card BIN country	Country where the card was issued	`NG`, `RU`
Payer country	Payer's declared country	`US`
Payer IP country	Country resolved from payer's IP	`CN`
Email domain	Domain part of payer's email	`tempmail.com`
Payment method	Type of payment	`card`, `bank_transfer`
Recurring	Whether the transaction is recurring	`true` / `false`

Score impact: Number of points this rule adds (e.g., 30).
Signal override: Optionally, a rule can produce a direct signal (reject, force_3ds) instead of contributing to the score.

Block/Allow Lists

Lists contain concrete values used for pre-scoring transaction filtering. Lists are organized into groups, and groups are referenced by antifraud plans.

List Types

Type	What it matches	Example
IP address	Payer IP (IPv4, IPv6, or CIDR range)	`192.168.1.0/24`
Email fingerprint	Hashed payer email	Automatically matched
Phone fingerprint	Hashed payer phone	Automatically matched
Card fingerprint	Hashed card identity	Automatically matched
Card BIN	Card BIN prefix	`411111`
Country	ISO country code	`NG`
Custom	Arbitrary string value	Device fingerprint

How Matching Works

The engine evaluates lists in this order:

Allowlist checked first. If a transaction attribute matches an allowlist entry, that attribute is marked as trusted and blocklist evaluation is skipped for it.
Blocklist checked second. If a transaction attribute matches a blocklist entry (and was not already allowed by step 1), the engine returns reject immediately (hard block).
No match on either list: neutral result, scoring rules determine the signal.

Allowlist takes priority over blocklist for the same attribute. If a card fingerprint appears in both an allowlist group and a blocklist group referenced by the same plan, the allowlist match wins and the card is not blocked.

Managing Lists

Portal: Navigate to Risk > Lists.

Create a group: Give it a name, select type (blocklist or allowlist), and set status to enabled.
Add entries: Add individual values or import in bulk. Each entry can have a reason (e.g., fraud, chargeback, manual). Optionally set an expiration date (expiresAt) on any entry.
Reference in plan: Assign the group to an antifraud plan.

Entry Expiration

List entries support an optional expiresAt timestamp. When set, the entry is automatically excluded from matching once the expiration time passes. Expired entries are not deleted -- they remain in the database for audit purposes but are no longer evaluated during risk checks.

This is useful for temporary blocks (e.g., blocking an IP for 30 days after a chargeback investigation) or time-limited allowlist entries (e.g., trusting a card BIN during a promotional period).

Blocklist entries for email and phone use fingerprints (one-way hashes), not raw values. This means you add the actual email or phone number, and the system converts it to a fingerprint for privacy-safe matching.

3DS Configuration

The risk engine influences 3DS authentication through two mechanisms:

Scoring rule signal: A scoring rule can produce a force_3ds signal, requiring 3DS for transactions matching its conditions.
Score-based 3DS: Configure a score threshold above which 3DS is automatically required.

Common 3DS strategies:

Strategy	Configuration
Always require 3DS	Set a `force_3ds` rule with no conditions (matches all transactions)
Never require 3DS	Do not configure any 3DS-related rules
Risk-based 3DS	Set a `force_3ds` scoring rule triggered by a score threshold (e.g., score > 40)
Amount-based 3DS	Set a `force_3ds` scoring rule with an amount condition (e.g., amount > 10000)

Failure Mode

The risk engine is a synchronous step in the payment pipeline and must handle timeouts and errors gracefully. Each tenant can configure how the engine behaves when risk evaluation fails.

Fail Open vs. Fail Closed

Mode	Behavior on timeout or error
`fail_open` (default)	Proceed as if the signal is `allow`. The failure is logged in the pipeline trace with reason `risk_check_timeout_fail_open`. Transactions are not blocked.
`fail_closed`	Decline the transaction with a `RISK_CHECK_UNAVAILABLE` error. Safest option, but blocks all transactions when the engine is down.

Configure this in your tenant risk settings. The default timeout for risk evaluation is 200ms. Tenant risk settings, the score thresholds above included, are shared by test and live mode.

fail_closed is the safest option for high-risk merchants but will cause all transactions to be declined during a risk engine outage. Use fail_open if transaction throughput is a priority and you have other fraud controls in place.

Circuit Breaker

The risk engine uses a circuit breaker pattern to detect sustained failures:

Healthy: All risk evaluations run normally.
Degraded: Triggered when the error rate exceeds 50% within a 2-minute window. Risk check is skipped, and all transactions proceed as allow with reason risk_check_circuit_breaker_open.
Recovery: The circuit breaker automatically resets when risk evaluations begin succeeding again.

The circuit breaker thresholds are configured at the platform level and are not adjustable per tenant.

Best Practices

Give every merchant a plan. There is no default plan, so a merchant without one is not risk-checked. Start with a conservative test plan for sandbox merchants and a matching live plan to assign at approval. Tune thresholds based on actual chargeback data as you accumulate transaction history.

Use allowlists for trusted merchants. If certain card BINs or countries are consistently legitimate for your business, add them to an allowlist to reduce false positives.

Review risk scores on declined transactions regularly to verify thresholds are calibrated correctly.
Start with higher thresholds (fewer rejections) and tighten as you identify fraud patterns.
Use review signal for borderline transactions rather than outright rejection — this lets operators make manual decisions while you gather data.
Block known fraud sources (IPs, BINs) proactively after chargeback investigations.