NEW APP AVAILABLE FOR DOWNLOAD NOW

Get it on Google PlayDownload on the App Store
RizPay|RizPay Developer API
Get API Keys

Cable TV

Subscribe to DStv, GOtv, and Startimes

Renew cable TV subscriptions for DStv, GOtv, and Startimes.

Supported Providers

ProviderDescription
DSTVMultiChoice DStv
GOTVMultiChoice GOtv
STARTIMESStarTimes

Purchase Flow

Cable TV purchases require a two-step process:

  1. Verify - Validate the smart card/decoder number
  2. Purchase - Make the subscription payment

Step 1: List Products

List available packages for a provider:

bash
curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  "https://my.rizpay.app/api/partners/v1/products/cabletv?provider=GOTV"

Response:

json
{
  "status": { "code": 200, "message": "Success" },
  "data": [
    {
      "id": "prd_gotv_max",
      "name": "GOtv Max",
      "type": "cabletv",
      "provider": "GOTV",
      "package": "GOtv Max",
      "amount": "7200.00",
      "fee": "0.00"
    },
    {
      "id": "prd_gotv_jolli",
      "name": "GOtv Jolli",
      "type": "cabletv",
      "provider": "GOTV",
      "package": "GOtv Jolli",
      "amount": "4850.00",
      "fee": "0.00"
    },
    {
      "id": "prd_gotv_jinja",
      "name": "GOtv Jinja",
      "type": "cabletv",
      "provider": "GOTV",
      "package": "GOtv Jinja",
      "amount": "2700.00",
      "fee": "0.00"
    }
  ]
}

Step 2: Verify Decoder

Required before purchase. Validates the decoder and returns customer details.

bash
curl -X POST \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_gotv_max",
    "smart_number": "1234567890"
  }' \
  https://my.rizpay.app/api/partners/v1/purchases/verify

Response:

json
{
  "status": { "code": 200, "message": "Success" },
  "data": {
    "verified": true,
    "customer_name": "JOHN DOE",
    "smart_number": "1234567890",
    "current_package": "GOtv Jolli",
    "due_date": "2024-01-20"
  }
}

Verification Errors

ErrorMeaning
VERIFICATION_FAILEDInvalid smart card/decoder number
PRODUCT_UNAVAILABLEProvider service is down

Step 3: Make Purchase

After verification, make the subscription payment:

bash
curl -X POST \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_gotv_max",
    "smart_number": "1234567890",
    "amount": "7200.00",
    "phone_number": "08012345678",
    "external_reference": "1736234400E5F6G7"
  }' \
  https://my.rizpay.app/api/partners/v1/purchases

Response:

json
{
  "status": { "code": 201, "message": "Purchase created" },
  "data": {
    "id": "txn_abc123",
    "reference": "cable-order-001",
    "product_id": "prd_gotv_max",
    "amount": "7200.00",
    "fee": "0.00",
    "total": "7200.00",
    "status": "pending",
    "smart_number": "1234567890",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Successful Purchase

When the transaction completes:

json
{
  "status": { "code": 200, "message": "Success" },
  "data": {
    "id": "txn_abc123",
    "status": "successful",
    "new_package": "GOtv Max",
    "new_due_date": "2024-02-15",
    "completed_at": "2024-01-15T10:30:05Z"
  }
}

The subscription is activated automatically. No token or manual action required.

Complete Example

javascript
// Generate external reference: 10-digit timestamp + 6 alphanumeric
function generateReference() {
  const timestamp = Math.floor(Date.now() / 1000);
  const chars =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
  let suffix = "";
  for (let i = 0; i < 6; i++) {
    suffix += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return `${timestamp}${suffix}`;
}

async function subscribeCableTV(smartNumber, packageId, phoneNumber) {
  const API_KEY = "sk_live_your_secret_key";
  const BASE_URL = "https://my.rizpay.app/api/partners/v1";

  // Step 1: Find the package
  const productsRes = await fetch(
    `${BASE_URL}/products/cabletv?provider=GOTV`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const products = await productsRes.json();
  const product = products.data.find((p) => p.id === packageId);

  if (!product) {
    throw new Error("Package not found");
  }

  // Step 2: Verify decoder
  const verifyRes = await fetch(`${BASE_URL}/purchases/verify`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      product_id: product.id,
      smart_number: smartNumber,
    }),
  });

  const verification = await verifyRes.json();
  if (!verification.data.verified) {
    throw new Error("Invalid decoder number");
  }

  // Show customer details for confirmation
  console.log(
    `Subscribing ${verification.data.customer_name} to ${product.package}`
  );

  // Step 3: Make purchase
  const purchaseRes = await fetch(`${BASE_URL}/purchases`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      product_id: product.id,
      smart_number: smartNumber,
      amount: product.amount,
      phone_number: phoneNumber,
      external_reference: generateReference(),
    }),
  });

  return await purchaseRes.json();
}

Package Changes

Customers can:

  • Upgrade - Subscribe to a higher package
  • Downgrade - Subscribe to a lower package (applies at renewal)
  • Renew - Extend their current package

The verification response shows the current package, helping you guide customers.

DStv Packages

PackageTypical Price
DStv Premium~24,500
DStv Compact Plus~16,600
DStv Compact~10,500
DStv Confam~6,200
DStv Yanga~3,500
DStv Padi~2,500

GOtv Packages

PackageTypical Price
GOtv Supa+~9,600
GOtv Supa~6,400
GOtv Max~7,200
GOtv Jolli~4,850
GOtv Jinja~2,700
GOtv Smallie~1,575

Prices may vary. Always check the products endpoint for current pricing.

Required Scope

Requires the purchase_cable_tv scope on your API key.

Next Steps