Introduction

Quickteller SVA gives you access to airtime vending, over 3000 billers, instant transfers to all bank acounts in Nigeria, several banks and mobile wallets in Africa.

Sample Requests

Quickteller SVA APIs are HTTP based RESTful APIs therefore API request and response format are in JSON. We have provided sample request and responses next to each endpoint in this documentation. All you need to do is replace the dummy parameters with yours. You can also download our postman collection and environment variables to test the Quickteller SVA API.


BASE URL (Test)

https://sandbox.interswitchng.com

BASE URL (Production)

https://passport.interswitchng.com

Sample Code

We created a sample code implemented in C#. Feel free to alter the look and feel based on your taste and requirement(s). Don't forget to alter the links and paths appropriately before uploading to a web server.

Response Code

Please refer to the standard HTTP response codes. Where anything starting with 2XX signifies approved, 4XX means client error and 5XX indicates server error. When the response codes start with 4XX or 5XX, an error object will be returned to explain further the reason for this failure. Find common response code and its description below:


Code Description
E10 The service field tag has not been populated.
E11 This requests expects a transactionType field to be set and it is not.
E12 SecurityToken header is missing.
E13 Username or password is wrong.
E14 Missing content type header.
E15 The transaction you are trying to do is not supported.
E16 The service you have specified is not available.
E17 The service provider you have specified has not been set up on the platform.
E18 The service is unreachable at the moment.
E19 A bad response was received from service provider.
E20 Your request has timed out.
E21 An unknown error has occurred.
E22 Access key has not been supplied. Ensure the Authorization header has been set appropriately.
E23 Nonce has not been supplied. Ensure the Nonce header has been set appropriately.
E24 Please synchronize your time with the server and ensure your time is not outside of 30mins of the Server local time.The standard time zone used is GMT
E25 Nonce has already been used
E26 Signature failed for this request. Contact Interswitch.
E27 An unknown error occured during Authentication. Contact Interswitch
E28 Your credentials do not have access to this resource
E29 Timestamp is missing in your header.
E30 SecurityToken header is bad.
E31 XML data is badly formatted
E32 JSON data is badly formatted
E33 Keystore is not accessible. Contact Interswitch.
E34 The system is busy at the moment, please try again later.
E35 Bad request to service provider. Contact Interswitch.
E36 Bad request to service processor. Contact Interswitch.
E37 Bad request from client. Kindly check your message.
E38 Bad response from service provider. Contact Interswitch.
E39 Bad response from service processor. Contact Interswitch.
E40 Bad response to client. Contact Interswitch.
E41 Bad request from client. Kindly check your message.

Services and Methods

The table below contains all the services and methods that you can access vai Quickteller SVA

Bill Payment/Recharge Recharge Only Do Transfer
GetBillers (Mandatory) GetBillerPaymentItems (Mandatory) Name Enquiry (Mandatory)
GetBillerPaymentItems (Mandatory) GetBillerPaymentItems (Mandatory) GetBanksCode (Optional)
SendBillPaymentAdvice (Mandatory) SendBillPaymentAdvice (Mandatory) FundTransfer (Mandatory)
CustomerValidation (Mandatory) QueryTransaction (Mandatory) QueryTransaction (Mandatory)
GetBillerCategories (Optional)
QueryTransaction (Mandatory)


Authentication

Authenticate your API calls by including your access token in the Authorization header of every request you make. Interswitch utilizes OAuth 2 to facilitate authorization and grants access to an application either on behalf of a user or on behalf of the application itself.

Application Authorization

To get an access token, create a project on the Interswitch Developer Console and obtain the Client ID and Secret Key of the project and encode the them using this format client_id:secret_key using base64encode. Copy the encoded value of your Client ID and Secret Key and make a call to the endpoint below with the Authorization header that contains the word Basic followed by a space and the base64-encoded value. Ensure that you use the Content-Type:application/x-www-form-urlencoded header and finally pass the grant_type=client_credentials in the body of the request.


Endpoint

POST

/passport/oauth/token

Sample Request

import requests
url = "https://sandbox.interswitchng.com/passport/oauth/token"
body = {"grant_type":"client_credentials"}
headers = {
    'authorization': "Basic SUtJQTFCNzU5M0M0NDAyQkM1RTAwQzQ2QUM4QjFDMUNDMEI4NUVFQkIwODg6c2VjcmV0",
    'content-type': "application/x-www-form-urlencoded"}
