Agents

Info

Agents are field operators who provide cash-in/cash-out services to subscribers. SmartPay supports a hierarchical agent network with super-agents and sub-agents.

Agent Hierarchy

Super-Agent

Regional managers

• Register sub-agents
• Fund sub-agent float
• View network performance
• Higher commission tier

Sub-Agent

Field agents

• Process cash-in/cash-out
• Receive float from super-agent
• Earn per-transaction commission
• Mobile-based operations

---

Endpoints

Register Agent

POST /api/v1/agents

Register new super/sub agent

Get Agent

GET /api/v1/agents/{id}

Get agent details

List Agents

GET /api/v1/agents

List agents with filters

Lookup Agent

GET /api/v1/agents/lookup

Find agent by phone number

Fund Agent

POST /api/v1/agents/{id}/fund

Add float to agent account

Cash-In

POST /api/v1/agents/cashin

Credit subscriber wallet

Transfer Float

POST /api/v1/agents/transfer

Transfer to sub-agent

Get Balance

GET /api/v1/agents/{id}/balance

Check agent float balance

---

Agent Object

{
  "id": "agent_abc123",
  "type": "super_agent",
  "business_name": "ABC Money Services",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+23277123456",
  "email": "john@abcmoney.sl",
  "location": "Freetown",
  "status": "active",
  "float_balance": 5000000,
  "float_balance_formatted": "5,000,000.00 SLE",
  "commission_tier": "standard",
  "settlement_mode": "instant",
  "parent_agent_id": null,
  "sub_agent_count": 12,
  "created_at": "2025-01-01T10:00:00Z"
}

---

Agent Status

Active

Can process transactions

Suspended

Temporarily disabled

Terminated

Permanently deactivated

---

Agent Lifecycle

Registration

Admin or super-agent registers new agent with business details

Account Setup

System creates agent account and user credentials

Float Funding

SmartPay or super-agent adds initial float balance

Operations

Agent processes cash-in/cash-out for subscribers

Settlement

Agent settles with SmartPay or super-agent periodically

---

Cash-In Flow

Subscriber Arrives

Customer brings cash to agent location

Identify Subscriber

Agent looks up subscriber by phone or card

Process Cash-In

Agent enters amount and PIN to process

Balance Update

Agent float debited, subscriber credited

Confirmation

Both receive WhatsApp notification

---

Commission Structure

Agent Type	Cash-In	Cash-Out
Super-Agent	0.3%	0.5%
Sub-Agent	0.2%	0.3%

Info

Commission is earned from fees charged to subscribers and credited instantly to agent balance.

---

Common Workflows

Register New Sub-Agent

1. Super-agent logs into dashboard
2. Navigate to Agent Management
3. Call POST /api/v1/agents with agent_type: "sub_agent"
4. Include parent_agent_id referencing super-agent
5. New agent receives credentials via WhatsApp

Fund Sub-Agent Float

1. Super-agent checks own balance
2. Call POST /api/v1/agents/{sub_agent_id}/fund
3. Amount transferred from super to sub-agent
4. Both balances updated atomically

Process Customer Cash-In

1. Agent looks up subscriber by phone
2. Collects cash from customer
3. Call POST /api/v1/agents/cashin
4. Agent float decreases, subscriber wallet increases
5. Commission credited to agent

---

Permissions

Role	Can Register	Can Fund	Can View
System Admin	Super + Sub	Any agent	All
Super-Agent	Sub only	Own sub-agents	Own network
Sub-Agent	None	None	Own profile

---

Related

Compliance

Agent transaction monitoring

Suspicious Activity

Flag unusual agent behavior