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://demo.api.vultlocal.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://demo.api.vultlocal.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://demo.api.vultlocal.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://demo.api.vultlocal.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://demo.api.vultlocal.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_FLOAT`	Agent doesn’t have enough float	Request float from master agent
`INVALID_PIN`	Wrong transaction PIN	Retry with correct PIN
`SUBSCRIBER_NOT_FOUND`	Phone/card not registered	Help customer register
`AGENT_SUSPENDED`	Agent account suspended	Contact support
`DAILY_LIMIT_EXCEEDED`	Agent 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"
  }
}

Agent Lookup API

Look up agent by phone

Cash-In API

Process cash deposits

Float Transfer API

Transfer float between agents

Agent Balance API

Check agent float

Integration Guides

Reference

Agent Integration

Agent Integration Guide

Overview

Cash-In

Cash-Out

Float Transfer

Agent Types

Agent Hierarchy

Prerequisites

Authentication

Cash-In Operation

Flow

API Call

Response

Float Transfer

API Call

Response

Agent Lookup

Balance Check

Error Handling

Error Response Example

Best Practices

Float Management

Security

Operations

Compliance

Webhooks (Optional)

Agent Lookup API

Cash-In API

Float Transfer API

Agent Balance API

​Agent Integration Guide

​Overview

Cash-In

Cash-Out

Float Transfer

​Agent Types

​Agent Hierarchy

​Prerequisites

​Authentication

​Cash-In Operation

​Flow

​API Call

​Response

​Float Transfer

​API Call

​Response

​Agent Lookup

​Balance Check

​Error Handling

​Error Response Example

​Best Practices

Float Management

Security

Operations

Compliance

​Webhooks (Optional)

​Related

Agent Lookup API

Cash-In API

Float Transfer API

Agent Balance API

Agent Integration Guide

Overview

Agent Types

Agent Hierarchy

Prerequisites

Authentication

Cash-In Operation

Flow

API Call

Response

Float Transfer

API Call

Response

Agent Lookup

Balance Check

Error Handling

Error Response Example

Best Practices

Webhooks (Optional)

Related