response = requests.request("POST", url, data=body, headers=headers)
print(response.text)
REQUEST PARAMETERS
Parameters Required Type Description
ClientId Yes String Application key. Navigate to `https://developer.interswitchgroup.com` for your application key
SecretKey Yes String Application secret. Navigate to `https://developer.interswitchgroup.com` for your application secret.
grant_type Yes String This must be set to client_credentials

Sample Response (Success)

{ 
  "access_token": "{Your access token}",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "profile",
  "merchant_code": "MX10003",
  "requestor_id": "123588975884",
  "client_name": "kL79ov",
  "payable_id": "359854",
  "jti": "19800d56-3ac6-44c2-b318-8f2ece419840"
}

Sample Response (Failure)

{ 
  "code": "Unauthorized",
  "description": "Bad credentials",
  "errors": null
}
RESPONSE PARAMETERS
Parameters Description
access_token A new access token that is used to authenticate against resources that belong to the app itself.
token_type Always bearer
expires_in The lifetime of the access token, in seconds

Authorization headers should be in the following format: Authorization: Bearer Encoded(clientId:secreteKey)

Process Flows

Find below the basic flow for making calls to Quickteller SVA:

  • To get all billers, make an API call to GetBillers.
  • To gets the items attached to a particular biller, make an API call to GetBillerPaymentItems.
  • To get send request to ISW for processing, make an API call to SendBillPaymentAdvice.
  • To find items that requires validation e.g. Disco, LCC etc, make an API call to CustomerValidation.
  • To get the status of a specific transaction, make an API call to QueryTransaction.

Airtime Purchase

  • External system maintains a list of all organization it plans to support. This can be obtained by a mix of the following calls: GetBillers, GetBillerPaymentItems, GetBillerCategories.
  • External system debits user’s VA or accepts mode of payment.
  • External system sends a SendBillPaymentAdvice message to Interswitch containing all relevant information to complete the bill payment.
  • Interswitch credits organization and performs settlement against external system’s sponsor bank.
  • In the case of any error, Interswitch will respond appropriately and this would go all the way to the external system to do reversals internally
  • External system can always use a QueryTransaction call to Interswitch to verify any transaction status.

Bill Payment

  • External system maintains a list of all organization it plans to support. This can be obtained by a mix of the following calls: GetBillers, GetBillerPaymentItems, GetBillerCategories.
  • External system debits user’s account or accepts mode of payment
  • External system sends a SendBillPaymentAdvice message to Interswitch containing all relevant information to complete the bill payment Interswitch credits organization and performs settlement against external system’s sponsor bank.
  • In the case of any error, Interswitch will respond appropriately and this would go all the way to the external system to do reversals internally
  • External system can always use a QueryTransaction call to Interswitchto verify any transaction status

Transfer to Account

  • External system debits user’s virtual account or accepts a mode of payment
  • External system sends a DoTransfer message to Interswitch
  • Interswitch application uses the preconfigured float card of the VA for a debit and credits the beneficiary bank
  • External system can always use a QueryTransaction call to Interswitch to verify any transaction status

Transfer to Prepaid Card

  • External system debits user’s virtual account or accepts a mode of payment
  • External system sends a DoTransfer message to Interswitch
  • Interswitch application uses the preconfigured float card of the VA for a debit and credits the Prepaid Card
  • External system can always use a QueryTransaction call to Interswitch to verify any transaction status

Test Credentials

If you want to quickly test the Quickteller SVA API, use the test details below to make an API call.

Test Details
Terminal ID Request Reference/Transfer Code Prefix Initiating Entity Code
3DMO0001 1453 DMO
Test SVA Card
Card Number Expiry Date Pin
6280511000000095 Dec 2026 0000
Name Enquiry/Transfer/Query
Account number Bank code Bank name
0014261063 058 GTB
9999999999 011 First Bank
Bill Payment (Non PIN Based)
DSTV Valid customerId Amount paymentCode Billerid category
0000000001 1460000 10401 104 2
Bill Payment (PIN Based)
paymentCode Valid customerId (meter number) PHCN billerid Category
90501 0434556574 905 1
Recharge (Airtime)
paymentCode customerId/customerMobile billerid Category
90101 2348056731573 901 4


Get Billers

This method retrieves billers based on the supplied search criteria.

Endpoint

GET

/v2/quickteller/billers

Request Parameters
Field Name Required Length Format Description
Terminal ID True 8 Alphanumeric Terminal ID (This is usually provided by Interswitch but you can use the Terminal ID provided in this documentation to test)

