Agent Network
Agents are local businesses authorized to handle cash transactions for OLIVE users.Agent Types
| Type | Description |
|---|---|
super_agent | Top-level agent (bank, large business). Cannot have parent. |
sub_agent | Individual shop/kiosk. Must have parent_agent_id. |
Agent Status
| Status | Description |
|---|---|
active | Can perform transactions (default) |
inactive | Account dormant |
suspended | Temporarily blocked by admin |
Commission Tiers
| Tier | Top-up Rate | Withdrawal Rate |
|---|---|---|
| 1 | 1.0% | 0.5% |
| 2 | 1.5% | 0.75% |
| 3 | 2.0% | Higher |
Settlement Modes
| Mode | Description |
|---|---|
instant | Commission paid immediately (default) |
weekly | Accumulated, paid weekly |
monthly | Accumulated, paid monthly |
Agent Fields
| Field | Type | Description |
|---|---|---|
id | TEXT | Unique agent ID |
agent_type | TEXT | super_agent or sub_agent |
parent_agent_id | TEXT | For sub-agents (FK to agents) |
agent_name | TEXT | Display name |
business_name | TEXT | Registered business name |
contact_person | TEXT | Primary contact |
phone_number | TEXT | Unique phone |
email | TEXT | Business email |
business_address | TEXT | Physical address |
district | TEXT | Sierra Leone district |
location | TEXT | Location description |
float_balance | INTEGER | Working capital (SLE) |
balance | BIGINT | Account balance |
commission_tier | INTEGER | 1, 2, or 3 |
tier_level | INTEGER | Legacy tier field |
settlement_mode | TEXT | instant/weekly/monthly |
kyc_documents | TEXT | KYC doc URLs |
kyc_document_url | TEXT | Primary KYC doc |
agent_pin_hash | TEXT | PIN hash (SHA256) |
status | TEXT | active/inactive/suspended |
created_at | TIMESTAMP | Registration date |
Validation Rules
Super Agent:- Cannot have
parent_agent_id - Business name required
- Contact person required
- Phone required
- Commission tier 1-3
- Must have
parent_agent_id - Same field requirements as super agent
Float Operations
| Operation | Effect on Float |
|---|---|
| Cash-in from customer | Decreases |
| Cash-out to customer | Increases |
| Float transfer from super | Increases |
| Float transfer to sub | Decreases |
Agent PIN
Every agent has a 4-digit PIN:- Hashed:
SHA256(pin)(no salt) - Required for transaction authorization
- Validated before any float operation