Spectranet API

This section contains the recommended flow for integrating Spectranet services on the VTpass RESTful API.

 

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 Spectranet Payment RESTful API, the endpoints below applies:

  • Get Variation Codes: this returns variation codes for various Spectranet (subscription plans)
  • 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 Spectranet subscription plans can be accessed with the endpoint below:

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

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

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

 

EXPECTED RESPONSE

{  
   "response_description":"000",
   "content": {
        "ServiceName": "Spectranet",
        "serviceID": "spectranet",
        "convinience_fee": "0 %",
        "variations": [
            {
                "variation_code": "vt-1000",
                "name": "Spectranet N1000",
                "variation_amount": 1000,
                "fixedPrice": "Yes"
            },
            {
                "variation_code": "vt-2000",
                "name": "Spectranet N2000",
                "variation_amount": 2000,
                "fixedPrice": "Yes"
            },
            ....
        ],
        "varations": [
            {
                "variation_code": "vt-1000",
                "name": "Spectranet N1000",
                "variation_amount": 1000,
                "fixedPrice": "Yes"
            },
            {
                "variation_code": "vt-2000",
                "name": "Spectranet N2000",
                "variation_amount": 2000,
                "fixedPrice": "Yes"
            },
            .....
        ]
    }
}

PURCHASE PRODUCT

Using a POST method, Spectranet bundle can with the endpoint below:

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

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

ServiceID: spectranet

 

The sandbox environment provides specific scenarios to simulate success, failure, or unexpected outcomes for spectranet purchases. Use the examples below to test and observe how your integration behaves.

Refer to the table below to find the correct phone number for simulating various API responses:

Phone Number  Event Description
1212121212 Successful  Returns a successful response for testing spectranet purchases.
201000000000 Pending Simulates an unexpected pending response.
500000000000 Unexpected Response Simulates an expected response, used to test how your system handles anomalies.
400000000000 No Response Simulates a scenario where the API returns no response.
300000000000 Timeout Simulates a timeout scenario for testing response handling under delays.
Any random phone number other than the above Failed Simulates a failed scenario for testing error handling for transaction failure.

 

NEEDED PAYLOAD

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 spectranet
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).
quantity 1 Number The quantity you want to purchase
amount O Number The amount of the variation (as specified in the GET VARIATIONS endpoint as variation_amount)

This amount will be ignored as the variation code determine the price of the data bundle.
phone M Number The phone number of the customer or recipient of this service

 

EXPECTED RESPONSE

{
    "code": "000",
    "content": {
        "transactions": {
            "status": "delivered",
            "product_name": "Spectranet",
            "unique_element": "1212121212",
            "unit_price": 1000,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 40,
            "total_amount": 960,
            "discount": null,
            "type": "Data Services",
            "email": "sandbox@vtpass.com",
            "phone": "07061933309",
            "name": null,
            "convinience_fee": 0,
            "amount": 1000,
            "platform": "api",
            "method": "api",
            "transactionId": "16490633278997623167611852"
        }
    },
    "response_description": "TRANSACTION SUCCESSFUL",
    "requestId": "202204041008ksemeoqykrmtisffmfkd45jkfdjdjjeodlkuwokdckfjf",
    "amount": "1000.00",
    "transaction_date": {
        "date": "2022-04-04 10:08:47.000000",
        "timezone_type": 3,
        "timezone": "Africa/Lagos"
    },
    "purchased_code": "PIN: 08999186, S/N:81560189",
    "cards": [
        {
            "serialNumber": "81560189",
            "pin": "08999186",
            "expiresOn": "2040-10-12",
            "value": 1000
        }
    ]
}

 

QUERY TRANSACTION STATUS

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 reference with which you sent when purchasing a transaction after the transaction has been executed.

 

EXPECTED RESPONSE

{
    "code": "000",
    "content": {
        "transactions": {
            "status": "delivered",
            "product_name": "Spectranet",
            "unique_element": "1212121212",
            "unit_price": 1000,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 40,
            "total_amount": 960,
            "discount": null,
            "type": "Data Services",
            "email": "sandbox@vtpass.com",
            "phone": "07061933309",
            "name": null,
            "convinience_fee": 0,
            "amount": 1000,
            "platform": "api",
            "method": "api",
            "transactionId": "16490633278997623167611852"
        }
    },
    "response_description": "TRANSACTION SUCCESSFUL",
    "requestId": "202204041008ksemeoqykrmtisffmfkd45jkfdjdjjeodlkuwokdckfjf",
    "amount": "1000.00",
    "transaction_date": {
        "date": "2022-04-04 10:08:47.000000",
        "timezone_type": 3,
        "timezone": "Africa/Lagos"
    },
    "purchased_code": "PIN: 08999186, S/N:81560189",
    "cards": [
        {
            "serialNumber": "81560189",
            "pin": "08999186",
            "expiresOn": "2040-10-12",
            "value": 1000
        }
    ]
}