Fraud Detection

Related docs: Security Compliance · Payment Architecture · Microservices · Data Models

---

1. Overview

Pakashop implements a dedicated fraud detection microservice (pakashop-fraud, port 3006) that evaluates every payment initiation in real-time. The system uses a rules-based engine with composite risk scoring to detect and prevent fraudulent transactions.

---

2. Architecture

Payment Initiation Request
  │
  ▼
pakashop-backend (port 3080)
  │
  ├──► pakashop-fraud (port 3006) ──► Risk Score Calculation
  │                                    │
  │                                    ├── Velocity Check
  │                                    ├── Amount Anomaly
  │                                    ├── Self-Dealing Detection
  │                                    ├── Geographic Analysis
  │                                    └── Device Fingerprinting
  │
  │◄─── { score: 45, status: "PASSED", rules: [] }
  │
  ▼
Payment proceeds OR blocked

---

3. Fraud Rules Engine

3.1 Active Rules

Rule ID	Name	Threshold	Weight	Description
VEL_001	Payment Velocity	>5 payments/hour from same IP	25	Detects rapid-fire payment attempts
VEL_002	Account Velocity	>10 payments/day from same user	20	Detects account takeover or testing
AMT_001	Amount Anomaly	>3x average order value	20	Detects unusual purchase amounts
AMT_002	Micro-Amount Testing	Less than K 1.00 payment	15	Detects card testing behavior
SDL_001	Self-Dealing	Buyer = Seller	100	Immediate block; same account buying from own shop
GEO_001	Geographic Anomaly	Payment from new country/region	15	Detects account takeover from unusual location
DEV_001	New Device	First payment from new device	10	Elevated scrutiny for new devices
DEV_002	Device Mismatch	Device fingerprint changed	20	Detects session hijacking
HRS_001	Off-Hours Activity	Payment between 2-5 AM local time	5	Slight elevation for unusual hours

3.2 Risk Score Calculation

// services/fraud/src/engine/score.js
function calculateRiskScore(evaluation) {
  let score = 0;
  const triggeredRules = [];

  for (const rule of RULES) {
    if (rule.evaluate(evaluation)) {
      score += rule.weight;
      triggeredRules.push(rule.id);
    }
  }

  // Cap at 100
  score = Math.min(score, 100);

  return {
    score,
    triggeredRules,
    status: score < 30 ? 'PASSED' : score < 70 ? 'REVIEW' : 'BLOCKED'
  };
}

3.3 Score Interpretation

Score Range	Status	Action
0-29	PASSED	Payment proceeds normally
30-69	REVIEW	Payment blocked; added to fraud review queue
70-100	BLOCKED	Payment blocked immediately; order flagged

---

4. Data Collection

4.1 Evaluation Context

The fraud service collects the following data for each evaluation:

{
  "userId": "uuid",
  "orderId": "uuid",
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0...",
  "deviceFingerprint": "abc123...",
  "amount": 250.00,
  "currency": "ZMW",
  "paymentMethod": "MTN_MONEY",
  "phoneNumber": "+260977123456",
  "shopId": "uuid",
  "billingAddress": { ... },
  "timestamp": "2026-05-12T10:00:00Z",
  "isNewDevice": false,
  "previousPaymentsCount": 5,
  "previousPaymentsToday": 2,
  "accountAgeDays": 30
}

4.2 Redis Cache for Velocity Checks

Key: fraud:velocity:{ip}:{hourBucket}
Value: { paymentCount, amountTotal, lastPaymentAt }
TTL: 1 hour

Key: fraud:velocity:user:{userId}:{dayBucket}
Value: { paymentCount, amountTotal, lastPaymentAt }
TTL: 24 hours

---

5. API Endpoints

5.1 Internal Evaluation Endpoint

Called by pakashop-backend during payment initiation.

POST /internal/evaluate
Headers: X-Internal-Key: {INTERNAL_API_KEY}

Request:

{
  "userId": "uuid",
  "orderId": "uuid",
  "ipAddress": "192.168.1.1",
  "deviceFingerprint": "abc123",
  "amount": 250.00,
  "currency": "ZMW",
  "paymentMethod": "MTN_MONEY",
  "shopId": "uuid",
  "timestamp": "2026-05-12T10:00:00Z"
}

Response:

{
  "score": 45,
  "status": "REVIEW",
  "triggeredRules": ["VEL_001", "AMT_001"],
  "recommendation": "Flag for manual review",
  "evaluatedAt": "2026-05-12T10:00:01Z"
}

5.2 Admin Review Queue Endpoints

Method	Path	Auth	Description
GET	/api/v1/fraud/queue	FRAUD_ANALYST, PLATFORM_ADMIN	List pending reviews
GET	/api/v1/fraud/queue/:id	FRAUD_ANALYST, PLATFORM_ADMIN	Get review details
POST	/api/v1/fraud/queue/:id/approve	FRAUD_ANALYST, PLATFORM_ADMIN	Approve blocked transaction
POST	/api/v1/fraud/queue/:id/reject	FRAUD_ANALYST, PLATFORM_ADMIN	Reject blocked transaction
GET	/api/v1/fraud/rules	PLATFORM_ADMIN	List all fraud rules
PUT	/api/v1/fraud/rules/:id	PLATFORM_ADMIN	Update rule (threshold, weight, active status)
GET	/api/v1/fraud/stats	PLATFORM_ADMIN	Fraud statistics dashboard

---

6. Admin Review Workflow

6.1 Review Dashboard

The fraud review dashboard displays:

• Blocked transaction details (amount, user, shop, payment method)
• Triggered rules with explanations
• User's payment history
• Risk score breakdown
• Device fingerprint information
• Geographic location data

6.2 Review Actions

Action	Effect
Approve	Payment proceeds; FraudEvent.status = APPROVED; order continues
Reject	Order cancelled; FraudEvent.status = REJECTED; customer notified
Escalate	Marked for senior review; FraudEvent.status = ESCALATED
Add Note	Analyst adds contextual note to FraudEvent.notes

---

7. Configuration

7.1 Environment Variables

# Fraud Detection
FRAUD_VELOCITY_HOURLY_LIMIT=5
FRAUD_VELOCITY_DAILY_LIMIT=10
FRAUD_AMOUNT_MULTIPLIER=3.0
FRAUD_MICRO_AMOUNT_THRESHOLD=1.00
FRAUD_REVIEW_SCORE_THRESHOLD=30
FRAUD_BLOCK_SCORE_THRESHOLD=70
FRAUD_CACHE_TTL_HOURS=24

7.2 Rule Configuration

Rules can be dynamically adjusted via the admin dashboard without redeployment:

// PUT /api/v1/fraud/rules/VEL_001
{
  "threshold": 5,
  "weight": 25,
  "isActive": true,
  "description": "Payment velocity from same IP"
}

---

8. Monitoring

8.1 Key Metrics

Metric	Alert Threshold	Description
fraud_evaluation_time_ms	> 100ms p95	Time to evaluate a transaction
fraud_blocked_rate	> 10%	Percentage of payments blocked
fraud_false_positive_rate	> 5%	Approved transactions that were flagged
fraud_queue_depth	> 100	Number of pending reviews
fraud_review_time_minutes	> 30	Average time to review a case

8.2 Alerts

• High block rate: May indicate overly aggressive rules; review thresholds
• High false positive rate: May indicate rules too sensitive; adjust weights
• Queue backlog: Scale fraud analyst team or adjust auto-approval thresholds

---

For internal use only. Do not distribute outside Pakashop engineering.