> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handle.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Biller Categories

> Retrieve all 28 supported biller categories (Utilities, Telcos, Government MDAs, Taxes, Hospitals, Universities, Lifestyle & Gift Cards) with active item counts.

Retrieve the complete list of all 28 active bill payment, utility, travel, institutional collection, and digital voucher categories supported on the Handle network.

### Complete Categories Matrix

#### 1. Utilities & Telecommunications

| Category ID | Display Name | Live Offerings | Description |
| :- | :- | :- | :- |
| `AIRTIME` | Airtime | 19 items | Top-up airtime across MTN, Airtel, Glo, 9mobile |
| `DATA` | Data | 274 items | Mobile and broadband data bundles (Daily, Weekly, Monthly) |
| `ELECTRICITY` | Electricity | 50 items | All 11 Nigerian Electricity Distribution Companies (DisCos) |
| `CABLE_TV` | Cable TV | 160 items | Pay TV bouquets for DSTV, GOtv, StarTimes, Showmax |
| `INTERNET` | Internet | 51 items | Fixed fiber and wireless ISPs (Smile, Spectranet) |
| `SOLAR` | Solar Energy | 26 items | Solar energy subscriptions and home power systems |
| `UTILITIES` | Utilities | 8 billers | Municipal water boards and waste management utilities |

#### 2. Education, Travel & Entertainment

| Category ID | Display Name | Live Offerings | Description |
| :- | :- | :- | :- |
| `EDUCATION` | Education | 12 items | WAEC scratch cards, JAMB registration e-PINs, Universities |
| `FLIGHTS` | Flights | 2 items | Multi-carrier domestic and regional airline flight bookings |
| `BETTING` | Betting | 61 items | Wallet funding for Bet9ja, SportyBet, 1xBet, BangBet |
| `GAMING` | Gaming Subscriptions | 12 items | PlayStation, Xbox Live, Steam, Nintendo digital cards |
| `TRANSPORT` | Transport | 3 items | Cowry transit card topups and interstate bus transport |
| `ESIM` | Global Travel eSIM | 6 items | Global travel roaming eSIM packs for 150+ countries |

#### 3. Institutional & Government Collections

| Category ID | Display Name | Live Offerings | Description |
| :- | :- | :- | :- |
| `GOVERNMENT` | Government Payments | 478 billers | Federal MDAs, State Governments, and TSA revenues |
| `TAXES` | Taxes & Inland Revenue | 12 billers | FIRS, State Internal Revenue Services, Custom duties |
| `HOSPITALS` | Hospitals | 10 billers | University Teaching Hospitals and Federal Medical Centres |
| `INSURANCE` | Insurance | 8 billers | Health HMOs and motor/life insurance policies |
| `RELIGIOUS` | Religious Institutions | 15 billers | Churches, Mosques, and Missions (Tithes & Offerings) |
| `ASSOCIATIONS` | Associations & Societies | 20 billers | Professional bodies (COREN, NBA, ICAN, NIM) |
| `FINANCIAL_SERVICES` | Financial Services | 18 billers | Microfinance, Investment, and FinTechs |
| `CREDIT_LOANS` | Credit & Loans | 14 billers | Loan repayment and credit platforms |
| `MICRO_PENSIONS` | Micro Pensions | 5 billers | PenCom and micro pension fund contributions |
| `INVOICE` | Invoice Collections | 1 biller | Direct corporate electronic invoice settlement |

#### 4. Lifestyle, Retail & Digital Gift Cards

