Bill Payment Api

Version 1

For TV, Internet, Electricity, WAEC Pin payment

This API allows you to pay your bills from your wallet account.

You are required to enable 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.
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 (recommended). Note: if you use a reference, ensure you also pass "ref" as a post parameter for every request
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
PENDING => Transaction not processed
B001 => Authentication Failed
B002 => Operation not allowed on account
B003 => API not enabled for this account
B004 => Invalid request
B005 => Product has no plan in this category
B006 => Validation failed
B007 => Insufficient Balance
B008 => Invalid Amount
B009 => Operation Failed

Step 1. GET PRODUCT LIST

Url: https://estoresms.com/bill_payment_processing/v/2/
Method: POST
Request Format: FORM-DATA
Response Format: JSON

Available category include tv, internet, electricity, waec

SAMPLE REQUEST 1 

   username: user123,
   hash: 6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe,
   category: tv

SAMPLE RESPONSE 
{
    "response": "OK",
    "result": [
        {
            "product_id": "BPD-NGCA-AQA",
            "name": "DSTV",
            "hasProductList": true,
            "hasValidation": false,
            "openRange": false
        },
        {
            "product_id": "BPD-NGCA-AQC",
            "name": "GOTV",
            "hasProductList": true,
            "hasValidation": false,
            "openRange": false
        },
        {
            "product_id": "BPD-NGCA-AWA",
            "name": "StarTimes",
            "hasProductList": false,
            "hasValidation": true,
            "openRange": true,
            "min_denomination": 1000,
            "max_denomination": 50000,
            "step": 1
        }
    ]
}
openRange: Indicates the available product list has no fixed amount and price, hence you can supply any amount within the minimum and maximum limit, step is the allowed interval
product_id: This is the product ID
hasProductList: The product has a fixed list of plan with amount, that can be fetched in step 2
hasValidation: You can validate the identity of the customer making payment, that can be done in step 3
Hint: If product does not have validation and product list, you can proceed to the final step (step 4)

Step 2. GET PRODUCT PLANS

Url: https://estoresms.com/bill_payment_processing/v/2/
Method: POST
Request Format: FORM-DATA
Response Format: JSON

Note: Product ID must be gotten from step 1

For DSTV and GOTv, you must supply smartcard number

SAMPLE REQUEST 1 (DSTV & GOTV) 
   username: user123,
   hash: 6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe,
   category: tv,
   product:  BPD-NGCA-AQA 
   number: 4122773388
                
 
SAMPLE REQUEST 2
   username: user123,
   hash: 6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe,
   category: tv,
   product:  BPD-NGCA-AQA


SAMPLE RESPONSE 1
{
   "first_name":"A A",
   "last_name":"GEORGE",
   "status":"Active",
   "primary_product_id":"BPD-DSTV-971",
   "primary_product_name":"DStv Padi ",
   "primary_product_price":"1850.00",
   "primary_product_currency":"NGN",
   "plans":[
             {
               "plan_id":"BPD-DSTV-921",
               "name":"Premium",
               "price":"18400",
               "currency":"NGN"
             },
             
             {
               "plan_id":"BPD-DSTV-931",
               "name":"Compact Plus",
               "price":"12400",
               "currency":"NGN"
             },
             
             {
               "plan_id":"BPD-DSTV-941",
               "name":"Compact ",
               "price":"7900",
               "currency":"NGN"
             },
             
             {
               "plan_id":"BPD-DSTV-951",
               "name":"Confam",
               "price":"4615",
               "currency":"NGN"
             },
             
             {
                "plan_id":"BPD-DSTV-961",
                "name":"Yanga",
                "price":"2565",
                "currency":"NGN"
            },
            
            {
            
               "plan_id":"BPD-DSTV-971",
               "name":"Padi",
               "price":"1850",
               "currency":"NGN"
            }
       ]
}    

SAMPLE RESPONSE 2
{
    "response": "B005",
    "message": "Product has no plan in this category"
}

Note:
Subscription Status can be Active or Suspended
Primary product is the last subscription done on the account

Step 3. Customer Validation

Url: https://estoresms.com/bill_payment_processing/v/2/
Method: POST
Request Format: FORM-DATA
Response Format: JSON

SAMPLE REQUEST 
username: user123,
hash: 6a7ba624db21e84c6cb58e9e7f0055c8316bc2c2e3ac1d35e8c3fe,
category: tv,
product:  BPD-NGCA-AQA,
validate: 41320018196

SAMPLE RESPONSE 
{
    "response": "OK",
    "result": {
        "name": "ARON A VICTOR",
        "number": "41320018196"
    }
}

In this case the customer is attempting to purchase a dstv plan, validate field holds the SmartCard Number

Step 4. MAKE A PURCHASE

Url: https://estoresms.com/bill_payment_processing/v/2/
Method: POST
Request Format: FORM-DATA
Response Format: JSON

SAMPLE REQUEST 1 
username: user123,
hash: 21e84c6cb58e9e7f0055c8316bc2c2e4ac1d35e8c3fe6a7ba624db,
ref: myRef,
category: tv,
product:  BPD-NGCA-AQA,
plan: ACSSE36,
number: 41320018196

SAMPLE REQUEST 2 (Example for startimes subscription) 
username: user123,
hash: 21e84c6cb58e9e7f0055c8316bc2c2e4ac1d35e8c3fe6a7ba624db,
ref: myRef,
category: tv,
product:  BPD-NGCA-AWA,
amount: 1000,
number: 20020018196

SAMPLE REQUEST 3 (Example for electricity subscription) 
username: user123,
hash: 21e84c6cb58e9e7f0055c8316bc2c2e4ac1d35e8c3fe6a7ba624db,
ref: myRef,
category: electricity,
product:  BPE-NGCABIA-OR,
amount: 1000,
number: 0100040261,
prepaid: 1

SAMPLE REQUEST 4 (Example for waec payment) 
username: user123,
hash: 21e84c6cb58e9e7f0055c8316bc2c2e4ac1d35e8c3fe6a7ba624db,
ref: myRef,
category: waec,
product:  BPM-NGCA-ASA,
plan: 700

SAMPLE RESPONSE 1 
{
    "response": "OK",
    "transaction_id": "5a3388ac22a",
    "discounted_amount": "1980",
    "message": "Payment was successful"
}

SAMPLE RESPONSE 2 
{
    "response": "OK",
    "transaction_id": "5a3388ac22a",
    "discounted_amount": "980",
    "message": "Payment was successful",
    "pin_code": "3022399443",
    "pin_message": "Operator Message : 2.2KWh at N21.65 per KWh; Account : 0100040261; Receipt No : 4952724; Transaction ID :20171208120600~1013417"
}

SAMPLE RESPONSE 3 
{
    "response": "OK",
    "transaction_id": "5a3388ac22b",
    "discounted_amount": "700",
    "message": "Payment was successful",
    "pins":[
             {
               "serialNumber":"WRN192775404",
               "pin":"740525808961",
               "expiresOn":null
             }
           ]
}

SAMPLE RESPONSE 4 
{
    "response": "B007",
    "message": "Insufficient Balance"
}