Sample Response (Success)

{ “billers”: [ { 
  “categoryid”: “3”, 
  “categoryname”: “State Payments”, 
  “categorydescription”: “Pay state taxes”, 
  “billerid”: “303”, 
  “billername”: “Abia State Infrastructural Development Agency”, 
  “customerfield1”: “Customer No”, 
  “customerfield2”: “”, 
  “supportemail”: “quickteller@interswitchng.com”, 
  “paydirectProductId”: “3332”, 
  “paydirectInstitutionId”: “0”, 
  “narration”: “Pay”, 
  “shortName”: “ASIDA”, 
  “surcharge”: “10000”, 
  “currencyCode”: “566”, 
  “quickTellerSiteUrlName”: “asida”, 
  “amountType”: “0”, 
  “currencySymbol”: “NGN”, 
  “customSectionUrl”: “”, 
  “logoUrl”: “q.jpg”, 
  “type”: “”, “url”: “” }]}


GetBillers Response Parameters
Code Description
categoryid Category Id
categoryname Biller Category
categorydescription Description of Category
billerid Biller’s Unique identifier
billername Name of biller
customerfield1 Customer Id Field 1
customerfield2 Customer Id Feld 2
currencySymbol The symbol of the currency
logoUrl Base URL is https://quickteller.sandbox.interswitchng.com/Content/Images/Downloaded/

The response parameters above are returned per biller.


Get Biller Categories

This method retrieves all the biller category types

Endpoint

GET

/api/v2/quickteller/categorys

Request Parameters
Field Name Required Length Format Description
Terminal ID True 8 Alphanumeric Terminal ID (This is usually provided by Interswitch but you can use the Terminal ID provided in this documentation to test)

Sample Response (Success)

{“categorys”: 
    [{“categoryid”: “1”,
    “categoryname”: “Utility Bills”, 
    “categorydescription”: “Pay your utility bills here”},
    {“categoryid”: “2”,
    “categoryname”: “Cable TV Bills”,
    “categorydescription”: “Pay for your cable TV subscriptionshere”}]}


GetBillerCategories Response Parameters
Code Description
categoryid Category Id
categoryname Biller Category
categorydescription Description of Category


Get Billers By Category

This method retrieves billers based on the supplied search criteria.

Endpoint

GET

/api/v2/quickteller/categorys/{id}/biller

Request Parameters
Field Name Required Length Format Description
Terminal ID True 8 Alphanumeric Terminal ID (This is usually provided by Interswitch but you can use the Terminal ID provided in this documentation to test)
id True Alphanumeric An ID of the category to be returned. Please use a valid value returned from Get Categories API

Sample Response (Success)

{ “billers”:
    [ { “categoryid”: “3”, 
    “categoryname”: “State Payments”, 
    “categorydescription”: “Pay state taxes”, 
    “billerid”: “303”, 
    “billername”: “Abia State Infrastructural Development Agency”, 
    “customerfield1”: “Customer No”, 
    “customerfield2”: “”, 
    “supportemail”: “quickteller@interswitchng.com”, 
    “paydirectProductId”: “3332”, 
    “paydirectInstitutionId”: “0”,
    “narration”: “Pay”, 
    “shortName”: “ASIDA”, 
    “surcharge”: “10000”, 
    “currencyCode”: “566”, 
    “quickTellerSiteUrlName”: “asida”, 
    “amountType”: “0”, 
    “currencySymbol”: “NGN”, 
    “customSectionUrl”: “”, 
    “logoUrl”: “q.jpg”, 
    “type”: “”, “url”: “” }]}


Response Parameters
Code Description
categoryid Category Id
categoryname Biller Category
categorydescription Description of Category
billerid Biller’s Unique identifier
billername Name of biller
customerfield1 Customer Id Field 1
customerfield2 Customer Id Feld 2
currencySymbol The symbol of the currency
logoUrl Base URL is https://quickteller.sandbox.interswitchng.com/Content/Images/Downloaded/

The response parameters above are returned per biller.


Get Biller Payment Items

This method retrieves billers based on the supplied search criteria.

Endpoint

GET

/api/v2/quickteller/billers/{billerId}/paymentitems

Request Parameters
Field Name Required Length Format Description
Terminal ID True 8 Alphanumeric Terminal ID (This is usually provided by Interswitch but you can use the Terminal ID provided in this documentation to test)
BillerId True >2 Numeric Unique per biller. Returned in GetBillers response

