---
updatedAt: 2025-11-11T00:27:51.000Z
agentTools:
projectIndex: https://docs.interswitchgroup.com/v1.1/llms.txt
---
# Airtime Recharge (Virtual Top up)
Quickteller service v5
This service allows merchants to automate airtime recharge and data services for multiple Nigerian telcos. Similar to [Bills Payment](https://docs.interswitchgroup.com/docs/bills-payment), it provides access to Quickteller's Airtime recharge functionality.
## How to Use virtual top-up:
The diagram below explains further:
> 📘 TEST DATA
>
> Test Terminal ID: 3PBL0001
>
> Request Reference/Transfer Code Prefix: 1453
>
> Test SVA Card: 6280511000000095, Dec 2026, 0000
>
> Initiating Entity Code: PBL
>
> RECHARGE (Airtime)\
> paymentCode: 90101\
> customerId/customerMobile: 234805673157\
> billerid: 901, Category: 4
**Step 1:**
Make a **GET** API call to [Get Billers](https://docs.interswitchgroup.com/reference/get-billers) . This call will list available biller categories with their respective **category ids**. The category for **airtime recharge** should have the category ID as **3**
**Request:**
```
curl 'https://qa.interswitchng.com/quicktellerservice/api/v5/services/categories' \
--H 'Authentication: Bearer Token'
--H 'terminalId: ' \
--H 'Content-Type: application/json'
-X GET
```
**Response:**
```
{
"BillerCategories": [
{
"Id": 1,
"Name": "Utility Bills",
"Description": "Pay your utility bills here",
"Billers": []
},
{
"Id": 2,
"Name": "Cable TV Bills",
"Description": "Pay for your cable TV subscriptions here",
"Billers": []
},
{
"Id": 3,
"Name": "State Payments",
"Description": "Pay state taxes",
"Billers": []
},
{
"Id": 4,
"Name": "Mobile/Recharge",
"Description": "Recharge your phone",
"Billers": []
},
{
"Id": 7,
"Name": "Donations",
"Description": "Donate to a worthy cause",
"Billers": []
},
{
"Id": 8,
"Name": "Phone Bills",
"Description": "Pay all post paid phone bills",
"Billers": []
},
{
"Id": 9,
"Name": "Subscriptions",
"Description": "Pay for your other subscriptions (like ISP) here",
"Billers": []
},
{
"Id": 11,
"Name": "Embassy Payments",
"Description": "Make your embassy payments here",
"Billers": []
},
{
"Id": 12,
"Name": "Tax Payments",
"Description": "Tax Payments",
"Billers": []
},
{
"Id": 13,
"Name": "Insurance/Smart",
"Description": "Insurance Payments",
"Billers": []
},
{
"Id": 14,
"Name": "Others",
"Description": "Others",
"Billers": []
},
{
"Id": 15,
"Name": "Airlines",
"Description": "Airlines",
"Billers": []
},
{
"Id": 16,
"Name": "Transport",
"Description": "Transport",
"Billers": []
},
{
"Id": 17,
"Name": "Products and Services",
"Description": "Products and Services",
"Billers": []
},
{
"Id": 18,
"Name": "Funds Transfer",
"Description": "Funds Transfer",
"Billers": []
},
{
"Id": 19,
"Name": "Microfinance",
"Description": "Microfinance",
"Billers": []
},
{
"Id": 20,
"Name": "Mobile Money",
"Description": "Load your mobile wallet",
"Billers": []
},
{
"Id": 22,
"Name": "PayChoice",
"Description": "Upperlink PayChoice Schools",
"Billers": []
},
{
"Id": 23,
"Name": "Event Tickets",
"Description": "Event Tickets",
"Billers": []
},
{
"Id": 24,
"Name": "Quickteller Business",
"Description": "Revenue Collections",
"Billers": []
},
{
"Id": 25,
"Name": "Transfer Money",
"Description": "Transfers money to various destinations",
"Billers": []
},
{
"Id": 26,
"Name": "Receive Money",
"Description": "Receives money from various sources",
"Billers": []
},
{
"Id": 27,
"Name": "Religious Institutions",
"Description": "Give for Religious cause",
"Billers": []
}
],
"ResponseCode": "90000",
"ResponseCodeGrouping": "SUCCESSFUL"
}
```
**Step 2:**
Make a subsequent call to [Get Billers by Category](https://docs.interswitchgroup.com/reference/get-billers-by-category-2) while passing the required query parameter - **category id** (should be the value 4). This will provide a list of available telcos with their respective **biller ids**.
**Request:**
```
curl 'https://qa.interswitchng.com/quicktellerservice/api/v5/services?categoryId={id}' \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-H "TerminalID: " \
-X GET
```
**Response:**
```
{
billers: [{
categoryid: "4",
categoryname: "Mobile Recharge",
categorydescription: "Recharge your phone",
billerid: "901",
billername: "Airtel Mobile Top-Up",
customerfield1: "Phone Number",
customerfield2: "",
supportemail: "oadeoye@interswitchng.com",
paydirectProductId: "0",
paydirectInstitutionId: "0",
narration: "Top up your line automatically",
shortName: "ZainMTU",
surcharge: "0",
currencyCode: "566",
quickTellerSiteUrlName: "zainmtu",
riskCategoryId: "",
amountType: "null",
pageFlowInfo: {
allowRetry: true,
finishButtonName: "Finish",
performInquiry: true,
startPage: "DoPayment.aspx",
usesPaymentItems: true
},
currencySymbol: "NGN",
customMessageUrl: "",
customSectionUrl: "",
logoUrl: "zain2.gif",
networkId: "6280510420",
productCode: "6280510421",
type: "MO",
url: ""
}]
}
```
**Step 3:**
You can then proceed to make a call to [Get Biller Payment Items](https://docs.interswitchgroup.com/reference/get-biller-payment-item) while passing the required path parameter - **biller id**. This will provide a list of airtimes supported by the telco.
The sample's expected values will be MTN-100 and MTN-200.
**Request:**
```
curl 'https://qa.interswitchng.com/quicktellerservice/api/v5/services/options?serviceid={billerid}' \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-H "TerminalID: " \
-X GET
```
**Response:**
```
{
paymentitems: [{
categoryid: "4",
billerid: "109",
isAmountFixed: false,
paymentitemid: "02",
paymentitemname: "MTN 200",
amount: "20000",
billerType: "MO",
code: "02",
currencyCode: "566",
currencySymbol: "NGN",
itemCurrencySymbol: "",
sortOrder: "0",
pictureId: "0",
paymentCode: "10902",
itemFee: "0",
paydirectItemCode: "02"
}]
}
```
**Step 4:**
Send a [Bill Payment Advice](https://docs.interswitchgroup.com/reference/send-transaction) to Quickteller. The **customer\_id** field should be the phone number to be recharged.
**Request:**
```
curl' https://qa.interswitchng.com/quicktellerservice/api/v5/Transactions' \
-H "Authentication: Bearer " \
-H "Content-Type: application/json" \
-H "TerminalID: " \
-d '{“TerminalId”:,“paymentCode”:”10403″,“customerId”:”0000000001″,“customerMobile”:”2348056731576″,“customerEmail”:”johndoe@gmail.com”,“amount”:”360000″,“requestReference”:”1194000023″}' \
-X POST
```
**Response:**
```
{
transactionRef: "PBL|Web|3PBL0001|ZainPIN|010721111153|CJDJUXJUUR",
responseCode: "90000",
responseMessage: "Success",
responseCodeGrouping: "SUCCESSFUL"
}
```
If the transaction is successful, a virtual card tied to your account is debited, and value is given to the customer. If the transaction fails, there will be no debit to the virtual card.