HTTP API

Developers can use our HTTP APIs to quickly and easily integrate with their systems and applications.

BALANCE CHECK API

Command:
https://mobileairtimeng.com/httpapi/balance.php?userid=xxxx&pass=xxxx

PARAMETERS
Userid = your registered number
pass = api key (available in your vendor area. See V-Home)

AIRTIME TOP UP API

  • Instant Top up GSM networks such as; MTN, Glo, Etisalat, Airtel, Visaphone
  • Dispense Mobile Top up from as low as N50 on all networks.
  • Switch between Instant Sell & Share and VTU
  • E-mail notification to vendor.
  • No activation fee

Command:
https://mobileairtimeng.com/httpapi/?userid=xxxx&pass=xxxx&network=x&phone=xxxxx&amt=xx&user_ref=xxx

Command (JSON)
https://mobileairtimeng.com/httpapi/?userid=xxxx&pass=xxxx&network=x&phone=xxxxx&amt=xx&user_ref=xxx&jsn=json

Userid = your registered number
pass = api key (available in your vendor area-dashboard)
phone = receiver's number
user_ref= user defined reference (optional but can be useful in querying a transaction)
network= network (replace the network with the system code)

Network

System Code

Airtel

1

9Mobile

2

MTN
15

Glo

6


Response Codes
100 - Successful
101 - Account not activated
102 - Invalid amount
103 - Insufficient balance
104 - Invalid user id
105 - Invalid log in
106 - No network selected
107 - Invalid phone
108 - Other Platform errors
109 – Invalid Developer Account

Sample Response
: Response is separated by pipe( | ); code | responseMessage
A successful recharge; 100|Recharge successful|userReference

Sample JSON Response: {"code":100, "message":"Recharge successful", "user_ref":"atyp12390"}

MTN ETRANZACT PREMIUM FOR BULK RECHARGE

Minimum top up is 1,000 at 3.5% discount.
Command:
https://mobileairtimeng.com/httpapi/mtnetvtu?userid=xxxx&pass=xxxx&network=x&phone=xxxxx&amt=xx&user_ref=xxx&jsn=json

GLOBAL TOP UP

Top up any mobile number in the world using the API explained below.
To verify mobile number and get details
https://mobileairtimeng.com/httpapi/globalvtu-conf?userid=xxx&pass=xxx&phone=xxx
Ensure that the phone number is in international format without the + e.g. 233558285196 is a Ghana mobile number.
Sample responses: {"response":"OK","info":{"openRange":true,"country":"Ghana","operator":"MTN","msisdn":"233558285196"},"products":[{"id":"ETRX-MTN-OR","min":1,"max":100,"topup_currency":"GHS","rate":"67.09"}]}

"response":"OK","info":{"openRange":false,"country":"United States","operator":"ATT USA","msisdn":"13175154840"},"products":[{"id":"TRTO-1459-10","topup_currency":"USD","topup_amount":"10","price":3605.1},{"id":"TRTO-1459-12","topup_currency":"USD","topup_amount":"12","price":4326.12},{"id":"TRTO-1459-15","topup_currency":"USD","topup_amount":"15","price":5407.65},{"id":"TRTO-1459-20","topup_currency":"USD","topup_amount":"20","price":7210.2},{"id":"TRTO-1459-25","topup_currency":"USD","topup_amount":"25","price":9012.75},{"id":"TRTO-1459-30","topup_currency":"USD","topup_amount":"30","price":10815.3},{"id":"TRTO-1459-35","topup_currency":"USD","topup_amount":"35","price":12617.85},{"id":"TRTO-1459-40","topup_currency":"USD","topup_amount":"40","price":14420.4},{"id":"TRTO-1459-45","topup_currency":"USD","topup_amount":"45","price":16222.95},{"id":"TRTO-1459-50","topup_currency":"USD","topup_amount":"50","price":18025.5},{"id":"TRTO-1459-55","topup_currency":"USD","topup_amount":"55","price":19828.05},{"id":"TRTO-1459-60","topup_currency":"USD","topup_amount":"60","price":21630.6},{"id":"TRTO-1459-65","topup_currency":"USD","topup_amount":"65","price":23433.15},{"id":"TRTO-1459-70","topup_currency":"USD","topup_amount":"70","price":25235.7},{"id":"TRTO-1459-75","topup_currency":"USD","topup_amount":"75","price":27038.25},{"id":"TRTO-1459-80","topup_currency":"USD","topup_amount":"80","price":28840.8},{"id":"TRTO-1459-85","topup_currency":"USD","topup_amount":"85","price":30643.35},{"id":"TRTO-1459-90","topup_currency":"USD","topup_amount":"90","price":32445.9},{"id":"TRTO-1459-95","topup_currency":"USD","topup_amount":"95","price":34248.45},{"id":"TRTO-1459-100","topup_currency":"USD","topup_amount":"100","price":36051}]}

