The Startimes Subscription Payment API
This section contains the recommended flow for integrating Startimes Subscription Payment services on the VTpass RESTful API.
The VTpass Startimes subscription payment API allows you to renew/recharge the subscription on a Startimes decoder using the Smartcard number.
Authentication
Learn about authentication from here.
Available Endpoints
To integrate the VTpass Startimes Subscription Payment RESTful API, the endpoints below applies:
- Get Variation Codes: this returns variation codes for various Startimes bouquets (subscription plans)
- Verify Smartcard Number
- Purchase Product (Using the variation code gotten in the first step)
- Query transaction status
GET VARIATION CODES
Using a GET method, the VTpass variation codes for Startimes bouquets can be accessed with the endpoint below:
Live: https://vtpass.com/api/service-variations?serviceID=startimes
Sandbox: https://sandbox.vtpass.com/api/service-variations?serviceID=startimes
| FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
| N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{
"response_description":"000",
"content":{
"ServiceName":"Startimes Subscription",
"serviceID":"startimes",
"convinience_fee":"100 %",
"varations":[
{
"variation_code":"nova",
"name":"Nova - 900 Naira - 1 Month",
"variation_amount":"900.00",
"fixedPrice":"Yes"
},
{
"variation_code":"basic",
"name":"Basic - 1,300 Naira - 1 Month",
"variation_amount":"1300.00",
"fixedPrice":"Yes"
},
...
]
}
}
VERIFY SMARTCARD NUMBER
This endpoint allows you to verify the Smartcard number before attempting to make payment.
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 startimes |
EXPECTED RESPONSE
{
"code":"000",
"content":{
"Customer_Name":"Mr DsTEST",
"Status":"Open",
"Customer_ID":"1212121212",
"DUE_DATE":"2019-07-23T00:00:00"
}
}
PURCHASE PRODUCT
This endpoint allows you to recharge a Startimes decoder using it’s smartcard number.
YouCan also use this method to topup a Startimes ewallet.
Using a POST method, Startimes Subscription Payment services can be purchased with the endpoint below:
Live: https://vtpass.com/api/pay
Sandbox: https://sandbox.vtpass.com/api/pay
ServiceID: startimes
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 startimes |
| billersCode | M | String | The smart card number or ewallet 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 |
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": "Startimes Subscription",
"unique_element": "1212121212",
"unit_price": 1000,
"quantity": 1,
"service_verification": null,
"channel": "api",
"commission": 25,
"total_amount": 975,
"discount": null,
"type": "TV Subscription",
"email": "sandbox@vtpass.com",
"phone": "07061933309",
"name": null,
"convinience_fee": 0,
"amount": 1000,
"platform": "api",
"method": "api",
"transactionId": "1586355943878"
}
},
"response_description": "TRANSACTION SUCCESSFUL",
"requestId": "3476iiwiwjjjajahhhaa768whjjdhsjjehdddsh",
"amount": "1000.00",
"transaction_date": {
"date": "2020-04-08 15:25:43.000000",
"timezone_type": 3,
"timezone": "Africa/Lagos"
},
"purchased_code": ""
}
You can check out the complete list of RESPONSE CODES HERE.