Kaduna Electric API Integration
This section contains the recommended flow for integrating Kaduna Electricity Bills Payment services on the VTpass RESTful API.
This API allows payment to both prepaid and postpaid KAEDCO meters.
The VTpass KAEDCO payment API allows you to vend token for KAEDCO Prepaid meters and also pay electricity bills for KAEDCO Postpaid meters using the meter number / Account ID.
For Prepaid meters, a token is generated. This token will be loaded on the customer’s meter by the customer.
Please display token to customer after a successful transaction, also send token by email and SMS to customer.
Kaduna Electric covers the following states: Kaduna, Kebbi, Sokoto and Zamfara.
Authentication
Learn about authentication from here.
Available Endpoints
To integrate the VTpass Kaduna Electricity (KAEDCO) Bills Payment RESTful API, the endpoints below applies:
- Verify Meter Number
- Purchase Product (prepaid and postpaid payments available)
- Query transaction status
Always ensure you validate the customer’s meter number.
ServiceID: kaduna-electric
VERIFY METER NUMBER
Using a POST method, you can verify a meter number with the following endpoint:
Live: https://vtpass.com/api/merchant-verify
Sandbox: https://sandbox.vtpass.com/api/merchant-verify
On Sandbox, please use the following meter numbers (sandbox) to test:
For prepaid: 1111111111111
For Postpaid: 1010101010101
To simulate a failed meter number validation, please use any number apart from the one provided above as meter number.
| FIELDS | M/O | TYPE | DESCRIPTION |
| billersCode | M | Number | The meter number you wish to make the bills payment on.
On Sandbox For Postpaid: 1010101010101 |
| serviceID | M | String | Service ID as specified by VTpass. In this case, it is kaduna-electric |
| type | M | String | This is basically the type of meter you are trying to validate. It can be either prepaid or postpaid |
EXPECTED RESPONSE
{
"code":"000",
"content":{
"Customer_Name":"SUNDAY AGAGARAGA",
"Account_Number":"0101100000133",
"Meter_Number":"0101100000133",
"Business_Unit":"OJO",
"Address":"",
"Customer_Arrears":""
}
}
PURCHASE PRODUCT (Payment)
You can make a purchase for either a prepaid or postpaid meter.
Prepaid Meter Payment
Using a POST method, prepaid Token can be vended for Kaduna Electric prepaid meters with the endpoint below:
Live: https://vtpass.com/api/pay
Sandbox: https://sandbox.vtpass.com/api/pay
ServiceID: kaduna-electric
On Sandbox, please use the following prepaid meter number to test:
For prepaid: 1111111111111
To simulate a failed prepaid meter purchase, please use any number apart from the one provided above as meter number.
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| request_id | M | String | This is a unique reference with which you can use to identify and query the status of a given transaction after the transaction has been executed.
Click here to understand how to generate a valid request ID
|
| serviceID | M | String | Service ID as specified by VTpass. In this case, it is kaduna-electric |
| billersCode | M | String | The meter number you wish to make the bills payment on |
| variation_code | M | String | This is the meter type. In this case prepaid |
| amount | M | Number | The amount (Naira) of electricity you want to purchase. |
| phone | M | Number | The phone number of the customer or recipient of this service |
EXPECTED RESPONSE
{
"code":"000",
"content":{
"transactions":{
"amount":1000,
"convinience_fee":0,
"status":"delivered",
"name":null,
"phone":"07061933309",
"email":"sandbox@vtpass.com",
"type":"Electricity Bill",
"created_at":"2019-08-17 02:27:26",
"discount":null,
"giftcard_id":null,
"total_amount":992,
"commission":8,
"channel":"api",
"platform":"api",
"service_verification":null,
"quantity":1,
"unit_price":1000,
"unique_element":"1010101010101",
"product_name":"Kaduna Electric Payment - KAEDCO"
}
},
"response_description":"TRANSACTION SUCCESSFUL",
"requestId":"hg3hgh3gdiud4w2wb33",
"amount":"1000.00",
"transaction_date":{
"date":"2019-08-17 02:27:27.000000",
"timezone_type":3,
"timezone":"Africa/Lagos"
},
"purchased_code":"Token : 42167939781206619049 Bonus Token : 62881559799402440206",
"mainToken":"42167939781206619049",
"mainTokenDescription":"Normal Sale",
"mainTokenUnits":16666.666,
"mainTokenTax":442.11,
"mainsTokenAmount":3157.89,
"bonusToken":"62881559799402440206",
"bonusTokenDescription":"FBE Token",
"bonusTokenUnits":50,
"bonusTokenTax":null,
"bonusTokenAmount":null,
"tariffIndex":"52",
"debtDescription":"1122"
}
Postpaid Meter Payment
Using a POST method, electricity bills can be paid for Kaduna Electric postpaid meters with the endpoint below:
Live: https://vtpass.com/api/pay
Sandbox: https://sandbox.vtpass.com/api/pay
ServiceID: kaduna-electric
On Sandbox, please use the following meter number to test:
For postpaid: 1010101010101
To simulate a failed postpaid meter payment, please use any number apart from the one provided above as meter number.
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| request_id | M | String | This is the reference with which you can use to query the status of a given transaction after the transaction has been executed. |
| serviceID | M | String | Service ID as specified by VTpass. In this case, it is kaduna-electric |
| billersCode | M | String | The meter number you wish to make the bills payment on |
| variation_code | M | String | This is the meter type. In this case postpaid
|
| amount | M | Number | The amount (Naira) of electricity you want to purchase |
| phone | M | Number | The phone number of the customer or recipient of this service |
EXPECTED RESPONSE
{
"code":"000",
"content":{
"transactions":{
"amount":1000,
"convinience_fee":0,
"status":"pending",
"name":null,
"phone":"07061933309",
"email":"sandbox@vtpass.com",
"type":"Electricity Bill",
"created_at":"2019-08-17 02:29:16",
"discount":null,
"giftcard_id":null,
"total_amount":992,
"commission":8,
"channel":"api",
"platform":"api",
"service_verification":null,
"quantity":1,
"unit_price":1000,
"unique_element":"1010101010101",
"product_name":"Kaduna Electric Payment - KAEDCO"
}
},
"response_description":"TRANSACTION SUCCESSFUL",
"requestId":"hg3hgh3gdiud4w2wb33e",
"amount":"1000.00",
"transaction_date":{
"date":"2019-08-17 02:29:17.000000",
"timezone_type":3,
"timezone":"Africa/Lagos"
},
"purchased_code":""
}
QUERY TRANSACTION STATUS
Using a POST method, transaction status can be queried with the endpoint below:
LIVE: https://vtpass.com/api/requery
Sandbox: https://sandbox.vtpass.com/api/requery
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| request_id | M | String | This is the reference with which you sent when purchasing a transaction after the transaction has been executed. |
EXPECTED RESPONSE
For Successful Prepaid Meter Payment
{
"code": "000",
"content": {
"transactions": {
"status": "delivered",
"product_name": "KAEDCO - Kaduna Electric",
"unique_element": "1111111111111",
"unit_price": 1000,
"quantity": 1,
"service_verification": null,
"channel": "api",
"commission": 10,
"total_amount": 990,
"discount": null,
"type": "Electricity Bill",
"email": "sandbox@vtpass.com",
"phone": "07061933309",
"name": null,
"convinience_fee": 0,
"amount": 1000,
"platform": "api",
"method": "api",
"transactionId": "1586356641579"
}
},
"response_description": "TRANSACTION SUCCESSFUL",
"requestId": "3476isjjjjssajahhhaasa768whjjdhsjjehdddsh",
"amount": "1000.00",
"transaction_date": {
"date": "2020-04-08 15:37:21.000000",
"timezone_type": 3,
"timezone": "Africa/Lagos"
},
"purchased_code": "Token : 40364652026905256691",
"token": "40364652026905256691",
"exchangeReference": "4780534156977207",
"resetToken": null,
"units": "500 kWh",
"fixChargeAmount": null,
"tariff": "StubTariff",
"taxAmount": null
}
For Successful Postpaid Meter Payment
{
"code": "000",
"content": {
"transactions": {
"status": "delivered",
"product_name": "KAEDCO - Kaduna Electric",
"unique_element": "1010101010101",
"unit_price": 1000,
"quantity": 1,
"service_verification": null,
"channel": "api",
"commission": 10,
"total_amount": 990,
"discount": null,
"type": "Electricity Bill",
"email": "sandbox@vtpass.com",
"phone": "07061933309",
"name": null,
"convinience_fee": 0,
"amount": 1000,
"platform": "api",
"method": "api",
"transactionId": "1586356641579"
}
},
"response_description": "TRANSACTION SUCCESSFUL",
"requestId": "3476isjjjjssajahhhaasa768whjjdhsjjehdddsh",
"amount": "1000.00",
"transaction_date": {
"date": "2020-04-08 15:37:21.000000",
"timezone_type": 3,
"timezone": "Africa/Lagos"
},
"purchased_code": "Token : 40364652026905256691",
"token": "40364652026905256691",
"exchangeReference": "4780534156977207",
"resetToken": null,
"units": "500 kWh",
"fixChargeAmount": null,
"tariff": "StubTariff",
"taxAmount": null
}
You can check out the complete list of RESPONSE CODES HERE.