Agent Cash-In
POST
/agents/cashinOpen in the API playground →
Info
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
Authorizationstringheaderrequired
Bearer token (API key or Agent JWT)
Request Body
agent_idstringbodyrequired
UUID of the agent performing cash-in
subscriber_idstringbodyrequired
UUID of subscriber receiving funds
card_serialstringbody
Card serial number (alternative to subscriber_id)
amountstringbodyrequired
Amount in SLE (e.g., 50.00 or 50)
agent_pinstringbodyrequired
Agent's 4-digit PIN for authentication
Transaction Flow
Validation
Agent PIN verified, subscriber looked up by ID or card serial
Compliance Check
Transaction checked against daily limits and fraud rules
Fee Calculation
Agent fee calculated based on fee settings
Balance Updates
Agent debited, subscriber credited atomically
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
| Code | Error | Description |
|---|---|---|
| 400 | INVALID_AMOUNT | Amount format incorrect |
| 400 | INVALID_PIN | Agent PIN is wrong |
| 400 | INSUFFICIENT_FLOAT | Agent float balance too low |
| 404 | SUBSCRIBER_NOT_FOUND | Subscriber/card not found |
| 403 | SUBSCRIBER_BLOCKED | Subscriber account is blocked |
| 403 | COMPLIANCE_REJECTED | Transaction exceeds limits |