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
Field | Field Name | Date Type | Max Length | Required | Description |
---|---|---|---|---|---|
1 | CustomerId | string | Max | True | This is the id of the customer who is trying to create the voucher |
2 | amount | Long | True | This is the amount of voucher that needs to be created | |
3 | Type | string | 10 | True | This is the type of voucher been created (gift or Recharge) |
4 | ExpiryDate | Datetime | True | This is the expiry date of the voucher | |
5 | CodeConfig | object | false | An object which contains: prefix: string suffix: string allowedChar: string pattern: string |
Redeem Voucher Request - Parameters
Field | Field Name | Date Type | Max Length | Required | Description |
---|---|---|---|---|---|
1 | CustomerId | string | Max | True | This is the id of the customer who is trying to create the voucher |
2 | amount | Long | True | This is the amount of voucher that needs to be created | |
3 | Type | string | 10 | True | This is the type of voucher been created (gift or Recharge) |
4 | ExpiryDate | Datetime | True | This is the expiry date of the voucher | |
5 | CodeConfig | object | false | An 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
Field | Field Name | Description |
---|---|---|
1 | TransactionRef | The transaction reference |
2 | RechargePin | The recharge pin |
3 | ApprovedAmount | The transaction amount |
4 | MiscData | The other miscellaneous data |
5 | AdditionalInfo | The other miscellaneous data |
6 | ResponseCode | The response code from the downstream |
7 | ResponseDescription | The response description of the transaction |
8 | ResponseCodeGrouping | The 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 Code | Description |
---|---|
VS005 | TYPE_CANNOT_BE_EMPTY |
VS007 | UNRECOGNISED_TYPE |
VS008 | VOUCHER_TYPE_NOT ALLOWED |
VS009 | INVALID_START_DATE |
VS010 | BAD_START_DATE_FORMAT |
VS011 | BAD_EXPIRY_DATE_FORMAT |
VS012 | GIFT_OBJECT_NOT_SPECIFIED |
VS013 | DISCOUNT_OBJECT_NOT_SPECIFIED |
VS014 | INVALID_GIFT_BALANCE |
VS015 | INVALID_LENGTH |
VS016 | INVALID_EXPIRY_DATE |
VS017 | INVALID_REDEEM_QUANTITY |
VS019 | INVALID_CODE_CONFIG_LENGTH |
VS021 | NOT_AUTHORISED_TO_REDEEM_VOUCHER |
Response Codes - Redeem Vouchers
Response Code | Description |
---|---|
VS001 | VOUCHER_NOT_FOUND |
VS002 | REDEMPTION_QUANTITY_EXCEEDED |
VS003 | VOUCHER_IS_USED |
VS004 | REDEMPTION_AMOUNT_EXCEEDED |
VS006 | UNRECOGNISED_VOUCHER |
VS018 | ACCESS_DENIED |
VS020 | VOUCHER_NOT_STARTED |
VS021 | NOT_AUTHORIZE_TO_REDEEM_VOUCHER |
Updated 3 months ago