Showmax Subscription Payment API

This documentation contains the updated flow for integrating Showmax Subscription Payment services on the VTpass RESTful API.

The VTpass Showmax subscription payment API allows you to recharge the subscription on your Showmax account using Phone number.

 

Authentication

Learn about authentication from here.

 

 

Updated Endpoints

To integrate the VTpass Showmax Subscription Payment RESTful API, the endpoints below applies:

  • Get Variation Codes: this returns variation codes for Showmax (subscription plans)
  • New Product Purchase (Using the variation code gotten in the first step)
  • Query transaction status

 

GET VARIATION CODES

Using a GET method, the VTpass variation codes for Showmax can be accessed with the endpoint below:

Live:   https://vtpass.com/api/service-variations?serviceID=showmax

Sandbox: https://sandbox.vtpass.com/api/service-variations?serviceID=showmax

FIELDS Mandatory/Optional TYPE DESCRIPTION
N/A N/A N/A N/A

 

EXPECTED RESPONSE

{  
   "response_description":"000",
   "content":{  
      "ServiceName": "ShowMax",
      "serviceID": "showmax",
      "convinience_fee":"100 %",
      "varations":[  
         {
                "variation_code": "full",
                "name": "Full",
                "variation_amount": "2900.00",
                "fixedPrice": "Yes"
            },
            {
                "variation_code": "mobile_only",
                "name": "Mobile Only",
                "variation_amount": "1450.00",
                "fixedPrice": "Yes"
            },
            {
                "variation_code": "sports_full",
                "name": "Sports Full",
                "variation_amount": "6300.00",
                "fixedPrice": "Yes"
            },
            {
                "variation_code": "sports_mobile_only",
                "name": "Sports Mobile Only",
                "variation_amount": "3200.00",
                "fixedPrice": "Yes"
            },
         ...
      ]
   }
}

 

PURCHASE PRODUCT

This endpoint allows you to subscribe to your Showmax account using the customer’s phone number.

Using a POST method, Showmax Subscription Payment services can be purchased with the endpoint below:

Live: https://vtpass.com/api/pay

Sandbox: https://sandbox.vtpass.com/api/pay

ServiceID: showmax

 

Phone number (billerscode) on sandbox: 08011111111

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 showmax
billersCode M String The phone number you wish to make the Subscription payment on
variation_code M String The code of the variation (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)

 

EXPECTED RESPONSE

{
    "response_description": "TRANSACTION SUCCESSFUL",
    "code": "000",
    "content": {
        "transactions": {
            "status": "delivered",
            "product_name": "ShowMax",
            "unique_element": "08011111111",
            "unit_price": 1450,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 29,
            "total_amount": 1421,
            "discount": null,
            "type": "TV Subscription",
            "email": "sandbox@vtpass.com",
            "phone": "08011111111",
            "name": null,
            "convinience_fee": 0,
            "amount": 1450,
            "platform": "api",
            "method": "api",
            "transactionId": "17334640242523229520771662"
        }
    },
    "requestId": "202412060625879psk9020kk2",
    "amount": "1450.00",
    "transaction_date": {
        "date": "2024-12-06 06:47:04.000000",
        "timezone_type": 3,
        "timezone": "Africa/Lagos"
    },
    "purchased_code": "Voucher SHMVHXQ9L3RXGPU",
    "Voucher": [
        "SHMVHXQ9L3RXGPU"
    ]
}

 

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

{
    "response_description": "TRANSACTION SUCCESSFUL",
    "code": "000",
    "content": {
        "transactions": {
            "status": "delivered",
            "product_name": "ShowMax",
            "unique_element": "08011111111",
            "unit_price": 1450,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 29,
            "total_amount": 1421,
            "discount": null,
            "type": "TV Subscription",
            "email": "sandbox@vtpass.com",
            "phone": "08011111111",
            "name": null,
            "convinience_fee": 0,
            "amount": 1450,
            "platform": "api",
            "method": "api",
            "transactionId": "17334640242523229520771662"
        }
    },
    "requestId": "202412060625879psk9020kk2",
    "amount": "1450.00",
    "transaction_date": {
        "date": "2024-12-06 06:47:04.000000",
        "timezone_type": 3,
        "timezone": "Africa/Lagos"
    },
    "purchased_code": "Voucher SHMVHXQ9L3RXGPU",
    "Voucher": [
        "SHMVHXQ9L3RXGPU"
    ]
}

You can check out the complete list of RESPONSE CODES HERE.