Anti-Money Laundering (AML) Module

Overview

The Anti-Money Laundering (AML) module provides compliance capabilities for detecting and reporting suspicious activities, managing watchlists, and handling Suspicious Activity Reports (SARs). It protects the institution from money laundering and terrorism financing risks.

API Prefix: /api/v1/aml

Route Verification Status

• Source Router: app/api/v1/endpoints/aml.py
• Live Route Count: 20
• Verification State: Verified (2026-06-28)
• Canonical Tracking: docs/API_ROUTE_DOCUMENTATION_TODO.md
• Verification Method: Route decorators extracted from @r.<method>(...) in app/api/v1/endpoints/aml.py.

Key Features

1. Risk Profiling

• Customer risk assessment
• Agent risk profiling
• Risk score calculation
• Risk categorization (Low, Medium, High, Very High)
• Risk monitoring and updates

2. Watchlist Management

• Global watchlist integration (OFAC, EU, etc.)
• Customer watchlist checking
• Agent watchlist monitoring
• Watchlist alert generation
• False positive management

3. Fraud & Suspicious Activity Detection

• Transaction pattern analysis
• Velocity checks (rapid transactions)
• Geographic anomalies
• Behavioral pattern detection
• Automated rule engine

4. Blacklist Management

• Customer blacklisting
• Agent blacklisting
• Temporary suspension
• Permanent ban
• De-listing procedures

5. Suspicious Activity Reports (SARs)

• SAR creation and filing
• Investigation workflow
• Evidence collection
• Decision documentation
• Regulatory filing

6. Case Management

• AML case creation
• Case investigation
• Evidence tracking
• Case resolution
• Document management

7. Compliance Monitoring

• Transaction monitoring
• Customer account review
• Periodic KYC updates
• Risk reassessment
• Regulatory reporting

API Endpoints (Verified Against Live Router)

For the complete AML endpoint inventory (all 20 routes with method, effective path, and source line), use: - docs/API_ROUTE_LIVE_REFERENCE.md -> section aml.py (20 routes)

Permission Dependency Notes (Verified)

Confirmed explicit permission checks in aml.py include: - Risk operations: add_risk, fetch_risk, get_risk, toggle_risk, edit_risk, fetch_agentrisk. - Watchlist operations: add_watchlist, get_watchlist, fetch_watchlist, edit_watchlist. - Case and blacklist operations: aml_action, fetch_blacklist, get_backlist, edit_blacklist, fetch_case, get_case, hold_case, status_case, download_case. - SAR operations: fetch_sar.

Standard Error Response Matrix

{
  "status_code": 400,
  "error_code": "AML_ERROR",
  "message": "Human-readable summary",
  "details": {}
}

Common mappings: - 400 invalid risk/case action or compliance rule failure. - 401 unauthenticated request. - 403 permission denied. - 404 risk/watchlist/case/sar resource not found. - 409 conflicting case/status transition. - 422 schema validation failure. - 429 throttled request. - 500 internal AML processing or integration error.

Database Models

Risk Management

• RiskProfile: Customer/agent risk assessment
• RiskParameter: Risk calculation parameters
• RiskScore: Calculated risk scores
• RiskAuditTrail: Risk history

Watchlist & Blacklist

• Watchlist: Global watchlist entries
• CustomerWatchlistMatch: Customer watchlist alerts
• Blacklist: Blacklisted customers/agents
• BlacklistReason: Blacklist justification

Suspicious Activity

• SuspiciousActivityReport (SAR): SAR filing
• SAREvidence: Supporting evidence
• SARDecision: Investigation decision
• SARSubmission: Regulatory filing record

Case Management

• AMLCase: Investigation case
• CaseEvidence: Case supporting documents
• CaseNote: Investigation notes
• CaseHold: Fund holds on accounts

Risk Assessment Scoring

Risk Score Calculation

Base Score: 100

Risk Factors:
- Customer Age: -0 to -20
  (Newer customers higher risk)
- KYC Tier: -0 to -30
  (Lower KYC tier higher risk)
- Transaction Velocity: -0 to -40
  (High velocity increases risk)
- Geographic Risk: -0 to -25
  (High-risk countries increase)
- Transaction Type: -0 to -15
  (Unusual types increase risk)
- Account History: -0 to -20
  (Recent account higher risk)

Final Score Interpretation:
- 80-100: Low Risk (Green)
- 60-79: Medium Risk (Yellow)
- 40-59: High Risk (Orange)
- Below 40: Very High Risk (Red)

Risk Categories

Customer Risk Profile:
1. Low Risk: Established customer, consistent patterns
2. Medium Risk: New customer or unusual activity
3. High Risk: Multiple red flags or violations
4. Very High Risk: Clear indicators of illicit activity

Agent Risk Profile:
1. Low Risk: Established agent, excellent compliance
2. Medium Risk: New agent or minor compliance issues
3. High Risk: Repeated policy violations
4. Very High Risk: Criminal history or major violations

Suspicious Activity Detection Rules

Transaction-Based Rules

Rule 1: High Velocity
- Condition: >10 transactions in 1 hour
- Action: Flag and review
- Risk Level: Medium

Rule 2: Structuring (Smurfing)
- Condition: Multiple transactions just below limit (9,999 ZMW)
- Action: Flag and investigate
- Risk Level: High

Rule 3: Round Amount Pattern
- Condition: Multiple transactions for exact round amounts
- Action: Monitor pattern
- Risk Level: Medium

Rule 4: Late Night Transactions
- Condition: Large transactions outside business hours
- Action: Alert and review
- Risk Level: Low-Medium

