[UPDATED] DSTV Subscription Payment API
This documentation contains the updated flow for integrating DSTV Subscription Payment services on the VTpass RESTful API.
The VTpass DSTV subscription payment API allows you to renew/recharge the subscription on a DSTV decoder using the Smartcard number.
Authentication
The VTpass API uses Basic Authentication.
It should be passed as a concatenated string like this
username:password
Please use the following details for authentication
Username: YourVtpassEmail
Password: YourPassword
Please create your authentication details by following the instructions here.
Updated Endpoints
To integrate the VTpass DSTV Subscription Payment RESTful API, the endpoints below applies:
- Get Variation Codes: this returns variation codes for various dstv bouquets (subscription plans)
- Verify Smartcard Number
- New Product Purchase (Using the variation code gotten in the first step)
- Renew Product (Using the amount gotten from the verify smartcard number endpoint)
- Query transaction status
GET VARIATION CODES
Using a GET method, the VTpass variation codes for DSTV bouquets can be accessed with the endpoint below:
Live: https://vtpass.com/api/service-variations?serviceID=dstv
Sandbox: https://sandbox.vtpass.com/api/service-variations?serviceID=dstv
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{ "response_description":"000", "content":{ "ServiceName":"DSTV", "serviceID":"dstv", "convinience_fee":"100 %", "varations":[ { "variation_code":"dstv1", "name":"DStv Access N2000", "variation_amount":"2000.00", "fixedPrice":"Yes" }, { "variation_code":"dstv2", "name":"DStv Family N4000", "variation_amount":"4000.00", "fixedPrice":"Yes" }, ... ] } }
VERIFY SMARTCARD NUMBER
This endpoint allows you to verify the Smartcard number before attempting to make payment.
This endpoint returns the customer name, current bouquet, subscription due date and the renewal amount (which will be used for BOUQUET RENEWAL).
Using a POST method, you can verify a smartcard numbers with the endpoint below:
Live: https://vtpass.com/api/merchant-verify
Sandbox: https://sandbox.vtpass.com/api/merchant-verify
Smartcard number (billerscode) on sandbox: 1212121212
To simulate a failed smart card number validation on sandbox, please use any number apart from the one provided above as the smart card number.
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
billersCode | M | Number | The smart card number you wish to make the Subscription payment on.
On Sandbox |
serviceID | M | String | Service ID as specified by VTpass. In this case, it is dstv |
EXPECTED RESPONSE
{ "code":"000", "content":{ "Customer_Name":"Mr DsTEST", "Status":"Open", "DUE_DATE":"2019-07-23T00:00:00", "Customer_Number": 48209000, "Customer_Type": "DSTV", "Current_Bouquet": "DStv Premium-Asia N17630 + DStv French only N6050 + DStv Premium-French N20780", "Current_Bouquet_Code": "dstv10, dstv5, dstv9", "Renewal_Amount": 2500 } }
PURCHASE PRODUCT
This endpoint allows you to change or renew a DSTV decoder using its smartcard number.
For product purchase one can totally change the current bouquet of the DSTV decoder or subscribe a fresh bouquet on a DSTV decoder using the NEW PURCHASE/BOUQUET CHANGE endpoint or one can renew the current bouquet using the BOUQUET RENEWAL endpoint.
After carrying out verification, you need to display the following:
- Customer Name
- Customer’s current bouquet Current_Bouquet
- The amount due for renewing the current bouquet. This is in the field Renewal_Amount . Please note that this amount might be different from the real price for renewing the current bouquet due to “promos” or “special offers”
Then you ask the customer if they want to renew the current bouquet at that price OR change their bouquet.
The option selected will determine if you will use the A (Change Bouquet) or B (Bouquet Renewal) option.
Product purchase endpoints are as follows:
A. BOUQUET CHANGE
This endpoint allows you to recharge a DSTV decoder afresh / change the existing bouquet of a DSTV decoder using its smartcard number. This option is for a new subscriber to DSTV or a returning subscriber who would like to change his/her bouquet.
Using a POST method, DSTV Subscription Payment services can be purchased with the endpoint below:
Live: https://vtpass.com/api/pay
Sandbox: https://sandbox.vtpass.com/api/pay
ServiceID: dstv
Smartcard number (billerscode) on sandbox: 1212121212
To simulate a failed transaction on sandbox, please use any number apart from the one provided above as the smart card number.
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
request_id | M | String | This is a unique reference with which you can use to identify and query the status of a given transaction after the transaction has been executed. |
serviceID | M | String | Service ID as specified by VTpass. In this case, it is dstv |
billersCode | M | String | The smart card number you wish to make the Subscription payment on |
variation_code | M | String | The code of the variation of the bouquet (as specified in the GET VARIATIONS method as variation_code). |
amount | O | Number | The amount of the variation (as specified in the GET VARIATIONS endpoint as variation_amount)
NOTE: This is optional. If you specify amount, we will topup decoder with the amount. If you do not specify amount, then we will use the price set for the bouquet (as returned in GET VARIATION CODES endpoint) |
phone | M | Number | The phone number of the customer or recipient of this service |
subscription_type | M | String | The type of subscription in this case change. |
quantity | O | Number | The number of months viewing month e.g 1 |
EXPECTED RESPONSE
{ "code":"000", "content":{ "transactions":{ "status":"initiated", "channel":"api", "transactionId":"1563857332996", "method":"api", "platform":"api", "is_api":1, "discount":null, "customer_id":100649, "email":"sandbox@vtpass.com", "phone":"07061933309", "type":"TV Subscription", "convinience_fee":"0.00", "commission":0.75, "amount":"50", "total_amount":49.25, "quantity":1, "unit_price":"50", "updated_at":"2019-07-23 05:48:52", "created_at":"2019-07-23 05:48:52", "id":7349787 } }, "response_description":"TRANSACTION SUCCESSFUL", "requestId":"SAND000001112A9320223291", "amount":"50.00", "transaction_date":{ "date":"2019-07-23 05:48:52.000000", "timezone_type":3, "timezone":"Africa/Lagos" }, "purchased_code":"" }
B. BOUQUET RENEWAL
This endpoint allows you to renew a DSTV decoder subscription using its smartcard number. This option is strictly for a returning customer who desires to renew his/her current DSTV bouquet. Using this option, there may be a discount on the renewal price [according to the discretion of DSTV] as opposed to the actual cost of the customer’s DSTV bouquet.
NOTE: You are to first verify the DSTV smartcard number using the MERCHANT VERIFY endpoint and use the Renewal_Amount obtained from the MERCHANT VERIFY endpoint as the amount in your request payload.
Using a POST method, DSTV Subscription Payment services can be purchased with the endpoint below:
Live: https://vtpass.com/api/pay
Sandbox: https://sandbox.vtpass.com/api/pay
ServiceID: dstv
Smartcard number (billerscode) on sandbox: 1212121212
To simulate a failed transaction on sandbox, please use any number apart from the one provided above as the smart card number.
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
request_id | M | String | This is a unique reference with which you can use to identify and query the status of a given transaction after the transaction has been executed. |
serviceID | M | String | Service ID as specified by VTpass. In this case, it is dstv |
billersCode | M | String | The smart card number you wish to make the Subscription payment on |
amount | O | Number | The amount of the variation (as specified in the GET VARIATIONS endpoint as variation_amount)
NOTE: This is optional. If you specify amount, we will topup decoder with the amount. If you do not specify amount, then we will use the price set for the bouquet (as returned in GET VARIATION CODES endpoint) |
phone | M | Number | The phone number of the customer or recipient of this service |
subscription_type | M | String | The type of subscription in this case renew. |
EXPECTED RESPONSE
{ "code":"000", "content":{ "transactions":{ "status":"initiated", "channel":"api", "transactionId":"1563857332996", "method":"api", "platform":"api", "is_api":1, "discount":null, "customer_id":100649, "email":"sandbox@vtpass.com", "phone":"07061933309", "type":"TV Subscription", "convinience_fee":"0.00", "commission":0.75, "amount":"50", "total_amount":49.25, "quantity":1, "unit_price":"50", "updated_at":"2019-07-23 05:48:52", "created_at":"2019-07-23 05:48:52", "id":7349787 } }, "response_description":"TRANSACTION SUCCESSFUL", "requestId":"SAND000001112A9320223291", "amount":"50.00", "transaction_date":{ "date":"2019-07-23 05:48:52.000000", "timezone_type":3, "timezone":"Africa/Lagos" }, "purchased_code":"" }
QUERY TRANSACTION STATUS
This endpoint allows you to retrieve data such as status of transaction using the request_id you supplied.
Using a POST method, transaction status can be queried with the endpoint below:
Live: https://vtpass.com/api/requery
Sandbox: https://sandbox.vtpass.com/api/requery
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
request_id | M | String | This is the unique reference provided when carrying out the transaction. |
EXPECTED RESPONSE
{ "code": "000", "content": { "transactions": { "status": "delivered", "product_name": "DSTV Subscription", "unique_element": "1212121212", "unit_price": 1000, "quantity": 1, "service_verification": null, "channel": "api", "commission": 15, "total_amount": 985, "discount": null, "type": "TV Subscription", "email": "sandbox@vtpass.com", "phone": "07061933309", "name": null, "convinience_fee": 0, "amount": 1000, "platform": "api", "method": "api", "transactionId": "1586355735881" } }, "response_description": "TRANSACTION SUCCESSFUL", "requestId": "34762wj2iiwiwjjjajahhhaa768whjjdhshdddsh", "amount": "1000.00", "transaction_date": { "date": "2020-04-08 15:22:15.000000", "timezone_type": 3, "timezone": "Africa/Lagos" }, "purchased_code": "" }
You can check out the complete list of RESPONSE CODES HERE.