Overview
Cable TV purchases are a two-step flow:
- Validate the smartcard number to confirm it exists and retrieve the customer name
- 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.
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") |
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"
}'
Sample response
{
"success": true,
"message": "Validation successful",
"data": {
"customerName": "John Doe"
}
}
Always display customerName to the user for confirmation before proceeding to purchase. This prevents funding the wrong decoder.
Step 2 — Cable subscription
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 |
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"
}'
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
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
