> ## 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 VAS Catalog

> Retrieve normalized bill payment catalog items, tariffs, face values, and canonical keys with zero external latency.

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=GOVERNMENT` or `category=ELECTRICITY`): Returns all available offerings or registered billers for that industry.
* **Passing `billerCode`** (e.g. `billerCode=S0000573002` or `billerCode=AEDC`): Returns all fee products, tariffs, and dynamic `customFields` for that specific biller.


## OpenAPI

````yaml openapi.json GET /bill-payment/catalog
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/catalog:
    get:
      tags:
        - VAS & Bill Payments
      summary: Get VAS Catalog
      description: >-
        Retrieve active bill payment packages, tariffs, canonical keys, and
        institutional billers.
      parameters:
        - name: category
          in: query
          required: false
          description: Category filter (Retail VAS, Travel, Lifestyle, or Institutional)
          schema:
            type: string
            enum:
              - 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
            default: ELECTRICITY
          example: ELECTRICITY
        - name: billerCode
          in: query
          required: false
          description: Biller provider code (e.g. AEDC, IKEDC, MTN, DSTV, WAEC)
          schema:
            type: string
          example: AEDC
      responses:
        '200':
          description: Catalog items retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    example: 2
                  category:
                    type: string
                    example: ELECTRICITY
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: cly239847120938471029
                        canonicalKey:
                          type: string
                          example: electricity:aedc:prepaid
                        category:
                          type: string
                          example: ELECTRICITY
                        billerCode:
                          type: string
                          example: AEDC
                        title:
                          type: string
                          example: AEDC Prepaid Electricity
                        description:
                          type: string
                          example: >-
                            Abuja Electricity Distribution Company - Instant
                            Token Vend
                        faceValue:
                          type: number
                          example: 0
                        primaryProvider:
                          type: string
                          example: KUDA
                        fallbackCount:
                          type: integer
                          example: 1
                        metadata:
                          type: object
                        lastSyncedAt:
                          type: string
                          format: date-time
                          example: '2026-10-01T10:30:00.000Z'
              example:
                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'
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.