API Documentation

Getting Started

Welcome to the Airtime to Cash Automation API. This RESTful API allows you to integrate airtime to cash conversion functionality into your applications.

Base URL

https://automation.airtimetocash.com

Fast Integration

Get up and running in 30 minutes with our comprehensive API documentation.

Secure & Reliable

Enterprise-grade security with 99.9% uptime guarantee and comprehensive error handling.

JSON Response Codes

Custom response codes returned in the JSON response body to indicate the status of your request.

Code	Description
2000	The Request is successful
3000	The Request failed
4000	The Request is pending (not sure of delivery - needs manual intervention)
4030	The Request is forbidden
4010	Your Session expired
4290	Too many requests
5030	Service/Recipient is unavailable at the moment

HTTP Status Codes

Standard HTTP status codes for failed requests returned by our API.

Code	Status	Description
403	Forbidden	The Request is forbidden
422	Unprocessable Entity	Unprocessable entity
401	Unauthorized	Unauthorized
404	Not Found	Route/Resource not found
429	Too Many Requests	Too many requests
500	Internal Server Error	Internal Server error (set to pending)

Authentication

All API requests require proper authentication to ensure secure access to our services.

Authentication Methods

OTP Endpoints

For Generate OTP and Verify OTP endpoints:

Basic Headers

Content-Type: application/json
Accept: application/json

Protected Endpoints

For all other endpoints (after OTP verification):

Bearer Token Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

Token Generation: The Bearer token must be generated from your account under the Developer's Module. This token is required for all endpoints except Generate OTP and Verify OTP.

Supported Networks

Our API supports all major Nigerian mobile networks for airtime to cash conversion. Each network has specific codes and amount limits that must be adhered to when making API requests.

MTN Nigeria

Network Code: MTN

Amount Range: ₦50 - ₦10,000

Airtel Nigeria

Network Code: AIRTEL

Amount Range: ₦50 - ₦20,000

Globacom

Network Code: GLO

Amount Range: ₦50 - ₦1,000

9mobile

Network Code: 9MOBILE

Amount Range: ₦50 - ₦20,000

Important Notes

• Network codes must be used exactly as specified (case-sensitive)
• Amount limits are strictly enforced for each network
• All amounts are in Nigerian Naira (₦)
• Minimum conversion amount is ₦50 for all networks

API Endpoints

Complete list of available endpoints for airtime to cash conversion.

POST

Generate OTP

Generate OTP for phone number verification before airtime transfer.

Endpoint

POST /api/v1/generate/otp

Request Body

JSON

{
  "networkName": "MTN",
  "sender": "0806******73"
}

Parameters

Parameter	Type	Required	Description
networkName	string	Yes	Network provider (MTN, AIRTEL, GLO, 9MOBILE)
sender	string	Yes	Phone number

Response

Success Response (HTTP 200)

{
  "code": 2000,
  "message": "Otp sent successfully to +23486*****73"
}

Error Response - Too Many Requests (HTTP 429)

{
  "code": 4290,
  "message": "Too many requests in few time"
}

Error Response - Access Denied (HTTP 400)

{
  "code": 4030,
  "message": "You are not allowed to access this module!"
}

POST

Verify OTP

Verify the OTP sent to the phone number.

Endpoint

POST /api/v1/verify/otp

Request Body

JSON

{
  "networkName": "MTN",
  "sender": "0806******73",
  "otp": "123456"
}

Parameters

Parameter	Type	Required	Description
networkName	string	Yes	Network provider (MTN, AIRTEL, GLO, 9MOBILE)
sender	string	Yes	Phone number
otp	string	Yes	OTP code received via SMS

Response

Success Response (HTTP 200)

{
  "code": 2000,
  "message": "Otp verified.",
  "data": {
    "airtimeBalance": "₦0.42",
    "tariff": "SMEPlus 186 Prepaid",
    "type": "Prepaid",
    "sessionId": "20230521232229|744673|18"
  }
}

Error Response - Maximum Attempts (HTTP 200)

{
  "code": 3000,
  "message": "You've reached the maximum number of attempts. Please try to login again."
}

Error Response - Wrong OTP (HTTP 200)

{
  "code": 3000,
  "message": "Wrong phone number or verification code."
}

POST

Login with Session ID

Retrieve SIM information using a valid session ID to access airtime transfer functionality.

Endpoint

POST /api/v1/login/with/session/id

Authentication Required: This endpoint requires a Bearer token. Include Authorization: Bearer {YOUR_TOKEN} in your request headers.

Request Body

JSON

{
  "networkName": "MTN",
  "sender": "0806******73",
  "sessionId": "20230521232229|744673|18"
}

Parameters

Parameter	Type	Required	Description
networkName	string	Yes	Network provider (MTN, AIRTEL, GLO, 9MOBILE)
sender	string	Yes	Phone number
sessionId	string	Yes	Valid session ID (Gotten from Verify OTP response)