Sample Response (Success)

"paymentitems": [
        {
            "categoryid": "1",
            "billerid": "905",
            "isAmountFixed": false,
            "paymentitemid": "01",
            "paymentitemname": "Meter Token",
            "amount": "0",
            "billerType": "PH",
            "code": "01",
            "currencyCode": "566",
            "currencySymbol": "NGN",
            "itemCurrencySymbol": "",
            "sortOrder": "0",
            "pictureId": "0",
            "paymentCode": "90501",
            "itemFee": "10000"
        }
    ]
}


GetBillerPaymentItems Response Parameters
Code Description
categoryid Category Id
billerid Id of Quickteller Biller
isAmountFixed False is returned for variable amount, while True is returned for fixed amount. If amount is fixed,it is mandatory to send the exact returned in the GetBillerPaymentItems response in your SendBillpaymentAdvice request.
paymentitemid Item Id
paymentitemname Payment Item name
amount Item Amount
code Item code
currencyCode Currency code
currencySymbol Symbol of the Currency. Example NGN for Niara
itemCurrencySymbol Currency code
paymentcode Unique Payment item identifier

A HTTP response code 200 is sent back for a success. The parameters above are returned per biller.


Customer Validation

This method is used to notify the biller of the payment

Endpoint

POST

/api/v2/quickteller/customers/validations

Request Parameters
Parameter Required Length Description
Customers True Contains the array for customer to be validated
PaymentCode True <=20 Unique payment code for a biller
CustomerId True <=50 Customer’s Unique Identifier

Response Parameters
Parameter Length Description
Customers Contains the array for customer to be validated
PaymentCode <=20 Unique payment code for a biller
CustomerId <=50 Customer’s Unique Identifier
FullName Customers Name
ResponseCode Response code for the request made

Sample Response (Success)

{“Customers”: [
{“paymentCode”: “04342512”,
“customerId”: “98325”,
“responseCode”: “90000”,
“fullName”: “IBE EMMANUEL”,
“amount”: “1500000”,
“amountType”: “5”,
“amountTypeDescription”: “Biller requires exact amount: NGN 15,000.00.”}]}

The amountType is the response data that shows the expected amount to be paid by the customer. on customer validation, you are expected to validate the allowed amount to be paid by the customer.

Amount Types (Example)

“amount”: “1500000”,
“amountType”: “5”
customer is expected to pay exact amount (N1500000) as returned.
“amount”: “1500000”,
“amountType”: “4”
customer can pay any amount below 1500000


Amount Type Description
Response Lable Meaning
0 None Any amount can be paid
1 Minimum If the returned amount is 1000, customer can pay any amount from 1000
2 Greater than minimum If the returned amount is 1000, customer can pay any amount greater than 1000
3 Maximum If the amount returned is 1000, customer can pay any amount below or equal to 1000
4 Less than Maximum If the amount returned is 1000, customer can pay any amount below to 1000
5 Exact The exact amount returned must be paid


Send Bill Payment Advice

This method is used to notify the biller of the payment

Endpoint

POST

/api/v2/quickteller/payments/advices

Sample Request

{“TerminalId”:”3FTH0001″,
“paymentCode”:”10403″,
“customerId”:”0000000001″,
“customerMobile”:”2348056731576″,
“customerEmail”:”iswtester2@yahoo.com”,
“amount”:”360000″,
“requestReference”:”1194000023″}


Request Parameters
Parameter Required Length Description
TerminalId True Terminal ID assigned by Interswitch
PaymentCode True <=20 Unique payment code retrieved from GetBillerPaymentItems call
CustomerId True <=50 Customer’s Unique Identifier
CustomerMobile False <=13 Customer’s Mobile Number.
CustomerEmail False <=50 Customer’s Email Number.
Amount True <=50 Paid by customer. Amount should be sent in lower denomination
CustomerEmail False <=50 Customer’s Email Address
requestReference True <=12 Unique requestReference generated on Client’s system and sent in DoTransfer request. 4 digit requestreference prefix will be provided by Interswitch


Response Parameters
Code Response
TransactionReference (A billPayment transaction) Unique Transaction reference generated by Interswitch
MiscData (Only returned if a billpayment is PIN based) Biller’s Token
PIN(Only returned if a billpayment is PIN based) Biller’s Token
ResponseCodeGrouping A response of status is returned (SUCCESS, FAILED, or PENDING)


Western Union

https://sandbox.interswitchng.com/api/v2/quickteller/sendAdviceRequest

