Agent Management Module¶

Overview¶

The Agent Management module handles field agent and operator onboarding, device management, store/branch management, location tracking, and agent performance monitoring. It supports the distributed agent network that provides banking services in remote areas via USSD, mobile terminals, and point-of-sale devices.

API Prefix: /api/v1/agent

Route Verification Status¶

Source Router: app/api/v1/endpoints/agent.py
Live Route Count: 47
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/agent.py.

Key Features¶

1. Agent/Operator Management¶

Register field agents and operators
Operator profile and credential management
Agent verification and approval workflows
Agent status tracking (Active, Inactive, Suspended, Terminated)
Agent hierarchy and reporting structure
Performance tracking and KPIs

2. Agent Categories¶

Categorize agents (Telco Agents, Retail Partners, Super Agents)
Category-specific features and limits
Role-based category permissions
Agent capability tracking
Category lifecycle management

3. Device Management¶

Register and manage agent devices (Mobile, Terminal, POS)
Device binding to specific agents/operators
Device activation and deactivation
Device security management
IMEI/Serial number tracking
Backup device assignment

4. Store/Branch Management¶

Register physical store locations
Store hierarchy (HQ, Region, District, Store)
Store staff and operator assignment
Store operational hours
Store performance metrics
Store contact and location information

5. Geofencing & Location Tracking¶

Define store geofence boundaries
Track agent real-time location
Location-based access control
Geofence violations and alerts
Store visit tracking and frequency
Location history and audit trail

6. Agent Performance Monitoring¶

Transaction statistics per agent
Revenue tracking
Customer acquisition metrics
Service quality metrics
Compliance tracking
Agent rankings and leaderboards

7. Agent Financial Management¶

Commission and incentive tracking
Agent wallet/float management
Settlement and fund transfers
Agent financial limits
Float management (inventory of cash)
Reconciliation with agents

8. Agent Security¶

Device authentication and verification
Agent credential management
Suspicious activity detection
Audit trail for all agent actions
Compliance monitoring
Risk profiling

API Endpoints (Verified Against Live Router)¶

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

This document focuses on workflow and domain behavior. The live reference above is the canonical endpoint parity source.

Database Models¶

Core Agent Models¶

Agent: Main agent record
ID, name, phone, email, status
Agent category assignment
Document verification
Rating and performance metrics
Registration and approval dates
Operator: Agent operator/staff
ID, name, phone, credentials
Assigned agent
Role and permissions
Device assignments
Performance metrics
AgentCategory: Agent classification
Category name and code
Features and capabilities
Transaction limits
Commission rates
Requirements and qualifications

Device Models¶

StoreDevice: Physical device
IMEI/Serial number
Device type (Mobile, Terminal, POS)
Device status
Activation and expiry dates
OperatorDeviceBinding: Device assignment to operator
Device ID to operator mapping
Binding timestamp
Status and binding history

Location Models¶

Location: Agent/store location
Latitude and longitude
Address
Area/Region
Location type (Store, Kiosk, etc.)
StoreGeofencing: Geofence boundary
Store location
Radius and boundary coordinates
Geofence status
LocationHistory: Location tracking
Agent ID and timestamp
Location (lat/long)
Accuracy
Device ID

Store Models¶

Store: Physical store/branch
Store code and name
Location
Region/District hierarchy
Store type
Operating hours
StoreOperatorAssignment: Staff assignment
Store to operator mapping
Assignment period
Role at store

Performance & Financial Models¶

AgentPerformance: Performance metrics
Transaction count and volume
Revenue generated
Commission earned
Customer acquisition
Compliance metrics
AgentFloat: Agent cash float
Float balance
Float transactions (load/disbursement)
Float reconciliation
AgentCommission: Commission tracking
Transaction-based commissions
Fixed commissions
Incentive payouts
Commission history

Agent Onboarding Flow¶

New Agent Registration¶

1. Agent Application
   ├─ Fill registration form
   ├─ Provide personal details
   ├─ Upload identification documents
   ├─ Provide store/business location
   └─ Accept terms and conditions

2. Document Verification
   ├─ Verify national ID
   ├─ Verify address proof
   ├─ Check business registration (if applicable)
   ├─ Perform background check
   └─ Status: VERIFIED or REJECTED

