### 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": "" } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.