Agent Integration

Complete guide for integrating with the SmartPay agent network for cash-in, cash-out, and float management operations.

Overview

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

Warning

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

---

Related

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