Agents are field operators who provide cash-in/cash-out services to subscribers. OLIVE 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/agentsRegister new super/sub agentGet Agent
GET /api/v1/agents/{id}Get agent detailsList Agents
GET /api/v1/agentsList agents with filtersLookup Agent
GET /api/v1/agents/lookupFind agent by phone numberFund Agent
POST /api/v1/agents/{id}/fundAdd float to agent accountCash-In
POST /api/v1/agents/cashinCredit subscriber walletTransfer Float
POST /api/v1/agents/transferTransfer to sub-agentGet Balance
GET /api/v1/agents/{id}/balanceCheck agent float balanceAgent Object
Agent Status
Active
Can process transactions
Suspended
Temporarily disabled
Terminated
Permanently deactivated
Agent Lifecycle
1
Registration
Admin or super-agent registers new agent with business details
2
Account Setup
System creates agent account and user credentials
3
Float Funding
OLIVE or super-agent adds initial float balance
4
Operations
Agent processes cash-in/cash-out for subscribers
5
Settlement
Agent settles with OLIVE or super-agent periodically
Cash-In Flow
1
Subscriber Arrives
Customer brings cash to agent location
2
Identify Subscriber
Agent looks up subscriber by phone or card
3
Process Cash-In
Agent enters amount and PIN to process
4
Balance Update
Agent float debited, subscriber credited
5
Confirmation
Both receive WhatsApp notification
Commission Structure
Commission is earned from fees charged to subscribers and credited instantly to agent balance.
Common Workflows
Register New Sub-Agent
Register New Sub-Agent
- Super-agent logs into dashboard
- Navigate to Agent Management
- Call
POST /api/v1/agentswithagent_type: "sub_agent" - Include
parent_agent_idreferencing super-agent - New agent receives credentials via WhatsApp
Fund Sub-Agent Float
Fund Sub-Agent Float
- Super-agent checks own balance
- Call
POST /api/v1/agents/{sub_agent_id}/fund - Amount transferred from super to sub-agent
- Both balances updated atomically
Process Customer Cash-In
Process Customer Cash-In
- Agent looks up subscriber by phone
- Collects cash from customer
- Call
POST /api/v1/agents/cashin - Agent float decreases, subscriber wallet increases
- Commission credited to agent
Permissions
Related
Compliance
Agent transaction monitoring
Suspicious Activity
Flag unusual agent behavior