Please note that the amount you can specify for recharge is determined by the mobile operator. Some operators allow variable amounts while others are fixed. So, with the verify API, you can get the details of the operator. From the samples given above, the Ghana operator will allow variable amount while the United States operator has fixed amounts (topup_amount).

To recharge any international number
https://mobileairtimeng.com/httpapi/globalvtu?userid=xxx&pass=xxx&phone=xxx&product=xxx&amt=xxx
product = product id obtained from the verify API
amt = it could be variable or fixed which depends on the operator

To recharge the Ghana mobile with 1 GHS (variable);
https://mobileairtimeng.com/httpapi/globalvtu?userid=xxx&pass=xxx&phone=233558285196&product=ETRX-MTN-OR&amt=1&user_ref=xxx&jsn=json

To recharge the United States mobile with 10 USD (fixed);
https://mobileairtimeng.com/httpapi/globalvtu?userid=xxx&pass=xxx&phone=13175154840&product=TRTO-1459-10&amt=10&user_ref=xxx&jsn=json

Sample JSON Response: {"code":100, "message":"Recharge successful", "user_ref":"ato12s90"}

CHECK TRANSACTION STATUS

This is useful for checking the status of a recharge or top up (airtime, data, cable tvs).
Command:
https://mobileairtimeng.com/httpapi/status?userid=xxxx&pass=xxxx&transid=xxx
- transid = user defined reference during transaction i.e. user_ref

MTN SME DATA API/MTN DATA SHARE API

Command:
https://mobileairtimeng.com/httpapi/datashare?userid=xxxx&pass=xxxx&network=x&phone=xxxxx&datasize=xx&user_ref=xxx

Command (JSON)
https://mobileairtimeng.com/httpapi/datashare?userid=xxxx&pass=xxxx&network=x&phone=xxxxx&datasize=xx&jsn=json&user_ref=xxx

Userid = your registered number
pass = api key (available in your vendor area dashboard)
phone = receiver's number
datasize = 1000 (1GB)
= 2000 (2GB)
= 5000 (5GB)
network = 1 (MTN)

Response Codes
Same as airtime or VTU

Sample Response
: Response is separated by pipe( | ); code | responseMessage
A successful data request;
100|Data recharge completed|batchnumber OR
100|Data recharge in progress|batchnumber

Sample JSON Response: {"code":100,"message":"Data recharge completed","batchno":"128981"}

CHECK STATUS MTN SME DATA TRANSACTION

Command:
https://mobileairtimeng.com/httpapi/datastatus?batch=xxxx
- batch = user defined reference

DATA TOP UP API (MTN, ETISALAT, AIRTEL)

Data top up is available for MTN, Airtel and Etisalat.

Command:
https://mobileairtimeng.com/httpapi/datatopup.php?userid=xxxx&pass=xxxx&network=x&phone=xxxxx&amt=xx

Command (JSON):
https://mobileairtimeng.com/httpapi/datatopup.php?userid=xxxx&pass=xxxx&network=x&phone=xxxxx&amt=xx&jsn=json