Headers

Click here to learn how to compute the required headers for authentication.

Request Parameters

Field Length Description
TerminalId Mandatory Terminal ID assigned by Interswitch
PaymentCode Mandatory <=20 Unique payment code retrieved from GetBillerPaymentItems call
CustomerId Mandatory <=50 Customer’s Unique Identifier
CustomerMobile Optional <=13 Customer’s Mobile Number
CustomerEmail Optional <=50 Customer’s Email Address
Amount Mandatory <=50 Amount Paid by customer. Amount should be sent in lower denomination
CustomerEmail Optional <=50 Customer’s Email Address
requestReference Mandatory <=12 Unique requestReference generated on Client’s system and sent in DoTransfer request. 4 digit requestreference prefix will be provided by Interswitch.
CustomerEmail Optional <=50 Customer’s Email Address
CustReference Mandatory 10 MTCN
PayerCountryCode Mandatory
PayeeAccountNumber Mandatory
PayeeAccountType Mandatory
Amount Mandatory
ExpectedCurrency Mandatory
PayeeFirstname Mandatory
PayeeSurname Mandatory
ReceiverPhoneNumber Mandatory
TestAnswer Mandatory
IdType Optional
IdNumber Optional
CountryOfIssue Optional
DateOfBirth Optional
IdExpirationDate Optional
CountryOfBirth Optional

Sample Request

