> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dancity.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Cable TV

> Validate a smartcard and renew a cable TV subscription

## Overview

Cable TV purchases are a two-step flow:

1. **Validate** the smartcard number to confirm it exists and retrieve the customer name
2. **Buy** the subscription using the validated details

Supported providers include DSTV, GOtv, Startimes, and others available in your catalog.

## Authentication

Both endpoints require your merchant API key **and** the `channel: API` header.

```http theme={null}
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
channel: API
```

***

## Step 1 — Validate smartcard

```
POST /api/v1/cable/validate
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `smartcardNumber` | string | ✓ | Customer's smartcard/decoder number |
| `cablename` | string | ✓ | Provider name (e.g., `"DSTV"`, `"GOTV"`) |

```bash cURL theme={null}
curl -sS -X POST "https://api.dancity.app/api/v1/cable/validate" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "channel: API" \
  -d '{
    "smartcardNumber": "1234567890",
    "cablename": "DSTV"
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://api.dancity.app/api/v1/cable/validate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
    "Content-Type": "application/json",
    channel: "API",
  },
  body: JSON.stringify({
    smartcardNumber: "1234567890",
    cablename: "DSTV",
  }),
});
const { data } = await res.json();
console.log(data.customerName); // show to user for confirmation
```

```python Python theme={null}
import requests, os

res = requests.post(
    "https://api.dancity.app/api/v1/cable/validate",
    headers={
        "Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
        "Content-Type": "application/json",
        "channel": "API",
    },
    json={"smartcardNumber": "1234567890", "cablename": "DSTV"},
)
customer_name = res.json()["data"]["customerName"]
```

### Sample response

```json theme={null}
{
  "success": true,
  "message": "Validation successful",
  "data": {
    "customerName": "John Doe"
  }
}
```

> [!NOTE]
>
> Always display `customerName` to the user for confirmation before proceeding to purchase. This prevents funding the wrong decoder.

***

## Step 2 — Cable subscription

```
POST /api/v1/cable/buy
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `smartcardNumber` | string | ✓ | Same number used in validation |
| `cableplan` | string | ✓ | `planId` from `GET /api/v1/plans/cable` |
| `customerName` | string | ✓ | Name returned from validation step |
| `customerRef` | string | | Your internal reference ID |
| `saveAsBeneficiary` | boolean | | Save smartcard as beneficiary |
| `beneficiaryName` | string | | Label for saved beneficiary |
| `promocode` | string | | Discount promo code |

```bash cURL theme={null}
curl -sS -X POST "https://api.dancity.app/api/v1/cable/buy" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "channel: API" \
  -d '{
    "smartcardNumber": "1234567890",
    "cableplan": "GOtv_Supa_Plus_monthly_N16_800",
    "customerName": "John Doe",
    "customerRef": "CABLE-REF-001"
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://api.dancity.app/api/v1/cable/buy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
    "Content-Type": "application/json",
    channel: "API",
  },
  body: JSON.stringify({
    smartcardNumber: "1234567890",
    cableplan: "GOtv_Supa_Plus_monthly_N16_800",
    customerName: "John Doe",
    customerRef: "CABLE-REF-001",
  }),
});
const data = await res.json();
```

```python Python theme={null}
import requests, os

res = requests.post(
    "https://api.dancity.app/api/v1/cable/buy",
    headers={
        "Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
        "Content-Type": "application/json",
        "channel": "API",
    },
    json={
        "smartcardNumber": "1234567890",
        "cableplan": "GOtv_Supa_Plus_monthly_N16_800",
        "customerName": "John Doe",
        "customerRef": "CABLE-REF-001",
    },
)
print(res.json())
```

***

## Full purchase flow

```
1. GET /api/v1/plans/cable
   → list available plans and their names

2. POST /api/v1/cable/validate  { smartcardNumber, cablename }
   → confirm customer identity

3. Show customerName to user → user confirms

4. POST /api/v1/cable/buy
   → send smartcardNumber, cableplan, customerName
```

> [!WARNING]
>
> Do not proceed to purchase if the validation step fails. An invalid smartcard number will result in a failed transaction that may still debit your wallet.

## Next steps

* [Catalog: browse cable plans](https://docs.dancity.app/guides/catalog.md)
* [Transactions: verify purchase status](https://docs.dancity.app/guides/transactions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.