MTN VTU API Integration
This section contains the recommended flow for integrating MTN VTU services on the VTpass RESTful API.
Authentication
Learn about authentication from here.
Available Endpoints
To integrate the VTpass MTN VTU RESTful API, the endpoints below applies:
- Purchase Product
- Query transaction status
Purchase products
Using a POST method, MTN VTU services can be purchased with the endpoint below:
Live: https://vtpass.com/api/pay
Sandbox: https://sandbox.vtpass.com/api/pay
ServiceID: mtn
The sandbox environment provides specific scenarios to simulate success, failure, or unexpected outcomes for airtime 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 |
08011111111 |
Successful | Returns a successful response for testing airtime 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 mtn |
amount | M | Number | The amount you wish to topup |
phone | M | Number | The phone number of the recipient of this service |
EXPECTED RESPONSE
{ "code":"000", "response_description":"TRANSACTION SUCCESSFUL", "requestId":"SAND0192837465738253A1HSD", "transactionId":"1563873435424", "amount":"50.00", "transaction_date":{ "date":"2019-07-23 10:17:16.000000", "timezone_type":3, "timezone":"Africa/Lagos" }, "purchased_code":"" }
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": "MTN Airtime VTU", "unique_element": "08011111111", "unit_price": 1000, "quantity": 1, "service_verification": null, "channel": "api", "commission": 35, "total_amount": 965, "discount": null, "type": "Airtime Recharge", "email": "sandbox@vtpass.com", "phone": "07061933309", "name": null, "convinience_fee": 0, "amount": 1000, "platform": "api", "method": "api", "transactionId": "1586355406511" } }, "response_description": "TRANSACTION SUCCESSFUL", "requestId": "3476wjjse1a2jjjajahhhaa7jjdhshdddsh", "amount": "1000.00", "transaction_date": { "date": "2020-04-08 15:16:46.000000", "timezone_type": 3, "timezone": "Africa/Lagos" }, "purchased_code": "" }
You can check out the complete list of RESPONSE CODES HERE.