Quick Start

Last updated: July 18th, 2018

Billing API

This is the BILLING API

  • Quick summary
  • Version 2.1.5

What is this API for?

This is the documentation for the billing API. This API allows you to make utility and airtime payments.

How do I get set up?

  • Ensure that you have a merchant account with iPay africa.
  • Ensure your account has been set up to allow transactions
  • Ensure that you have a security key
  • Ensure that you have been provided with a base URL
  • Ensure that your merchant bulkpay account has been funded with funds

Contribution guidelines

We really appreciate feedback and suggestions. Issues, and suggestions can be emailed to [email protected]

Who do I talk to?

iPay technical for technical support

URI and Versioning

We hope to improve the API over time. The changes won’t always be backward compatible, so we’re going to use versioning. There is currently no rate limit.

For versioning purposes, only removal of a non-optional field or alteration of an existing field will be considered incompatible changes. You should gracefully handle additional fields you do not expect.

Endpoints

The base URL depends on the server this sits on so it varies this will be provided to you

Getting Started

Funding Your Billing Account directly from customers through the iPay gateway in realtime

One can fund their billing account by transferring funds directly from their account income ( transactions done using iPay ) to their billing funds. To have access to the iPay C2B intergration click here. Ensure that on successful callback, this end point is called. POST https://apis.ipayafrica.com/payments/v2/billing/fund

The reason for this is to ensure that the funds paid in are immediately made available for bill processing

Below are the parameters to be posted to the end point

Field Description
vid
This is the vendor ID of the merchant, ie merchant who will be using this bulkpay system
time
This is the timestamp of the time this request is posted
currency
This is the currency from which one should move the funds from, currently KES only supported.
hash
This is a hash of the posted data, just to verify that this is from the vendor.
Example of a successful response

                                            {
                                              "header_status": 200,
                                              "msg": {
                                                "status": 1,
                                                "text": "amount moved",
                                                "amount": 10000,
                                                "reference": "BILLINGXX95X55",
                                                "posted_time": "2017-01-05 14:38:01"
                                              }
                                            }
                                        

Note

This end point sits on a different base URL

Funding Your Billing Account from other sources

  • If you are an existing iPay merchant, you can use the backoffice/dashboard to move funds from your inbox to your bulkpay account, however, the funds moved will be less the iPay commission for C2B transactions.
  • One can use EFT or RTGS to pay into the iPay bank account. Once the funds reflect, we will update your bulkpay account immediately.
Billers

This end point is used to check to provide a list of operators that one can make payments to.

GET /billing/list

send the variable
Field Description
vid
This is the vendor ID of the person, ie merchant who will be using this billing system

Example of a successful response

                                            {
                                                  "header_status": 200,
                                                  "data": [
                                                      {
                                                          "biller_name": "Safaricom",
                                                          "biller_code": "safaricom",
                                                          "biller_category": "airtime",
                                                          "minimum_balance": "10.00",
                                                          "secondary_account": "false"
                                                      },
                                                      {
                                                          "biller_name": "Airtel",
                                                          "biller_code": "airtel",
                                                          "biller_category": "airtime",
                                                          "minimum_balance": "10.00",
                                                          "secondary_account": "false"
                                                      },
                                                      {
                                                          "biller_name": "Nairobi Water",
                                                          "biller_code": "nairobi_water",
                                                          "biller_category": "water",
                                                          "minimum_balance": "200.00",
                                                          "secondary_account": "false"
                                                      },
                                                      {
                                                          "biller_name": "GoTv",
                                                          "biller_code": "gotv",
                                                          "biller_category": "tv",
                                                          "minimum_balance": "500.00",
                                                          "secondary_account": "true"
                                                      }
                                                  ]
                                              }
                                            

Note

This end point does not require a hash


Response values
Variable Name Description
header_status This is the header response for the billing request.
data JSON array of the data
biller_name Full names of the operator
biller_code The biller code used in the iPay system. This value should be used to send data in the Create end point
biller_category The category under which the biller falls under
minimum_balance The minimum amount which one can transact with the operator
secondary_account This is mostly the phone number, some operators require additional data inorder to process a transaction ie Kenya Power requires one to post the phone number in addition to the account number

Biller Info

This end point is used to get the status of a biller.


                                               GET /billing/biller/status
                                        
send the variable
Field Description
vid
This is the vendor ID of the person, ie merchant who will be using this billing system
biller_name
This is the name of the biller_code as received from the billing list.
Example of a successful response

                                        {
                                                "header_status": 200,
                                                "data": {
                                                        "biller_name": "GoTv",
                                                        "biller_code": "gotv",
                                                        "biller_category": "tv",
                                                        "minimum_balance": "500.00",
                                                        "secondary_account": "true",
                                                        "status": "OFFLINE"
                                                }
                                        }
                                        

Note

This end point does not require a hash. We strongly recommend that you query first before using the create end point. as this will give you the status of the biller before hand.

Response values
Variable Name Description
header_status This is the header response for the billing request.
data JSON object of the data
biller_name Full names of the operator
biller_code The biller code used in the iPay system. This value should be used to send data in the Create end point
biller_category The category under which the biller falls under
minimum_balance The minimum amount which one can transact with the operator
secondary_account This is mostly the phone number, some operators require additional data inorder to process a transaction ie Kenya Power requires one to post the phone number in addition to the account number
status This status indicates whether the biller is under maintenance or are experiencing a downtime on the operator end. The value is either OFFLINE or ONLINE boolean value. ONLINE indicating that the biller is active.

Create

POST   POST /transaction/create

