Cable TV Subscription API (DSTV, GOtv, StarTimes)

Endpoint

Send a POST request with the subscription details in the request body.

Production URL

https://pairgate.com/api/v1/cable/purchase

Method POST

Test Endpoint

https://pairgate.com/api/v1/test/cable/purchase

Authentication

This request requires a valid Bearer token.

Header	Value	Description
`Authorization`	`Bearer {token}`	Your unique API authorization token
`Content-Type`	`application/json`	Required for POST requests

Body Parameters

Required parameters marked below. Send them as JSON in the request body.

Parameter	Type	Required	Description
`provider_id`	string	Yes	Provider slug (e.g. `dstv`, `gotv`)
`plan_id`	string	Yes	Plan ID from the cable plans list
`smartcard`	string	Yes	Smartcard / IUC number
`recipient_name`	string	No	Name to associate with the subscription (defaults to "Unknown Customer")
`reference`	string	Yes	Your unique reference for this transaction (8–100 characters)

Code Examples

Choose your preferred language below. Replace the parameters and YOUR_API_KEY with your actual values.

PHP (Laravel)

// Purchase Cable TV Subscription
$response = Http::withHeaders([
    'Authorization' => 'Bearer YOUR_API_KEY',
    'Content-Type' => 'application/json',
])->post('https://pairgate.com/api/v1/cable/purchase', [
    'provider_id' => 'dstv',
    'plan_id' => '68',
    'smartcard' => '1234567890',
    'recipient_name' => 'John Doe',
    'reference' => 'my-cable-order-001',
]);

$result = $response->json();

dd($result);

cURL

curl -X POST "https://pairgate.com/api/v1/cable/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "dstv",
    "plan_id": "68",
    "smartcard": "1234567890",
    "recipient_name": "John Doe",
    "reference": "my-cable-order-001"
  }'

Node.js

const axios = require('axios');

const purchaseCableTV = async () => {
    try {
        const response = await axios.post(
            'https://pairgate.com/api/v1/cable/purchase',
            {
                provider_id: 'dstv',
                plan_id: '68',
                smartcard: '1234567890',
                recipient_name: 'John Doe',
                reference: 'my-cable-order-001'
            },
            {
                headers: {
                    'Authorization': 'Bearer YOUR_API_KEY',
                    'Content-Type': 'application/json'
                }
            }
        );
        
        console.log(response.data);
    } catch (error) {
        console.error(error.response?.data || error.message);
    }
};

purchaseCableTV();

Python

import requests
import json

url = "https://pairgate.com/api/v1/cable/purchase"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "provider_id": "dstv",
    "plan_id": "68",
    "smartcard": "1234567890",
    "recipient_name": "John Doe",
    "reference": "my-cable-order-001"
}

try:
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    data = response.json()
    print(json.dumps(data, indent=2))
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

String jsonBody = "{"
    + "\"provider_id\": \"dstv\","
    + "\"plan_id\": \"68\","
    + "\"smartcard\": \"1234567890\","
    + "\"recipient_name\": \"John Doe\","
    + "\"reference\": \"my-cable-order-001\""
    + "}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://pairgate.com/api/v1/cable/purchase"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

try {
    HttpResponse response = client.send(request, 
        HttpResponse.BodyHandlers.ofString());
    
    System.out.println(response.body());
} catch (Exception e) {
    System.err.println("Error: " + e.getMessage());
}

Example Request Body

{
  "provider_id": "dstv",
  "plan_id": "68",
  "smartcard": "1234567890",
  "recipient_name": "John Doe",
  "reference": "my-cable-order-001"
}

Response Format

Success Response (200)

{
  "code": 200,
  "status": "success",
  "data": {
    "status": true,
    "message": "Cable subscription successful & processing.",
    "reference_code": "TRXCAB20260615104818CQ3",
    "balance_before": 20000.00,
    "balance_after": 15600.00,
    "amount": 4400.00,
    "plan": "Dstv Padi",
    "smartcard": "1234567890"
  }
}

Test Response (200)

{
  "code": 200,
  "status": "success",
  "data": {
    "test_mode": true,
    "message": "This is a test — no balance deducted.",
    "request": {
      "provider_id": "dstv",
      "plan_id": "68",
      "smartcard": "1234567890",
      "recipient_name": "John Doe",
      "reference": "my-cable-order-001"
    },
    "balance": 20000.00
  }
}

Response Fields

Field	Type	Description
`status`	boolean	`true` if successful
`message`	string	Status description
`reference_code`	string	Your transaction reference for status checks
`balance_before`	float	Wallet balance before debit
`balance_after`	float	Wallet balance after debit
`amount`	float	Amount charged
`plan`	string	Package name
`smartcard`	string	Smartcard number subscribed

Error Responses

The following errors may occur when calling this endpoint.

Status	Code	Description
422	`Invalid provider`	Provider not found or inactive
422	`Plan not found`	Plan ID is invalid or unavailable
422	`Insufficient balance`	Wallet balance is too low
422	`Duplicate reference`	This reference has already been used
401	`Missing API key`	No Bearer token provided
401	`Invalid API key`	Token does not match any active key
403	`Suspended`	API key or account has been suspended
429	`Rate limited`	Too many requests

Cable TV Purchase

Quick Summary