amt = the price for the data.
Use this API to get the product list for each network;
https://mobileairtimeng.com/httpapi/get-items?userid=xxx&pass=xxx&service=mtn
https://mobileairtimeng.com/httpapi/get-items?userid=xxx&pass=xxx&service=airtel
https://mobileairtimeng.com/httpapi/get-items?userid=xxx&pass=xxx&service=glo
IMPORTANT:
Data top up will come in as airtime but would be automatically converted to the particular bundle. A recipient that has borrowed airtime will not receive the data top up because the airtime (or part) would have been deducted before conversion. 
To Check Data balance
Airtel: *123*10# or *140#, Etisalat: *228#, MTN: *131*4#, GLO: *127*0#

CHECK CUSTOMER INFORMATION API (Startimes, DStv/Gotv)

This is required to validate customer before recharging decoder.

Command:
https://mobileairtimeng.com/httpapi/customercheck?userid=xxx&pass=xxx&bill=xxx&smartno=xxx

Command (JSON):
https://mobileairtimeng.com/httpapi/customercheck?userid=xxx&pass=xxx&bill=xxx&smartno=xxx&jsn=json

bill = startimes, gotv or dstv
smartno = smart card no or ICU

Response
Response is a string separated by pipe ( | ).
100|customerName|balance
JSON Sample
{"code":100,"customerName":"Alex Jones ","balance":60}

customerName = customer name
balance = customer balance

Failed Response
101|message
{"code":104,"message":"invalid account"}

GOtv/DStv Successful Reponse
Response string separated with pipe;
100|customerName|decoderStatus|dueDate|invoicePeriod|customerNumber

JSON Response
{"code":100,"customerName":"Alex Jones ","decoderStatus":"opened","dueDate":"2018-10-09","invoicePeriod":1,"customerNumber":128392}

customerName = Full name of customer
decoderStatus = OPENED/CLOSED
dueDate = Subscription expiration date
invoiceDate = months
customerNumber = customer number on GOtv or DStv

NB: Startimes API, GOtv API and DStv API requires a one-time activation fee of N5,000.

STARTIMES API Recharge

  • Recharges Startimes decoder instantly.
  • Sends SMS notification to client or customer
  • Sends SMS notification to vendor.

Command:
https://mobileairtimeng.com/httpapi/startimes?userid=xxx&pass=xxx&phone=xxx&amt=xxx&smartno=xxx&user_ref=xxx

Command (JSON):
https://mobileairtimeng.com/httpapi/startimes?userid=xxx&pass=xxx&phone=xxx&amt=xxx&smartno=xxx&jsn=json&user_ref=xxx
amt = amount to recharge
phone = phone number to receive SMS notification
smartno = smart card number

Response
Response is a string separated by pipe ( | ). Below is a typical successful operation;
100|Successful|exchangeReference|responseMessage

JSON Response
{"code":100,"message":"Successful","exchangeReference":"177269","responseMessage":"operation successful"}

message = status message
exchangeReference = Unique reference number generated on Startimes platform
responseMessage = return message from Startimes

GOTV/DSTV RECHARGE API

  • Recharges GOtv decoder instantly.
  • Sends SMS notification to client or customer
  • Sends SMS/Email notification to vendor.

Command:
https://mobileairtimeng.com/httpapi/multichoice?userid=xxx&pass=xxx&phone=xxx&amt=xxx&smartno=xxx&customer=xxx&invoice=x&billtype=xx&customernumber=x

Command (JSON):
https://mobileairtimeng.com/httpapi/multichoice?userid=xxx&pass=xxx&phone=xxx&amt=xxx&smartno=xxx&customer=xxx&invoice=x&billtype=xx&customernumber=x&jsn=json

smartno = decoder number
customer = customer name received during customer check
invoice = invoice number received during customer check
billtype = gotv or dstv
amt = recharge or bouquet in amount.
customernumber = customer number received during customer check

For Gotv;
- 400 = Gotv Lite
- 1250 = Gotv value
- 1900 = Gotv Plus
- 3200 = Gotv Max
You can also use any amount that is available for Gotv.

