Fraud Module¶

The fraud module provides the core fraud detection infrastructure. External scoring intelligence lives in extensions (ext_ipqs, ext_maxmind, ext_signifyd, ext_riskified); the core provides data models, rule orchestration, and admin UI.

Rules are edited from Settings → Fraud, with a separate blocklist tab:

Architecture¶

Fraud assessment runs in two phases during checkout:

1. Pre-payment (before process_payment): blocklist matching, velocity checks, address mismatch detection, proxy/VPN/Tor signals, and the extension's score_checkout() method.
2. Post-payment (after process_payment): AVS/CVV rule evaluation and the extension's score_post_payment() method (for Signifyd/Riskified chargeback guarantee providers).

Scores from both phases are merged. The worst decision wins (block > review > allow).

Key Files¶

Models¶

FraudRule¶

Configurable rules evaluated at checkout. Channel-scoped (nullable channel_id).

Config JSON: {"window_hours": 24, "threshold": 5}

FraudBlocklist¶

Blocked or flagged values. Checked during pre-payment assessment.

CustomerRiskEvent¶

Immutable audit log for fraud activity. Displayed on the customer detail page.

GraphQL API¶

Queries¶

• fraudDashboard — aggregated metrics for the dashboard page
• fraudReviewQueue(limit, offset) — orders pending fraud review
• fraudRules(channelId) — configured rules
• fraudBlocklist(channelId, entryType) — blocklist entries
• customerRiskEvents(customerId, accountId, limit) — risk timeline

Mutations¶

• approveFraudReview(orderId) — approve an order, transition to AwaitingFulfillment
• declineFraudReview(orderId, reason) — decline and cancel
• createFraudRule(...) / updateFraudRule(...) / deleteFraudRule(...) — rule CRUD
• addToFraudBlocklist(...) / removeFromFraudBlocklist(...) — blocklist CRUD

Permissions¶

Order Risk Fields¶

Added to the orders table:

Building a Fraud Extension¶

Implement FraudScoringStrategy from modules/auth/strategies.py:

class MyFraudStrategy(FraudScoringStrategy):
    @property
    def provider_name(self) -> str:
        return "my_provider"

    async def score_login(self, context: FraudContext) -> FraudScore:
        # IP-based login risk
        ...

    async def score_checkout(self, context: FraudContext) -> FraudScore:
        # Pre-payment scoring
        ...

    async def score_post_payment(self, context: FraudContext) -> FraudScore:
        # Post-auth scoring (for guarantee providers)
        ...

    async def report_decision(self, order_id, decision, analyst_id=None):
        # Feedback loop for ML training
        ...

Register in your extension's on_activate:

strategy_resolver.register(
    FraudScoringStrategy,
    MyProxyStrategy(),
    name="fraud_scoring",
    extension_name=self.name,
)

The FraudContext provides 30+ fields covering IP, geo, buyer identity, billing/shipping addresses, payment data, and order details. See the dataclass in modules/auth/strategies.py for the full list.

Affiliate Fraud Guard (Decided #179)¶

Affiliate commission attribution has its own multi-factor fraud guard layered on top of the order-level fraud signal. The guard evaluates four signals before crediting commission:

1. Click → conversion latency — windows that are too tight or stale relative to the program's expected conversion curve
2. IP correlation — buyer IP matches the affiliate's last-known login or referrer IP
3. Account self-attribution — the buyer's billing email matches an affiliate-managed account
4. Velocity — abnormal click density from a single source

A suspicious commission enters the Affiliate Review Queue (admin /affiliates/approvals). The affiliate sees the order in their dashboard but the commission is pending_review; on approve/deny the commission either posts to the ledger or is voided. The signals and decision are written to affiliate_commission_audit for appeal.

The guard is implemented in vectis.modules.affiliate.services.evaluate_fraud_signals(); thresholds are per-channel settings.