Skip to main content
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 agent

Get Agent

GET /api/v1/agents/{id}Get agent details

List Agents

GET /api/v1/agentsList agents with filters

Lookup Agent

GET /api/v1/agents/lookupFind agent by phone number

Fund Agent

POST /api/v1/agents/{id}/fundAdd float to agent account

Cash-In

POST /api/v1/agents/cashinCredit subscriber wallet

Transfer Float

POST /api/v1/agents/transferTransfer to sub-agent

Get Balance

GET /api/v1/agents/{id}/balanceCheck 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

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

Agent TypeCash-InCash-Out
Super-Agent0.3%0.5%
Sub-Agent0.2%0.3%
Commission is earned from fees charged to subscribers and credited instantly to agent balance.

​
Common Workflows

  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
  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
  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

RoleCan RegisterCan FundCan View
System AdminSuper + SubAny agentAll
Super-AgentSub onlyOwn sub-agentsOwn network
Sub-AgentNoneNoneOwn profile

Compliance

Agent transaction monitoring

Suspicious Activity

Flag unusual agent behavior