Product · Entertainment

Cable TV

Verify customer smartcards, browse bouquets, and renew or upgrade subscriptions across DSTV, GOtv, StarTimes, and Showmax.

Base path/api/v1/partner/cabletv

Authx-api-key (+ x-signature on verify/purchase)

Supported CarriersDSTV (dstv) · GOtv (gotv) · StarTimes (startimes) · Showmax (showmax)

Rate limit30 requests / 60s (failure circuit breaker)

1. List Cable TV Providers

Query the supported pay-TV operators and their slug identifiers:

List cable TV providers

GET /partner/cabletv/providers

API key only

cURL

curl https://api.billpadi.com/api/v1/partner/cabletv/providers \
  -H "x-api-key: $API_KEY"

Example response — 200 OK

{
  "success": true,
  "message": "Cable TV providers retrieved",
  "data": [
    { "id": "64f1c1a1c4d5e6f7a8b9c201", "name": "DSTV", "code": "dstv" },
    { "id": "64f1c1a1c4d5e6f7a8b9c202", "name": "GOtv", "code": "gotv" },
    { "id": "64f1c1a1c4d5e6f7a8b9c203", "name": "StarTimes", "code": "startimes" },
    { "id": "64f1c1a1c4d5e6f7a8b9c204", "name": "Showmax", "code": "showmax" }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/cabletv/providers"
}

2. List Bouquets / Packages

Retrieve all packages available for a given provider slug or provider ID:

List bouquets for provider

GET /partner/cabletv/packages/:providerId

API key only

cURL

curl https://api.billpadi.com/api/v1/partner/cabletv/packages/dstv \
  -H "x-api-key: $API_KEY"

Example response — 200 OK

{
  "success": true,
  "message": "Cable TV packages retrieved",
  "data": [
    {
      "id": "64f3c2a1c4d5e6f7a8b9c211",
      "code": "dstv-padi",
      "name": "DStv Padi",
      "amount": 4400,
      "validity": "1 Month"
    },
    {
      "id": "64f3c2a1c4d5e6f7a8b9c212",
      "code": "dstv-yanga",
      "name": "DStv Yanga",
      "amount": 6000,
      "validity": "1 Month"
    },
    {
      "id": "64f3c2a1c4d5e6f7a8b9c213",
      "code": "dstv-compact",
      "name": "DStv Compact",
      "amount": 15700,
      "validity": "1 Month"
    }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/cabletv/packages/dstv"
}

3. Verify Smartcard Number

Always verify a customer's smartcard or IUC number before initiating payment. This resolves the registered customer name and current active bouquet:

Verify smartcard / IUC

POST /partner/cabletv/verify

Signature required

Field	Type	Required	Description
smartCardNumber	string	required	Decoder smartcard or IUC number
serviceCode	string	required	Provider slug: `dstv`, `gotv`, `startimes`, or `showmax`

cURL

Node.js

curl -X POST https://api.billpadi.com/api/v1/partner/cabletv/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "smartCardNumber": "1234567890",
    "serviceCode": "dstv"
  }'

const res = await partnerClient.post("/cabletv/verify", {
  smartCardNumber: "1234567890",
  serviceCode: "dstv"
});

Example response — 200 OK

{
  "success": true,
  "message": "Smartcard verified successfully",
  "data": {
    "smartCardNumber": "1234567890",
    "customerName": "CHINEDU OKEKE",
    "currentPlan": "DStv Yanga",
    "dueDate": "2026-07-28"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/cabletv/verify"
}

4. Renew or Change Subscription

Submit a subscription payment for renewal or package upgrade:

Renew or change subscription

POST /partner/cabletv/purchase

Signature required

Field	Type	Required	Description
provider	string	required	Provider slug: `dstv`, `gotv`, `startimes`, or `showmax`
smartCardNumber	string	required	Customer smartcard number
productId	string	required	Target package `code` or MongoDB `id` from packages catalog
type	string	required	`renew` (keep current plan) or `change` (upgrade/downgrade bouquet)
partnerReference	string	required	Unique reference string (2–100 characters) for idempotency

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/cabletv/purchase \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "provider": "dstv",
    "smartCardNumber": "1234567890",
    "productId": "dstv-compact",
    "type": "change",
    "partnerReference": "PR-CTV-40218"
  }'

Example response — 200 OK

{
  "success": true,
  "message": "Cable TV subscription initiated",
  "data": {
    "transactionReference": "TXN_1720603200000_2B3C",
    "partnerReference": "PR-CTV-40218",
    "status": "pending",
    "smartCardNumber": "1234567890",
    "package": "DStv Compact",
    "amount": 15700
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/cabletv/purchase"
}

Upon carrier activation, Billpadi fires a cabletv.purchase.success webhook.

5. Transaction Status & Listing

Get cable TV transaction status

GET /partner/cabletv/transactions/:reference

API key only

List cable TV transactions

GET /partner/cabletv/transactions

API key only

← PreviousElectricity Next →Betting Wallet Funding