Developer API · Cable TV API
Cable TV API for DStv, GOtv and StarTimes
Fetch the current packages, check the smartcard or IUC number, then renew or change a subscription with one request.
- REST and JSON
- Bearer API key
- Refund on every failed purchase
/v1/cabletv/purchase{
"product_type": "dstv",
"smartcard_number": "1212121212",
"package_code": "dstv-compact",
"amount": 19000,
"phone": "08012345678",
"subscription_type": "renew",
"request_ref": "b7e2f4a1-3d5c-4e6f-8a9b-0c1d2e3f4a5b"
}Endpoints
All requests go to https://api.vtuagent.com with your key in the Authorization header.
Example request
POST /v1/cabletv/purchase, in the language your site is built with.
curl -X POST https://api.vtuagent.com/v1/cabletv/purchase \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_type": "dstv",
"smartcard_number": "1212121212",
"package_code": "dstv-compact",
"amount": 19000,
"phone": "08012345678",
"subscription_type": "renew",
"request_ref": "b7e2f4a1-3d5c-4e6f-8a9b-0c1d2e3f4a5b"
}'const res = await fetch('https://api.vtuagent.com/v1/cabletv/purchase', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.VTUAGENT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"product_type": "dstv",
"smartcard_number": "1212121212",
"package_code": "dstv-compact",
"amount": 19000,
"phone": "08012345678",
"subscription_type": "renew",
"request_ref": "b7e2f4a1-3d5c-4e6f-8a9b-0c1d2e3f4a5b"
}),
});
const result = await res.json();$ch = curl_init('https://api.vtuagent.com/v1/cabletv/purchase');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('VTUAGENT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'product_type' => 'dstv',
'smartcard_number' => '1212121212',
'package_code' => 'dstv-compact',
'amount' => 19000,
'phone' => '08012345678',
'subscription_type' => 'renew',
'request_ref' => 'b7e2f4a1-3d5c-4e6f-8a9b-0c1d2e3f4a5b',
]),
]);
$result = json_decode(curl_exec($ch), true);import os, requests
res = requests.post(
"https://api.vtuagent.com/v1/cabletv/purchase",
headers={"Authorization": f"Bearer {os.environ['VTUAGENT_API_KEY']}"},
json={
"product_type": "dstv",
"smartcard_number": "1212121212",
"package_code": "dstv-compact",
"amount": 19000,
"phone": "08012345678",
"subscription_type": "renew",
"request_ref": "b7e2f4a1-3d5c-4e6f-8a9b-0c1d2e3f4a5b"
},
)
result = res.json()Response
{
"status": "successful",
"status_code": 200,
"message": "Cable TV purchase was successful",
"reference": "b7e2f4a1-3d5c-4e6f-8a9b-0c1d2e3f4a5b",
"data": {
"amount": "19000",
"package_code": "dstv-compact",
"smartcard_number": "1212121212"
}
}How it behaves
Packages from the provider
POST /v1/cabletv/variations returns each package_code with its current price, so you never hard-code a bouquet price.
Renew or change
Set subscription_type to renew to extend the current bouquet, or change to move the customer to another one.
Charged once, refunded on failure
Your wallet is debited when the request is accepted. If the provider rejects the purchase you get HTTP 424 and the money is already back in your wallet.
Safe to retry
Every purchase carries your own request_ref (a UUID works). Sending the same reference twice is rejected with 400, so a retry after a timeout can’t charge you twice.
Cable TV commission by account type
The share of each payment paid back to you. API accounts get the API column.
| Provider | Regular | Agent | API |
|---|---|---|---|
| DStv | 0.5% | 0.8% | 1% |
| GOtv | 0.8% | 0.8% | 1% |
| StarTimes | 0.8% | 0.8% | 1% |
Commission is paid into your commission balance on every successful purchase. Agent and API accounts earn more.
Get your API key
- Step 1
Create an account
Sign up for free with your email.
- Step 2
Apply for API access
On Upgrade Account, choose API User and add the website or app you’ll connect.
- Step 3
Get your key
Once you’re approved, generate your key in Settings → API Keys. Send it as Authorization: Bearer <key> on every request.
- Step 4
Fund your wallet
Purchases are paid from your wallet balance at API prices, so top it up by bank transfer or card.
Questions people ask
Which cable TV providers are supported?
DStv, GOtv and StarTimes. Use dstv, gotv or startimes as the product_type.
How do I get package prices?
Call POST /v1/cabletv/variations with the product_type. Each package comes with the package_code and amount to send when you buy.
Can I check a smartcard before paying?
Yes. POST /v1/cabletv/verify returns the customer details on the smartcard or IUC number.
Do I earn commission on cable TV renewals?
Yes. The API rate for each provider is in the table on this page.
Other APIs
Start selling with the Cable TV API
Apply for API access, then follow the docs at docs.vtuagent.com.