Response

Success Response (HTTP 200)

{
  "code": 2000,
  "message": "Session record retrieved.",
  "data": {
    "airtimeBalance": "₦0.42",
    "tariff": "SMEPlus 186 Prepaid",
    "type": "Prepaid",
    "sessionId": "20230521232229|744673|18"
  }
}

Error Response - Session Expired (HTTP 200)

{
  "code": 4010,
  "message": "Session Id Expired. Request a new otp."
}

POST

Check Quota Availability

Check if there are available recipients for airtime conversion before making a transfer.

Endpoint

POST /api/v1/check/quota/availability

Authentication Required: This endpoint requires a Bearer token. Include Authorization: Bearer {YOUR_TOKEN} in your request headers.

Request Body

JSON

{
  "networkName": "MTN",
  "amount": 1000
}

Parameters

Parameter	Type	Required	Description
networkName	string	Yes	Network provider (MTN, AIRTEL, GLO, 9MOBILE)
amount	integer	Yes	Amount to check availability for (minimum ₦50)

Network Limits: MTN (₦50-₦10,000), AIRTEL (₦50-₦20,000), GLO (₦50-₦1,000), 9MOBILE (₦50-₦20,000)

Response

Success Response

{
  "code": 5030,
  "message": "Recipient(s) Available"
}

Error Response (HTTP 200)

{
  "code": 5030,
  "message": "Unavailability of recipient!"
}

POST

Transfer Airtime

Transfer airtime and convert to cash.

Endpoint

POST /api/v1/transfer/airtime

Authentication Required: This endpoint requires a Bearer token. Include Authorization: Bearer {YOUR_TOKEN} in your request headers.

Request Body

JSON

{
  "networkName": "MTN",
  "sender": "0806******73",
  "amount": 1000,
  "reference": "TXN123456789",
  "pin": "1234",
  "sessionId": "20230521232229|744673|18"
}

Parameters

Parameter	Type	Required	Description
networkName	string	Yes	Network provider (MTN, AIRTEL, GLO, 9MOBILE)
sender	string	Yes	Phone number
amount	integer	Yes	Amount to transfer (minimum ₦50)
reference	string	Yes	Unique transaction reference (10-40 characters)
pin	string	Yes	SIM Transfer PIN
sessionId	string	Yes	Valid session ID (Gotten from Verify OTP response)

Response

Success Response (HTTP 200)

{
  "code": 2000,
  "message": "Yello! You have gifted N50.0 to 23481****89. Share link https://mtnapp.page.link/myMTNNGApp with 23481****89 to download new MyMTN app for exciting offers.",
  "data": {
    "amountConverted": "₦50",
    "recipient": "23481****89",
    "balanceBefore": "₦220,751.8",
    "balanceAfter": "₦220,701.8",
    "automationCharges": "₦2",
    "sessionId": "20230521232229|744673|18"
  }
}

Pending Response (HTTP 200)

{
  "code": 4000,
  "message": "Your request is being processed...!",
  "data": {
    "amountConverted": "₦50",
    "recipient": "23481****89",
    "balanceBefore": "₦220,751.8",
    "balanceAfter": "₦220,701.8",
    "automationCharges": "₦2",
    "sessionId": "20230521232229|744673|18"
  }
}

Session Expired (HTTP 200)

{
  "code": 4010,
  "message": "Session Id Expired. Request a new otp."
}

Recipient Unavailable (HTTP 200)

{
  "code": 5030,
  "message": "Unavailability of recipient!"
}

Low Balance (HTTP 200)

{
  "code": 3000,
  "message": "Y'ello! Your account balance is low. Please recharge and try again. Thank you. "
}

Invalid PIN (HTTP 200)

{
  "code": 3000,
  "message": "You have entered an invalid pin. Please double-check the pin and try again. Thank you."
}

Rate Limits

API rate limits to ensure fair usage and system stability.

Standard Rate

60

requests per minute

Maximum Rate

100

requests per minute (based on request)

Note: Rate limits are enforced per IP address. Standard rate is 60 requests per minute, with maximum of 100 requests per minute available based on request. Contact our team for custom rate limits based on your business needs.

Documentation

Getting Started

Base URL

Fast Integration

Secure & Reliable

JSON Response Codes

HTTP Status Codes

Authentication

Authentication Methods

OTP Endpoints

Protected Endpoints

Supported Networks

MTN Nigeria

Airtel Nigeria

Globacom

9mobile

Important Notes

API Endpoints

Generate OTP

Request Body

Parameters

Response

Verify OTP

Request Body

Parameters

Response

Login with Session ID

Request Body

Parameters

Response

Check Quota Availability

Request Body

Parameters

Response

Transfer Airtime

Request Body

Parameters

Response

Rate Limits

Standard Rate

Maximum Rate

Ready to Start Building?