| Category ID | Display Name | Live Offerings | Description |
| :- | :- | :- | :- |
| `GIFT_CARDS` | Gift Cards & Vouchers | 25 items | Digital gift cards (Apple, Amazon, Steam, Shoprite, Spar) |
| `SHOPPING` | Shopping & Retail | 15 items | E-commerce, supermarket, and mall shopping vouchers |
| `FOOD_DINING` | Food & Dining | 10 items | Restaurant & food delivery credits (Chowdeck, Domino's) |
| `LIFESTYLE_BEAUTY` | Health & Beauty | 8 items | Spa treatments, salon, grooming, and wellness services |
| `HOME_LIVING` | Home & Living | 6 items | Home furnishing, appliance maintenance, and cleaning vouchers |


## OpenAPI

````yaml openapi.json GET /bill-payment/categories
openapi: 3.0.3
info:
  title: Handle Merchant Payment Gateway API
  description: >-
    Developer API specification for accepting cardless, instant
    Account-to-Account (A2A) payments via Handle.
  version: 1.0.0
  contact:
    name: Handle Developer Support
    email: support@handle.ng
    url: https://handle.ng
servers:
  - url: https://api-local.handle.ng/api/v1
    description: Local Development (SSL)
  - url: https://api.handle.ng/api/v1
    description: Production Live Gateway
security:
  - BearerAuth: []
paths:
  /bill-payment/categories:
    get:
      tags:
        - VAS & Bill Payments
      summary: Get Biller Categories
      description: >-
        Retrieve all 28 supported biller categories (Utilities, Telcos, Travel,
        Lifestyle, Government MDAs, Taxes, Hospitals, Universities) with active
        item counts.
      responses:
        '200':
          description: List of all supported biller categories
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    example: 28
                  categories:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ELECTRICITY
                        name:
                          type: string
                          example: Electricity
                        itemCount:
                          type: integer
                          example: 50
              example:
                count: 28
                categories:
                  - id: AIRTIME
                    name: Airtime
                    itemCount: 19
                  - id: DATA
                    name: Data
                    itemCount: 274
                  - id: INTERNET
                    name: Internet
                    itemCount: 51
                  - id: CABLE_TV
                    name: Cable Tv
                    itemCount: 160
                  - id: ELECTRICITY
                    name: Electricity
                    itemCount: 50
                  - id: UTILITIES
                    name: Utilities
                    itemCount: 8
                  - id: EDUCATION
                    name: Education
                    itemCount: 12
                  - id: FLIGHTS
                    name: Flights
                    itemCount: 2
                  - id: BETTING
                    name: Betting
                    itemCount: 61
                  - id: GAMING
                    name: Gaming
                    itemCount: 12
                  - id: SOLAR
                    name: Solar
                    itemCount: 26
                  - id: TRANSPORT
                    name: Transport
                    itemCount: 3
                  - id: ESIM
                    name: Esim
                    itemCount: 6
                  - id: GOVERNMENT
                    name: Government
                    itemCount: 54
                  - id: TAXES
                    name: Taxes
                    itemCount: 12
                  - id: HOSPITALS
                    name: Hospitals
                    itemCount: 10
                  - id: INSURANCE
                    name: Insurance
                    itemCount: 8
                  - id: RELIGIOUS
                    name: Religious
                    itemCount: 15
                  - id: ASSOCIATIONS
                    name: Associations
                    itemCount: 20
                  - id: FINANCIAL_SERVICES
                    name: Financial Services
                    itemCount: 18
                  - id: CREDIT_LOANS
                    name: Credit Loans
                    itemCount: 14
                  - id: MICRO_PENSIONS
                    name: Micro Pensions
                    itemCount: 5
                  - id: INVOICE
                    name: Invoice
                    itemCount: 1
                  - id: GIFT_CARDS
                    name: Gift Cards
                    itemCount: 25
                  - id: SHOPPING
                    name: Shopping
                    itemCount: 15
                  - id: FOOD_DINING
                    name: Food Dining
                    itemCount: 10
                  - id: LIFESTYLE_BEAUTY
                    name: Lifestyle Beauty
                    itemCount: 8
                  - id: HOME_LIVING
                    name: Home Living
                    itemCount: 6
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Supply your secret API key (e.g. `sk_live_...` or `sk_test_...`) in the
        Authorization header.
      x-default: sk_test_handle_master_key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.