[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://api-service.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://api-service.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 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://api-service.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.

Click here to understand how to generate a valid request ID
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 M 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://api-service.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.

Click here to understand how to generate a valid request ID
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 M 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://api-service.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.