Rule 5: Unusual Beneficiary
- Condition: Funds sent to new beneficiary immediately
- Action: Verify beneficiary
- Risk Level: Medium

Customer-Based Rules

Rule 1: High-Risk Country
- Condition: Customer from OFAC-listed country
- Action: Block account
- Risk Level: Very High

Rule 2: Watchlist Match
- Condition: Customer name matches global watchlist
- Action: Investigate immediately
- Risk Level: Very High

Rule 3: Rapid KYC Upgrade
- Condition: KYC upgraded multiple times in short period
- Action: Verify documents
- Risk Level: Medium-High

Rule 4: Multiple Failed Attempts
- Condition: >5 failed login attempts
- Action: Block account pending verification
- Risk Level: Medium

AML Workflow

Transaction Monitoring

1. Transaction Occurs
   ├─ System evaluates all AML rules
   ├─ Calculates risk score
   └─ Determines action

2. Risk Assessment
   ├─ Low Risk: Process normally
   ├─ Medium Risk: Flag for review, allow processing
   ├─ High Risk: Hold pending investigation
   └─ Very High Risk: Block immediately

3. Investigation (if flagged)
   ├─ Create AML case
   ├─ Assign investigator
   ├─ Gather evidence
   ├─ Review documentation
   └─ Make determination

4. Resolution
   ├─ If approved: Release hold, process transaction
   ├─ If denied: Block account, file SAR if needed
   ├─ If suspicious: File SAR with regulator
   └─ Update risk profile

SAR Filing Process

1. Identification
   ├─ Suspicious activity detected
   ├─ Initial review completed
   └─ Meets reporting threshold

2. Investigation
   ├─ Gather all evidence
   ├─ Document findings
   ├─ Consult with compliance
   ├─ Determine if SAR warranted
   └─ Draft SAR filing

3. Internal Approval
   ├─ Compliance review
   ├─ Legal review
   ├─ Senior management approval
   └─ Document approval

4. Regulatory Filing
   ├─ File with financial intelligence unit
   ├─ Include all supporting documentation
   ├─ Maintain filing records
   └─ File deadline: typically 10 days

5. Follow-up
   ├─ Monitor for feedback from regulator
   ├─ Maintain confidentiality of filing
   ├─ Continue monitoring related accounts
   └─ Document outcomes

Controllers & Business Logic

AML Controllers

• controller/aml.py: Core AML logic
• assess_risk(): Calculate risk score
• evaluate_rules(): Check all rules
• create_aml_case(): Initiate investigation

• file_sar(): File SAR report

• controller/watchlist.py: Watchlist management

• check_watchlist(): Check against global lists
• add_to_watchlist(): Add customer/agent

• alert_on_match(): Generate alerts

• controller/blacklist.py: Blacklist enforcement

• add_to_blacklist(): Blacklist customer/agent
• check_blacklist(): Verify not blacklisted
• delist(): Remove from blacklist

Configuration

Risk Parameters

{
  "customer_risk_parameters": {
    "age_days_threshold": 90,
    "kyc_tier_weight": 0.3,
    "velocity_weight": 0.4,
    "geographic_risk_weight": 0.2,
    "transaction_type_weight": 0.1
  },
  "alert_thresholds": {
    "daily_transaction_amount": 1000000,
    "daily_transaction_count": 50,
    "velocity_per_hour": 10
  },
  "high_risk_countries": [
    "North Korea", "Iran", "Syria", ...
  ]
}

Rule Configuration

{
  "rules": [
    {
      "name": "High Velocity",
      "condition": "transactions_in_1h > 10",
      "action": "flag_for_review",
      "risk_level": "medium",
      "enabled": true
    },
    {
      "name": "Structuring",
      "condition": "pattern_just_below_limit",
      "action": "investigate",
      "risk_level": "high",
      "enabled": true
    }
  ]
}

Error Handling

AML Errors

• WATCHLIST_MATCH: Customer on watchlist
• BLACKLIST_VIOLATION: Customer is blacklisted
• HIGH_RISK_TRANSACTION: Transaction flagged as high risk
• INVESTIGATION_PENDING: Investigation in progress
• ACCOUNT_FROZEN: Account frozen pending investigation
• SAR_FILING_REQUIRED: Suspicious activity requires SAR

Testing

Test Categories

• Risk score calculation
• Rule engine evaluation
• Watchlist matching
• Blacklist enforcement
• SAR filing workflow
• Case management

Test Files

• tests/test_aml.py: AML tests
• conftest.py: AML test fixtures

Performance Considerations

1. Rule Evaluation: Evaluate rules asynchronously
2. Watchlist Caching: Cache watchlist entries
3. Risk Calculation: Pre-calculate for known customers
4. Alert Batching: Batch alerts for processing
5. Reporting: Generate reports in background

Compliance & Regulatory

Reporting Requirements

• SARs: File within 10 days of discovery
• Periodic Reports: Monthly/quarterly compliance reports
• Customer Due Diligence: Annual KYC updates
• Documentation: Maintain for 7 years

Regulatory Bodies

• Financial Intelligence Unit (FIU)
• Bank of Zambia (BoZ)
• FATF (Financial Action Task Force)
• International AML standards

Integration Points

Internal Modules

• Customer Management: Customer risk data
• Transaction Processing: Transaction monitoring
• Agent Management: Agent risk profiling
• Wallet: Balance holds
• Authentication: Account freeze

Related Documentation

• Customer Management - KYC & Risk
• Transaction Processing - Transaction Monitoring
• Agent Management - Agent Risk Profiles