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:
| Level | Endpoint | What it returns |
|---|
| Services | GET /api/v1/services | Top-level service categories (e.g., Airtime, Data, Cable TV) |
| Products | GET /api/v1/products | Specific providers within a service (e.g., MTN, DSTV) |
| Plans | GET /api/v1/plans/data, .../cable, .../internet | Individual purchase options with prices |
Authentication
All catalog endpoints use your merchant API key only.
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Get services
Returns all service categories.
curl -sS "https://api.dancity.app/api/v1/services" \
-H "Authorization: Bearer $DANCITY_API_KEY"
Get products
Returns products (providers/operators) within a service. Filter by service name to get only the products you need.
| Query param | Type | Description |
|---|
service | string | Service name from GET /api/v1/services (e.g. Airtime, Data) |
# All airtime products
curl -sS "https://api.dancity.app/api/v1/products?service=AIRTIME" \
-H "Authorization: Bearer $DANCITY_API_KEY"
Get data plans
Returns data plans for purchase. Each plan includes a planId — pass that value as plan in POST /api/v1/data/buy.
| Field | Description |
|---|
_id | Internal Mongo id |
product | Product name (e.g. MTN GIFTING) |
plan | Data size (e.g. 40MB, 1GB) |
price | Price in NGN |
validity | Validity period (e.g. 1 Day, 30 days) |
planId | Send this to buy — e.g. 40GB_MTN_GIFTING_1Day |
| Query param | Type | Description |
|---|
product | string | Product name from GET /api/v1/products (e.g. MTN GIFTING, GLO GIFTING). Spaces, underscores, and hyphens all work: MTN GIFTING, MTN_GIFTING, MTN-GIFTING. |
curl -sS "https://api.dancity.app/api/v1/plans/data?product=MTN%20GIFTING" \
-H "Authorization: Bearer $DANCITY_API_KEY"
Get cable plans
Returns cable TV subscription plans. Each item includes a planId — pass that as cableplan in POST /api/v1/cable/buy.
| Field | Description |
|---|
_id | Internal Mongo id |
product | Cable provider (e.g. GOTV, DSTV) |
plan | Package name (e.g. GOtv Supa Plus - monthly N16,800) |
price | Price in NGN |
planId | Send this to buy — e.g. GOtv_Supa_monthly_N11_400 |
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_800GOtv Max + GOTV → GOtv_Max
| Query param | Type | Description |
|---|
product | string | Product name from GET /api/v1/products (e.g. DSTV, GOTV, Startimes). |
curl -sS "https://api.dancity.app/api/v1/plans/cable?product=GOTV" \
-H "Authorization: Bearer $DANCITY_API_KEY"
Recommended catalog caching strategy
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
