Introduction to Electronic Billing API

Welcome to the our Agency API! You can use our API to access our Electronic Billing API endpoints, which you can use to get information on your profile,create your secret key and other things in and out of our database.

Agent needs to create a secret key first before any request can be accepted through this API

We have language bindings in Shell, Python, and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Secret Key

To create your secret key :

import requests

url = 'baseurl/set-secretkey/'
values={"secretkey":"alphanumeric"}
headers = {"content-type" : "application/json",'Authorization':api-key}
req = requests.post(url,data=json.dumps(values),headers=headers)

PAYLOAD={"secretkey":"alphanumeric"}
curl "baseurl/set-secretkey/" \
  request POST -H "Authorization: api-key"
  --data "${PAYLOAD}

fetch('baseurl/set-secretkey/', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
        'Authorization':api-key
    },
    body: JSON.stringify({"secretkey":"alphanumeric"})
})
   .then(response => response.json())
   .then(response => console.log(JSON.stringify(response)))

The above command returns JSON structured like this:

  {
    "status": 200,
    "message": "Operation Successful"
  },

This endpoint allows agent to generate his/her secret key that will be padded to his/her api-key for authourization.

HTTP Request

POST baseurl

Query Parameters

Parameter	Description	Required
secretkey	Agent Secret Code	Yes.

Authentication

To authorize, use this code:


import requests

url = 'baseurl/myprofile/'
headers = {"content-type" : "application/json",'Authorization':api-key}
req = requests.get(url,headers=headers)

# With shell, you can just pass the correct header with each request
curl "baseurl/myprofile/" \
  -H "Authorization: api-key"

fetch('baseurl/myprofile/', {
   headers: {
      'Accept': 'application/json',
      'Authorization':api-key
   }
})
   .then(response => response.text())
   .then(text => console.log(text))

Make sure to replace api-key with your API key.

The above command returns JSON structured like this:

{
"name": "DARSEF LIMITED",
 "address":"58,Oguntolu Street",
 "phone":"07032916005",
 "urlcallback": "https://api.mydomain.com", 
 "email": "whale@mydomain.com", 
 "datecreated": "13-11-2024",
 "status":"ACTIVE"
}

You get your API key through your mail at setup.

We expect the API key to be included in all API requests to the server in a header that looks like the following:

baseurl:'baseurl'

Authorization: Bearer 'your api key + secret key'

You must replace your api key with your personal API key. E.g 'Bearer A1234a-83972-09938-738382+secretkey'.

API Requests and Responses

Get Marchant List

import requests

url = 'baseurl/my-marchants/'
headers = {"content-type" : "application/json",'Authorization':api-key}
req = requests.get(url,headers=headers)

curl "baseurl/my-marchants/" \
  request GET -H "Authorization: api-key"

fetch('baseurl/my-marchants/', {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
        'Authorization':api-key
    },
})
   .then(response => response.json())
   .then(response => console.log(JSON.stringify(response)))

The above command returns JSON structured like this:

   [{"name": "EREDO LCDA", "code": "03"},{"name": "YABA LCDA", "code": "04"}]

This endpoint allows agent to get the list of our marchants i.e Local Governments or LCDAs.

HTTP Request

GET baseurl

Get Rate Payer Bill Details

import requests

url = 'baseurl/get-payer-bill/'
values={'billno':'240000089','code':'03'}
headers = {"content-type" : "application/json",'Authorization':api-key}
req = requests.post(url,data=json.dumps(values),headers=headers)

PAYLOAD={'billno':'240000089','code':'03'}
curl "baseurl/get-payer-bill/" \
  request POST -H "Authorization: api-key"
  --data "${PAYLOAD}

fetch('baseurl/get-payer-bill/', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
        'Authorization':api-key
    },
    body: JSON.stringify({'billno':'240000089','code':'03'})
})
   .then(response => response.json())
   .then(response => console.log(JSON.stringify(response)))

The above command returns JSON structured like this:

  {
    "errorcode": "000", "message": "Good", 
    "bill": {"name":"NIBFIX MOTORS", "address":"0,ATLANTIC HALL ROAD, POKA", "totalbill":"10000.00","year":"2024","billno":"240000089","desc":"RTV(10000)"},
    "billno":"240000089",
    "code": "03"
  }

This endpoint allows agent to get details of a bill using the bill no and marchant code from our server.

HTTP Request

POST baseurl

Query Parameters

Parameter	Description	Required
billno	Unique bill no	Yes
code	Marchant Code	Yes

Return Payment Details

import requests

url = 'baseurl/return-payment-details/'
values={'billno':'240000089','date':'2024-11-14','amount':'20,000.98','bankref':'referenceid','code':'03'}
headers = {"content-type" : "application/json",'Authorization':api-key}
req = requests.post(url,data=json.dumps(values),headers=headers)

PAYLOAD={'billno':'240000089','date':'2024-11-14','amount':'20,000.98','bankref':'referenceid','code':'03'}
curl "baseurl/return-payment-details/" \
  request POST -H "Authorization: api-key"
  --data "${PAYLOAD}

fetch('baseurl/return-payment-details/', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
        'Authorization':api-key
    },
    body: JSON.stringify({'billno':'240000089','date':'2024-11-14','amount':'20,000.98','bankref':'referenceid','code':'03'})
})
   .then(response => response.json())
   .then(response => console.log(JSON.stringify(response)))

The above command returns JSON structured like this:

  {
    "message":"Successful"
  }

This endpoint allows agent to return payment made on rate payer bill for us to verify and process for intrnal use.

HTTP Request

POST baseurl

Query Parameters

Parameter	Description	Required
billno	Unique bill no	Yes
date	Transaction date	Yes
amount	Amount Paid on the bill	Yes
bankref	Bank Reference Code for verification	Yes
code	Marchant Code	Yes

Errors

Our Agency API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The requested is hidden for administrators only.
404	Not Found -- The specified Page could not be found.
405	Method Not Allowed -- You tried to access with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- You're requesting too many! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.