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 Precedence

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

Creating an Antifraud Plan

Portal: Navigate to Risk > Antifraud Plans > Create.

1. Name: Give the plan a descriptive name (e.g., "Standard Risk Profile").
2. Blocklist groups: Select which blocklist groups to evaluate.
3. Allowlist groups: Select which allowlist groups to apply.
4. Scoring rules: Select which scoring rules to include.
5. Status: Set to enabled to activate.

Assigning a Plan

Plans are assigned to a target entity at one of three levels:

The system resolves the active plan by checking merchant first, then tenant. Only one plan can be active per entity at a time. Enabling a new plan automatically disables the previous one.

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

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

The full score-to-signal mapping:

Creating a Scoring Rule

Portal: Navigate to Risk > Scoring Rules > Create.

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

3. Score impact: Number of points this rule adds (e.g., 30).
4. 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

How Matching Works

The engine evaluates lists in this order:

1. Allowlist checked first. If a transaction attribute matches an allowlist entry, that attribute is marked as trusted and blocklist evaluation is skipped for it.
2. 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).
3. No match on either list: neutral result, scoring rules determine the signal.

Managing Lists

Portal: Navigate to Risk > Lists.

1. Create a group: Give it a name, select type (blocklist or allowlist), and set status to enabled.
2. 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.
3. 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).

3DS Configuration

The risk engine influences 3DS authentication through two mechanisms:

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

Common 3DS strategies:

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

Configure this in your tenant risk settings. The default timeout for risk evaluation is 200ms.

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

• 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.