3. Agency Assignment
   ├─ Assign to agent category
   ├─ Set transaction limits
   ├─ Assign store location
   └─ Status: STAGED

4. Approval Workflow
   ├─ Regional manager review
   ├─ Compliance check
   ├─ Final approval
   └─ Status: APPROVED

5. Device Provisioning
   ├─ Generate device credentials
   ├─ Issue mobile device or terminal
   ├─ Provide training materials
   └─ Status: ACTIVE

6. Go-Live
   ├─ Agent can start transactions
   ├─ Real-time monitoring active
   ├─ Performance tracking enabled
   └─ Ready for customer interactions

Operator Assignment to Agent¶

1. Operator Registration
   ├─ Identify operator/staff member
   ├─ Verify employment with agent
   ├─ Collect credentials
   └─ Create operator record

2. Role Assignment
   ├─ Assign permissions based on role
   ├─ Set transaction limits
   ├─ Define operational hours
   └─ Assign to agent

3. Device Binding
   ├─ Register operator device (IMEI)
   ├─ Bind device to operator
   ├─ Enable device authentication
   └─ Activate credentials

4. Training & Go-Live
   ├─ Provide system training
   ├─ Test transactions
   ├─ Activate operator
   └─ Monitor first transactions

Agent Categories¶

Category 1: Super Agent¶

Max daily transaction: 1,000,000
Max agent count: 50
Features: Full feature access, operator management
Commission: 1.5%
Requirements: Business registration, tax clearance

Category 2: Regional Agent¶

Max daily transaction: 500,000
Max agent count: 10
Features: Full feature access, regional operations
Commission: 1.0%
Requirements: Business registration

Category 3: Local Agent¶

Max daily transaction: 100,000
Max agent count: 1
Features: Basic transactions, limited services
Commission: 0.75%
Requirements: National ID, address proof

Category 4: Retail Partner¶

Max daily transaction: 50,000
Max agent count: 0 (individual)
Features: Sales point only, no sub-agents
Commission: 0.5%
Requirements: National ID

Geofencing & Location Management¶

Geofence Boundary Setup¶

1. Define Store Location
   ├─ Latitude: -12.8845
   ├─ Longitude: 28.3203
   └─ Store name: "Lusaka Main"

2. Set Geofence Radius
   ├─ Radius: 500 meters
   ├─ Buffer: 50 meters (warning zone)
   └─ Enable geofence

3. Configure Restrictions
   ├─ Check-in required daily
   ├─ Alert on geofence exit
   ├─ Restrict transactions outside geofence (optional)
   └─ Log all location data

Location Tracking & Monitoring¶

Real-time Updates:
├─ Agent app sends location every 5 minutes
├─ Location recorded with timestamp
├─ Accuracy calculated from GPS data
├─ Geofence status determined

Geofence Alerts:
├─ Agent enters geofence → Check-in notification
├─ Agent exits geofence → Alert to supervisor
├─ Prolonged outside geofence → Escalate alert
└─ System can restrict transactions if needed

Controllers & Business Logic¶

Key Controllers¶

controller/agent.py: Agent operations
create_agent(): Register new agent
verify_agent(): KYC verification
assign_category(): Category assignment
get_agent_metrics(): Performance tracking
controller/operator.py: Operator management
create_operator(): Register operator
assign_to_agent(): Link operator to agent
verify_operator(): Operator verification
controller/store.py: Store management
create_store(): Register store
assign_operators(): Assign staff to store
set_geofence(): Configure geofence
controller/device.py: Device management
register_device(): Register new device
bind_device(): Bind to operator
validate_device(): Device authentication
controller/location.py: Location tracking
track_location(): Record agent location
check_geofence(): Check geofence status
get_location_history(): Retrieve location data
controller/agent_performance.py: Performance monitoring
calculate_metrics(): Calculate KPIs
track_commissions(): Commission calculations
generate_reports(): Performance reports

Configuration¶

Agent Category Configuration¶

{
  "code": "super_agent",
  "name": "Super Agent",
  "daily_transaction_limit": 1000000,
  "max_sub_agents": 50,
  "commission_percent": 1.5,
  "features": [
    "loan_origination",
    "wallet_creation",
    "bill_payment",
    "merchant_payment",
    "operator_management"
  ],
  "requirements": {
    "documents": ["business_registration", "tax_clearance"],
    "min_experience_months": 6
  },
  "active": true
}

