Bills Payment
TV Subscription

Cable TV Subscription

Manage cable TV subscriptions for all major Nigerian providers. Retrieve available providers, view subscription packages, validate customer accounts, and subscribe seamlessly.

Get TV Providers

Retrieve a list of available cable TV providers.

Endpoint

GET https://api.budpay.com/api/v2/tv

Sample Request

Endpoint: GET https://api.budpay.com/api/v2/tv

1curl -X GET 'https://api.budpay.com/api/v2/tv' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY'
{  "success": true,  "code": "00000",  "message": "Fetched successfully",  "data": [    {      "provider": "DSTV",      "providerLogoUrl": "assets/images/bills/Pay-DSTV-Subscription.jpg"    },    {      "provider": "GOTV",      "providerLogoUrl": "assets/images/bills/Gotv-Payment.jpg"    },    {      "provider": "STARTIMES",      "providerLogoUrl": "assets/images/bills/Startimes-Subscription.jpg"    },    {      "provider": "SHOWMAX",      "providerLogoUrl": "assets/images/bills/ShowMax.jpg"    }  ]}
Powered byXendr

Response Fields

FieldTypeDescription
successBooleanIndicates if request was successful
codeStringResponse code
messageStringResponse message
dataArrayArray of TV provider objects

Provider Object Fields

FieldTypeDescription
providerStringCable TV provider name
providerLogoUrlStringURL path to provider logo image

Get TV Packages

Retrieve available subscription packages for a specific TV provider.

Endpoint

GET https://api.budpay.com/api/v2/tv/packages/{provider}

Sample Request

Endpoint: GET https://api.budpay.com/api/v2/tv/packages/GOTV

1curl -X GET 'https://api.budpay.com/api/v2/tv/packages/GOTV' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY'
{  "success": true,  "code": "00000",  "message": "CableTv Packages Fetched successfully",  "data": [    {      "id": 34,      "name": "GOtv Max N3,600",      "code": "gotv-max",      "amount": "3600"    },    {      "id": 35,      "name": "GOtv Jolli N2,460",      "code": "gotv-jolli",      "amount": "2460"    },    {      "id": 36,      "name": "GOtv Jinja N1,640",      "code": "gotv-jinja",      "amount": "1640"    },    {      "id": 37,      "name": "GOtv Smallie - monthly N800",      "code": "gotv-smallie",      "amount": "800"    },    {      "id": 38,      "name": "GOtv Smallie - quarterly N2,100",      "code": "gotv-smallie-3months",      "amount": "2100"    },    {      "id": 39,      "name": "GOtv Smallie - yearly N6,200",      "code": "gotv-smallie-1year",      "amount": "6200"    },    {      "id": 56,      "name": "GOtv Supa - monthly N5,500",      "code": "gotv-supa",      "amount": "5500.00"    }  ]}
Powered byXendr

Request Parameters

ParameterTypeRequiredDescription
providerStringYesTV provider name (DSTV, GOTV, STARTIMES, SHOWMAX)

Response Fields

Package Object Fields

FieldTypeDescription
idIntegerUnique package ID
nameStringPackage name with price
codeStringPackage code for subscription
amountStringPackage price in Naira

Validate TV Customer

Validate a customer's account number before subscription.

Endpoint

POST https://api.budpay.com/api/v2/tv/validate

Sample Request

Endpoint: POST https://api.budpay.com/api/v2/tv/validate

1curl -X POST 'https://api.budpay.com/api/v2/tv/validate' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY' \4  -d '{5  "provider": "GOTV",6  "number": "2019505346"7}'
{  "success": true,  "code": "00000",  "message": "SUCCESSFUL",  "data": {    "orderNo": "211104130931335009",    "reference": "25696593r9622",    "status": "Delivered",    "errorMsg": null  }}
Powered byXendr

Request Parameters

Body Parameters

ParameterTypeRequiredDescription
providerStringYesTV provider name (DSTV, GOTV, STARTIMES, SHOWMAX)
numberStringYesCustomer account/smartcard number

Response Fields

FieldTypeDescription
successBooleanIndicates if validation was successful
codeStringResponse code
messageStringResponse message
data.orderNoStringOrder number
data.referenceStringValidation reference
data.statusStringValidation status
data.errorMsgStringError message if any (null on success)

Subscribe to TV

Purchase a cable TV subscription for a customer.

Endpoint