For Dstv
2000 = Dstv Access
4000 = Dstv Family
6800 = Compact
You can also use any amount that is available for Dstv.

Response:
Successful response;
100|Successful|exchangeReference

JSON Response
{"code":100,"message":"Successful","exchangeReference":"112377269"}
message = status message
exchangeReference = Unique reference number generated on MultiChoice platform

Failed;
101|message
{"code":103,"message":"invalid log in"}

ELECTRICITY API

Pay and generate tokens for Electricity companies (DISCOS) on your website or app.
Available; Ikeja Electricity (IKEDC), Kano Electricity (KEDC), Abuja Electricity, Ibadan Electricity (IBEDC), EKO (EKEDC), Enugu (EEDC), Port Harcourt (PHEDC) etc
Get Available Electricity Companies (DISCOS)

Command (with JSON Response):
http://mobileairtimeng.com/httpapi/power-lists?userid=xxx&pass=xxx

Sample Response
{"response":"OK","result":[{"product_id":"BPE-NGIE-OR","name":"Ikeja Electric","hasProductList":false,"hasValidation":true,"openRange":true,"min_denomination":"500","max_denomination":"50000","step":100},{"product_id":"BPE-NGIB-OR","name":"Ibadan Distribution","hasProductList":false,"hasValidation":true,"openRange":true,"min_denomination":"1000","max_denomination":"50000","step":100}]}

Validate Customer Meter No
This is useful to get customer information.

Command (JSON Response):
http://mobileairtimeng.com/httpapi/power-validate?userid=xxx&pass=xxx&service=xxx&meterno=xxx&jsn=json

service - the product_id of the Electricity company/DISCO
meterno - customer meter number
Sample Response
{"code":100,"message":"Nwobodo C"}
Code is 100 for successful validation and the value of the message will be the customer name.

Pay Electricity

Command (JSON Response):
http://mobileairtimeng.com/httpapi/power-pay?userid=xxx&pass=xxx&user_ref=xxx&service=xxx&meterno=xxx&mtype=xxx&amt=xxx&jsn=json

service - the product_id of the Electricity company/DISCO
user_ref - unique user defined reference (useful for querying transaction) meterno - customer meter number
mtype - meter type, 1 for prepaid, 0 for postpaid.
NB: You can get available DISCOs and validate customer meter number without activation on the API but you must be activated to pay and generate token. A one-time activation fee of N5,000 is required to pay and generate electricity tokens.
Sample Response
{"code":100,"message":"Recharge successful","user_ref":"ibk748737","meterno":"36565","pincode":"08205597303581330549","pinmessage":"CreditToken:08205597303581330549 / TranId:106208046 / Value:22.4. Thank you for using the service. Ikeja Electric.\Recharge: 500"}
The pimessage parameter will contain the token and other important information for the payment

Money Transfer API

Send money directly to bank accounts in Nigeria instantly and also securely. Click here

Bulk SMS API

Bulk SMS API comes with detailed reporting. Failed SMS will not be charged. Pricing is determined by vendor level. See SMS pricing on the home page

Command: https://www.mobileairtimeng.com/smsapi/bulksms.php
POST parameters
username=xxx
password=xxx
message=xxx
mobile=xxx
sender=xxx
route=x
vtype=1

username = Your registered phone number
password= api key
message = message to send
mobile = recipients format e.g 081xxx,080xxx,070xxx. Separate multiple numbers with comma
sender = caption to display to recipients. Max of 11 characters
normal route = 1
vtype = 1 (for vendors)

Response Codes and Format
Success messages comes with 2001 while failed or rejected messages comes with 2002
Successful message format:
2001|phone|message sent e.g. 2001|2348135534866|message sent
Failed or Rejected SMS:
2002|phone|reason e.g. 2002|2348135534866|dnd rejected
Bulk numbers separated by comma:
The responses are also separated by comma e.g.
2001|2348139170491|message sent,2001|2348135534866|message sent

Do you have enquiries? Please contact us here