Store Configuration¶

{
  "code": "store_001",
  "name": "Lusaka Main Store",
  "region": "Lusaka",
  "district": "Lusaka",
  "location": {
    "latitude": -12.8845,
    "longitude": 28.3203
  },
  "geofence": {
    "radius_meters": 500,
    "enabled": true
  },
  "operating_hours": {
    "monday_to_friday": "08:00-20:00",
    "saturday": "08:00-18:00",
    "sunday": "closed"
  }
}

Device Configuration¶

{
  "imei": "123456789012345",
  "device_type": "mobile_terminal",
  "model": "Sunmi V2",
  "os": "Android 11",
  "app_version": "2.5.0",
  "encryption_enabled": true,
  "geolocation_enabled": true,
  "location_update_interval_seconds": 300
}

Agent Performance Metrics¶

KPI Tracking¶

Daily Active Agents
├─ Count of agents who performed transactions today
└─ Trend: Day-over-day comparison

Total Transaction Volume
├─ Sum of all agent transactions
├─ By category
└─ By transaction type

Average Agent Revenue
├─ Revenue per agent
├─ Commission earned
└─ Trend analysis

New Customers Acquired
├─ Registered via agent
├─ Successful KYC
└─ Active status

Transaction Success Rate
├─ Successful transactions / attempted
├─ By transaction type
└─ By agent

Compliance Metrics
├─ Geofence compliance (% time in geofence)
├─ Daily check-in compliance
├─ Documentation compliance
└─ Fraud incident rate

Integration Points¶

External Services¶

Geolocation Service: GPS/Google Maps integration
Telecom Provider: Device/IMEI verification
Background Check Services: Agent verification
Business Registry: Business registration validation

Internal Modules¶

Authentication: Agent device authentication
Wallet System: Agent float management
Transaction System: Agent transactions
Loan Management: Agent loan origination
Customer Management: Customer registration by agent
Notification System: Agent alerts and notifications
Reporting System: Agent performance reports
AML: Agent risk profiling

Agent Security Features¶

Device Authentication: IMEI/Device binding
Credential Management: Agent login credentials
Transaction Limits: Per-agent and per-category limits
Geofencing: Location-based access control
Audit Logging: All agent actions logged
Suspicious Activity Detection: Pattern-based alerts
Compliance Monitoring: KYC and document verification
Risk Profiling: Agent risk assessment

Error Handling¶

Common Errors¶

AGENT_NOT_FOUND: Agent ID doesn't exist
DEVICE_NOT_REGISTERED: Device IMEI not registered
DEVICE_BINDING_FAILED: Unable to bind device
GEOFENCE_VIOLATION: Agent outside geofence
LIMIT_EXCEEDED: Transaction limit exceeded
AGENT_INACTIVE: Agent account is inactive
OPERATOR_NOT_AUTHORIZED: Operator lacks permission
LOCATION_NOT_AVAILABLE: GPS data not available

Testing¶

Test Categories¶

Agent registration and approval workflows
Device binding and authentication
Geofence boundary detection
Location tracking accuracy
Performance metrics calculation
Commission calculations
Operator assignment flows

Test Files¶

tests/test_agent.py: Agent operations
conftest.py: Agent test fixtures

Performance Considerations¶

Location Tracking: Batch GPS updates to reduce database load
Geofence Calculations: Cache geofence boundaries
Metrics Aggregation: Pre-calculate daily metrics
Device Binding: Index on IMEI for fast lookup
Performance Reports: Generate async in background

Common Use Cases¶

1. Agent Onboarding¶

Register → Verify → Category Assignment → 
Device Provisioning → Approval → Go-Live

2. Daily Agent Check-In¶

Agent starts app → Location captured →
Geofence verification → Check-in recorded →
Ready for transactions

3. Transaction Execution¶

Agent sells service to customer →
Device validates agent is in geofence →
Transaction processed →
Commission calculated →
Performance metrics updated

4. Performance Monitoring¶

Daily: Dashboard shows agent metrics
Weekly: Revenue and commission reports
Monthly: Performance rankings and bonus eligibility
Quarterly: Agent compliance review