VTpass API

https://www.vtpass.com/documentation
Admin
VTpass API is a RESTful API that allows developers to integrate bills payment and messaging services...
Tokens:3,784
Snippets:44
Trust Score:9.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Request ID format example

Source: https://www.vtpass.com/documentation/how-to-generate-request-id

Example of a valid request ID string using the required timestamp prefix.

```text
"request_id" => "202202071830YUs83meikd"
```

--------------------------------

### GET Request Authentication Headers

Source: https://www.vtpass.com/documentation/authentication

Include these headers in the request to authenticate GET operations.

```http
api-key: xxxxxxxxxxxxxxxxxxxx
public-key: PK_xxxxxxxxxxxxxxxxx
```

--------------------------------

### API Key Authentication Headers

Source: https://www.vtpass.com/documentation/authentication

Instructions for including API keys in request headers for GET and POST operations.

```APIDOC
## API Key Authentication

### Description
VTpass requires API keys to be passed in the request headers for authentication. The specific keys required depend on the HTTP method used.

### GET Request Headers
- **api-key**: Required - Your static API key.
- **public-key**: Required - Your public key (PK_...).

### POST Request Headers
- **api-key**: Required - Your static API key.
- **secret-key**: Required - Your secret key (SK_...).
```

--------------------------------

### Retrieve Service Variations Response

Source: https://www.vtpass.com/documentation/variation-codes

Example JSON response structure returned when querying service variations for a specific product.

```json
{
   "response_description":"000",
   "content": {
      "ServiceName":"GOTV Payment",
      "serviceID":"gotv",
      "convinience_fee":"100 %",
      "variations":[
         {
            "variation_code":"gotv-lite",
            "name":"GOtv Lite N400",
            "variation_amount":"400.00",
            "fixedPrice":"Yes"
         },
         {
            "variation_code":"gotv-value",
            "name":"GOtv value N1250",
            "variation_amount":"1250.00",
            "fixedPrice":"Yes"
         },
         ...
      ],
   }
}
```

--------------------------------

### Get Service Categories Response

Source: https://www.vtpass.com/documentation/available-services

The expected JSON response structure when querying the service categories endpoint.

```json
{
    "response_description": "000",
    "content": [
        {
            "identifier": "airtime",
            "name": "Airtime Recharge"
        },
        {
            "identifier": "data",
            "name": "Data Services"
        },
        {
            "identifier": "tv-subscription",
            "name": "TV Subscription"
        },
        {
            "identifier": "electricity-bill",
            "name": "Electricity Bill"
        },
        {
            "identifier": "education",
            "name": "Education"
        },
        {
            "identifier": "other-services",
            "name": "Other Merchants/Services"
        },
        {
            "identifier": "insurance",
            "name": "Insurance"
        }
    ]
}
```

--------------------------------

### GET /api/service-categories

Source: https://www.vtpass.com/documentation/available-services

Retrieves a list of all available service categories, such as airtime, data, and utility payments.

```APIDOC
## GET /api/service-categories

### Description
Retrieves the list of available service categories supported by the VTpass platform.

### Method
GET

### Endpoint
https://vtpass.com/api/service-categories

### Response
#### Success Response (200)
- **response_description** (string) - Status code indicating success (e.g., "000").
- **content** (array) - List of service objects.

#### Response Example
{
    "response_description": "000",
    "content": [
        {
            "identifier": "airtime",
            "name": "Airtime Recharge"
        },
        {
            "identifier": "data",
            "name": "Data Services"
        },
        {
            "identifier": "tv-subscription",
            "name": "TV Subscription"
        },
        {
            "identifier": "electricity-bill",
            "name": "Electricity Bill"
        },
        {
            "identifier": "education",
            "name": "Education"
        },
        {
            "identifier": "other-services",
            "name": "Other Merchants/Services"
        },
        {
            "identifier": "insurance",
            "name": "Insurance"
        }
    ]
}
```

--------------------------------

### GET /api/service-variations

Source: https://www.vtpass.com/documentation/variation-codes

Retrieves the list of variation codes for a specific service, such as cable TV bouquets or data plans.

```APIDOC
## GET /api/service-variations

### Description
Retrieves the available variation codes for a given service ID. This is used to identify specific product options like data plans or cable TV bouquets.

### Method
GET

### Endpoint
https://vtpass.com/api/service-variations

### Parameters
#### Query Parameters
- **serviceID** (string) - Mandatory - The unique identifier for the service to retrieve variations for.

### Response
#### Success Response (200)
- **response_description** (string) - Status code description.
- **content** (object) - Contains the service details and list of variations.

#### Response Example
{
   "response_description": "000",
   "content": {
      "ServiceName": "GOTV Payment",
      "serviceID": "gotv",
      "convinience_fee": "100 %",
      "variations": [
         {
            "variation_code": "gotv-lite",
            "name": "GOtv Lite N400",
            "variation_amount": "400.00",
            "fixedPrice": "Yes"
         }
      ]
   }
}
```

--------------------------------

### Transaction Status Requery Response

