Cable TV smartcard verification API for Nigerian apps
Verify a DStv, GOtv or StarTimes decoder before checkout, distinguish its existing bouquet from the selected package and preserve the confirmed purchase.
Already registered? Open API settings and follow the business-access steps. Sandbox purchases do not deliver real services.
Reviewed
A decoder's current bouquet and the package a customer wants to buy can differ. A checkout that silently copies the existing bouquet into a new order may sell the wrong subscription even when the decoder number is valid.
Select a package, then verify its recipient
Read /products/cabletv with the supported provider parameter when narrowing the catalogue to DSTV, GOTV or STARTIMES. The returned package carries a service attribute. Keep that value with the selected product; it belongs in the purchase body, not in a guessed catalogue parameter.
Call POST /purchases/verify with the selected product_id and the customer's smart_number. Keep the smart number as a string so leading zeros survive form handling and storage. Use a sandbox key and sandbox base URL while developing the flow.
Require data.verified to be true. Read the customer name and decoder details from data.customer. When current_bouquet or due_date is present, show it as context about the verified account. Do not treat those fields as an instruction to change the customer's selected package.
Make the confirmation screen unambiguous
| Information | Source |
|---|---|
| Decoder or smartcard number | The verified target |
| Customer name | The verification response, when available |
| Package being purchased | The selected catalogue product |
| Service | The selected product's service value |
| Amount the customer will pay | Your confirmed retail total |
| Current bouquet | Verification context, when returned |
Keep this confirmation with the order on your server. If the decoder, service or selected package changes, verify the revised selection and ask for confirmation again. A customer who selects an upgrade should see the exact package being ordered; do not promise a particular activation time or proration rule without a confirmed basis for that promise.
Separate verification from fulfillment
A verified decoder is not a completed subscription. After the authorized purchase, persist data.id and inspect data.attributes.status. A pending response should keep the receipt in a processing state. Handle a later successful or reversed outcome against that same order.
For sandbox purchases, use the configured smartcard fixtures. Omit the optional phone number: the simulator chooses its scenario from the first recipient field present, and including a phone number can prevent the smart number from selecting the intended case.
Test a valid decoder with a deliberately changed package, a failed verification and a pending purchase. Confirm that the receipt continues to show the customer's selected package when the catalogue later changes. If the customer reports that channels have not returned, investigate the saved purchase instead of buying another subscription automatically.