Skip to main content
POST
/
agents
/
cashin
Agent cash-in transaction
curl --request POST \
  --url https://olive-gateway-a6ba.onrender.com/api/v1/agents/cashin \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "<string>",
  "agent_pin": "<string>",
  "amount": "<string>",
  "subscriber_id": "<string>"
}
'
{}
Agent cash-in allows field agents to deposit cash into subscriber wallets. The agent’s float balance is debited, and the subscriber is credited.

​
Endpoint

POST /api/v1/agents/cashin

​
Authentication

​
Authorization
string
required
Bearer token (API key or Agent JWT)

​
Request Body

​
agent_id
string
required
UUID of the agent performing cash-in
​
subscriber_id
string
required
UUID of subscriber receiving funds
​
card_serial
string
Card serial number (alternative to subscriber_id)
​
amount
string
required
Amount in SLE (e.g., 50.00 or 50)
​
agent_pin
string
required
Agent’s 4-digit PIN for authentication

​
Transaction Flow

1

Validation

Agent PIN verified, subscriber looked up by ID or card serial
2

Compliance Check

Transaction checked against daily limits and fraud rules
3

Fee Calculation

Agent fee calculated based on fee settings
4

Balance Updates

Agent debited, subscriber credited atomically
5

Notifications

WhatsApp notification sent to subscriber

​
Example

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_abc123",
    "subscriber_id": "sub_xyz789",
    "amount": "50.00",
    "agent_pin": "1234"
  }'

​
Errors

CodeErrorDescription
400INVALID_AMOUNTAmount format incorrect
400INVALID_PINAgent PIN is wrong
400INSUFFICIENT_FLOATAgent float balance too low
404SUBSCRIBER_NOT_FOUNDSubscriber/card not found
403SUBSCRIBER_BLOCKEDSubscriber account is blocked
403COMPLIANCE_REJECTEDTransaction exceeds limits

Agent Balance

Check agent float balance before cash-in

Fund Agent

Add float to agent account

Authorizations

​
Authorization
string
header
required

API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'

Body

application/json

Cash-in details

​
agent_id
string
required
​
agent_pin
string
required

Agent's PIN for authentication

​
amount
string
required

Accepts decimal format like "50.00" or "50"

​
subscriber_id
string
required
​
card_serial
string

Response

OK

The response is of type object.