Agent Cash-In - OLIVE Payment Platform

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

{}

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

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

Request
Response
By Card Serial

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

{
  "success": true,
  "message": "Cash-in successful",
  "transaction_id": "txn_cashin_abc123",
  "amount": "50.00 SLE",
  "agent_balance": "450,000.00 SLE",
  "subscriber_balance": "75,000.00 SLE",
  "commission_earned": "0.25 SLE"
}

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",
    "card_serial": "OLIV0001",
    "amount": "100.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

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

The response is of type object.

Fund Agent

Transfer Float

Documentation Index

​Endpoint

​Authentication

​Request Body

​Transaction Flow

​Example

​Errors

​Related

Agent Balance

Fund Agent

Authorizations

Body

Response

Endpoint

Authentication

Request Body

Transaction Flow

Example

Errors

Related