{"paymentCode":"50204",
"customerId":"0693621805",
"customerMobile":"2348056731576",
"customerEmail":"iswtester2@yahoo.com",
"pageFlowValues":"CustReference:5381319048|PayerCountryCode:AE|PayeeAccountNumber:0115715470|
PayeeAccountType:20|Amount:100000|
ExpectedCurrency:566|PayeeFirstname:Peace|PayeeSurname:Idaewor|ReceiverPhoneNumber:08056731576|
TestAnswer:ans|IdType:Driver's License|IdNumber:123456|CountryOfIssue:NG|DateOfBirth:20082017|
IdExpirationDate:12122020|CountryOfBirth:NG|","requestReference":"1453100010125","amount":100000}


Response Parameters
Code Response
transactionRef (A billPayment transaction) Unique Transaction reference generated by Interswitch
transferCode
recipientName This should be displayed on the receipt


Sample Response

{
  "transactionRef":"WU|GTB|AC|310717153744|CUGFQVHQUU",
  "transferCode":"102900048490",
  "recipientName": "TEST1 TEST2 TEST3"
}

Query Transaction

This method is used to retrieve the status of a transaction

Endpoint

GET

{{base url}}api/v2/quickteller/transactions?requestreference=requestReferencevalue

Find a sample request for querying a transaction (where 119420151169 is a sample requestReference) below:

Sample Request

https://sandbox.interswitchng.com/api/v2/quickteller/transactions?requestreference=119420151169


Request Parameters
Field Name Required Length Format Description
RequestReference True 20 Alphanumeric The request reference passed in the ‘SendBillPaymentAdvice’ method or the transfer code passed in the ‘DoTransfer’ method
Terminal ID False 8 Alphanumeric Terminal ID provided by Interswitch


QueryTransaction Response

{ 
    “recharge”: {
    “biller”: “ZainMTU”,
    “customerId1”: “08090673520”,
    “customerId2”: null,
    “paymentTypeName”: “Zain MTU 50”,
    “paymentTypeCode”: “01”,
    “billerId”: “901”},
    “amount”: “32900”,
    “currencyCode”: “566”,
    “customer”: “”,
    “customerEmail”: “iswtester2@yahoo.com”,
    “customerMobile”: “2348056731576”,
    “paymentDate”: “3/17/2017 1:10:13 PM”,
    “requestReference”: “14561489752590”,
    “serviceCode”: “01”,
    “serviceName”: “Zain MTU 50”,
    “serviceProviderId”: “901”,
    “status”: “Complete”,
    “surcharge”: “0”,
    “transactionRef”: “XXT|Web|3XXT0001|ZainMTU|170317131013|00000040”,
    “transactionResponseCode”: “90000”,
    “transactionSet”: “Recharge”,
    “responseCode”: “90000”
}
Response Parameters
Response Description
TransactionResponseCode TransactionResponseCode confirms the status of the queried transaction

SVA Cashout

Base Url (Sandbox)

https://sandbox.interswitchng.com

Headers

{
    Content-Type: application/json
    Authorization: { passport generated bearer token }
}

Pay Inquiry

This method is used to perform Quickteller Payment Inquiry

Endpoint

POST

{base url}/api/v2/quickteller/transactions/inquirys

Sample Request

{
    "paymentCode": "04226901",
    "customerId": "3394433",
    "customerMobile": "08032269223",
    "customerEmail": "customer1@gmail.com"
    "pageFlowValues": "BankId:16|DestinationAccountNumber:0221149201|DestinationAccountType:10|Amount:60000|ReciepientName:GBOLAHAN MUSBAU SUBAIR",
    "amount": "60000"
}


Request Parameters
Field Name Required Length Format Description
paymentCode True <=20 Alphanumeric The Payment Code that identifies the biller. Please see Get Biller response
customerId True <=50 Alphanumeric Customer ID e.g. smart card number, meter number
customerMobile False <=50 Alphanumeric Customer mobile number
customerEmail False <=50 Alphanumeric Customer email
amount False <=50 long Amount
pageFlowValues False Alphanumeric This is required when you are sending a funds transfer trasaction. Example: BankId:16|Destination|AccountNumber:0221149201|DestinationAccountType:10|Amount:60000|ReciepientName:GBOLAHAN MUSBAU SUBAIR


Sample Response (Success)

{
    "isAmountFixed": 1, 
    "surcharge": 5250, 
    "biller": "Transfer to Account", 
    "amount": 60000, 
    "paymentItem": "TransferToAccount", 
    "narration": "Tran/889069242845/0221149201/GBOLAH/LANG", 
    "customerId": 2348102692068, 
    "shortTransactionRef": 889069242845, 
    "transactionRef": "IQT|T|MOB|CA|WEMA|AC|220319101419|P3ED97DH", 
    "customerName": 221149201, 
    "responseCode": 90000}


Response Parameters
Field Name Description
customerName Customer’s name
TransactionReference Unique Transaction reference generated by Interswitch
shortTransactionRef Transaction reference
narration Transaction remark. This will show up in Customer’s bank statement
surcharge The transaction fee to be charged by Interswitch


Send Transaction

This method is used to perform Quickteller Payment Transaction

Endpoint

POST

{base url}/api/v2/quickteller/transactions

Sample Request

{
    "amount": 250000,
    "pinData": "****************",
    "secureData": "****************",
    "msisdn": 2348030014003,
    "transactionRef": "AQT|T|MOB|4AQT0001|KEDP|241016153410|00012392",
    "cardBin": 53701002040
}


Request Parameters
Field Name Required Length Format Description
amount True <=20 Numeric Transaction amount in minor denomination
pinData True 16 Hexadecimal Encrypted PIN Block
secureData True 512 Hexadecimal Other Transaction sensitve data e.g. Card, CVV, Exp Date
msisdn False <=13 Numeric Customer Mobile phone
transactionRef True <=60 Alphanumeric Transaction reference returned during Bill Payment inquiry call
cardBin True <=11 Numeric The first 11 number of the Card Number


Sample Response (Success)

{
    "responseCode": 90000,
    "shortTransactionRef": 999969541767,
    "responseDescription": "Your transaction has been processed successfully.",
    "rechargePin": "Virtual Top Up",
    "transactionRef": "UBA|MOB|4AQT0001|MTNV|241016154029|00008356",
    "transactionResponseCode": "00",
    "transactionResponseDesc": "Your transaction has been processed successfully."
}

Get Bank Id

GetBankCode Method is implemented and used to retrieve banks code.

Endpoint

GET

{base url}/api/v2/quickteller/configuration/fundstransferbanks

Sample Response

{
 "banks": [
 {
 "id": "31",
 "cbnCode": "044",
 "bankName": "Access Bank Nigeria Plc",
 "bankCode": "ABP"
 },
 {
 "id": "101",
 "cbnCode": "056",
 "bankName": "Ecobank Nigeria 2",
 "bankCode": "ECO2"
 },
 {
 "id": "128",
 "cbnCode": "085",
 "bankName": "First Inland Bank Plc",
 "bankCode": "FIB"
 },
 {
 "id": "10",
 "cbnCode": "058",
 "bankName": "Guaranty Trust Bank Plc",
 "bankCode": "GTB"
 },
 {
 "id": "121",
 "cbnCode": "232",
 "bankName": "Sterling Bank Plc",
 "bankCode": "SBP"
 },
 {
 "id": "117",
 "cbnCode": "057",
 "bankName": "Zenith Bank International",
 "bankCode": "ZIB"}]}
{
 "banks": [
 {
 "id": "31",
 "cbnCode": "044",
 "bankName": "Access Bank Nigeria Plc",
 "bankCode": "ABP"
 },
 {
 "id": "101",
 "cbnCode": "056",
 "bankName": "Ecobank Nigeria 2",
 "bankCode": "ECO2"
 },
 {
 "id": "128",
 "cbnCode": "085",
 "bankName": "First Inland Bank Plc",
 "bankCode": "FIB"
 },
 {
 "id": "10",
 "cbnCode": "058",
 "bankName": "Guaranty Trust Bank Plc",
 "bankCode": "GTB"
 },
 {
 "id": "121",
 "cbnCode": "232",
 "bankName": "Sterling Bank Plc",
 "bankCode": "SBP"
 },
 {
 "id": "117",
 "cbnCode": "057",
 "bankName": "Zenith Bank International",
 "bankCode": "ZIB"}]}

Bank Codes

Bank Entity Codes
Bank Name Bank CBN Code
Access Bank  044
Diamond Bank 063
Ecobank 050
FCMB 214
Fidelity Bank 070
First Bank of Nigeria 011
Guaranty Trust Bank 058
Heritage Bank 030
Jaiz Bank 301
Keystone 082
Providus 101
Polaris (Skye Bank) 076
Stanbic IBTC Bank 039
Standard chartered 068
Sterling Bank 232
Suntrust Bank 100
Union Bank 032
United Bank for Africa 033
Unity Bank 215
Wema Bank 035
Zenith International Bank 057


Payment Channels
Code Name
1 ATM
2 POS
3 Web
4 Mobile
5 Kiosk
6 Voice
7 Location

Sample Libraries

This section contains the Quickteller Biller and Fund Transfer API functions and calls bundle together in easy to use Dynamic-link libraries (DLLs), and components you can add into your projects.

Definition of Terms

We've exaplained some important concepts you need to know before delving into the Sample Lbraries:

  • Biller: A biller is any Organization, Institution or Business that is able to exchange services for a fee. Example: Telecoms provider (Airtel, Glo, MTN), Government Body (Lagos State) etc.

  • Category: Billers are grouped under categories. For instance, all cable providers(DSTV, GOTV) can e grouped under a cable Category.

  • Customer - An individual that has an intent and/or pays for any of the services offered by a Biller.

  • PaymentItem - A biller (e.g DSTV) can offer different services and hence different prices for them. Each of those services, falls under a payment-item and has a unique payment-item-code. We say that a user has intent to pay for a payment-item offered by a Biller. An example of a payment-item under DSTV is the DSTV Premium Bouquet

What this SDK provides for you

  • Get All Billers: Get a list of all billers supported on our platform.

  • Get All Categorys: Get a list of all categorys and associated billers supported on our platform.

  • Get All Billers under a Category: Get a list of all biilers under a particular category.

  • Get Biller Payment Items: Get a list of all payment-items under aparticular Biller.

  • Validate Customer: Validates a customer-id under a particular biller.

  • Make payment for a customer: Makes a payment for a payment-item for a particular customer.

  • Query the status of a transaction: Query the status of a transaction made in the past based on the Request Reference.

C

This SDK helps you get a list of all banks supported on our platform, validates an account number against a particular bank and transfers funds from a senders account to receivers account.

Prerequisites

Sample Codes and Libraries

PHP

This SDK helps you get a list of all banks supported on our platform, validates an account number against a particular bank and transfers funds from a senders account to receivers account.

Prerequisites

Sample Codes and Libraries

Quick start

Composer

"interswitch/interswitch": "dev-master"
composer require interswitch/interswitch:dev-master

Java

This SDK helps you get a list of all banks supported on our platform, validates an account number against a particular bank and transfers funds from a senders account to receivers account.

Prerequisites

Sample Codes and Libraries

Quickstart

maven

    &lt;groupId&gt;com.interswitch&lt;/groupId&gt;
    &lt;artifactId&gt;interswitch-java&lt;/artifactId&gt;
    &lt;version&gt;0.0.1&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;com.google.code.gson&lt;/groupId&gt;
    &lt;artifactId&gt;gson&lt;/artifactId&gt;
    &lt;version&gt;2.6.2&lt;/version&gt;
&lt;/dependency&gt;

Fetch All Banks Request

To get started, try out our simple Fetch All banks request.

Fetch All Banks Request

<span class="pl-k">import</span> <span class="pl-smi">com.interswitch.techquest.auth.Interswitch</span>;
<span class="pl-k">import</span> <span class="pl-smi">com.interswitch.transfer.FundsTransfer</span>;
<span class="pl-k">private</span> <span class="pl-k">static</span> <span class="pl-k">final</span> <span class="pl-smi">String</span> initiatingEntityCode <span class="pl-k">=</span> <span class="pl-s"><span class="pl-pds">"</span>XXT<span class="pl-pds">"</span></span>;
<span class="pl-k">private</span> <span class="pl-k">final</span> <span class="pl-k">static</span> <span class="pl-smi">String</span> clientId <span class="pl-k">=</span> <span class="pl-s"><span class="pl-pds">"</span>IKIA6570778A3484D6F33BC7E4165ADCA6CF06B2860A<span class="pl-pds">"</span></span>;
<span class="pl-k">private</span> <span class="pl-k">final</span> <span class="pl-k">static</span> <span class="pl-smi">String</span> clientSecret <span class="pl-k">=</span> <span class="pl-s"><span class="pl-pds">"</span>DXfUwpuIvMAKN84kv38uspqGOsStgFS0oZMjU7bPwpU=<span class="pl-pds">"</span></span>; 
<span class="pl-k">public</span> <span class="pl-k">static</span> <span class="pl-k">void</span> main(<span class="pl-k">String</span>[] args) {
    <span class="pl-smi">FundsTransfer</span> transfer <span class="pl-k">=</span> <span class="pl-k">new</span> <span class="pl-smi">FundsTransfer</span>(clientId, clientSecret, <span class="pl-smi">Interswitch</span><span class="pl-c1"><span class="pl-k">.</span>ENV_SANDBOX</span>);
    <span class="pl-k">try</span> {
        <span class="pl-smi">BankResponse</span> bankResponse <span class="pl-k">=</span> transfer<span class="pl-k">.</span>fetchBanks();
        <span class="pl-k">Bank</span>[] bank <span class="pl-k">=</span> bankResponse<span class="pl-k">.</span>getBanks(); <span class="pl-c">// a bank array of all banks</span>
        <span class="pl-k">if</span> (bank <span class="pl-k">instanceof</span> <span class="pl-smi">Object</span>) {
            <span class="pl-c">// successful</span>
            <span class="pl-smi">Bank</span> testBank <span class="pl-k">=</span> bank[<span class="pl-c1">0</span>]; <span class="pl-c">// bank at index 0</span>
            <span class="pl-smi">String</span> cbnCode <span class="pl-k">=</span> testBank<span class="pl-k">.</span>getCbnCode(); <span class="pl-c">// Central bank code</span>
            <span class="pl-smi">String</span> bankName <span class="pl-k">=</span> testBank<span class="pl-k">.</span>getBankName(); <span class="pl-c">// bank name:</span>
            <span class="pl-smi">String</span> bankCode <span class="pl-k">=</span> testBank<span class="pl-k">.</span>getBankCode(); <span class="pl-c">// bankcode in alphabetical form: UBA, GTB, FBN</span>
         }
    }
    <span class="pl-k">catch</span>(<span class="pl-smi">Exception</span> ex) {
        <span class="pl-c">//</span>
        ex<span class="pl-k">.</span>printStackTrace();}}

Node Js

This SDK helps you get a list of all banks supported on our platform, validates an account number against a particular bank and transfers funds from a senders account to receivers account.

Prerequisites

Sample Codes and Libraries

Installation

$ npm install interswitch-funds-transfer

Running sample app

cd B2C-Funds-Transfer-nodejs
node AppDriver.js

FAQs

Error Possible problem Resolution
E38 You have not been configured on Quickteller Platform Contact your Support Engineer. Application Parameter configuration is pending
E28 You do not have sufficient right to access this service Contact your Support Engineer. Resources or Access right need to be enabled.
E26 Invalid authentication credentials: signature cannot be authenticated Faulty signature computation. Confirm hextobase64 encoding is done properly. "Signature"=hexToBase64(Sha1.hash(signatureCipher))) where "signatureCipher" = httpMethod + "&"+ url + "&" +timestamp + "&" + nonce + "&" + clientId + "&" + clientSecret
E15 This transaction is not yet supported. Please API documentation for supported transaction type Check the URL you're using e.g. payment instead of payments
10002 Invalid transfer code/Invalid request prefix You're not using the right request prefix.


ON THIS PAGE