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

Step 1: Make a call to Create Voucher (E pins). This generates a set of random numbers to be used to recharge.
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 .
NOTE: Payment code can be gotten by making a Get Biller Payment Items call.
Step 3: 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.

The diagram below breaks the process flow down:

📘

Endpoint

Create Voucher - https://qa.interswitchng.com/quicktellerservice/api/v5/vouchers/generateVoucher

📘

Endpoint

Redeem Voucher - https://qa.interswitchng.com/quicktellerservice/api/v5/vouchers/redeemVoucher

Headers

Authentication Bearer {{token}}
Content-Type : Appication/Json
TerminalID [yourTerminalID]

{{token}} is generated using guide Generate Access Token

Create Voucher Request - Parameters

FieldField NameDate TypeMax LengthRequiredDescription
1CustomerIdstringMaxTrueThis is the id of the customer who is trying to create the voucher
2amountLongTrueThis is the amount of voucher that needs to be created
3Typestring10TrueThis is the type of voucher been created (gift or Recharge)
4ExpiryDateDatetimeTrueThis is the expiry date of the voucher
5CodeConfigobjectfalseAn object which contains:
prefix: string
suffix: string
allowedChar: string
pattern: string

Redeem Voucher Request - Parameters

FieldField NameDate TypeMax LengthRequiredDescription
1CustomerIdstringMaxTrueThis is the id of the customer who is trying to create the voucher
2amountLongTrueThis is the amount of voucher that needs to be created
3Typestring10TrueThis is the type of voucher been created (gift or Recharge)
4ExpiryDateDatetimeTrueThis is the expiry date of the voucher
5CodeConfigobjectfalseAn object which contains:
prefix: string
suffix: string
allowedChar: string
pattern: string

Sample Requests

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
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 Message Field description

FieldField NameDescription
1TransactionRefThe transaction reference
2RechargePinThe recharge pin
3ApprovedAmountThe transaction amount
4MiscDataThe other miscellaneous data
5AdditionalInfoThe other miscellaneous data
6ResponseCodeThe response code from the downstream
7ResponseDescriptionThe response description of the transaction
8ResponseCodeGroupingThe group the response code belongs

Sample Response

{
TransactionRef: "PBL|Web|3pbl|VOS|020523100514|Y7UYYH3QEG",
RechargePIN:"1220002"
ApprovedAmount: "100",
MiscData:"1220002",
AdditionalInfo:{
1220002:"1220002"
},
ResponseCode: "90000"
ResponseDescription: "Success",
ResponseCodeGrouping: "SUCCESSFUL",
}
{
transactionRef: "PBL|Web|3pbl|CGM|020523100532|XCMNTTMPXJ",
ApprovedAmount: "100",
AdditionalInfo:{},
responseCode: "90000"
responseDescription: "Success",
responseCodeGrouping: "SUCCESSFUL",
}

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