Fraud Prevention & Security

Paid pluginsize Mplanned, not built

Indicative price, not an offer: EUR 250-500/year or EUR 600 one-off

Generated from docs/plan/paid/fraud-prevention-security/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Fraud Prevention & Security integrates ML-based fraud detection (via MaxMind, Sift, or Kount), device fingerprinting, and behavioral analysis to flag risky orders, block account takeover attempts, and provide merchants with audit trails and chargeback management tools to win disputes.

The problem

Chargebacks and data breaches threaten profitability and customer trust. Merchants have no tooling to detect suspicious orders, verify customer identity, or prevent account takeover. A single data breach costs thousands in fines and reputation damage. Competitors offer fraud scoring and chargeback tools.

What it does

• Real-time fraud scoring on order creation (0-100 scale; merchant sets reject/flag threshold)
• Device fingerprinting: capture browser/device identifier at checkout to detect multi-account abuse
• IP geolocation + velocity checks: flag if customer checks out from 2 countries in 1 hour
• Address mismatch detection: billing address differs from shipping (customizable threshold)
• Email validation: detect disposable/temporary email addresses at checkout
• CVV/BIN validation: check card BIN against merchant’s history for anomalies
• Velocity rules: flag if same customer/email makes 5 orders in 10 minutes
• Optional 3D Secure (3DS) enforcement: require identity verification on high-risk orders
• High-risk order queue: admin reviews flagged orders before fulfillment; approve, reject, or require 3DS
• Chargeback management: record disputed orders with reason, evidence tracking, and resolution status
• Webhook listener for payment processor dispute notifications (Stripe disputes, etc.)
• Custom rules engine: merchants can set rules (e.g., ‘reject if score > 75 AND order > EUR 500’)
• Fraud alert notifications: email merchant when risky order is detected
• Blacklist/whitelist management: manually add email/IP/card fingerprint to blocklist or trustlist
• Audit trail: every fraud decision (flag, approve, reject, dispute) is logged with reason and timestamp
• Chargeback dispute assistant: template generator for evidence submission to payment processor

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• PCI DSS audit or certification (merchants must maintain their own PCI scope). Reason: PCI compliance is a merchant responsibility, not a feature. Feature helps stay clean; does not audit or certify.
• Account takeover prevention beyond velocity and device checks (no CAPTCHA, no SMS OTP). Reason: Account security is separate from order fraud; belongs in a dedicated feature.
• Biometric verification or face recognition (no ML model inference). Reason: Biometric is compliance-heavy, regionally-specific, and requires stateful storage; belongs in a separate feature.
• Machine learning model training or fine-tuning (paid feature uses external service models only). Reason: ML ops is expensive; feature integrates, does not train.
• Insurance or chargeback guarantee (no AstroBaaS financial liability). Reason: Insurance is a business/legal product, not a software feature.
• Multi-region fraud rules (feature uses global rules; merchants in high-fraud regions manually tune). Reason: Localization is per-country; feature provides the hook, not 190 rule sets.
• Real-time payment processor balance reconciliation (disputes reported via webhook, not polled). Reason: Processor state is authoritative; feature listens, does not read continuously.
• Automated refunds based on fraud verdict (manual approval only). Reason: Refunds are financial transactions; must not be automated without explicit merchant confirmation.

Data model

New tables: FraudScore (join on orders): id, orderId (fk), score (0-100), verdict (enum: approved, flagged, rejected), reason (string), externalServiceId (from Sift/MaxMind), deviceFingerprint (hashed), ipGeolocation (json), riskFactors (json array), verifiedAt (timestamp, nullable), reviewedAt (timestamp, nullable), reviewedBy (fk to staff). ChargebackDispute (join on orders): id, orderId (fk), externalDisputeId (string from processor), reason (enum), amount (minor units), currency (frozen), reportedAt (timestamp), status (enum: open, under_review, won, lost), evidenceSubmittedAt (timestamp, nullable), resolution, notes (text), auditLog (json array). FraudRule (configuration): id, name, condition (json), action (enum: flag, reject, verify_3ds), enabled (bool), createdAt, updatedAt. Blacklist/Whitelist (two tables): id, type (enum: email, ip, card_fingerprint), value, reason, listedAt, expiresAt (nullable). Indexes: (orderId) on FraudScore/ChargebackDispute, (externalDisputeId), (type, value) on blacklist/whitelist. This IS a migration: 5 new tables + indexes.

API

