Airtime Recharge (E-pins)

Quickteller Service v5

📘

This service is only available in Nigeria

E pins (Voucher service)

E-pins also known as voucher service is an airtime recharge service that enables merchants resell airtime to their customers in the form of a 16-20 digit code. Merchants make profit on a transaction basis and by integrating this endpoint, merchants will be able to create and redeem vouchers on any network across Nigeria.

Process flow

The diagram below breaks the process flow down:

Step 1:

Make a call to Create Voucher (E pins).

This generates a set of random numbers to be used to recharge.

Request:

curl https://qa.interswitchng.com/quicktellerservice/api/v5/vouchers/generateVoucher \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-H "TerminalID: <your_terminal_id>" \
-D '{
    "customerId": "234131670272",
    "amount": "100",
    "type": "GIFT",
    "expiryDate": "2023-06-22"
    "codeConfig": {
    "prefix": "1",
    "suffix":"2",
    "length":5,
    "allowedChar":"12890",
    "pattern":""
    
    }
   
}'
-X POST

Response:

{
TransactionRef: "PBL|Web|3pbl|VOS|020523100514|Y7UYYH3QEG",
RechargePIN:"1220002"
ApprovedAmount: "100",
MiscData:"1220002",
AdditionalInfo:{
1220002:"1220002"
},
ResponseCode: "90000"
ResponseDescription: "Success",
ResponseCodeGrouping: "SUCCESSFUL",
}

Step 2:

Make a call to Redeem Voucher (E pins).

The generated numbers in step 1 above, the phone number to be recharged and the payment code of the provider of the voucher are required for this call.

The voucher can only be redeemed before the expiryDate defined during the creation of the voucher .

Request:

curl https://qa.interswitchng.com/quicktellerservice/api/v5/vouchers/redeemVoucher \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-H "TerminalID: <your_terminal_id>" \
-D '{
    "customerId": "234131670272",
    "customerEmail" :"[email protected]",
    "customerMobile" :"2349124888776",
    "paymentCode": "52005",
    "amount": "100",
    "voucherCode":"1220002"
}'
-X POST

Response:

{
transactionRef: "PBL|Web|3pbl|CGM|020523100532|XCMNTTMPXJ",
ApprovedAmount: "100",
AdditionalInfo:{},
responseCode: "90000"
responseDescription: "Success",
responseCodeGrouping: "SUCCESSFUL",
}

📘

Payment code can be gotten by making a Get Biller Payment Items call.

If the transaction is successful, the virtual card tied to the partner is debited at redemption. However, if it fails, there will be no debit to the virtual card.

Response Codes - Create Vouchers

Response CodeDescription
VS005TYPE_CANNOT_BE_EMPTY
VS007UNRECOGNISED_TYPE
VS008VOUCHER_TYPE_NOT ALLOWED
VS009INVALID_START_DATE
VS010BAD_START_DATE_FORMAT
VS011BAD_EXPIRY_DATE_FORMAT
VS012GIFT_OBJECT_NOT_SPECIFIED
VS013DISCOUNT_OBJECT_NOT_SPECIFIED
VS014INVALID_GIFT_BALANCE
VS015INVALID_LENGTH
VS016INVALID_EXPIRY_DATE
VS017INVALID_REDEEM_QUANTITY
VS019INVALID_CODE_CONFIG_LENGTH
VS021NOT_AUTHORISED_TO_REDEEM_VOUCHER

Response Codes - Redeem Vouchers

Response CodeDescription
VS001VOUCHER_NOT_FOUND
VS002REDEMPTION_QUANTITY_EXCEEDED
VS003VOUCHER_IS_USED
VS004REDEMPTION_AMOUNT_EXCEEDED
VS006UNRECOGNISED_VOUCHER
VS018ACCESS_DENIED
VS020VOUCHER_NOT_STARTED
VS021NOT_AUTHORIZE_TO_REDEEM_VOUCHER