Tv – BudPay

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

curl https://api.budpay.com/api/v2/tv \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-X GET

Sample Response

{
    "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"
        }
    ]
}

Try it out

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if request was successful
`code`	String	Response code
`message`	String	Response message
`data`	Array	Array of TV provider objects

Provider Object Fields

Field	Type	Description
`provider`	String	Cable TV provider name
`providerLogoUrl`	String	URL 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

curl https://api.budpay.com/api/v2/tv/packages/GOTV \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-X GET

Sample Response

{
    "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"
        }
    ]
}

Try it out

Request Parameters

Parameter	Type	Required	Description
`provider`	String	Yes	TV provider name (DSTV, GOTV, STARTIMES, SHOWMAX)

Response Fields

Package Object Fields

Field	Type	Description
`id`	Integer	Unique package ID
`name`	String	Package name with price
`code`	String	Package code for subscription
`amount`	String	Package 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

curl https://api.budpay.com/api/v2/tv/validate \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
    "provider": "GOTV",
    "number": "2019505346"
}' \
-X POST

Sample Response

{
    "success": true,
    "code": "00000",
    "message": "SUCCESSFUL",
    "data": {
        "orderNo": "211104130931335009",
        "reference": "25696593r9622",
        "status": "Delivered",
        "errorMsg": null
    }
}

Try it out

Request Parameters

Body Parameters

Parameter	Type	Required	Description
`provider`	String	Yes	TV provider name (DSTV, GOTV, STARTIMES, SHOWMAX)
`number`	String	Yes	Customer account/smartcard number

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if validation was successful
`code`	String	Response code
`message`	String	Response message
`data.orderNo`	String	Order number
`data.reference`	String	Validation reference
`data.status`	String	Validation status
`data.errorMsg`	String	Error 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

curl https://api.budpay.com/api/v2/tv/pay \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Encryption: Signature_HMAC-SHA-512" \
-H "Content-Type: application/json" \
-d '{
    "provider": "GOTV",
    "number": "2019505346",
    "code": "gotv-max",
    "reference": "20220511035554758"
}' \
-X POST

Sample Response

{
    "success": true,
    "code": "00000",
    "message": "SUCCESSFUL",
    "data": {
        "orderNo": "211104130931335009",
        "reference": "20220511035554758",
        "status": "Delivered",
        "errorMsg": null
    }
}

Try it out

Request Parameters

Header Parameters

Field Name	Description	Required
Authorization	Bearer token with your secret key	Yes
Encryption	`Signature_HMAC-SHA-512` for request encryption	Yes
Content-Type	`application/json`	Yes

Body Parameters

Parameter	Type	Required	Description
`provider`	String	Yes	TV provider name (DSTV, GOTV, STARTIMES, SHOWMAX)
`number`	String	Yes	Customer account/smartcard number
`code`	String	Yes	Package code from packages endpoint
`reference`	String	Yes	Unique transaction reference

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if subscription was successful
`code`	String	Response code
`message`	String	Response message
`data.orderNo`	String	Order number from provider
`data.reference`	String	Your transaction reference
`data.status`	String	Subscription status (Delivered, Pending, Failed)
`data.errorMsg`	String	Error message if any (null on success)

Supported Providers

Provider	Description	Packages
DSTV	MultiChoice DSTV	Premium, Compact Plus, Compact, Confam, Yanga, Padi
GOTV	MultiChoice GOtv	Supa, Max, Jolli, Jinja, Smallie (monthly/quarterly/yearly)
STARTIMES	StarTimes	Nova, Basic, Smart, Classic, Super
SHOWMAX	Showmax Streaming	Entertainment, Sport, Pro packages

Subscription Status

Status	Description
`Delivered`	Subscription activated successfully
`Pending`	Subscription being processed
`Failed`	Subscription 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.

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

TV Subscription Workflow

💡

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

Get Providers: Fetch available TV providers
Select Provider: User selects their TV provider
Get Packages: Retrieve subscription packages for provider
Display Packages: Show packages with names, durations, and prices
Enter Account: User enters smartcard/IUC number
Validate Account: Verify account exists and is valid
Select Package: User selects desired subscription package
Generate Reference: Create unique transaction reference
Subscribe: Submit subscription request
Track Status: Monitor subscription activation
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

Airtime - Purchase mobile airtime
Data Bundles - Purchase mobile data bundles
Wallet Balance - Check wallet balance before subscriptions
Transaction History - View subscription history

Data Purchase Electricity