Skip to content

Cable TV

Renew or subscribe to DStv, GOtv, ShowMax and Startimes.

Startimes

Startimes is purchased through the same cables endpoints, using the STARTIMES cable type. There is no separate live Startimes purchase route — only the sandbox has one.

Cable plans

GET/api/v1/cables/

Public — no credential required.

curl "https://api.instapaybill.com/api/v1/cables/?type=DSTV"

Returns the cable plans for a product group. The type query parameter takes DSTV, GOTV, STARTIMES or SHOWMAX.

Each plan carries the fields you need to buy it:

{
  "name": "Compact",
  "productsCode": "DSTV_COMPACT",
  "packagename": "Compact",
  "amount": 5000,
  "category": "<categoryId>"
}

productsCode is the provider's plan identifier and is what you send as productsCode in the buy request.

Cable types

GET/api/v1/cables/types

Auth: API key or session.

curl https://api.instapaybill.com/api/v1/cables/types \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "User-Agent: my-integration/1.0"

Returns the supported cable types with their logos — the equivalent of GET /api/v1/electricity/ for discos. Use this to build a provider picker.

Validate a smart card

POST/api/v1/cables/validate

Confirms an IUC / smart card number and returns the subscriber's current bouquet and due date.

curl -X POST https://api.instapaybill.com/api/v1/cables/validate \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-integration/1.0" \
  -d '{
    "smartCardNo": "1234567890",
    "type": "DSTV"
  }'

Request body

Field Type Required Description
smartCardNo string ✅ IUC / smart card number. Numeric.
type string ✅ DSTV, GOTV, STARTIMES, SHOWMAX.

Success response — 200

{
  "msg": "DSTV cables validation successful",
  "data": {
    "status": "200",
    "customerName": "ADEBAYO SANDBOX",
    "accountStatus": "active",
    "currentBouquet": "Compact",
    "minimumPayable": 9000,
    "dueDate": "2026-10-18",
    "message": "Smart card validated successfully"
  }
}

minimumPayable is the outstanding balance on the account, and dueDate is when it must be paid. accountStatus is "active" for a good subscriber.

Unknown smart card — 300

{
  "error": [
    {
      "msg": "Smart card number not found",
      "path": "smartCardNo"
    }
  ]
}

Buy cable TV

POST/api/v1/cables/buy
curl -X POST https://api.instapaybill.com/api/v1/cables/buy \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-integration/1.0" \
  -d '{
    "smartCardNo": "1234567890",
    "type": "DSTV",
    "productsCode": "DSTV_COMPACT",
    "packagename": "Compact",
    "amount": 5000,
    "apiRefId": "order-3001"
  }'

Request body

Field Type Required Description
smartCardNo string ✅ IUC / smart card number. Numeric.
type string ✅ Cable type.
productsCode string — Provider plan code. Required by some providers.
packagename string — Provider package name.
amount number — Amount in naira.
dstvaddonCode string — DStv add-on package code.
apiRefId string — Your order reference. API-channel only.
pin string — Wallet PIN. Ignored for API-key requests.
promoCode / coupon string — Not applied for API-channel requests.

Only smartCardNo and type are validated as required. Supply the plan fields (productsCode, packagename, amount) — the platform uses them to build the provider request.

Success response — 200

{
  "msg": "DSTV Cables Purchase ₦5,000 of Compact to 1234567890 was successful",
  "data": {
    "code": 200,
    "reference": "IP|TN|C|126|20260918120000_ASDFG",
    "description": "DSTV Cable Subscription",
    "message": "DSTV Compact activated on 1234567890",
    "type": "cables"
  },
  "code": 200
}

Cables responses have no data.msg

Every other purchase service includes a data.msg field copied from the provider. Cables does not — its data object is built explicitly as { code, reference, description, message, type }. If your client reads data.msg, it will be undefined for cable purchases. Read data.message instead; it is present on all five services.

Pending — 300

{
  "code": 300,
  "reference": "IP|TN|C|126|20260918120000_ASDFG",
  "error": [
    {
      "path": "cables-merrybills",
      "msg": "Your purchase is being verified with the provider. We will confirm delivery shortly."
    }
  ]
}

Failure — 400

{
  "code": 400,
  "reference": "IP|TN|C|126|20260918120000_ASDFG",
  "error": [
    {
      "path": "cables-merrybills",
      "msg": "Cable provider declined transaction"
    }
  ]
}

Guards

Check Rejects when Response
checkNetworkState The cable category is flagged networkBad 300 with canSchedule: true
UserActive Account suspended 403
TransactionStatusAndKYCCheck No BVN and no NIN 300, path: "kyc_required"
usecases.cables The service is switched off 300
Category enabled The cable category is off 300
Wallet balance Insufficient funds 300
Biller health The provider is flagged down 300
Duplicate guards An identical request is in flight 300
KYC purchase gate privilege === 'user' with no BVN/NIN 300, path: "kyc"