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

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.

 

 

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
Use: 1212121212

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": ""
}