Deposit

Credit a User's Wallet

Deposit funds directly into a user's Academia wallet. The user is identified by phone number.

Endpoint: POST /deposit

Important

Always call User Lookup first to confirm the user's identity before making a deposit. Deposits are irreversible.

Request

curl -X POST https://api.academia.ly/api/v1/reseller/deposit \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0912345678",
    "amount": 50.0,
    "external_transaction_id": "RUNPAY-TXN-12345"
  }'

Field	Type	Required	Description
phone	string	Yes	User's phone number
amount	number	Yes	Amount in LYD to deposit. Minimum: 0.01
external_transaction_id	string	Yes	Your unique reference ID for this transaction

About external_transaction_id

This is your transaction reference --- a unique identifier from your system. It serves two purposes:

1. Duplicate protection --- if you accidentally send the same request twice, the second request will be rejected instead of creating a double deposit
2. Reconciliation --- both sides can reference this ID when comparing records

DANGER

Each external_transaction_id can only be used once. Sending the same ID again will return a 409 Conflict error.

Response

Success (200):

{
  "data": {
    "transaction_id": 307,
    "phone": "0912345678",
    "first_name": "Foulen",
    "amount": 50.0,
    "external_transaction_id": "RUNPAY-TXN-12345"
  }
}

Field	Type	Description
data.transaction_id	integer	Academia's internal transaction ID. Save this as proof of payment.
data.phone	string	The user's phone number
data.first_name	string	User's first name
data.amount	number	Amount deposited in LYD
data.external_transaction_id	string	Your reference ID echoed back

TIP

Save the transaction_id from the response. This is Academia's official record of the deposit and can be used as proof of payment on receipts.

Errors

Status	Response	Meaning
401	{"message": "Invalid credentials."}	Invalid or expired token
403	{"message": "Access denied."}	IP not whitelisted
404	{"message": "User not found."}	No user with this phone number
409	See below	Duplicate transaction
422	See below	Validation error or daily limit exceeded

Duplicate transaction (409):

{
  "message": "Duplicate transaction.",
  "external_transaction_id": "RUNPAY-TXN-12345"
}

Daily limit exceeded (422):

{
  "message": "Daily limit exceeded.",
  "daily_max_amount": 5000,
  "used_today": 4980,
  "remaining": 20,
  "requested": 50
}