POST the variables
Field Description
vid
This is the vendor ID of the person, ie merchant who will be using this billing system
biller_name
This is the name of the biller one is transacting with for example safaricom, airtel.
amount
This is the transaction amount.
account
This is the user’s account within the selected biller’s system that will be credited with the amount value. It is provided by the biller to the user.
phone
Some accounts for example Kenya Power,GOTV, Nairobi Water require a phone number in order to process.
merchant_reference
This is the unique reference from your system. at the moment it is not required but we plan to enforce it
hash
This is a hash of the posted data, just to verify that this is from the vendor.
Example of a successful response

                                            {
                                              "header_status": 200,
                                              "msg": {
                                                "status": 1,
                                                "text": "Transaction has been queued and is pending",
                                                "ipay_reference": "SAFDEXXXXXX00000194149555",
                                                "posted_time": "2017-01-05 14:38:01"
                                              }
                                            }
                                            

Note

This does not mean that a transaction is pending but it means it has been queued for processing. however it means it has it has succesfully hit our end.

  • we have added merchant_reference parameter to the list of params to be posted

Variable Name Description
header_status This is the header response for the billing request.
status This is a secondary status response to validate a success. the value is boolean ie 1 or 0. 1 indicating a success.
text Contains a descriptive response string.
ipay_reference This is a unique id our API generates for a successful request.
posted_time The date time the transaction was saved on the API in the format YYYY-MM-DD HH:MM:SS

Check status

Once a request has been made, it is important to check the status after wards as sometimes the payment may fail depending on different factors This allows you to see the transaction status.

POST /transaction/check/status
Field Description
vid
This is the vendor ID of the person, ie merchant who will be using this billing system
reference
This is the reference recieved when the billing request was done, it is used to requery.
hash
This is a hash of the posted data, just to verify that this is from the vendor.
Example of response

                                            {
                                              "header_status": 200,
                                              "msg": {
                                                "status": 1,
                                                "text": "Transaction has been queued and is pending",
                                                "ipay_reference": "SAFDEXXXXXX00000194149555",
                                                "posted_time": "2017-01-05 14:38:01"
                                              }
                                            }
                                        

Response values
Variable Name Description
header_status This is the header response for the billing request.
status This is a secondary status response to validate a success. the value is boolean ie 1 or 0. 1 indicating a success.
text This contains the payload json data of the transaction.
ipay_reference This is a unique id our API generates for a successful request.
biller_response_time This is the operator response time, ie the time the transaction hit the operator end. the format YYYY-MM-DD HH:MM:SS
biller_reference This field will have a unique value when a transaction has been successful
transaction_status This shows the transaction status from the operator end.
transaction_message This shows the transaction text from the operator end.
account This is the user’s account within the selected biller’s system that will be credited with the amount value. It is provided by the biller to the user.
amount This is the transaction amount.
biller_name This is the operator name used to process the request

Validate account

This request is used to validate selected accounts before using the create end point. At the moment This end point is only limited to kenya power


                                            POST /billing/validate/account
                                        
Field Description
vid
This is the vendor ID of the person, ie merchant who will be using this billing system
account
This is the account number in question
account_type
This is the biller name of the account number being queried eg kplc_postpaid or kplc_prepaid
hash
This is a hash of the posted data, just to verify that this is from the vendor.

Example of response

                                            {
                                                "header_status": 200,
                                                "status": 1,
                                                "text": "SUCCESS",
                                                "account_data": {
                                                    "account": "44XXXX718-01",
                                                    "name": "JOHN DOE 44XXXX718-01",
                                                    "amountdue": "237.62"
                                                }
                                            }
                                        

Response values
Variable Name Description
header_status This is the header response for the billing request.
prefix This is the prefix that was queried.
account The account number being queried.
name The account name. some times this data may not be available
text Shows the response of the account IF NOT SUCCESS should be considered not a valid account
status This is a secondary status response to validate a success. the value is boolean ie 1 or 0. 1 indicating a success.
amountdue The amount due. some times this data may not be available

Number Look up

This request is used to get the mobile operator based on the prefix. This will be useful when making an airtime purchase.


                                            POST /billing/phone/lookup
                                        
Field Description
vid
This is the vendor ID of the person, ie merchant who will be using this billing system
prefix
This is the mobile prefix. please note that it should be 3 characters for example 724
hash
This is a hash of the posted data, just to verify that this is from the vendor.

Example of response

                                            {
                                                "header_status": 200,
                                                "data": {
                                                    "prefix": "732",
                                                    "operator": "airtel"
                                                }
                                            }
                                        

Response values
Variable Name Description
header_status This is the header response for the billing request.
prefix This is the prefix that was queried.
operator This is the value of the operator that uses that prefix.

Account Balance

This request is used to check the available account balance (float).


                                            GET /billing/account/balance
                                        
Field Description
vid
This is the vendor ID of the person, ie merchant who will be using this billing system
hash
This is a hash of the posted data, just to verify that this is from the vendor.

Example of response

                                            {
                                                "header_status": 200,
                                                "balance": 1930984.00
                                            }
                                        

Response values
Variable Name Description
header_status This is the header response for the billing request.
balance Available funds at the moment.

How to generate the hash

The hash is a data string of the parameter name and the values in an ASCII order from small to large sort. If the value is null, then the signature may not be involved. The HMAC hashing algorithm currently being used is SHA256.

An example is shown below:


                                            <?php
                                                    $datastring = "key1=".$value1."&key2=".$value2
                                                    //(the key / parameter names above should be in alphabetical order. Your data string should **NOT** be urlencoded)
                                                    //*************************************************************************************************/
                                                    $hashkey = "yoursecuritykey"; //Provided by and supplied by iPay during account registration;
                                                    $datastring; //This is a string generated from the data to be posted (see above)
                                                    $hashid = hash_hmac("sha256", $datastring, $hashkey);