Redeem Voucher (E pins)

Process Flow

When you request a getBillerCategories endpoint, the Airtime Recharge category has the ID 4.
Hence, to get a list of all the billers in this category, you need to send the getBillersByCategory endpoint using 4 as the biller category. Your response should be similar to this:

{
  billers: [
    {
      categoryid: "4",
      categoryname: "Mobile Recharge",
      categorydescription: "Recharge your phone",
      billerid: "901",
      billername: "Airtel Mobile Top-Up",
      customerfield1: "Phone Number",
      ...
    },{
      categoryid: "4",
      categoryname: "Mobile Recharge",
      categorydescription: "Recharge your phone",
      billerid: "108",
      billername: "Airtel Recharge Pins",
      customerfield1: "Phone Number",
      ...
    },
    {
      categoryid: "4",
      categoryname: "Mobile Recharge",
      categorydescription: "Recharge your phone",
      billerid: "120",
      billername: "Etisalat Recharge Top-Up",
      customerfield1: "Phone No",
      ...
    },{
      categoryid: "4",
      categoryname: "Mobile Recharge",
      categorydescription: "Recharge your phone",
      billerid: "402",
      billername: "Glo QuickCharge",
      customerfield1: "Mobile number",
      ...
    }
    ...
  ]
}

You can then proceed to click on the GetBillerPaymentItems and SendBillPaymentAdvice endpoints by using the customer's phone number as the customer ID.

To learn how to perform authentication to access this service, click here

Sample response

Here is a sample response from a successful airtime recharge

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

E pins (Voucher service)

Through E pins, we have created an electronic voucher service that creates a 16 - 20 digit code where users can recharge their mobile phones. This is an electronic version of the legacy recharge cards with long pins however by integrate this endpoint, you will be enabled to create, redeem vouchers.

Create Voucher

Request Endpoint: https://sandbox.interswitchng.com/api/v2/quickteller/vouchers/create

Request Body Description

Field

Field name

Data type

Max length

Required

Description

1

paymentCode

string

5

false

This is the payment code

2

CustomerId

string

MAX

true

This is the ID of the customer who is trying to create the voucher

3

Amount

Long

true

This is the amount of voucher that needs to be created

4

Type

string

10

true

This is the type of voucher been created; gift | recharge

5

ExpiryDate

datetime

true

This is the expiry date of the voucher

6

StartDate

datetime

true

This is the start date of the voucher

7

Redemption.Quantity

int

false

This specifies the total number of time a user can redeem the voucher

8

CodeConfig.allowedChar

string

50

false

his specifies the length and pattern of the voucher

Request Headers

Request Body

Sample Response (Success)

Sample Response (Failed)

Response Codes

Response Code

Response Message

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

VS0021

NOT_AUTHORISED_TO_REDEEM_VOUCHER

Redeem Voucher

Request Endpoint: https://sandbox.interswitchng.com/api/v2/quickteller/vouchers/redeem

1CustomerIdstringMAXTrueThis is the customer Id that wants to redeem the voucher
2CustomerMobilestringMAXfalseThis is the mobile contact of the customer who is trying to redeem the voucher
3PaymentCodestring5TrueThis is the payment code of the biller
4AmountdecimalTrueThis is the amount of the voucher that wants to be redeemed
5CustomerEmailstring40FalseThe email of the customer
6voucherCodestringMAXTrueThis is the voucher code we are trying to redeem

Request Header

Response Codes

Response CodeResponse Message
VS001VOUCHER_NOT_FOUND
VS002REDEMPTION_QUANTITY_EXCEEDED
VS003VOUCHER_IS_USED
VS004REDEMPTION_AMOUNT_EXCEEDED
VS006UNRECOGNISED_VOUCHER
VS018ACCESS_DENIED
VS020VOUCHER_NOT_STARTED
VS021NOT_AUTHORIZE_TO_REDEEM_VOUCHER
Language
Authentication
Header
Click Try It! to start a request and see the response here!