Source: https://www.vtpass.com/documentation/re-query-services

Example JSON response returned by the requery endpoint upon a successful transaction status lookup.

```json
{
    "response_description": "TRANSACTION SUCCESSFUL",
    "code": "000",
    "content": {
        "transactions": {
            "status": "delivered",
            "product_name": "MTN Airtime VTU",
            "unique_element": "08011111111",
            "unit_price": 20,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 1,
            "total_amount": 19.3,
            "discount": null,
            "type": "Airtime Recharge",
            "email": "sandbox@sandbox.vtpass.com",
            "phone": "123450987623",
            "name": null,
            "extras": null,
            "convinience_fee": 0,
            "amount": 20,
            "platform": "api",
            "method": "wallet",
            "transactionId": "17415980564672211596777904",
            "product_id": 2,
            "commission_details": {
                "amount": 1,
                "rate": "3.50",
                "rate_type": "percent",
                "computation_type": "default"
            }
        }
    },
    "requestId": "2025031010146932932",
    "amount": 20,
    "transaction_date": "2025-03-10T09:14:16.000000Z",
    "purchased_code": ""
}
```

--------------------------------

### Verification Response Codes

Source: https://www.vtpass.com/documentation/response-codes

A list of response codes returned during DSTV, GOTV, Startimes, and electricity meter verification requests.

```APIDOC
## Verification Response Codes

| Response Code | Meaning | Note |
|---|---|---|
| 020 | BILLER CONFIRMED | BILLER CONFIRMED |
| 011 | INVALID ARGUMENTS | You are not passing at least one of the arguments expected in your request. |
| 012 | PRODUCT DOES NOT EXIST | PRODUCT DOES NOT EXIST |
| 030 | BILLER NOT REACHABLE AT THIS POINT | The biller for the product or service is unreachable. |

### Note
If any of the above status codes are received during a product purchase, the transaction should be treated as failed.
```

--------------------------------

### Expected Callback Response

Source: https://www.vtpass.com/documentation/callback-api-integration

The required JSON response format to acknowledge receipt of a webhook request.

```json
{
    "response":"success"
}
```

--------------------------------

### POST Request Authentication Headers

Source: https://www.vtpass.com/documentation/authentication

Include these headers in the request to authenticate POST operations.

```http
api-key: xxxxxxxxxxxxxxxxxxxx 
secret-key: SK_xxxxxxxxxxxxxxxxx
```

--------------------------------

### POST Callback Endpoint

Source: https://www.vtpass.com/documentation/callback-api-integration

The endpoint on your server that receives POST requests from VTpass for transaction status or variation code updates.

```APIDOC
## POST [Your Callback URL]

### Description
Receives automated updates from VTpass regarding transaction status changes or variation code updates.

### Method
POST

### Request Body
- **type** (string) - Required - Defines the type of callback sent.
- **data** (object) - Required - Contains the specific data required for the action.

### Response
#### Success Response (200)
- **response** (string) - Must be set to "success" to acknowledge receipt.

### Response Example
{
    "response": "success"
}
```

--------------------------------

### POST /api/requery

Source: https://www.vtpass.com/documentation/re-query-services

Retrieves the status and details of a transaction using the unique request_id.

```APIDOC
## POST /api/requery

### Description
This endpoint allows you to retrieve the status of a transaction using the request_id you supplied during the initial transaction.

### Method
POST

### Endpoint
https://vtpass.com/api/requery (Live) or https://sandbox.vtpass.com/api/requery (Sandbox)

### Parameters
#### Request Body
- **request_id** (String) - Mandatory - The unique reference provided when carrying out the transaction.

### Response
#### Success Response (200)
- **response_description** (String) - Status message of the transaction.
- **code** (String) - Response code indicating the result.
- **content** (Object) - Detailed transaction information including status, product name, and pricing.
- **requestId** (String) - The request ID associated with the query.
- **amount** (Number) - The transaction amount.
- **transaction_date** (String) - The date and time of the transaction.

### Response Example
{
    "response_description": "TRANSACTION SUCCESSFUL",
    "code": "000",
    "content": {
        "transactions": {
            "status": "delivered",
            "product_name": "MTN Airtime VTU",
            "unique_element": "08011111111",
            "unit_price": 20,
            "quantity": 1,
            "service_verification": null,
            "channel": "api",
            "commission": 1,
            "total_amount": 19.3,
            "discount": null,
            "type": "Airtime Recharge",
            "email": "sandbox@sandbox.vtpass.com",
            "phone": "123450987623",
            "name": null,
            "extras": null,
            "convinience_fee": 0,
            "amount": 20,
            "platform": "api",
            "method": "wallet",
            "transactionId": "17415980564672211596777904",
            "product_id": 2,
            "commission_details": {
                "amount": 1,
                "rate": "3.50",
                "rate_type": "percent",
                "computation_type": "default"
            }
        }
    },
    "requestId": "2025031010146932932",
    "amount": 20,
    "transaction_date": "2025-03-10T09:14:16.000000Z",
    "purchased_code": ""
}
```
Tokens:
Raw