POST https://api.budpay.com/api/v2/tv/pay

Sample Request

Endpoint: POST https://api.budpay.com/api/v2/tv/pay

1curl -X POST 'https://api.budpay.com/api/v2/tv/pay' \2  -H 'Encryption: Signature_HMAC-SHA-512' \3  -H 'Content-Type: application/json' \4  -H 'Authorization: Bearer YOUR_SECRET_KEY' \5  -d '{6  "provider": "GOTV",7  "number": "2019505346",8  "code": "gotv-max",9  "reference": "20220511035554758"10}'
{  "success": true,  "code": "00000",  "message": "SUCCESSFUL",  "data": {    "orderNo": "211104130931335009",    "reference": "20220511035554758",    "status": "Delivered",    "errorMsg": null  }}
Powered byXendr

Request Parameters

Header Parameters

Field NameDescriptionRequired
AuthorizationBearer token with your secret keyYes
EncryptionSignature_HMAC-SHA-512 for request encryptionYes
Content-Typeapplication/jsonYes

Body Parameters

ParameterTypeRequiredDescription
providerStringYesTV provider name (DSTV, GOTV, STARTIMES, SHOWMAX)
numberStringYesCustomer account/smartcard number
codeStringYesPackage code from packages endpoint
referenceStringYesUnique transaction reference

Response Fields

FieldTypeDescription
successBooleanIndicates if subscription was successful
codeStringResponse code
messageStringResponse message
data.orderNoStringOrder number from provider
data.referenceStringYour transaction reference
data.statusStringSubscription status (Delivered, Pending, Failed)
data.errorMsgStringError message if any (null on success)

Supported Providers

ProviderDescriptionPackages
DSTVMultiChoice DSTVPremium, Compact Plus, Compact, Confam, Yanga, Padi
GOTVMultiChoice GOtvSupa, Max, Jolli, Jinja, Smallie (monthly/quarterly/yearly)
STARTIMESStarTimesNova, Basic, Smart, Classic, Super
SHOWMAXShowmax StreamingEntertainment, Sport, Pro packages

Subscription Status

StatusDescription
DeliveredSubscription activated successfully
PendingSubscription being processed
FailedSubscription failed (check errorMsg)

Error Handling

400 Bad Request

{
    "success": false,
    "message": "Invalid request parameters"
}

401 Unauthorized

{
    "success": false,
    "message": "Authentication failed"
}

422 Validation Error

{
    "success": false,
    "message": "Validation error",
    "errors": {
        "number": ["Invalid account number"],
        "code": ["Invalid package code"]
    }
}

Best Practices

Tip: Always validate the customer account before initiating subscription to ensure the account exists and is valid.

  1. Validate Account First: Use validate endpoint before subscription
  2. Fetch Fresh Packages: Query packages endpoint for latest offerings
  3. Display Package Details: Show package name, duration, and price
  4. Verify Account Number: Ensure customer enters correct smartcard/IUC number
  5. Unique References: Generate unique reference IDs for each transaction
  6. Check Balance: Verify wallet balance before purchase
  7. Store Order Numbers: Save order numbers for customer support
  8. Handle Status: Implement proper handling for pending and failed statuses

TV Subscription Workflow

💡

Process Flow: Get providers → Select provider → Get packages → Validate account → Subscribe

  1. Get Providers: Fetch available TV providers
  2. Select Provider: User selects their TV provider
  3. Get Packages: Retrieve subscription packages for provider
  4. Display Packages: Show packages with names, durations, and prices
  5. Enter Account: User enters smartcard/IUC number
  6. Validate Account: Verify account exists and is valid
  7. Select Package: User selects desired subscription package
  8. Generate Reference: Create unique transaction reference
  9. Subscribe: Submit subscription request
  10. Track Status: Monitor subscription activation
  11. Notify User: Inform user of successful activation

Security Considerations

⚠️

Security: The Encryption header with HMAC-SHA-512 signature is required for all subscription payment requests.

  • HMAC Signature: Always include the Encryption: Signature_HMAC-SHA-512 header for payments
  • Server-Side Only: Never expose secret keys in frontend code
  • HTTPS Only: All requests must use secure HTTPS connections
  • Reference IDs: Use unpredictable reference IDs to prevent replay attacks
  • Validate Input: Sanitize account numbers and package codes before submission
  • Pre-Validation: Always validate accounts before accepting payment

Next Steps

Data PurchaseElectricity