Skip to navigation
VTUAgent Consumable APICable Tv

Purchase Cable TV Subscription

View as Markdown

Renews or changes a cable TV subscription for a smartcard / IUC number.

Before calling: verify the smartcard with POST /v1/cabletv/verify, and fetch a valid package_code + price from POST /v1/cabletv/variations. Send that price as amount.

Your wallet is debited immediately, then the provider is called synchronously. This endpoint does not long-poll or send a webhook — the HTTP response is final unless it is 202 pending, in which case resolve it with POST /v1/transaction/status.

HTTPstatusstatus_codeMeaning
200successful200Subscription activated
202pending202Provider still processing — poll /v1/transaction/status
400error—Bad payload, validation failure, insufficient balance, or duplicate request_ref
401——Missing, invalid or revoked API key
424failed424Provider rejected the purchase — wallet refunded
500error—Provider unreachable

Authentication

AuthorizationBearer

API key issued from the VTUAgent dashboard, sent as Authorization: Bearer {your_api_key}.

Request

This endpoint expects an object.
product_typeenumRequired
Allowed values:
smartcard_numberstringRequired
package_codestringRequired

From POST /v1/cabletv/variations.

amountdouble or stringRequired

Package price from POST /v1/cabletv/variations.

phonestringRequired
subscription_typeenumRequired
Allowed values:
request_refstringRequired<=50 characters

Your unique reference for this transaction, max 50 characters. A UUID is recommended. Re-using one is rejected with 400.

Response

Subscription activated
statusenum
Allowed values:
status_codeenum
Always equals the HTTP status.
Allowed values:
messagestring
referencestringOptional

Echo of your request_ref.

datamap from strings to anyOptional

Product-specific details; see the endpoint examples.

Errors

400
Bad Request Error
401
Unauthorized Error
424
Failed Dependency Error
500
Internal Server Error