Integration Flows

Voucher Generation Flow

Use this flow to generate prepaid voucher codes that you sell or distribute to customers.

Step 1: Authenticate
POST /token → Get bearer token

Step 2: Get available denominations
GET /denominations → List of denominations with IDs and values

Step 3: Generate voucher
POST /vouchers/generate → Returns code, serial number, value, and dates

Step 4: Deliver to customer
Print or deliver the code and serial number to the customer

Example

1. Get token:

curl -X POST https://api.academia.ly/api/v1/reseller/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password",
    "expires_at": "2026-05-09T00:00:00Z"
  }'

2. List denominations:

curl -X GET https://api.academia.ly/api/v1/reseller/denominations \
  -H "Authorization: Bearer {token}"

3. Generate a 100 LYD voucher:

curl -X POST https://api.academia.ly/api/v1/reseller/vouchers/generate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"denomination_id": 3}'

4. Response --- print this for the customer:

{
  "data": {
    "code": "001110016812345",
    "serial_number": "98712345678",
    "denomination_value": 100,
    "activation_date": "2026-04-09",
    "expiry_date": "2027-04-09"
  }
}

---

Deposit Flow

Use this flow to credit a user's wallet directly. The customer pays you, and you deposit the amount to their Academia account.

Step 1: Authenticate
POST /token → Get bearer token (if you don't already have one)

Step 2: Look up the user
GET /user-lookup?phone=xxx → Get first name and status

Step 3: Confirm identity
Verify the first name with the customer at your terminal

Step 4: Make the deposit
POST /deposit → Returns transaction_id as proof of payment

Step 5: Save the receipt
Save the transaction_id for your records

Example

1. Look up user by phone:

curl -X GET "https://api.academia.ly/api/v1/reseller/user-lookup?phone=0912345678" \
  -H "Authorization: Bearer {token}"

Response:

{
  "data": {
    "first_name": "Foulen",
    "status": "active"
  }
}

2. Confirm with customer: "Is the account holder named Foulen?"

3. Make the deposit:

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": "YOUR-UNIQUE-REF-001"
  }'

4. Response --- save transaction_id as proof:

{
  "data": {
    "transaction_id": 307,
    "phone": "0912345678",
    "first_name": "Foulen",
    "amount": 50.0,
    "external_transaction_id": "YOUR-UNIQUE-REF-001"
  }
}

---

Best Practices

• Cache your token --- don't request a new token for every API call. Reuse it until it's close to expiry.
• Cache denominations --- they rarely change. Refresh once a day or on startup.
• Always look up before depositing --- confirm the user's identity to avoid depositing to the wrong account.
• Use meaningful external_transaction_id values --- include your system's reference number for easy reconciliation.
• Handle errors gracefully --- check HTTP status codes and display appropriate messages to your operators.
• Save transaction_id from deposits --- this is your proof of payment from Academia's side.