Direct Airtime/Data Api

Version 2

Supports over 760 Networks worldwide.

If you are interested in generating only airtime pin, visit the link below


This API allows you to purchase airtime and data directly from your wallet account.

You are required to enable Airtime/Data Api Token in settings page, save and then copy Api token generated.
Note: Do not share your Api Token



Use sha512 encryption algorithm to generate a hash by combining your Api Token, Account Email Address, Account Username and Your Transaction Reference.
For querying transactions, airtime product list or data product list, DO NOT include Transaction Reference.
Phone numbers used in this documentation are masked because of privacy reasons.

PHP Sample:
$hash=hash('sha512', $token.$email.$username.$ref );
Note: The above example shows how to generate the hash in PHP, the dots are not part of the string but for concatenation
$Token is your Api Token
$Ref is an ID/Message generated by you for record tracking purposes
Download PHP Sample files
To check account balance:
https://www.estoresms.com/smsapi.php?username=user123&password=pass123&balance=true&

where Account Username is user123 and account password is pass123

Note: Your username and password must be url encoded


RESPONSE CODES
OK => Successful
FAIL => Not Successful
P000 => Incomplete information
P001 => Authentication Failed
P002 => API not enabled for this account
P003 => Failed to validate phone number
P004 => Network not supported
P005 => Phone number is required
P006 => Product ID is required
P007 => Amount is required
P008 => Invalid Amount
P009 => Operation Failed
P010 => Below Minimum amount allowed
P011 => Above Maximum amount allowed
P012 => Product does not exist
P013 => Insufficient Balance
P014 => Maximum of 5 requests allowed

Step 1. GET AIRTIME PRODUCT LIST

Url: https://estoresms.com/network_list/v/2
Method: POST
Request Format: JSON
Response Format: JSON

SAMPLE REQUEST 
{
   "username":"user123",
   "hash":"6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe",
   "phone":"+1410xxxxxxxx",
   "country":"US"
}

SAMPLE RESPONSE 1 
{
   "response":"OK",
       "info":{
                "openRange":true,
                "country":"United States",
                "operator":"MTS",
                "msisdn":"1410xxxxxxx"
              },

   "products":[
                {
                   "id":"US-50-OR",
                   "min":20,
                   "max":1500,
                   "topup_currency":"USD",
                   "rate":100
                 }
              ]
}
Open Range: Indicates the available product list has no fixed amount and price, hence you can supply any amount within the minimum and maximum limit
ID: This is the product ID
Topup Currency: The currency used by the phone network
Rate: How much we charge your account in Naira.
Hence,
1. You can request for a purchase between 20 USD to 1500 USD. Note: Avoid decimal points, 20.6 USD is rounded up to 21 USD
2. If you request for a purchase of 20 USD for example. Price= Amount*rate (Price=20*100)
3. Price is how much it costs in Naira. (Rounded up to 2 decimal places)


SAMPLE RESPONSE 2 
{
  "response":"OK",
  "info":{
           "openRange":false,
           "country":"United Kingdom",
           "operator":"Everything Everywhere EE",
           "msisdn":"4477xxxxxxxx"
         },
  "products":[
                {
                   "id":"UKBL-1755-5.00",
                   "topup_currency":"GBP",
                   "topup_amount":"5.00",
                   "price":1610.4
                },
                {
                   "id":"UKBL-1755-10.00",
                   "topup_currency":"GBP",
                   "topup_amount":"10.00",
                   "price":3217.5
                },
                {
                   "id":"UKBL-1755-15.00",
                   "topup_currency":"GBP",
                   "topup_amount":"15.00",
                   "price":4827.9
                }
            ]
}
Open Range: Indicates the product list has fixed amount and price
ID: This is the product ID
Topup Currency: The currency used by the phone network
Topup Amount: The amount of airtime that would be credited to line
Price: Price is how much it costs in Naira. (Rounded up to 2 decimal places)

Step 2. MAKE AIRTIME PURCHASE

Url: https://estoresms.com/network_processing/v/2
Method: POST
Request Format: JSON
Response Format: JSON

Note: Product ID must be gotten from step 1 for every purchase


SAMPLE REQUEST 
{
   "username":"user123",
   "ref":"myRef",
   "hash":"6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe",
   "callback":"https://mywebsite/callback",
   "request":[
                  {
                    "product":"US-50-OR",
                    "phone":"+1410xxxxxxx",
                    "amount":20,
                    "country":"UK"
                  },
                  {
                    "product":"UKBL-1755-5.00",
                    "phone":"+4477xxxxxxxx",
                    "country":"UK"
                  }
            ]
}


SAMPLE RESPONSE 1
{
   "failed":0,
   "result":[
              {
                "response":"OK",
                "ref":"myRef",
                "transaction_id":"api_5ab5261b9b029",
                "phone":"+1410xxxxxxx",
                "amount":"8389.26",
                "amount_charged":"8053.69",
                "pins":[
                         {
                           "serialNumber":"WRN192775404",
                           "pin":"740525808961",
                           "expiresOn":"30 days"
                         }
                       ]
              },
              {
                "response":"OK",
                "ref":"myRef",
                "transaction_id":"api_5ab5223b8b927",
                "phone":"+4477xxxxxxxx",
                "amount":"1610.4",
                "amount_charged":"1546",
                "pins":[]
              }
           ]
}

