API ReferenceDeveloper ConsoleDeveloper Community

Airtime Recharge (Virtual Top-up)

Suggest Edits

By utilising this service, you are able to automate airtime recharge and data services for various telco's in Nigeria. The process is similar to Bills Payment however the major differences are highlighted in this section. This service grants you access to request the Airtime recharge functionality of Quickteller. Merchants are able to integrate to the service and send airtime in two formats to their customers. These formats are the direct top-up or the voucher service (e-pins).

Typically, it is used alongside payments API or a wallet service to perform an actual transaction. Where a payment is made and the wallet is a store of value for your profit which comes from earning a commission.

In a scenario, where you need to allow your users buy airtime for their devices on your website or application, you charge the equivalent amount for the selected purchase on the users card or wallet and provide the appropriate user details and amount to the bills payment API.

Interswitch in turn charges a Virtual card (this is automatically set up for you at the point of go-live) attached to your account the equivalent amount, however you make a commission from every API call based on the commission structure and this profit will remain in your wallet however it can be moved between accounts should you choose to.

Process Flow

Step 1: Make a GET API call to Get Biller Categories. This call will provide a list of available biller categories with their respective category ids. The category for airtime recharge should have the category ID as 4
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.
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. Sample expected values will be MTN-100, MTN-200.
Step 4: Send a Bill Payment Advice to Quickteller. The customer_id field should be the phone number to recharged.
Step 5: 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.

The diagram below explains further:

919

📘

TEST DATA

Test Terminal ID: 3DMO0001

Request Reference/Transfer Code Prefix: 1453

Test SVA Card: 6280511000000095, Dec 2026, 0000

Initiating Entity Code: DMO

RECHARGE (Airtime)
paymentCode: 90101
customerId/customerMobile: 234805673157
billerid: 901, Category: 4

curl https://sandbox.interswitchng.com/api/v2/quickteller/categorys/4/billers \
-H "Authorization: InterswitchAuth <YOUR_AUTHORIZATION_STRING>" \
-H "Content-Type: application/json" \
-H "Signature: <YOUR_COMPUTED SIGNATURE>" \
-H "Timestamp: <CURRENT_TIMESTAMP>" \
-H "Nonce: <YOUR_COMPUTED_NONCE>" \
-H "SignatureMethod: SHA1" \
-H "TerminalID: <YOUR_TERMINAL_ID>" \
-X GET

curl https://sandbox.interswitchng.com/api/v2/quickteller/billers/109/paymentitems \
-H "Authorization: InterswitchAuth <YOUR_AUTHORIZATION_STRING>" \
-H "Content-Type: application/json" \
-H "Signature: <YOUR_COMPUTED SIGNATURE>" \
-H "Timestamp: <CURRENT_TIMESTAMP>" \
-H "Nonce: <YOUR_COMPUTED_NONCE>" \
-H "SignatureMethod: SHA1" \
-H "TerminalID: <YOUR_TERMINAL_ID>" \
-X GET

curl https://sandbox.interswitchng.com/api/v2/quickteller/payments/advices \
-H "Authorization: InterswitchAuth <YOUR_AUTHORIZATION_STRING>" \
-H "Content-Type: application/json" \
-H "Signature: <YOUR_COMPUTED SIGNATURE>" \
-H "Timestamp: <CURRENT_TIMESTAMP>" \
-H "Nonce: <YOUR_COMPUTED_NONCE>" \
-H "SignatureMethod: SHA1" \
-H "TerminalID: <YOUR_TERMINAL_ID>" \
-d '{“TerminalId”:<YOUR_TERMINAL_ID>,“paymentCode”:”10902″,“customerId”:”2348056731576″,“customerMobile”:”2348056731576″,“customerEmail”:”[email protected]”,“amount”:”360000″,“requestReference”:”1194000023″}' \
-X POST

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: ""
}]
}

{
	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"
	}]
}

{
  transactionRef: "DMO|Web|3DMO0001|ZainPIN|010721111153|CJDJUXJUUR",
  responseCode: "90000",
  responseMessage: "Success",
  responseCodeGrouping: "SUCCESSFUL"
}

Updated 7 months ago