API reference

Purchase cable TV

Purchase a cable TV subscription. Request fields, response examples and integration guidance.

POST /purchases/cable-tv

Example request

Server-side HTTP request

curl --request POST \
  --url "https://api.strongmb.ng/v1/purchases/cable-tv" \
  --header "Authorization: Bearer $STRONGMB_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
  "smart_card_number": "0123456789",
  "product_code": "smb_dst_pla_0c506",
  "reference": "SMB202609160001",
  "verify_token": "YVVIeHIwMTNmVXlZWEp3dnlGeUQwSlJpYkVRZmYyMXpscDNlZW9kY0s3VT0="
}'

// Server-side Node.js 22+; never expose your key in a browser.
async function main() {
  const response = await fetch("https://api.strongmb.ng/v1/purchases/cable-tv", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STRONGMB_API_KEY}`,
      Accept: "application/json",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
  "smart_card_number": "0123456789",
  "product_code": "smb_dst_pla_0c506",
  "reference": "SMB202609160001",
  "verify_token": "YVVIeHIwMTNmVXlZWEp3dnlGeUQwSlJpYkVRZmYyMXpscDNlZW9kY0s3VT0="
}),
    signal: AbortSignal.timeout(30000)
  });
  const result = await response.json();
  console.log(response.status, result);
  // For purchases, inspect data.status before showing a receipt.
}
main().catch(console.error);

<?php
// Requires the PHP cURL extension.
$client = curl_init('https://api.strongmb.ng/v1/purchases/cable-tv');
curl_setopt_array($client, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('STRONGMB_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "smart_card_number": "0123456789",
  "product_code": "smb_dst_pla_0c506",
  "reference": "SMB202609160001",
  "verify_token": "YVVIeHIwMTNmVXlZWEp3dnlGeUQwSlJpYkVRZmYyMXpscDNlZW9kY0s3VT0="
}',
]);
$raw = curl_exec($client);
if ($raw === false) {
    throw new RuntimeException(curl_error($client));
}
$status = curl_getinfo($client, CURLINFO_HTTP_CODE);
curl_close($client);
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
print_r(['http_status' => $status, 'response' => $result]);
// For purchases, inspect data.status before showing a receipt.

require 'net/http'
require 'json'

uri = URI('https://api.strongmb.ng/v1/purchases/cable-tv')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'
http.open_timeout = 10
http.read_timeout = 30
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer ' + ENV.fetch('STRONGMB_API_KEY')
request['Accept'] = 'application/json'
request['Content-Type'] = 'application/json'
request.body = '{
  "smart_card_number": "0123456789",
  "product_code": "smb_dst_pla_0c506",
  "reference": "SMB202609160001",
  "verify_token": "YVVIeHIwMTNmVXlZWEp3dnlGeUQwSlJpYkVRZmYyMXpscDNlZW9kY0s3VT0="
}'
begin
  response = http.request(request)
  result = JSON.parse(response.body)
  puts({ http_status: response.code, response: result }.to_json)
rescue StandardError => error
  warn error.message
end
# Reconcile an uncertain purchase before retrying.

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError

headers = {
    "Authorization": "Bearer " + os.environ["STRONGMB_API_KEY"],
    "Accept": "application/json",
    "Content-Type": "application/json",
}
payload = {'smart_card_number': '0123456789',
 'product_code': 'smb_dst_pla_0c506',
 'reference': 'SMB202609160001',
 'verify_token': 'YVVIeHIwMTNmVXlZWEp3dnlGeUQwSlJpYkVRZmYyMXpscDNlZW9kY0s3VT0='}
body = json.dumps(payload).encode("utf-8")
request = Request(
    "https://api.strongmb.ng/v1/purchases/cable-tv",
    data=body, headers=headers, method="POST"
)
try:
    with urlopen(request, timeout=30) as response:
        result = json.load(response)
        print(response.status, result)
except HTTPError as error:
    print(error.code, error.read().decode("utf-8"))
except URLError as error:
    print("Network error:", error.reason)
# Reconcile an uncertain purchase before retrying.

Subscribes the customer to a cable TV plan. Requires a valid verify_token from the customer validation step.

Request Body

Field	Type	Required	Description
smart_card_number	string	Required	The customer's smart card number
product_code	string	Required	Product code of the plan from `/products/cable-tv`
reference	string	Required	Your unique transaction reference. a-zA-Z0-9 only, 10–255 characters
verify_token	string	Required	The token returned from `/customer-validation/cable-tv`

Request Example

JSON Payload

{
  "smart_card_number": "0123456789",
  "product_code": "smb_dst_pla_0c506",
  "reference": "SMBD260aad1352sdda53ssdC9",
  "verify_token": "YVVIeHIwMTNmVXlZWEp3dnlGeUQwSlJpYkVRZmYyMXpscDNlZW9kY0s3VT0="
}

JSON — 201 Successful

{
  "status": true,
  "message": "Transaction completed successfully.",
  "data": {
    "status": "successful",
    "type": "cable_tv",
    "provider": "dstv",
    "title": "₦2,400 Subscription",
    "recipient": "0123456789",
    "recipient_name": null,
    "package_name": "Nova - 1 Month",
    "package_amount": 2400,
    "fee": "0.00",
    "reference": "SMBD260aa1352dda53aawasss7ssFAsdC9",
    "date": "2026-08-09 23:11:20",
    "currency": "NGN",
    "balance_before": "676888.55",
    "balance_after": "674488.55",
    "amount": "2400.00"
  },
  "metadata": { "code": "TRANSACTION_SUCCESSFUL", "timestamp": 1786313487, "trace_id": "0B890B3763" }
}

JSON — 200 Processing

{
  "status": true,
  "message": "Cable tv subscription is being processed.",
  "data": {
    "status": "processing",
    "type": "cable_tv",
    "provider": "dstv",
    "title": "₦2,400 Subscription",
    "recipient": "0123456789",
    "recipient_name": null,
    "package_name": "Nova - 1 Month",
    "package_amount": 2400,
    "fee": "0.00",
    "reference": "SMBD260aad1352dda53aawasss7ssFAsdC9",
    "date": "2026-08-09 23:11:47",
    "currency": "NGN",
    "balance_before": "674488.55",
    "balance_after": "672088.55",
    "amount": "2400.00"
  },
  "metadata": { "code": "ERR_TRANSACTION_PROCESSING", "timestamp": 1786313515, "trace_id": "880E71335E" }
}

JSON — 200 Failed (refunded)

{
  "status": false,
  "message": "Your transaction has failed, amount has been refunded to your wallet.",
  "data": {
    "status": "failed",
    "type": "cable_tv",
    "provider": "dstv",
    "title": "₦2,400 Subscription",
    "recipient": "0123456789",
    "package_name": "Nova - 1 Month",
    "package_amount": 2400,
    "reference": "SMBD260aad35dffdg2fsddak53ssdC9",
    "date": "2026-08-09 23:16:13",
    "currency": "NGN"
  },
  "metadata": { "code": "ERR_TRANSACTION_FAILED", "timestamp": 1786313790, "trace_id": "2C9EE727A6" }
}

JSON — 409 Duplicate Reference

{
  "status": false,
  "message": "Reference already exist. Please use a unique reference.",
  "data": null,
  "metadata": { "code": "ERR_REFERENCE_ALREADY_EXISTS", "timestamp": 1786313474, "trace_id": "0CB29BB82A" }
}

JSON — 402 Insufficient Balance

{
  "status": false,
  "message": "Insufficient wallet balance.",
  "data": null,
  "metadata": { "code": "ERR_INSUFFICIENT_BALANCE", "timestamp": 1786313600, "trace_id": "1D2E3F4A5B" }
}

Response Codes

Code	HTTP	Meaning
TRANSACTION_SUCCESSFUL	201	Subscription activated. Funds deducted and service delivered.
ERR_TRANSACTION_PROCESSING	200	Transaction submitted, pending provider confirmation. Poll by `reference`.
ERR_TRANSACTION_FAILED	200	Transaction attempted but failed. Amount automatically refunded to wallet.
ERR_REFERENCE_ALREADY_EXISTS	400	This reference is already used. Each transaction must have a unique reference.
ERR_INSUFFICIENT_BALANCE	402	Wallet balance is too low. Fund your wallet and retry.

The verify_token is single-use and expires. Always verify the smart card immediately before purchasing — do not cache and reuse tokens across separate purchase attempts.

Understand the request fields

Field	Integration guidance
`smart_card_number`	The customer or smart-card number. Confirm the returned customer identity before purchase.
`product_code`	An exact identifier from the matching product list, not a provider name or an identifier from a different API.
`amount`	Amount in Nigerian naira, not kobo. Check the current product price and minimum before submitting.
`reference`	Your saved identifier for this intended purchase. Use 10–255 letters or digits. Duplicate references are rejected.
`verify_token`	The opaque customer-validation token. Send it unchanged for the same customer. Validate again if the customer number changes.

Handle the purchase result

Show a receipt only for a successful outcome. Keep processing transactions pending. Reconcile failed or timed-out purchases before another attempt.

Transaction lifecycle · Troubleshoot errors

Response fields and types

Expand an object to explore its fields. [] indicates an array item. Error responses may return data: null.

Field path	JSON type	Meaning and handling
`status`	boolean	Request-level success flag. Check the HTTP status and metadata code as well; a successful API request is not by itself proof of purchase fulfillment.
`message`	string	Human-readable description of the result. Use metadata.code for programmatic error handling instead of parsing this text.
`data`	null \| object	Response data. Check the result before reading nested fields; an error may return null or validation details.
`data.status`	string	Purchase outcome: successful, processing or failed. Use this field rather than the top-level status flag to decide whether a purchase completed.
`data.type`	string	Service or transaction type, for example data, airtime, electricity or cable TV.
`data.provider`	string	Provider identifier associated with the purchased service.
`data.title`	string	Short display title for the transaction receipt.
`data.recipient`	string	Phone number, meter or customer identifier for the purchase. Compare it with the intended recipient.
`data.recipient_name`	null \| string	Customer name when available. A null value means the response does not provide a name.
`data.package_name`	string	Display name of the cable TV package.
`data.package_amount`	number	Face value or price reported for the selected package. Compare with the current product list.
`data.fee`	string	Additional fee reported for the purchase.
`data.reference`	string	Reference supplied when creating the purchase. Save it and use the same value for transaction verification.
`data.date`	string	Transaction date/time string returned for display.
`data.currency`	string	Currency code, such as NGN for Nigerian naira.
`data.balance_before`	string	Wallet balance before this transaction, as reported by the API.
`data.balance_after`	string	Wallet balance after this transaction, as reported by the API.
`data.amount`	string	Amount debited from your wallet for this purchase, in the indicated currency.
`metadata`	object	Diagnostic information about the response.
`metadata.code`	string	Machine-readable result code. Use it to distinguish validation, authentication and service errors.
`metadata.timestamp`	integer	Unix timestamp in seconds associated with the response.
`metadata.trace_id`	string	Correlation identifier for troubleshooting. Retain it with a redacted request when contacting support.

Always check metadata.code; do not rely on HTTP status alone. See response codes and recommended handling.

Test your integration Use the sandbox test values and examples.

Questions? Let’s work through them.

Having an issue or need help with your integration? Join the Strongmb Slack community to ask questions and get assistance from our team and other developers.

Keep API keys and customer details private when sharing examples.

Experiencing a service issue? Check Strongmb’s service status for incident updates.

Join our Slack community