Skip to main content

Overview

The catalog endpoints let you discover what’s available on the Dancity platform before initiating any purchase. Always fetch catalog data dynamically — identifiers (plan IDs, product names) can change over time. The catalog has three levels:

Authentication

All catalog endpoints use your merchant API key only.

Get services

Returns all service categories.

Get products

Returns products (providers/operators) within a service. Filter by service name to get only the products you need.

Get data plans

Returns data plans for purchase. Each plan includes a planId — pass that value as plan in POST /api/v1/data/buy.

Get cable plans

Returns cable TV subscription plans. Each item includes a planId — pass that as cableplan in POST /api/v1/cable/buy. How planId is built: slugified package name. If the package already includes the brand (e.g. GOtv Supa), the product is not repeated — GOtv_Supa_monthly_N11_400. For packages without the brand, the product is appended: Nova_monthly_Startimes. Examples:
  • GOtv Supa Plus - monthly N16,800 + GOTV → GOtv_Supa_Plus_monthly_N16_800
  • GOtv Max + GOTV → GOtv_Max

Catalog data (services, products, plans) doesn’t change frequently, but prices and availability can. We recommend:
  • Cache catalog responses for 15–60 minutes in production
  • Re-fetch on cache miss or user-initiated refresh
  • Never hard-code plan IDs — always resolve them from the catalog at runtime
Use the product name returned from /products as the product field in buy requests (e.g. "MTN Airtime", "MTN-Airtime", or "MTN_Airtime"). Use the plan _id as the plan field for data/internet purchases.

Next steps