Airtime Recharge (Virtual Top up)

This service allows merchants to automate airtime recharge and data services for multiple Nigerian telcos. Similar to 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 . 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: <YOUR_TERMINAL_ID>' \
--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 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 <TOKEN>" \
-H "Content-Type: application/json" \
-H "TerminalID: <YOUR_TERMINAL_ID>" \
-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: "[email protected]",
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 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 <TOKEN>" \
-H "Content-Type: application/json" \
-H "TerminalID: <YOUR_TERMINAL_ID>" \
-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 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 <TOKEN>" \
-H "Content-Type: application/json" \
-H "TerminalID: <YOUR_TERMINAL_ID>" \
-d '{“TerminalId”:<YOUR_TERMINAL_ID>,“paymentCode”:”10403″,“customerId”:”0000000001″,“customerMobile”:”2348056731576″,“customerEmail”:”[email protected]”,“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.