Note
This end point sits on a different base URL
This is the BILLING API
This is the documentation for the billing API. This API allows you to make utility and airtime payments.
We really appreciate feedback and suggestions. Issues, and suggestions can be emailed to [email protected]
iPay technical for technical support
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.
The base URL depends on the server this sits on so it varies this will be provided to you
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.
|
{
"header_status": 200,
"msg": {
"status": 1,
"text": "amount moved",
"amount": 10000,
"reference": "BILLINGXX95X55",
"posted_time": "2017-01-05 14:38:01"
}
}
This end point sits on a different base URL
This end point is used to check to provide a list of operators that one can make payments to.
GET /billing/list| Field | Description |
|---|---|
| vid | This is the vendor ID of the person, ie merchant who will be using this billing system
|
{
"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"
}
]
}
This end point does not require a hash
| 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 phone number in addition to the account number |
This end point is used to get the status of a biller.
GET /billing/biller/status
| Field | Description |
|---|---|
| vid | This is the vendor ID of the person, ie merchant who will be using this billing system
|
| biller_code | This is the name of the biller_code as received from the billing list.
|
{
"header_status": 200,
"data": {
"biller_name": "GoTv",
"biller_code": "gotv",
"biller_category": "tv",
"minimum_balance": "500.00",
"secondary_account": "true",
"status": "OFFLINE"
}
}
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.
| 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 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. |
POST POST /transaction/create| Field | Description |
|---|---|
| vid | This is the vendor ID of the person, ie merchant who will be using this billing system
|
| biller_name | Use the biller code with which to transact for example safaricom.
|
| 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 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.
|
{
"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"
}
}
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.
| 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 |
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.
|
{
"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"
}
}
| 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 |
This request is used to validate selected accounts before using the create end point. At the moment This end point is only limited to Nairobi water, GOTV and DSTV.
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
|
| hash | This is a hash of the posted data, just to verify that this is from the vendor.
|
| phone | This is the telephone number associated with the account.
|
{
"header_status": 200,
"status": 1,
"text": "SUCCESS",
"account_data": {
"account": "44XXXX718-01",
"name": "JOHN DOE 44XXXX718-01",
"amountdue": "237.62"
}
}
| 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 |
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.
|
{
"header_status": 200,
"data": {
"prefix": "732",
"operator": "airtel"
}
}
| 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. |
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.
|
{
"header_status": 200,
"balance": 1930984.00
}
| Variable Name | Description |
|---|---|
| header_status | This is the header response for the billing request. |
| balance | Available funds at the moment. |
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);