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 be created and username and password will be provided by the biller team.

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.

Authentication

You are expected to make a POST request to the server with your username and password.

To authorize, use this code:


import requests

url = 'baseurl/agent-login/'
values={'username':'myuser','password':'mypass03'}
headers = {"content-type" : "application/json",'Authorization':api-key}
req = requests.post(url,headers=headers)

# With shell, you can just pass the correct header with each request
PAYLOAD={'username':'myuser','password':'mypass03'}
curl "baseurl/agent-login/" \
  -H "Authorization: api-key"
   --data "${PAYLOAD}

fetch('baseurl/agent-login/', {
   headers: {
      'Accept': 'application/json',
      'Authorization':api-key
   }
})
body: JSON.stringify({'username':'myuser','password':'mypass03'})
   .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:

{
"status": "success", 
"apikey": "46656sieg896832q23921714hdk4195965525573", 
"msg": "OK"
}

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 '

API Requests and Responses

VERIFY Rate Payer Bill Details

import requests

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

PAYLOAD={'billno':'260000434'}
curl "baseurl/pos-payer-bill/" \
  request POST -H "Authorization: api-key"
  --data "${PAYLOAD}

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

The above command returns JSON structured like this:

{"status": "success", 
"message": "Good",
 "bill": {"name": "GOD OF MERCY", "address": "0,PALACE ROAD POKA", "totalbill": "3500.00", "year": "2026", "billno": "260000434", "desc": "R.T.V(500),SHOP PERMIT(3000),"},
  "billno": "260000434"
}

This endpoint allows agent to get details of a bill using the bill number from our server.

HTTP Request

POST baseurl

Query Parameters

Parameter	Description	Required
billno	Unique bill no	Yes

FETCH LG/LCDA REVENUE LISTS

import requests

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

curl "baseurl/pos-revenue-list/" \
  request GET -H "Authorization: api-key"

fetch('baseurl/pos-revenue-list/', {
    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:

    {"status": "success", 
"message": "Good", 
"bill": {"errorcode": "000",
      "message": "Successful", 
      "data": [{"name": "FOOD REGULATED/PROCESSING(15000)", "amount": "15000.00", "category": "FOOD REGULATED/PROCESSING", "id": "208"}, {"name": "\tLIQUIOR LICENCE FEE\tLIQUIOR LICENCE FEE(40000)", "amount": "40000.00", "category": "LIQUIOR LICENCE FEE", "id": "205"}, {"name": "AERATED WATER REGISTRATION LICENSE(10000)", "amount": "10000.00", "category": "AERATED WATER REGISTRATION LICENSE", "id": "142"}, {"name": "AERATED WATER REGISTRATION LICENSE(15000)", "amount": "15000.00", "category": "AERATED WATER REGISTRATION LICENSE", "id": "130"}, {"name": "AERATED WATER REGISTRATION LICENSE(20000)", "amount": "20000.00", "category": "AERATED WATER REGISTRATION LICENSE", "id": "211"}, {"name": "AERATED WATER REGISTRATION LICENSE(5000)", "amount": "5000.00", "category": "AERATED WATER REGISTRATION LICENSE", "id": "148"}, {"name": "AERATED WATER(5000)", "amount": "5000.00", "category": "AERATED WATER REGISTRATION LICENSE", "id": "160"}, {"name": "ANIMAL FEEDS(5000)", "amount": "5000.00", "category": "FOOD REGULATED/PROCESSING", "id": "165"}]
}
}

This endpoint allows agent to get lists of LG/LCDA revenue from our server.

HTTP Request

GET baseurl

CREATE NEW RATE PAYER

import requests

url = 'baseurl/pos-new-ratepayer/'
values={'name':'HYDRO VENTURES','address':"No 20, Mojoda Road, Ibonwon, Eredo, Epe, Lagos State","bills":["2","23"]}
headers = {"content-type" : "application/json",'Authorization':api-key}
req = requests.post(url,data=json.dumps(values),headers=headers)

PAYLOAD={'name':'HYDRO VENTURES','address':"No 20, Mojoda Road, Ibonwon, Eredo, Epe, Lagos State","bills":["2","23"]}
curl "baseurl/pos-new-ratepayer/" \
  request POST -H "Authorization: api-key"
  --data "${PAYLOAD}

fetch('baseurl/pos-new-ratepayer/', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
        'Authorization':api-key
    },
    body: JSON.stringify({'name':'HYDRO VENTURES','address':"No 20, Mojoda Road, Ibonwon, Eredo, Epe, Lagos State","bills":["2","23"]})
})
   .then(response => response.json())
   .then(response => console.log(JSON.stringify(response)))

The above command returns JSON structured like this:

  {"errorcode": "000", 
 "message": "Successful",
  "data": {"name": "Hydro Ventures", "address": "No 20, Mojoda Road, Ibonwon, Eredo, Epe, Lagos State", "rrr": "82983839494904", 
          "billno": "U202300000013", "totalbill": "650000.00"
          }
}

This endpoint allows agent to CREATE a new rate payer.

HTTP Request

POST baseurl

Query Parameters

Parameter	Description	Required
name	Rate Payer Name	Yes
address	Rate Payer Address	Yes
bills	List of bill ids	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.