Cable TV

Pay DStv, GOtv, and StarTimes subscriptions. Use product CABLE, put the smartcard / IUC number in msisdn, and send a catalog plan_code.


POST /v1/transactions

External create is sync — the response includes the final outcome. Response shapes: Field conventions.

1. List cable plans


GET /v1/plans/bills/cable

Optional filter: ?network=DSTV.


curl "https://api.subthingy.io/v1/plans/bills/cable?network=DSTV" \
  -H "X-Merchant-Key: mk_your_key_id" \
  -H "X-Merchant-Secret: your_issued_secret"

Sample response:


{
  "status": "2000",
  "description": "Operation Successful-BILLS-CABLE",
  "data": [
    {
      "id": 3001,
      "name": "DStv Padi",
      "network": "DSTV",
      "product": "CABLE",
      "amount_type": "fixed",
      "price": "2950"
    }
  ]
}

Use plan id as plan_code. For fixed bouquets, amount must match the catalog price.

Cable `network` values

`network`	Service
`DSTV`	DStv
`GOTV`	GOtv
`STARTIMES`	StarTimes

2. Pay cable TV

Example — DStv Compact (plan_code 3015):


curl -X POST "https://api.subthingy.io/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Key: mk_your_key_id" \
  -H "X-Merchant-Secret: your_issued_secret" \
  -d '{
    "merchant": "YOUR_MERCHANT",
    "msisdn": "10000000010",
    "network": "DSTV",
    "product": "CABLE",
    "plan_code": "3015",
    "amount": "10500",
    "request_ref": "subthingy-bill-dstv-001"
  }'

GOtv uses the same shape with network GOTV and smartcard 10000000020. StarTimes uses network STARTIMES and smartcard 10000000030.

Field	Required	Description
`merchant` or `merchant_code`	Yes	Your merchant profile
`msisdn` or `customer_msisdn`	Yes	Smartcard / IUC number
`network`	Yes	`DSTV`, `GOTV`, or `STARTIMES`
`product`	Yes	`CABLE`
`plan_code`	Yes	Catalog id from plans list
`amount`	Yes	Payment amount in Naira (string)
`request_ref` or `client_request_id`	Yes	Unique idempotency key

3. Check status (optional)


GET /v1/transactions/status?request_ref={request_ref}

See Bill payments overview — Check status.

Test smartcards

On test credentials, only these smartcards are accepted. Purchase returns the same success envelope as live (response_code 00, response_message Successful) and is simulated. Any other smartcard is rejected.

Network	`msisdn`	Verify extras
DStv	`10000000010`	`current_bouquet` `DStv Compact`, `customer_name` `Test Customer`
GOtv	`10000000020`	`current_bouquet` `GOtv Smallie`, `customer_name` `Test Customer`
StarTimes	`10000000030`	`current_bouquet` `StarTimes Classic`, `customer_name` `Test Customer`

Live credentials always require a real smartcard / IUC.

Ask your account manager to enable cable TV on your merchant profile before go-live.