Agent Integration Guide Complete guide for integrating with the OLIVE agent network for cash-in, cash-out, and float management operations.
Overview OLIVE agents are authorized individuals or businesses that facilitate cash transactions for subscribers who may not have direct access to digital banking.
Cash-In Customer deposits cash, agent credits wallet
Cash-Out Customer withdraws cash, agent debits wallet
Float Transfer Transfer float between agents
Agent Types Type Description Capabilities Master Agent Top-level agent, typically a bank/large business Fund sub-agents, view all transactions Sub-Agent Retail point (shop, kiosk) Handle customer transactions
Agent Hierarchy Prerequisites Before integrating:
Agent Registration
Agent must be registered in OLIVE with a unique ID and phone number
Float Funding
Master agent must fund sub-agent float via /agents/transfer
PIN Setup
Agent must have a transaction PIN configured
API Key
Obtain API key with agent scope
Authentication Agent operations use standard API key authentication:
curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/agents/cashin" \ -H "Authorization: Bearer olive_live_xxx" \ -H "Content-Type: application/json" \ -d '{...}'
Cash-In Operation Customer deposits cash with agent, who credits the customer’s wallet.
Flow
Customer Provides Info
Customer shows phone number or NFC card
Agent Looks Up Customer
Agent calls /agents/lookup to verify subscriber
Collect Cash
Agent collects physical cash from customer
Process Cash-In
Agent calls /agents/cashin with amount
Confirmation
Both agent and customer receive confirmation
API Call curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/agents/cashin" \ -H "Authorization: Bearer olive_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "agent_123abc", "subscriber_phone": "+23277123456", "amount": 100000, "pin": "1234" }'
Response { "success" : true , "transaction_id" : "txn_abc123" , "message" : "Cash-in successful" , "data" : { "subscriber_name" : "John Doe" , "amount" : 100000 , "currency" : "SLE" , "new_balance" : 250000 , "agent_float" : 400000 } }
Agent float is debited on cash-in. Ensure sufficient float before processing.
Float Transfer Transfer float between agents (typically master to sub-agent).
API Call curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/agents/transfer" \ -H "Authorization: Bearer olive_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "from_agent_id": "master_agent_001", "to_agent_id": "sub_agent_123", "amount": 500000, "pin": "1234" }'
Response { "success" : true , "transaction_id" : "txn_xyz789" , "message" : "Float transfer successful" , "data" : { "from_agent_float" : 1500000 , "to_agent_float" : 800000 } }
Agent Lookup Look up agent details by phone number:
curl -X GET "https://olive-gateway-a6ba.onrender.com/api/v1/agents/lookup?phone=+23277123456" \ -H "Authorization: Bearer olive_live_xxx"
{ "agent" : { "id" : "agent_123abc" , "name" : "John's Shop" , "phone" : "+23277123456" , "type" : "sub_agent" , "float_balance" : 500000 , "status" : "active" } }
Balance Check Get agent float balance:
curl -X GET "https://olive-gateway-a6ba.onrender.com/api/v1/agents/agent_123abc/balance" \ -H "Authorization: Bearer olive_live_xxx"
{ "agent_id" : "agent_123abc" , "float_balance" : 500000 , "currency" : "SLE" , "today_transactions" : 15 , "today_volume" : 750000 }
Error Handling Error Code Meaning Resolution INSUFFICIENT_FLOATAgent doesn’t have enough float Request float from master agent INVALID_PINWrong transaction PIN Retry with correct PIN SUBSCRIBER_NOT_FOUNDPhone/card not registered Help customer register AGENT_SUSPENDEDAgent account suspended Contact support DAILY_LIMIT_EXCEEDEDAgent hit daily limit Wait for next day
Error Response Example { "success" : false , "error" : { "code" : "INSUFFICIENT_FLOAT" , "message" : "Agent does not have sufficient float for this transaction" , "details" : { "requested" : 100000 , "available" : 50000 } } }
Best Practices
Float Management
Monitor float levels regularly
Set up low-float alerts
Reconcile daily with master agent
Security
Never share transaction PIN
Verify customer identity
Report suspicious activity
Operations
Keep physical cash secure
Issue receipts for all transactions
End-of-day reconciliation
Compliance
Follow KYC requirements
Report large transactions
Maintain transaction records
Webhooks (Optional) Subscribe to agent transaction events:
{ "event" : "agent.cashin.completed" , "data" : { "agent_id" : "agent_123abc" , "transaction_id" : "txn_abc123" , "amount" : 100000 , "timestamp" : "2025-01-15T10:30:00Z" } }