SAMPLE RESPONSE 2
{
   "failed":0,
   "result":[
              {
                "response":"PENDING",
                "ref":"myRef",
                "transaction_id":"api_5ab5261b9b029",
                "phone":"+1410xxxxxxx",
                "amount":"8389.26",
                "amount_charged":"8053.69"
              },
              {
                "response":"PENDING",
                "ref":"myRef",
                "transaction_id":"api_5ab5223b8b927",
                "phone":"+4477xxxxxxxx",
                "amount":"1610.4",
                "amount_charged":"1546"
              }
           ]
}
PENDING response means you will need to Query the transaction
later on for final status


SAMPLE RESPONSE 3
{
    "response":"P013",
    "message":"Insufficient Balance"
}


SAMPLE RESPONSE 4
{
   "failed":2,
   "result":[
                {
                  "response":"P008",
                  "message":"Invalid Amount",
                  "phone":"+1410xxxxxxx"
                },
                {
                  "response":"P006",
                  "message":"Product ID is required",
                  "phone":"+4477xxxxxxxx"
                }
            ]
}

Step 1. GET DATA PRODUCT LIST

Url: https://estoresms.com/data_list/v/2
Method: POST
Request Format: JSON
Response Format: JSON

SAMPLE REQUEST 
{
   "username":"user123",
   "hash":"6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe",
   "phone":"+234706xxxxxxx"
}

SAMPLE RESPONSE 1 
{
   "response":"OK",
       "info":{
                "openRange":false,
                "country":"Nigeria",
                "operator":"MTN",
                "msisdn":"234706xxxxxxx"
              },

   "products":[
                {
                   "id":"D-MFIN-5-50MB",
                   "topup_currency":"NGN",
                   "topup_amount":100,
                   "price":100,
                   "data_amount":"50",
                   "validity":"1 day"
                },
                {
                   "id":"D-MFIN-5-150MB",
                   "topup_currency":"NGN",
                   "topup_amount":200,
                   "price":200,
                   "data_amount":"150",
                   "validity":"7 days"
                },
                {
                   "id":"D-MFIN-5-750MB",
                   "topup_currency":"NGN",
                   "topup_amount":500,
                   "price":500,
                   "data_amount":"750",
                   "validity":"30 days"
                }
              ]
}
ID: This is the product ID
Topup Currency: The currency used by the phone network
Topup Amount: The cost of the data amount by the phone network
Price: How much we charge your account in Naira.
Data Amount: Data value recieved to line in MB.
i.e. 2500 equals 2.5GB and 200 equals 200MB

Step 2. MAKE DATA PURCHASE

Url: https://estoresms.com/data_processing/v/2
Method: POST
Request Format: JSON
Response Format: JSON

Note: Product ID must be gotten from step 1 for every purchase


SAMPLE REQUEST 
{
   "username":"user123",
   "ref":"myRef",
   "hash":"6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe",
   "callback":"https://mywebsite/callback",
   "request":[
                  {
                    "product":"D-MFIN-5-50MB",
                    "phone":"+234706xxxxxxx"
                  }
            ]
}


SAMPLE RESPONSE 1
{
   "failed":0,
   "result":[
              {
                "response":"OK",
                "ref":"myRef",
                "transaction_id":"api_5ab5261c9b005",
                "phone":"+234706xxxxxxx",
                "data_amount":"50",
                "amount":"100",
                "amount_charged":"96"
              }
           ]
}


SAMPLE RESPONSE 2
{
   "failed":0,
   "result":[
              {
                "response":"PENDING",
                "ref":"myRef",
                "transaction_id":"api_5ab5261c9b005",
                "phone":"+234706xxxxxxx",
                "data_amount":"50",
                "amount":"100",
                "amount_charged":"96"
              }
           ]
}
PENDING response means you will need to Query the transaction
later on for final status


SAMPLE RESPONSE 3
{
    "response":"P013",
    "message":"Insufficient Balance"
}


SAMPLE RESPONSE 4
{
   "failed":1,
   "result":[
                {
                  "response":"P006",
                  "message":"Product ID is required",
                  "phone":"+234706xxxxxxx"
                }
            ]
}

QUERY TRANSACTION

Url: https://estoresms.com/api_query
Method: POST
Request Format: JSON
Response Format: JSON

SAMPLE REQUEST 1 
{
   "username":"user123",
   "hash":"6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe",
   "transaction_id":"api_5ab5261c9b005"
}
SAMPLE REQUEST 2 
{
   "username":"user123",
   "hash":"6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe",
   "ref":"myRef"
}

Transaction ID: This is the ID we generate by our system after each request has been processed
Ref: The Transaction Reference you generated while making airtime or data purchase
SAMPLE RESPONSE 1
{
   "response":"FAIL",
   "message":"No record found"
}


SAMPLE RESPONSE 2
[
    {
            "transaction_id":"api_5ab5261b9b029",
            "ref":"myRef",
            "category":"airtime",
            "network":"Everything Everywhere EE",
            "phone":"+1410xxxxxxx",
            "status":"Approved",
            "date":"2018-03-23 16:32:47",
            "topup_currency":"GBP",
            "topup_amount":"5",
            "price":"8389.26",
            "amount_charged":"8053.69"
    },
    {
            "transaction_id":"api_5ab2cf5a69f63",
            "ref":"myRef",
            "category":"data",
            "network":"MTN",
            "phone":"+234706*******",
            "status":"Approved",
            "date":"2018-01-23 10:56:50",
            "topup_currency":"NGN",
            "topup_amount":"100",
            "data_amount":"50",
            "price":"100",
            "amount_charged":"96"
    }
]
Status can be Approved, Pending, Failed, Awaiting Confirmation, Cancelled or Reversed


If callback is sent with request, a POST request would be sent once the status of the transaction changes to the following above. Sample details of POST request: 

    [transaction_id] => api_5d1df2a313d00
    [reference] => myRef
    [status] => Approved