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

1	CustomerId	string	MAX	True	This is the customer Id that wants to redeem the voucher
2	CustomerMobile	string	MAX	false	This is the mobile contact of the customer who is trying to redeem the voucher
3	PaymentCode	string	5	True	This is the payment code of the biller
4	Amount	decimal		True	This is the amount of the voucher that wants to be redeemed
5	CustomerEmail	string	40	False	The email of the customer
6	voucherCode	string	MAX	True	This is the voucher code we are trying to redeem

Request Header

Response Codes

Response Code	Response Message
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