Cable TV Subscription API

Verify smartcard/IUC decoder numbers and renew or change bouquets across DSTV, GOTV, Startimes, and Showmax.

Supported Providers & Discount Rates

PROVIDER	SERVICE ID (`serviceID`)	SUBSCRIPTION TYPES	DISCOUNT (BASE PRICE)	STATUS
DSTV Subscription	`dstv`	Renew & Change	0.0%	Active
GOTV Subscription	`gotv`	Renew & Change	0.0%	Active
Startimes Subscription	`startimes`	Renew & Change	0.0%	Active
Showmax Subscription	`showmax`	Renew & Change	0.0%	Active

Step 1: Fetch Cable TV Bouquets

Query packages to retrieve available bouquet variation codes and exact renewal prices.

GET /api/v1/tv/variations?service_id=gotv

PARAMETER	TYPE	DESCRIPTION	REQUIRED
`service_id`	string	Provider identifier: `dstv`, `gotv`, `startimes`, or `showmax`.	Optional

Step 2: Verify Smartcard / IUC Number

POST /api/v1/tv/verify

PARAMETER	TYPE	DESCRIPTION	REQUIRED
`serviceID`	string	Service ID: `dstv`, `gotv`, `startimes`, or `showmax`.	Required
`billersCode`	string	Smartcard or IUC Number.	Required

Step 3: Purchase Cable Subscription

POST /api/v1/tv/purchase

Authentication & Headers

HEADER	VALUE	REQUIRED
`Authorization`	`Bearer YOUR_API_TOKEN`	Yes
`Content-Type`	`application/json`	Yes

Purchase Parameters

PARAMETER	TYPE	DESCRIPTION	REQUIRED
`serviceID`	string	Provider: `dstv`, `gotv`, `startimes`, or `showmax`.	Required
`billersCode`	string	Smartcard or IUC number.	Required
`variation_code`	string	Bouquet variation code from Step 1 (e.g. `gotv-jinja`, `dstv-yanga`).	Required
`amount`	numeric	Bouquet amount matching package price.	Required
`phone`	string	11-digit subscriber phone number.	Required
`subscription_type`	string	`change` (to switch package) or `renew` (to renew existing package).	Required
`request_id`	string	Optional unique reference ID for idempotency and duplicate request protection.	Optional

Sample Request Payload

JSON

{
    "serviceID": "gotv",
    "billersCode": "2029384756",
    "variation_code": "gotv-jinja",
    "amount": 3300,
    "phone": "08012345678",
    "subscription_type": "renew",
    "request_id": "REQ_TV_99182"
}

Success Response (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "TV Subscription successful",
    "data": {
        "transaction_ref": "202610194829108",
        "request_id": "REQ_TV_99182",
        "amount": 3300,
        "new_balance": 1442.0,
        "status": "success"
    }
}

Failed Response (400 Bad Request)

{
    "status": "failed",
    "code": 400,
    "message": "TV Subscription failed."
}