API Docs

Airtime Purchase Endpoint

Purchase airtime credits for mobile phones.

Endpoint

URL: /api/airtimeapi

Methods: POST, GET

Description

This API endpoint allows users to purchase airtime credits for mobile phones.

Authentication

To access this endpoint, users must include their API key and secret key in the request headers.

Request Headers

  • api-key (string, required): The API key of the user.
  • secret-key (string, required): The secret key of the user.

Request Body (POST)

  • phone (string, required): The phone number to recharge.
  • firstLevel (string, required): The network of airtime to purchase.
  • amount (number, required): The amount of airtime to purchase.
  • requestId (string, optional): The unique request identifier which you can use to query processed transaction. 5-50 characters long.

Usage Example

POST request to purchase airtime:

Content-Type: application/json
api-key: your-api-key
secret-key: your-secret-key

{
  "phone": "08032566178",
  "firstLevel": "MTN VTU", // value of this key can either be firstLevel or fId, e.g. "mtn-vtu" fId is more accurate
  "amount": 100,
  "requestId": "yourreference"
}
- The `amountUsed` field represents the actual amount deducted from the user's balance based on user level.

Response:

{
  "message": "Transaction successful",
  "data": {
    "transactionId": "1234567890",
    "email": "user@example.com",
    "activity": "MTN airtime",
    "status": "Successful",
    "recipient": "08032566178",
    "amount": 100,
    "amountUsed": 99,
    "initialBalance": 500,
    "finalBalance": 401,
    "Method": "API"
  }
}

Failed Response Format

{
  "message": "Transaction failed",
  "data": {
    "transactionId": "1234567890",
    "email": "user@example.com",
    "activity": "MTN airtime",
    "status": "Failed",
    "recipient": "08032566178",
    "amount": 100,
    "initialBalance": 500,
    "finalBalance": 500,
    "Method": "API"
  }
}

GET Request

Get the list of available firstLevel values:

Content-Type: application/json
api-key: your-api-key
secret-key: your-secret-key

Response:

[
  {
    "available": true,
    "firstLevel": "Mtn Vtu",
    "fId": "mtn-vtu",
    "amounts": [99],
    "secondLevels": []
  },
  {
    "available": true,
    "firstLevel": "Glo Vtu",
    "fId": "glo-vtu",
    "amounts": [98],
    "secondLevels": []
  },
  {
    "available": true,
    "firstLevel": "Airtel Vtu",
    "fId": "airtel-vtu",
    "amounts": [98],
    "secondLevels": []
  },
  {
    "available": true,
    "firstLevel": "9mobile Vtu",
    "fId": "9mobile-vtu",
    "amounts": [98],
    "secondLevels": []
  }
]
IABCONCEPT