• POST /api/fraud/check — called at order confirmation; returns score + verdict + reasons
• POST /api/fraud/rules — create/update fraud rule (staff only)
• GET /api/fraud/rules — list all active rules (staff only)
• DELETE /api/fraud/rules/{id} — delete a rule (staff only)
• POST /api/fraud/order/{orderId}/review — staff approves/rejects flagged order
• GET /api/fraud/order/{orderId}/score — retrieve fraud score + details for an order
• POST /api/fraud/blacklist — add email/IP/card to blocklist (staff only)
• GET /api/fraud/blacklist — retrieve blacklist (staff only)
• DELETE /api/fraud/blacklist/{id} — remove from blacklist (staff only)
• POST /api/fraud/whitelist — add email/IP to trustlist (staff only)
• POST /api/fraud/webhook/dispute — inbound from Stripe/payment processor on chargeback
• GET /api/fraud/disputes — list all chargebacks on account (staff only)
• POST /api/fraud/dispute/{orderId}/evidence — upload evidence (screenshots, fulfillment proof)
• GET /api/fraud/dispute/{orderId}/template — generate dispute response template
• POST /api/fraud/config — set fraud service (MaxMind/Sift/Kount) + API key (staff only)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Fraud settings card: toggle feature on/off, select fraud service (MaxMind/Sift/Kount), paste API key (masked). Fraud score threshold slider: set auto-reject and flag cutoffs (0-100). Rule builder UI: create rules with condition dropdowns (score > X, amount > EUR X, velocity, IP mismatch, device mismatch, email disposable) and action dropdowns (auto-approve, auto-reject, flag for review, require 3DS). High-risk order queue: table of flagged orders with order ID, customer, score, amount, risk factors, notes field, and action buttons (approve, reject, require 3DS). Chargeback dashboard: open/won/lost disputes, status, evidence uploaded. Blacklist/whitelist manager: add/remove entries, set expiration date. Audit log viewer: filter by order, action, date range. Dispute template generator: reason dropdown, auto-generated response text, markdown editor, submit button. Test score form: enter mock order data, see assigned score. Alert config: toggle email on high-risk detection.

The seam — why this is paid

Core owns: order creation atomicity, payment processing + tokenization, PCI compliance, refund API, audit trail schema. Paid pack owns: fraud detection workflow (calling external service API), score calculation, rule engine, high-risk queue, chargeback tracking, dispute evidence management. Boundary: core’s POST /orders endpoint is unchanged; fraud feature is async (score added post-order, or blocking if rule is ‘reject’). Core never knows about fraud; paid pack wraps the decision. Chargeback data flows back to core’s audit log, but chargeback management (evidence, responses, win/loss tracking) lives in paid pack only.

Requires external fraud service credentials (MaxMind, Sift, Kount). Support for ML model tuning and false-positive management.

Dependencies

• Core order schema (must already exist)
• Core payment adapter + tokenization (must already exist)
• Core audit log system (must already exist)
• Core webhook system (must already exist)
• Assumption: merchant has active Sift, MaxMind, or Kount account and API key
• Assumption: payment processor (Stripe, etc.) is configured with webhook endpoint for dispute notifications

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• An order with IP in France and shipping to US, placed within 1 hour of previous France order, is flagged as risky
• An order using a disposable email address (@tempmail.com) is flagged or rejected based on merchant’s rule
• Device fingerprint is captured at checkout; if same device makes 5 orders in 10 minutes, the 6th is flagged for velocity
• A flagged order remains in high-risk queue until staff explicitly approves or rejects it; fulfillment is blocked
• Chargeback notification received from Stripe creates a dispute record with status ‘open’
• Staff uploads evidence (email proof, fulfillment tracking); evidence is attached to dispute record with timestamp
• Blacklisted email address is rejected at checkout with ‘This email is not allowed’ message
• Custom rule ‘reject if score > 75 AND amount > EUR 500’ is applied; order is rejected with reason ‘High fraud risk’
• Disabling the feature stops fraud checking; orders are created normally; existing fraud scores and disputes remain visible for audit
• Payment processor updates dispute status to ‘won’ or ‘lost’ via webhook; dashboard shows updated status and resolution

Risks

False-positive rate: if threshold is too low, legitimate orders rejected and customers churn. Must monitor approval rate and support manual override. Fraud service API outage: if blocking is enabled, checkout fails for all users. Must have graceful fallback (log, flag, allow; alert merchant). PCI scope creep: if merchant’s fraud rule captures unencrypted card data in audit log, PCI audit fails. Every rule must sanitize card fields before logging. Chargeback dispute evidence must never include customer’s full name, address, or payment details unencrypted in audit log (use hashes or redact). Blacklist bypassing: attacker uses email alias, different card, different IP. Feature is a filter, not a complete gate. Rate limiting: fraud service charges per API call; high-traffic merchant exceeds quota. Must implement caching/batching + quota alerts. Dispute webhook signature validation: inbound chargebacks must be HMAC-signed; if not validated, attacker can forge ‘chargeback won’ message. Double-approval: staff approves flagged order; network delay causes retry; fulfillment happens twice. Make approval idempotent.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.