Payment Fraud Detection & Risk Scoring

Overview

Every payment processed through CommunityPay passes through a real-time fraud detection layer before reaching the payment gateway. The system computes a composite risk score from seven independent factors, each contributing weighted signals that determine whether the payment proceeds, requires review, or is blocked outright.

This is not a post-hoc analysis tool. It is a pre-authorization gate that evaluates before funds move.

Risk Scoring Architecture

The FraudDetector service computes a 0-100 risk score by evaluating seven independent factors in sequence. Each factor contributes an additive score, capped at 100.

The Seven Detection Factors

1. Amount Anomaly Detection Evaluates the payment amount against known fraud patterns and the unit's historical average. Payments exceeding 3x the unit's historical average receive elevated scores. Known fraud-pattern amounts (e.g., $9,999.99, $4,999.99) receive additional weight.

2. User Account Risk Evaluates the payer's account age, recent payment failure history, and login pattern diversity. Brand-new accounts (< 1 day) receive the highest risk weight. Multiple recent failures or logins from > 3 distinct IP addresses in 24 hours contribute additional signals.

3. Payment Velocity Measures transaction frequency across three time windows: 5-minute, 1-hour, and 24-hour. Rapid successive payments (multiple within 5 minutes) receive the highest velocity score. This detects automated payment attempts and card-testing behavior.

4. IP Reputation Checks the originating IP against an active blocklist maintained in the cache layer. Recent suspicious activity from the same IP address within 24 hours contributes to the score. Known high-risk IP ranges receive baseline scoring.

5. Duplicate Detection Identifies duplicate payment amounts from the same user within one hour, and exact duplicates (same unit, amount, month, year) across the payment history. Exact duplicates receive the highest weight in this category.

6. HOA-Level Risk Evaluates risk signals at the community level. HOAs with payment failure rates exceeding 30% in the past 7 days or newly onboarded communities (< 30 days) receive elevated scores.

7. Time-Based Patterns Flags transactions occurring during unusual hours (2-5 AM) or late-night weekend payments. These contribute lower-weight signals that compound with other factors.

Risk Thresholds and Actions

When a payment is blocked, the system: 1. Sets payment status to FAILED with reason "Payment blocked due to security concerns" 2. Logs the detection via AuditLogger.log_fraud_detected with full score breakdown 3. Sends a high-risk payment alert to HOA administrators

IP Blocklisting

The FraudAction service provides temporary IP blocking with configurable duration (default: 24 hours). Blocked IPs are stored in the Redis cache layer with: - Block timestamp - Reason for block - Duration in hours - Full audit logging via AuditLogger.log_suspicious_activity

Fraud Monitoring and Reporting

The FraudMonitor service provides continuous trend analysis:

• Trend Checking: Real-time monitoring of high-risk payment counts (24h and 7d windows), failure rate trends, and suspicious activity volume
• Fraud Reports: Configurable reporting periods (default: 30 days) with risk distribution analysis, top fraud reason rankings, and blocked payment counts

Additional Verification

For borderline-risk payments, the system can require additional verification: - Generates a cryptographically random verification token (secrets.token_urlsafe) - Stores the verification requirement in cache with 1-hour expiration - Associates the verification with the payment's risk score - Requires completion before payment proceeds

Integration Points

The fraud detection layer operates upstream of the payment gateway. The evaluation sequence is:

1. Payment initiated by resident
2. FraudDetector.calculate_risk_score evaluates all seven factors
3. FraudAction.handle_payment_risk determines action based on score
4. If allowed, payment proceeds to GatewayFactory.get_gateway() for processing
5. Fraud score and reasons are persisted on the Payment record for audit