Cable TV Subscription
You can integrate cable/TV bill payment purchase in these easy steps:
- List the cable/tv bill payment providers
- List the provider's details
- Validate the customer/smartcard details
- Initiate the bill payment purchase
1. Get the List of Cable/Tv Providers
To start television bill payment, make an API call to the list billers endpoint to fetch all the electricity providers’ details on Anchor. If this is successful, you will receive a list of all electricity providers on Anchor:
| Verb | URL |
|---|---|
GET | {{baseUrl}}/api/v1/bills/billers?category=television |
Sample request payload and sample response payload to list bill payment providers are given below:
curl --request GET \
--url 'https://api.sandbox.getanchor.co/api/v1/bills/billers?category=television' \
--header 'accept: application/json' \
--header 'x-anchor-key: <API Key>'
{
"data": [
{
"id": "168322497570327-anc_blr",
"type": "Provider",
"attributes": {
"name": "GoTV",
"category": "television",
"slug": "gotv"
}
},
{
"id": "168322497263424-anc_blr",
"type": "Provider",
"attributes": {
"name": "DSTV",
"category": "television",
"slug": "dstv"
}
},
{
"id": "16832249694682-anc_blr",
"type": "Provider",
"attributes": {
"name": "Startimes",
"category": "television",
"slug": "startimes"
}
}
],
"meta": {
"pagination": {
"totalPages": 1,
"number": 0,
"size": 20,
"total": 3
}
}
}
2. Get the Provider’s Details
| Verb | URL |
|---|---|
GET | {{baseUrl}}/api/v1/bills/billers/{billerId}/products |
Make the call to the list biller product endpoint and pass the television provider unique identifier billerId to fetch all the products of that provider. In the sample below, the id for Startimes: 16832249694682-anc_blr has been passed.
When you list the biller product, note the slug and price of the cable television product you want to purchase as you will use this in creating the bill payment.
price - price of the of the electricity specified in the country’s lowest currency unit. Price for television is a fixed price.
billerId is the unique Id of the electricity provider on Anchor.
slug is the human readable identifier of the electricity product/plan. When you list a biller product you will see the product slug on each biller product.
curl --request GET \
--url https://api.sandbox.getanchor.co/api/v1/bills/billers/16832249694682-anc_blr/products \
--header 'accept: application/json' \
--header 'x-anchor-key: <API Key>'
{
"data": [
{
"id": "16832249704292-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 10000,
"maximumAmount": 10000,
"currency": "NGN"
},
"name": "Nova - One Day 100 NGN",
"slug": "startimes_nova_one_day_100_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "16832249706917-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 40000,
"maximumAmount": 40000,
"currency": "NGN"
},
"name": "Nova - One Week 400 NGN",
"slug": "startimes_nova_one_week_400_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497086911-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 120000,
"maximumAmount": 120000,
"currency": "NGN"
},
"name": "Nova - One Month 1200 NGN",
"slug": "startimes_nova_one_month_1200_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497102415-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 20000,
"maximumAmount": 20000,
"currency": "NGN"
},
"name": "Basic - One Day 200 NGN",
"slug": "startimes_basic_one_day_200_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497114719-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 70000,
"maximumAmount": 70000,
"currency": "NGN"
},
"name": "Basic - One Week 700 NGN",
"slug": "startimes_basic_one_week_700_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497128423-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 210000,
"maximumAmount": 210000,
"currency": "NGN"
},
"name": "Basic - One Month 2100 NGN",
"slug": "startimes_basic_one_month_2100_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497142127-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 25000,
"maximumAmount": 25000,
"currency": "NGN"
},
"name": "Smart - One Day 250 NGN",
"slug": "startimes_smart_one_day_250_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497159531-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 90000,
"maximumAmount": 90000,
"currency": "NGN"
},
"name": "Smart - One Week 900 NGN",
"slug": "startimes_smart_one_week_900_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497181837-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 280000,
"maximumAmount": 280000,
"currency": "NGN"
},
"name": "Smart - One Month 2800 NGN",
"slug": "startimes_smart_one_month_2800_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497194641-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 32000,
"maximumAmount": 32000,
"currency": "NGN"
},
"name": "Classic - One Day 320 NGN",
"slug": "startimes_classic_one_day_320_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497209544-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 120000,
"maximumAmount": 120000,
"currency": "NGN"
},
"name": "Classic - One Week 1200 NGN",
"slug": "startimes_classic_one_week_1200_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497221249-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 310000,
"maximumAmount": 310000,
"currency": "NGN"
},
"name": "Classic - One Month 3100 NGN",
"slug": "startimes_classic_one_month_3100_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497233854-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 50000,
"maximumAmount": 50000,
"currency": "NGN"
},
"name": "Super - One Day 500 NGN",
"slug": "startimes_super_one_day_500_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497247658-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 180000,
"maximumAmount": 180000,
"currency": "NGN"
},
"name": "Super - One Week 1800 NGN",
"slug": "startimes_super_one_week_1800_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
},
{
"id": "168322497260162-anc_bll_itm",
"type": "Television",
"attributes": {
"price": {
"type": "Fixed",
"minimumAmount": 530000,
"maximumAmount": 530000,
"currency": "NGN"
},
"name": "Super - One Month 5300 NGN",
"slug": "startimes_super_one_month_5300_ngn"
},
"relationships": {
"provider": {
"data": {
"id": "16832249694682-anc_blr",
"type": "Provider"
}
}
}
}
]
}
3. Validation Customer Smartcard Number:
| Verb | Url |
|---|---|
GET | {{baseUrl}}/api/v1/bills/customer-validation/:billprovider_slug/:smartCardNumber |
The customer validation endpoint allows you to verify the name of the smart card number associated with a bill product provider. This endpoint is useful for ensuring that the smart card number provided by the customer is valid and correctly associated with the given provider.
Path Parameters
billprovider-slug: The unique identifier for the bill product provider. This should be replaced with the actual slug for the provider you are validating.
smartCardNumber: The customer smart card number you want to validate.
curl --location 'https://api.sandbox.getanchor.co/api/v1/bills/customer-validation/dstv_dstv_premium_month_1_21000ngn/7030495169' \
--header 'x-anchor-key: <API Key>'
{
"data": {
"id": "0",
"type": "CustomerDetail",
"attributes": {
"customerNumber": "7030495169",
"customerName": "Chinara Uba"
}
}
}
4. Initiate the Cable TV Bill Payment:
When you have identified the cable TV bill you want to purchase, and have validated the customer details, you can proceed to purchase the identified cable tv plan.
| Verb | Url |
|---|---|
GET | {{baseUrl}}/api/v1/bills |
| Attribute | Description |
|---|---|
type | The type for electricity bill payment is Television. |
amount | This is the fixed amount of the cable television plan (specified in the currencies lowest denomination). |
phoneNumber | The phone number of the validated customer |
smartCardNumber | The smart card number for which the bill payment is being made, or the smart card number to be recharged. |
productSlug | The slug of the product for which the payment is being made. |
reference | The unique identifier of the transaction on your system. |
You would need to pass the account id and type (Deposit or Subaccount) where this transaction will be initiated or charged from.
curl --request POST \
--url https://api.sandbox.getanchor.co/api/v1/bills \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-anchor-key: <API Key>' \
--data '
{
"data": {
"attributes": {
"smartCardNumber": "7030495169",
"amount": 290000,
"phoneNumber": "2347012345678",
"reference": "012345ee6789",
"productSlug": "dstv_ngn_2900_00_hdpvr_access_extraview"
},
"relationships": {
"account": {
"data": {
"type": "DepositAccount",
"id": "17145771745590-anc_acc"
}
}
},
"type": "Television"
}
}
'
{
"data": {
"id": "171983017394318-anc_bll",
"type": "BillPayment",
"attributes": {
"reference": "012345wee6789",
"createdAt": "2024-07-01T10:36:13.945347",
"amount": 290000,
"phoneNumber": "2347012345678",
"customerDetail": {
"smartcardNumber": "7030495169"
},
"detail": {
"provider": "DSTV",
"product": "NGN 2900.00 HDPVR Access/Extraview"
},
"category": "television",
"commissionAmount": 0,
"status": "COMPLETED",
"updatedAt": "2024-07-01T10:36:14.905424"
},
"relationships": {
"account": {
"data": {
"id": "17145771745590-anc_acc",
"type": "DepositAccount"
}
},
"customer": {
"data": {
"id": "169558360676414-anc_ind_cst",
"type": "IndividualCustomer"
}
}
}
}
}
Receive webhook events
You will receive bills.initiated events once the bill payment is initiated. If the bill payment is success full, you will receive bills.successful event. If this payment is not successful, you will receive bills.failed event.
{
"data": {
"id": "1719830039954185-anc_et",
"type": "bills.initiated",
"attributes": {
"createdAt": "2024-07-01T10:34:00"
},
"relationships": {
"bill": {
"data": {
"id": "171983003977713-anc_bll",
"type": "BillPayment"
}
},
"account": {
"data": {
"id": "17145771745590-anc_acc",
"type": "DepositAccount"
}
},
"customer": {
"data": {
"id": "169558360676414-anc_ind_cst",
"type": "IndividualCustomer"
}
}
}
}
{
"data": {
"id": "1719830040560187-anc_et",
"type": "bills.successful",
"attributes": {
"createdAt": "2024-07-01T10:34:01"
},
"relationships": {
"bill": {
"data": {
"id": "171983003977713-anc_bll",
"type": "BillPayment"
}
},
"account": {
"data": {
"id": "17145771745590-anc_acc",
"type": "DepositAccount"
}
},
"customer": {
"data": {
"id": "169558360676414-anc_ind_cst",
"type": "IndividualCustomer"
}
}
}
}
You can use the support included functionality when listening to this bill payment event to retrieve other information such as the payment detail or customer detail that is related to this event.
Below is a sample of bills.successful event with included functionality for BillPayment
{
"data": {
"id": "1719830039954185-anc_et",
"type": "bills.initiated",
"attributes": {
"createdAt": "2024-07-01T10:34:00"
},
"relationships": {
"bill": {
"data": {
"id": "171983003977713-anc_bll",
"type": "BillPayment"
}
},
"account": {
"data": {
"id": "17145771745590-anc_acc",
"type": "DepositAccount"
}
},
"customer": {
"data": {
"id": "169558360676414-anc_ind_cst",
"type": "IndividualCustomer"
}
}
}
},
"included": [
{
"id": "171983003977713-anc_bll",
"type": "BillPayment",
"attributes": {
"reference": "012345ee6789",
"createdAt": "2024-07-01T10:34:00",
"amount": 290000,
"phoneNumber": "2347012345678",
"customerDetail": {
"smartcardNumber": "7030495169"
},
"detail": {
"provider": "DSTV",
"product": "NGN 2900.00 HDPVR Access/Extraview"
},
"category": "television",
"commissionAmount": 0,
"status": "COMPLETED",
"updatedAt": "2024-07-01T10:34:01"
},
"relationships": {
"account": {
"data": {
"id": "17145771745590-anc_acc",
"type": "DepositAccount"
}
},
"customer": {
"data": {
"id": "169558360676414-anc_ind_cst",
"type": "IndividualCustomer"
}
}
}
}
]
}
{
"data": {
"id": "1719830040560187-anc_et",
"type": "bills.successful",
"attributes": {
"createdAt": "2024-07-01T10:34:01"
},
"relationships": {
"bill": {
"data": {
"id": "171983003977713-anc_bll",
"type": "BillPayment"
}
},
"account": {
"data": {
"id": "17145771745590-anc_acc",
"type": "DepositAccount"
}
},
"customer": {
"data": {
"id": "169558360676414-anc_ind_cst",
"type": "IndividualCustomer"
}
}
}
},
"included": [
{
"id": "171983003977713-anc_bll",
"type": "BillPayment",
"attributes": {
"reference": "012345ee6789",
"createdAt": "2024-07-01T10:34:00",
"amount": 290000,
"phoneNumber": "2347012345678",
"customerDetail": {
"smartcardNumber": "7030495169"
},
"detail": {
"provider": "DSTV",
"product": "NGN 2900.00 HDPVR Access/Extraview"
},
"category": "television",
"commissionAmount": 0,
"status": "COMPLETED",
"updatedAt": "2024-07-01T10:34:01"
},
"relationships": {
"account": {
"data": {
"id": "17145771745590-anc_acc",
"type": "DepositAccount"
}
},
"customer": {
"data": {
"id": "169558360676414-anc_ind_cst",
"type": "IndividualCustomer"
}
}
}
}
]
}
Updated 9 days ago