Get VAS Catalog
curl --request GET \
--url https://api-local.handle.ng/api/v1/bill-payment/catalog \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-local.handle.ng/api/v1/bill-payment/catalog"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-local.handle.ng/api/v1/bill-payment/catalog', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-local.handle.ng/api/v1/bill-payment/catalog",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-local.handle.ng/api/v1/bill-payment/catalog"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-local.handle.ng/api/v1/bill-payment/catalog")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-local.handle.ng/api/v1/bill-payment/catalog")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"count": 2,
"category": "ELECTRICITY",
"items": [
{
"id": "cly239847120938471029",
"canonicalKey": "electricity:aedc:prepaid",
"category": "ELECTRICITY",
"billerCode": "AEDC",
"title": "AEDC Prepaid Electricity",
"description": "Abuja Electricity Distribution Company - Instant Token Vend",
"faceValue": 0,
"primaryProvider": "KUDA",
"fallbackCount": 1,
"metadata": {
"meterType": "prepaid",
"minAmount": 500,
"maxAmount": 500000
},
"lastSyncedAt": "2026-10-01T10:30:00.000Z"
},
{
"id": "cly239847120938471030",
"canonicalKey": "electricity:ikedc:prepaid",
"category": "ELECTRICITY",
"billerCode": "IKEDC",
"title": "IKEDC Prepaid Electricity",
"description": "Ikeja Electric - Instant Token Vend",
"faceValue": 0,
"primaryProvider": "KUDA",
"fallbackCount": 1,
"metadata": {
"meterType": "prepaid",
"minAmount": 1000,
"maxAmount": 500000
},
"lastSyncedAt": "2026-10-01T10:30:00.000Z"
}
]
}Handle VAS & Bill Payments
Get VAS Catalog
Retrieve normalized bill payment catalog items, tariffs, face values, and canonical keys with zero external latency.
GET
/
bill-payment
/
catalog
Get VAS Catalog
curl --request GET \
--url https://api-local.handle.ng/api/v1/bill-payment/catalog \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-local.handle.ng/api/v1/bill-payment/catalog"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-local.handle.ng/api/v1/bill-payment/catalog', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-local.handle.ng/api/v1/bill-payment/catalog",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-local.handle.ng/api/v1/bill-payment/catalog"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-local.handle.ng/api/v1/bill-payment/catalog")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-local.handle.ng/api/v1/bill-payment/catalog")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"count": 2,
"category": "ELECTRICITY",
"items": [
{
"id": "cly239847120938471029",
"canonicalKey": "electricity:aedc:prepaid",
"category": "ELECTRICITY",
"billerCode": "AEDC",
"title": "AEDC Prepaid Electricity",
"description": "Abuja Electricity Distribution Company - Instant Token Vend",
"faceValue": 0,
"primaryProvider": "KUDA",
"fallbackCount": 1,
"metadata": {
"meterType": "prepaid",
"minAmount": 500,
"maxAmount": 500000
},
"lastSyncedAt": "2026-10-01T10:30:00.000Z"
},
{
"id": "cly239847120938471030",
"canonicalKey": "electricity:ikedc:prepaid",
"category": "ELECTRICITY",
"billerCode": "IKEDC",
"title": "IKEDC Prepaid Electricity",
"description": "Ikeja Electric - Instant Token Vend",
"faceValue": 0,
"primaryProvider": "KUDA",
"fallbackCount": 1,
"metadata": {
"meterType": "prepaid",
"minAmount": 1000,
"maxAmount": 500000
},
"lastSyncedAt": "2026-10-01T10:30:00.000Z"
}
]
}Fetch the complete catalog of supported utilities, telcos, TV packages, travel offers, lifestyle vouchers, and institutional billers directly from Handle’s unified catalog engine.
Supported Category Types
1. Utilities & Telecommunications
AIRTIME— Top-up airtime across MTN, Airtel, Glo, 9mobile.DATA— Broadband and mobile data bundles (Daily, Weekly, Monthly, Unlimited).ELECTRICITY— All 11 Nigerian Distribution Companies (DisCos) for prepaid & postpaid meters.CABLE_TV— DSTV, GOtv, StarTimes, Showmax bouquets.INTERNET— Fixed fiber & wireless ISPs (Smile, Spectranet).SOLAR— Solar energy subscriptions and home power systems.UTILITIES— Municipal water boards and waste management utilities.
2. Education, Travel & Entertainment
EDUCATION— WAEC scratch cards, JAMB registration e-PINs, and Universities.FLIGHTS— Multi-carrier flight bookings (Air Peace, Ibom Air, etc.).BETTING— Wallet funding for Bet9ja, SportyBet, 1xBet, BangBet.GAMING— PlayStation, Xbox Live, Steam digital cards.TRANSPORT— Cowry transit card topups and interstate bus transport.ESIM— Global travel roaming eSIM data packs.
3. Institutional & Government Collections
GOVERNMENT— Federal Ministries, Departments & Agencies (MDAs), TSA revenues, CAC, FRSC.TAXES— Federal Inland Revenue Service (FIRS), State Internal Revenue Services (LIRS, KADIRS), Customs.HOSPITALS— University Teaching Hospitals (LUTH, UCH, FMC) and specialist medical centers.INSURANCE— Health HMOs and motor/life insurance policies.RELIGIOUS— Churches, Mosques, and Missions.ASSOCIATIONS— Professional bodies (NBA, ICAN, COREN, NIM).FINANCIAL_SERVICES&CREDIT_LOANS— Microfinance, credit repayments, and investment schemes.MICRO_PENSIONS&INVOICE— Pension contributions and direct invoice settlement.
4. Lifestyle & Digital Vouchers
GIFT_CARDS— Digital gift cards and retail vouchers.SHOPPING— E-commerce, supermarket, and mall shopping vouchers.FOOD_DINING— Restaurant and food delivery credits.LIFESTYLE_BEAUTY— Spa, salon, and wellness services.HOME_LIVING— Home furnishing and appliance vouchers.
Dynamic Routing Convention
- Passing
category(e.g.category=GOVERNMENTorcategory=ELECTRICITY): Returns all available offerings or registered billers for that industry. - Passing
billerCode(e.g.billerCode=S0000573002orbillerCode=AEDC): Returns all fee products, tariffs, and dynamiccustomFieldsfor that specific biller.
Authorizations
Query Parameters
Category filter (Retail VAS, Travel, Lifestyle, or Institutional)
Available options:
AIRTIME, DATA, INTERNET, CABLE_TV, ELECTRICITY, UTILITIES, EDUCATION, FLIGHTS, BETTING, GAMING, SOLAR, TRANSPORT, ESIM, GOVERNMENT, TAXES, HOSPITALS, INSURANCE, RELIGIOUS, ASSOCIATIONS, FINANCIAL_SERVICES, CREDIT_LOANS, MICRO_PENSIONS, INVOICE, GIFT_CARDS, SHOPPING, FOOD_DINING, LIFESTYLE_BEAUTY, HOME_LIVING