Airtime Topup
Basic flow for Airtime Topup API
Sandbox Base URL: https://sandbox.giftbills.com/api/v1
Production Base URL: https://giftbills.com/api/v1
Gift Bills allows Reseller/Agent to topup their customers' airtime via API.
a. Call /api/v1/airtime to get all the avaliable airtime service providers.
b. Call /api/v1/airtime/topup to initialize topup transactions.
Note:- We advise that all tests should be done on our Sandbox environment. After tests have been done successfully and integration completed on the sandbox, kindly request to be provisioned on our Production Environment. Click Here to register sandbox account now.
Getting Airtime Providers
API Endpoint: /airtime
GET method
curl -X GET --header 'Authorization: Bearer API_KEY' --header 'MerchantId: username' --header 'content-type: application/json'
Sample Response
{
"success": true,
"code": "00000",
"message": "Fetched successfully",
"data": [
{
"provider": "AIRTEL",
"providerLogoUrl": "assets/images/bills/Airtel-Airtime.jpg",
"minAmount": "5",
"maxAmount": ""
},
{
"provider": "MTN",
"providerLogoUrl": "assets/images/bills/MTN-Airtime.jpg",
"minAmount": "5",
"maxAmount": ""
},
{
"provider": "GLO",
"providerLogoUrl": "assets/images/bills/GLO-Airtime.jpg",
"minAmount": "5",
"maxAmount": ""
},
{
"provider": "9MOBILE",
"providerLogoUrl": "assets/images/bills/9mobile-Airtime.jpg",
"minAmount": "5",
"maxAmount": ""
}
]
}
| RESPONSE PROPERTY | DESCRIPTION |
|---|---|
| provider | Airtime topup service provider |
| providerLogoUrl | Provider logo URL |
| minAmount | The minimum limit for a single transaction, if it is not returned, it means there is no limit |
| maxAmount | The maximum limit for a single transaction, if it is not returned, it means there is no limit |
To Initiate an Airtime Topup Transaction
API Endpoint: /airtime/topup
POST method
curl -X POST --header 'Authorization: Bearer API_KEY' --header 'MerchantId: username' --header 'content-type: application/json'
Sample Request Body
{
"provider": "MTN",
"number": "07036218209",
"amount": "100",
"reference": "GBR_2459392959593939"
}
| REQUEST PROPERTY | DESCRIPTION |
|---|---|
| MerchantId | Reseller/Agent account username |
| API_KEY | Reseller/Agent account api_key |
| provider | please use the provider returned in airtime-providers |
| number | beneficiary's phone number to recharge/topup |
| amount | Amount to Topup |
| reference | Order number of Reseller/Agent (unique order number from Reseller/Agent platform) |
Sample Response
{
"success": true,
"code": "00000",
"message": "SUCCESSFUL",
"data": {
"orderNo": "211104130931335009",
"reference": "25696593r9622",
"status": "Delivered",
"errorMsg": null
}
}
| RESPONSE PROPERTY | DESCRIPTION |
|---|---|
| orderNo | Order number of Gift Bills payment |
| reference | Reseller/Agent reference (unique order number from Reseller/Agent platform) |
| status | delivered successful Pending Failed |
| errorMsg | Will return actual server response of the transaction or null or no message |