Introduction

The Purchase API is designed to send payment requests to debit customer’s payment instrument and send a notification to merchants about a payment that has just been made. This documentation describes how a third-party will integrate with our API and gain indepth knowledge about all the components of our API and how they interrelate.

Purchase API process flow

The process Flow of the Purchase API

Sample Requests

The Purchase 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 use our collections page to view our API calls directly on your browser or download our postman collection and environment variables to easily test the Purchase API.


BASE URL (Test)

https://qa.interswitchng.com

BASE URL (Production)

https://passport.interswitchng.com

Sample Code

Find below sample codes implemented in various languages. Feel free to change 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.

Language Resources
Javascript Sample Code, Demo
PHP Sample Code, Demo
Java Sample Code, Demo
C# Sample Code, Demo
NodeJS Demo
Ruby Sample Code

Response Code

We use 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.


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).


Test Credentials

Find below test values that can be used to test the Purchase API.

ONE TIME PAYMENT
Parameters Sample Data
ClientId IKIA9614B82064D632E9B6418DF358A6A4AEA84D7218
Secret XCTiBtLy1G9chAnyg0z3BcaFK4cVpwDg/GTw2EmjTZ8=
merchantCode MX187
requestorId 00117614992
RECURRING PAYMENTS
Parameters Sample Data
ClientId IKIACA67D931869E40BE07EE418A0B07A4A6D9EEF588
Secret y0FISAGAS+OSIASec5Cts/khsWVXaWCoxZcLF2d8o/A=
merchantCode MX1209
TEST CARDS
Type Card Number Expiry Date Pin CVV
Successful Transaction Verve Test Card (No OTP) 6280511000000095 Dec 2026 0000 123
Insufficient Funds Verve Test Card 5061030000000000027 Sept 2019 1234 123
VISA Test Card (No iPIN) 4000000000000002 Apr 2020 No PIN 123
VISA Test Card (iPIN) 4000000000000002 Jan 2020 No PIN 123
Incorrect PIN (Masked as “Transaction Error”) Verve Test Card 5061030000000000035 Sept 2019 0000 123
AutoEnrollment Test Card (Response Code ‘M0’ returned) 506140000000000231 Jan 2020 1234 123

Card Payments

You can allow your customers to make card payments in any of the following ways below:

  • Payment with Card (No OTP Required)
  • Payment with Card (OTP Required)
  • Payment with Card (VISA Transactions)
  • Payment with Wallet (Requires OTP)

Payment with Card (No OTP Required)

This endpoint allows you to accept payments with card without a One Time Password (OTP).

Endpoint

POST

/api/v3/purchases

Sample Request

{
 "customerId": "1407002510", // Email, mobile number, BVN etc to uniquely identify the customer.
 "amount": "100",  // Amount in Naira.
 "transactionRef": "ESBDEV10000", // Unique transaction reference number (Max 20 chars).
 "currency":"NGN",   // ISO Currency code.
 "authData":"Lisy0gf1qwSgAOR4xNS5jkiLFSh0C6dYqyzQhxopAVHaG0DqTaB8yHYGPfYBAg2ZShyGp
 2YJRzLsxpquvRuUZe6IO7hV+DDG1fsfx6bzLL7i6c/UFcw/T+QrsNOUgLjSqqlRNkMFmn1XN3CT0PtYEM
 wExE38cFHjZN8dX2xZOKhwFJ9CJOs2VXeXCvfExxyZ5k3q+8dSxyHjYKrP3qfrjxhw7NFgEIvuo2xDlUTP
 6DLe8C/Z7QrBO3ggF7fo7Uz8t/vTcY7HvWmfX2UfiT7T5rzbOw24ahPZ8/tQg1dvpsiO81Qaw/lS+8P+Gi
 gkNO5+GeTpRjo+CO+n656zrwU8MQ=="  // Authentication Data.
}

Sample Response (Success)

{
  "transactionIdentifier": "FBN|WEB|VNA|23-05-2016|66593|177266",   // Transaction unique identifier.
  "message": "Approved by Financial Institution", // Success response message.
  "amount": "100.00", // Amount in Naira.
  "transactionRef": "ESBDEV10000"  // A unique transaction reference number.
}

Sample Response (Failure)

{
    "errors": [
        {
            "code": "Z1",  // Error code.
            "message": "Transaction Error" // Error message.
        }
    ],
    "transactionRef": "JB-1504003950-OTPPurchase" // A unique transaction transaction number
}

Payment with Card (OTP Required)

One Time Passwords (OTP) are an aspect of multi-factor authentication. They are short-lived passwords that work only for a single use. They’re usually generated by a dedicated piece of hardware, or by an app on the user’s mobile phone.

To accept payment with Card with OTP use this endpoint to make your request:

Endpoint

POST

/api/v3/purchases

Sample Request

{
    "customerId": "1407002510",// Email, mobile number, BVN etc to uniquely identify the customer.
    "amount": "200", // Amount in Naira.
    "transactionRef": "ESBDEV10002", // Unique transaction reference number (Max 20 chars).
    "currency":"NGN", // ISO Currency Code.
    "authData":"Lisy0gf1qwSgAOR4xNS5jkiLFSh0C6dYqyzQhxopAVHaG0DqTaB8yHYGPfYBAg2ZShyGp2YJRzLsxpquvRuUZe6IO7h
    V+DDG1fsfx6bzLL7i6c/UFc+QrsNOUgLjSqqlRNkMFmn1XN3CT0PtYEMwExE38cFHjZN8dX2xZOKhwFJ9CJOs2VXeXCvfExxyZ5k3q+8dSxyHjYKrP3qfrjxhw7NFgEIvuo2xDlUTP6DLe8C/Z7QrBO3ggF7fo7Uz8t/vTcY7HvWmfX2UfiT7T5rzbOw24ahPZ8/tQg1dvpsiO81Qaw/lS+8P+GigkNO5+GeTpRjo+CO+n656zrwU8MQ==" // Authentication Data.
}

Response Message (Success)

{
  "paymentId":"66599", // Payment Identifier.
  "responseCode": "T0", // Response Code.
  "amount": "200.00", // Amount in Naira.
  "transactionRef": "ESBDEV10002", // Unique transaction reference number.                                                  
  "message": "Kindly enter the OTP sent to 234812***8436 and dadub************itch.com" // Response message.
}

Response Message (Failure)

{
  "errors": [
    {
      "code": "10409", // Error code.
      "message": "Payment already completed"// Error message.
    }
  ],
  "transactionRef": "ESBDEV10002"  // A unique transaction reference number.
}

After the payment request has been sent, but the card is not registered for OTP, and OTP auto enrollment is supported, the response is similar to this.

Response (Requires OTP Enrollment)

{
  "message": "Kindly enter the mobile no registered with your bank",    // Response message.
  "responseCode": "M0", // Response Code for otp enrollment
  "paymentId": "3076959", // Payment Identifier.
  "transactionRef": "c470883b89dd433b998bed7aad63db9d"      
  // Your transaction reference  
}

OTP Enrollment

To autorize OTP to complete the payment transaction, make a POST call to the endpoint below:

Endpoint

POST

/api/v3/purchases/otps/auths

Sample Request

{
    "authData":"Lisy0gf1qwSgAOR4xNS5jkiLFSh0C6dYqyzQhxopAVHaG0DqTaB8yHYGPfYBAg2ZShyGp2YJRzLsxpquvRuUZe6IO7hV+DDG1fsfx6bzLL7i6c/UFcw/T+QrsNOUgLjSqqlRNkMFmn1XN3CT0PtYEMwExE38cFHjZN8dX2xZOKhwFJ9CJOs2VXeXCvfExxyZ5k3q+8dSxyHjYKrP3qfrjxhw7NFgEIvuo2xDlUTP6DLe8C/Z7QrBO3ggF7fo7Uz8t/vTcY7HvWmfX2UfiT7T5rzbOw24ahPZ8/tQg1dvpsiO81Qaw/lS+8P+GigkNO5+GeTpRjo+CO+n656zrwU8MQ==",    // Authentication Data.
    "paymentId":"66599",    // Payment Identifier.
    "otp":"742591" // One time password.
}

Sample Response (Success)

{
  "transactionIdentifier": "FBN|WEB|VNA|23-05-2016|66593|177266",   // Transaction unique identifier.
  "token": "5123452812351086018",                                   // Token for future payment.                  
  "tokenExpiryDate": "2004", // Card or Token expiry date in YYMM format.
  "panLast4Digits": "7499", // Card last four digits.
  "amount": "200.00",   // Amount in Naira.
  "transactionRef": "ESBDEV10002", // A unique transaction reference number.
  "message": "Approved by Financial Institution" // Success response message.
}

Sample Response (Failure)

{
  "errors": [
    {
      "code": "Z5",    // Error code.
      "message": "PAYMENT_ALREADY_PROCESSED" // Error message.
    }
  ],
  "paymentId": "66599"  // Payment Identifier.
}

Resend OTP

To request a Resend OTP function for a specific transactionRequest to complete a specific transaction, make a request to this endpoint.

Endpoint

POST

/api/v3/purchases/otps/resend

Sample Request

{
    "paymentId": "3436009",
    "amount": "2000",
    "currency": "NGN",
    "authData": "Z2vi7jzhpk/X182HJ4+2u0el5ZV9lwW/AOeXeOwDxvMLvI/Gu0j+008zwCyT1OhkQcz7H5ELtdNiNHeGtzBgYUNqazq2weqyV12onllgLtjcKYe8GCr7+Kx97iqYe3orYm9qxKc7TBKARLQ2ugd9dO5nboXMBmFHFH069vO7L0j0lU85XcYOH3J6fMOxAHdU0QuxT2UsOtP4eWCk3UL20gwkZk4o+YE7A1eeNqAoSdyvd5PwwlwUZ3PkFsXUorR7Xib0MnnMTkEKI6gJkEHc88sX3HTmbF5+dKKcn6tCUn20qT0iaXZNerPFqFZn9vRxmg6dZ5OWGAdtoSMCAC83ww=="
}
REQUEST PARAMETER
Parameter Description
paymentId The payment identifier of the current transaction which requires an OTP authorisation.
amount The amount of the transaction to be completed.
currency The ISO currency code
authData The authentication data for the transaction.

Sample Response (Success)

{
    "transactionRef": "15612627",
    "paymentId": "3436009",
    "message": "Kindly enter the OTP sent to 234812***8436 and dadub************itch.com",
    "amount": "2000.00",
    "responseCode": "T0"
}

Sample Response (Failure)

{
    "paymentId": "3436009",
    "errors": [
        {
            "code": "XS1",
            "message": "Your payment has exceeded the time required to pay"
        }
    ]
}

Device Fingerprint Authorization

To benefit from device fingerprint authorization, the device info such as IMEI is required as part of the request body for purchases.

How Device Fingerprint Works

Device fingerprint allows a user to make complete payment without the need to provide an OTP. When a user make three successful purchase requests with the same device info provided as part of the request body, the gateway prompts the user to subscribe for "Device Fingerprint" by setting a response parameter (registerFingerprint) to true. If the user respond affirmatively, then the fingerprint of the device will be registered and the user can perform transactions without the need for an OTP for a given period of time (say three months) or until when the user opted out.

Endpoint

POST

/api/v3/purchases/otps/auths

Sample Request

{ 
  "customerId": "1407002510",
  "amount": "200",
  "transactionRef": "Fingerprint25",
  "currency": "NGN",
  "authData": "mILBgKj6/EZpGX8xMKSfa7+MOUeOSYiotIleZrNtbLgkcnkCBJnBcp3AbqvRVxgdTYeT277QR7Fw9jXlvkx+dpUoyVyc7m1+qJQqVlBSNxBR43Apmj1/fXTlnAsKPKfeff7/sbZBXc0JHTvKcbTH8w4utpV00xATDH3dxNKw/aMIdUUjWPF9Aet4kiiCXj3wwbzGvpW1OkNeZDXxcr++UBRZwXkNP8fVBCl1+g3er20/u5Q0S8BEZWvo9U9NekVq5h9RwzqyfNWbCih9oty3pVvQF5F+FhNAnKoAnHgNs3pFg6LkcEJAfn6J7vkOuvMa261SlCrwECYDDDdwY1xrHg==",
  "deviceInfo": {
  "deviceId": "mydevice-111-333-444-555" }
}

The following fields in the table below are required in addition to the fields required for purchase requests.

REQUEST PARAMETER
Parameter Description
deviceInfo A JSON object property that encapsulate the device ID which description is given below.
deviceId A field in deviceInfo object that contains the device identifier such as IMEI of the underlying device used to perform a payment.

Sample Response (Success)

{
  "paymentId": "3719488",
  "responseCode": "T0",
  "message": "Kindly enter the OTP sent to 234812***8436 and dadub************itch.com",</p>
  "amount": "200.00",
  "responseCode": "T0",
  "plainTextSupportMessage": "Didn't get the OTP? Dial *322*0# on your phone (MTN, Etisalat, Airtel) Glo, use *805*0#.",
  "registerFingerPrint": true
}

The sample response above is obtained after three successful purchases. Worthy to note is an additional field registerFingerprint which is true if the user is eligible to register fo fingerprint authorization. If the user is interested in enabling fingerprint authorization, then he or she will responded with a field registerFingerPrintResponse which value is set to true. This is sent as part of the request body for the OTP authorization phase of the transaction. As shown in the sample below. The deviceInfo must always be provided. In a situation where the user is not interested in enabling fingerprint authorization, then the registerFingerPrintResponse field could be set to false or not included in the request body for the OTP authorisation.

Sample Request

{
  "paymentId": "3715732",
  "otp": "835149",
  "authData": "Z2vi7jzhpk/X182HJ4+2u0el5ZV9lwW/AOeXeOwDxvMLvI/Gu0j+008zwCyT1OhkQcz7H5ELtdNiNHeGtzBgYUNqazq2weqyV12onllgLtjcKYe8GCr7+Kx97iqYe3orYm9qxKc7TBKARLQ2ugd9dO5nboXMBmFHFH069vO7L0j0lU85XcYOH3J6fMOxAHdU0QuxT2UsOtP4eWCk3UL20gwkZk4o+YE7A1eeNqAoSdyvd5PwwlwUZ3PkFsXUorR7Xib0MnnMTkEKI6gJkEHc88sX3HTmbF5+dKKcn6tCUn20qT0iaXZNerPFqFZn9vRxmg6dZ5OWGAdtoSMCAC83ww==",
  "deviceInfo": {
  "deviceId": "mydevice-111-333-444-555"},
  "registerFingerPrintResponse": "true"
}

Sample Response

{
  "transactionRef": "Fingerprint24",
  "message": "Approved by Financial Institution",
  "transactionIdentifier": "FBN|API|MX6072|05-11-2019|3715732|270707",
  "amount": "200.00",
  "responseCode": "00"
}

After fingerprint authorization has been enabled, then the user can perform successful purchase requests for the next three months without the need to provide an OTP. The response body remains the same as for normal purchase request. Use the endpoint below if the user is interested in disabling fingerprint authorization.

Endpoint

POST

/api/v3/purchases/fingerprint/disable

Sample Request

{
  "authData": "mILBgKj6/EZpGX8xMKSfa7+MOUeOSYiotIleZrNtbLgkcnkCBJnBcp3AbqvRVxgdTYeT277QR7Fw9jXlvkx+dpUoyVyc7m1+qJQqVlBSNxBR43Apmj1/fXTlnAsKPKfeff7/sbZBXc0JHTvKcbTH8w4utpV00xATDH3dxNKw/aMIdUUjWPF9Aet4kiiCXj3wwbzGvpW1OkNeZDXxcr++UBRZwXkNP8fVBCl1+g3er20/u5Q0S8BEZWvo9U9NekVq5h9RwzqyfNWbCih9oty3pVvQF5F+FhNAnKoAnHgNs3pFg6LkcEJAfn6J7vkOuvMa261SlCrwECYDDDdwY1xrHg==",
  "deviceInfo": {
  "deviceId": "mydevice-111-333-444-555"}
}

Sample Response (Success)

{
  "responseCode": "200",
  "message": "Fingerprint disabled successfully"
}

Sample Response (Failure)

{
  "errors": [
  {"code": "E42",
  "message": "Fingerprint not enabled"}]
}

Payment with Card (VISA Transactions)

To accept payment with Card that requires cardinal (such as VISA card), use this end point to make your request.

Endpoint

POST

/api/v3/purchases

Sample Request

{
    "customerId": "1407002510", // Email, mobile number, BVN etc to uniquely identify the customer.
    "amount": "200", // Amount in naira.
    "transactionRef": "ESBDEV10003", // Unique transaction reference number.
    "currency":"NGN",   // ISO Currency code.
    "authData":"AMZtxiP2Jxx5PjYnM+YbtxMt56j/0cfaqo27oCTEa7ifuONNODvmshDVLYdSl0YZ41dETsI1ZgzRy6iYvPUZ0g2E41AU4wAcmU55sFsuEyAfuHWVrw/sOuyBtg/vO9k1Khv/KPNHw/bg8GvmWPclS1Ti4V01sMkEdjGDX3L3geh05fCHrk8/Z8VHOLMHQ4v9sKbsrwzglS9qBRTqHhfYmayG2+s4j3KE82hPeK/6trxtvJ0vCE6h2/UOyxaD+WjtrQblSW/g8Cpyhw3AkE9JR14bNxQXQWCeWI1obwPcGHE04gsKFLekBIjFqKlszMXHlkevBHgdSHnexbWjtj/O6Q==" // Auth data.
}

Sample Response (Success)

{
  "paymentId": "66603", // Payment Identifier.
  "responseCode": "S0",  // Response Code.
  "amount": "200.00",  // Amount in Naira.
  "transactionRef": "ESBDEV10003",  // Uniques transaction reference number.
  "transactionId": "MSPjKBV2Kyg91MQRMep0", // Transaction unique identifier.
  "eciFlag": "07",  // The Electronic Commerce Indicator (ECI) Flag e.g Visa:05: Issuer Liability,  07: Merchant Liability.
  "MD": "66603", // Merchant's session tracker. Set to blank if not used.
  "ACSUrl": "https://testcustomer34.cardinalcommerce.com/V3DSStart?osb=visa-3&VAA=B", // This is the URL to which your application must next send the cardholder to complete authentication.
  "TermUrl": "https://sandbox.interswitchng.com/collections/api/v1/pay/cardinalCallBack", // The URL for handling and processing the response from the ACSUrl.
  "PaReq": "eNpVUttu4jAQffdXoH5AbOeCtGhqKQVp2+2GpmlL9zU4s2AgTuo4Bf6+doBe3uacuficGcPz2iDOnlD2BgVk2HXlCkequr7KnvLN/c0ivD+ufvHssciwZVcC8rTANwHvaDrVaMEDFoRAL5C4EUauS20FlPLt5m4u4jiOogjoGRKo0dzNBA+jOBkDPSECuqxRpBXaXm+UGqVbpSsEOtAEZNNra44iGbuWCyDQm51YW9tOKN3jsi2PgdLWSdkrK9d6Fcimpo6tlEFpaYV1A9T3EKBfOvPeR52zf1CVeF7MH8utnS42f/7iq0yyF168bPlOztJroL6CQFVaFCHjY5aE0YjzScInPAY68ATK2gsU89/zUchYwJgzf6IItP6x9IRc0ue+U85pbwxqebF6QQTw0DYafRvQz9gZ+ZI/vfVLl9btM5/pij10u+Vh+v/233IfcrnPZVE0/g5DxTBQuS06FfEwUQ0rpX4KPV+Znj+Ei358lA9Mdboe"  // Content of the Payload field from cmpi_lookup.
}

Sample Response (Failure)

 {
  "errors": [
    {
      "code": "10409", // Error code.
      "message": "Payment already completed" // Error Message.
    }
  ],
  "transactionRef": "ESBDEV10003" // Transaction unique identifier.
}

Authorize Transaction (VISA)

To authorize a transaction using cardinal (i.e responseCode = S0), create an html page that has a form that submits on page load with the value of ACSUrl from the response as the action of the form.

Sample Form

<body onload ='form1.submit()'>
    <!-- NOTE: ACSUrl, TermUrl, MD and PaReq should be replaced with their corresponding values.
    e.g ACSUrl = "https://testcustomer34.cardinalcommerce.com/V3DSStart?osb=visa-3&VAA=B"
        TermUrl = "https://sandbox.interswitchng.com/collections/api/v1/pay/cardinalCallBack"
        MD = "66603"
        PaReq = "eNpVUttu4jAQffdXoH5AbOeCtGhqKQVp2+2GpmlL9zU4s2AgTuo4Bf6+doBe3uacuficGcPz2iDOnlD2BgVk2HXlCkequr7KnvLN/c0ivD+ufvHssciwZVcC8rTANwHvaDrVaMEDFoRAL5C4EUauS20FlPLt5m
    4u4jiOogjoGRKo0dzNBA+jOBkDPSECuqxRpBXaXm+UGqVbpSsEOtAEZNNra44iGbuWCyDQm51YW9tOKN3jsi2PgdLWSdkrK9d6Fcimpo6tlEFpaYV1A9T3EKBfOvPeR52zf1CVeF7MH8utnS42f/7iq0yyF168bPlOztJroL6CQFVaFCHjY5aE0YjzScInPAY68ATK2gsU89/zUchYwJgzf6IItP6x9IRc0ue+U85pbwxqebF6QQTw0DYafRvQz9gZ+ZI/vfVLl9btM5/pij10u+Vh+v/233IfcrnPZVE0/g5DxTBQuS06FfEwUQ0rpX4KPV+Znj+Ei358lA9Mdboe"
-->
  <form id="form1" action=ACSUrl method="post">
    <input name="TermUrl" value=TermUrl>
    <input name="MD" value=MD>
    <input name="PaReq" value=PaReq>
  </form>

The sample form above opens the Visa cardinal authorization page, where the user can enter their Visa Card iPin/Password and Submit. After submmitting, you need to authorize the cardinal transaction by calling the endpoint below.

Endpoint

POST

/api/v3/purchases/otps/auths

Sample Request

{
    "paymentId":"66603", // Payment Identifier.
    "transactionId":"MSPjKBV2Kyg91MQRMep0", //Transaction unique identifier.
    "eciFlag":"07" // The Electronic Commerce Indicator (ECI) Flag e.g Visa:05: Issuer Liability, 06: Issuer Liability, 07: Merchant Liability.
}

Sample Response (Success)

{
    "transactionIdentifier": "GTB|WEB|VNA|23-05-2016|66603|999591", // Transaction unique identifier.
    "token": "5123453847245380", // Card Number or Token.
    "tokenExpiryDate": "2004", // Card or Token expiry date in YYMM format.
    "panLast4Digits": "0002", // Last for digit of payment instrument.
    "amount": "200.00",  // Amount in Naira.
  "transactionRef": "ESBDEV10003", // Unique transaction reference number.
  "message": "Approved by Financial Institution"  // Response message.
}

Sample Response (Success)

{
  "errors": [
    {
      "code": "Z5", // Error code.
      "message": "PAYMENT_ALREADY_PROCESSED"  // Error message.
    }
  ],
  "paymentId": "66603" // Transaction unique identifier.
}

Payment with Wallet (Requires OTP)

This type of purchase uses the card hash as the pan in the auth data unlike a normal purchase where the card pan is used. Also, this feature allows fingerprint authentication after three requests with the same device-id and card hash.

Endpoint

POST

/api/v2/purchases

Sample Request

{
  "authData": "eoBZduQLkqRDw8oZMBMoONLWCZN25FV2GLWY3hIRHLdIlxaXs2voUj/jL+XkfGhnNGsRmjN
  af9gy9tpLLuV3XUA4lyGhmAJtKVZO4Bv9LPNfq4HgvpU1++8/gyRUX7oIv684uxg3WNMmGZz9NSbBtPLJ2
  wPwBgAkmu4ieFxUwyLieVoL41zG6yFQWPegoBVaSAeI3DyGsdS244V+koBLLEvrsM+mB1krdEEFx6N+0C
  cCZAJ2PnHB9cLAsVMcHBfo5UD2Y94fxgOE/JSJ9xnlRRexE2CK6ZcFbmnWuOReg47FJwsT5gzW0bA8U7
  C7FQZQgnvDb/cxcqIUhB9vHtDUBQ==",
  "instrumentIdentifier": "049118E0A39A4D0A5913A14538B4D279FCD66BDE4BB2E3ECD",
  "transactionType": "REGULAR",
  "deviceInfo": {
  "deviceId": "myDevice-111-333-444-777"},
  "transactionRef": "2343rrf5tggol1",
  "amount": "1000",
  "customerId": "0000000001",
  "currency": "NGN"
}
REQUEST PARAMETER
Parameter Required Description
Auth Data True Auth data consists of the card hash, expiry date, cvv and pin. Note: The PAN in the AuthData can be a tokenized PAN or an ordinary PAN
Instrument Identifier True Instrument Identifier for the particular card hash used
Device Info True Device info object consists of the device id
Currency True The currency for the purchase
Customer Id True Customer Id
Amount True Desired amount
Transaction Reference True Transaction Reference

Sample Response (Success)

{
  "paymentId": "3396964",
  "message": "Kindly enter the OTP sent to 234812***8436 and mario*******mail.com",
  "responseCode": "T0",
  "amount": "1000.00",
  "transactionRef": "2343rrf5tggol1"
}

Sample Response (Success)

{
  "errors": [
  {"code": "10409",
  "message": "Payment already completed"}],
  "transactionRef": "2343rrf5tggol1"
} 

Authorize Wallet Transaction with OTP

As initially stated, you need to authorize a transaction with a second API call when OTP is involved. The PAN in the AuthData can be a tokenized PAN or an ordinary PAN. To a wallet transaction with OTP, make a request to the endpoint below:

Endpoint

POST

/api/v2/purchases/otps/auths

Card Validation

As part of transaction flow, we check that a card is valid. The endpoints below allows you to be able to validate a card and we return a response to you and the validity.

Validation

To check if a card is valid and get a token, use this end point to make your request.

Endpoint

POST

/api/v3/purchases/validations

Sample Request

{
 "transactionRef": "ESBDEV10004", // Unique transaction reference number.
 "authData":"Lisy0gf1qwSgAOR4xNS5jkiLFSh0C6dYqyzQhxopAVHaG0DqTaB8yHYGPfYBAg2ZShyGp2YJRzLsxpquvRuUZe6IO7hV+DDG1fsfx6bzLL7i6cUFcwT+QrsNOUgLjSqqlRNkMFmn1XN3CT0PtYEMwExE38cFHjZN8dX2xZOKhwFJ9CJOs2VXeXCvfExxyZ5+8dSxyHjYKrP3qfrjxhw7NFgEIvuo2xDlUTP6DLe8CZ7QrBO3ggF7fo7Uz8tvTcY7HvWmfX2UfiT7T5rzbOw24ahPZ8tQg1dvpsiO81QawlS+8P+GigkNO5+GeTpRjo+CO+n656zrwU8MQ==" // Authentication Data.
}
REQUEST PARAMETERS
Parameters Description
transactionRef Unique transaction reference number (Max 20 chars).
authData Authentication Data.

Sample Response (Success)

{
  "responseCode": "T0", // Response code.
  "transactionRef": "ESBDEV10004", // Unique transaction reference number.
  "message": "Kindly enter the OTP sent to 234812***8436 and dadub************itch.com" // Response message.
}

Sample Response (Failure)

{
  "errors": [
    {
      "code": "E42",  // Error code.
      "message": "Auth Data error" // Error message.
    }
  ],
  "transactionRef": "ESBDEV10004" // Unique transaction reference number.
}

Card Validation Authorization (VISA)

To authorize card validation use this endpoint

Endpoint

POST

/api/v3/purchases/validations/otps/auths

Sample Request

{
    "authData":"AMZtxiP2Jxx5PjYnM+YbtxMt56j/0cfaqo27oCTEa7ifuONNODvmshDVLYdSl0YZ41dETsI1ZgzRy6iYvPUZ0g2E41AU4
    wAcmU55sFsuEyAfuHWVrw/sOuyBtg/vO9k1Khv/KPNHw/bg8GvmWPclS1Ti4V01sMkEdjGDX3L3geh05fCHrk8/Z8VHOLMHQ4v9sKbsrw
    zglS9qBRTqHhfYmayG2+s4j3KE82hPeK/6trxtvJ0vCE6h2/UOyxaD+WjtrQblSW/g8Cpyhw3AkE9JR14bNxQXQWCeWI1obwPcGHE04gs
    KFLekBIjFqKlszMXHlkevBHgdSHnexbWjtj/O6Q==", // Authentication Data.
    "transactionId":"MSPjKBV2Kyg91MQRMep0", // Transaction unique identifier.
    "eciFlag":"07", // The Electronic Commerce Indicator (ECI) Flag e.g Visa:05: Issuer Liability, 06: Issuer Liability, 07: Merchant Liability.
      "transactionRef": "cW5m837DjswX"
}
REQUEST PARAMETER
Parameter Description
transactionRef Unique transaction reference number (Max 20 chars).
authData Authentication Data.
transactionId Transaction Id
eciFlag The Electronic Commerce Indicator (ECI) Flag e.g Visa:05: Issuer Liability, 06: Issuer Liability, 07: Merchant Liability.

Sample Response (Success)

{
    "transactionIdentifier": "GTB|WEB|VNA|23-05-2016|66603|999591", // Transaction unique identifier.
    "tokenExpiryDate": "2004", // Card or Token expiry date in YYMM format.
    "cardType": "Visa", // Type of the card.
    "transactionRef": "ESBDEV10003", // Unique transaction reference number.
    "token": "5123453847245380", // Card Number or Token.
    "panLast4Digits": "0002",  // PAN Last four digit.
    "balance": "" // Monetary balance of payment instrument.
}

Authorize Transaction

Use this endpoint to complete a card validation with OTP.

Endpoint

POST

/api/v3/purchases/validations/otps/auths

Sample Request

{
 "transactionRef": "ESBDEV10004", // Unique transaction reference number.
 "authData":"Lisy0gf1qwSgAOR4xNS5jkiLFSh0C6dYqyzQhxopAVHaG0DqTaB8yHYGPfYBAg2ZShyGp2YJRzLsxpquvRuUZe6IO7h
  V+DDG1fsfx6bzLL7i6c/UFcw/T+QrsNOUgLjSqqlRNkMFmn1XN3CT0PtYEMwExE38cFHjZN8dX2xZOKhwFJ9CJOs2VXeXCvfExxyZ5
  k3q+8dSxyHjYKrP3qfrjxhw7NFgEIvuo2xDlUTP6DLe8C/Z7QrBO3ggF7fo7Uz8t/vTcY7HvWmfX2UfiT7T5rzbOw24ahPZ8/tQg1d
  vpsiO81Qaw/lS+8P+GigkNO5+GeTpRjo+CO+n656zrwU8MQ==", // Authentication Data.
 "otp":"864923" // OTP sent to the mobile device or email address of the card holder.
}

Sample Response (Success)

{
  "token": "5123452812351086018", // Token generated after successful validation, which can be used in making payment in future.
  "tokenExpiryDate": "2004", // Token expiry date.
  "panLast4Digits": "7499",  // PAN last four digits.
  "transactionRef": "ab1cfgh89bvbfgvrt2", // Transaction reference number.
  "balance": "5,208,513.10",  // Card balance.
  "cardType": "Verve"  // Card type.
}

Sample Response (Failure)

{
  "errors": [
    {
      "code": "Z5",  // Error code.
      "message": "PAYMENT_ALREADY_PROCESSED"  // Error message.
    }
  ],
  "paymentId": "66603" // Payment identifier.
}

Authorize VISA Transactions

Use this endpoint to authorize cardinal for card validation.

Endpoint

POST

/api/v3/purchases/validations/otps/auths

Sample Request

{
    "authData":"AMZtxiP2Jxx5PjYnM+YbtxMt56j/0cfaqo27oCTEa7ifuONNODvmshDVLYdSl0YZ41dETsI1ZgzRy6iYvPUZ0g2E41AU4
    wAcmU55sFsuEyAfuHWVrw/sOuyBtg/vO9k1Khv/KPNHw/bg8GvmWPclS1Ti4V01sMkEdjGDX3L3geh05fCHrk8/Z8VHOLMHQ4v9sKbsrw
    zglS9qBRTqHhfYmayG2+s4j3KE82hPeK/6trxtvJ0vCE6h2/UOyxaD+WjtrQblSW/g8Cpyhw3AkE9JR14bNxQXQWCeWI1obwPcGHE04gs
    KFLekBIjFqKlszMXHlkevBHgdSHnexbWjtj/O6Q==",  // Authentication Data.
    "transactionId":"MSPjKBV2Kyg91MQRMep0", // Transaction unique identifier.
    "eciFlag":"07",  // The Electronic Commerce Indicator (ECI) Flag e.g Visa:05: Issuer Liability, 06: Issuer Liability, 07: Merchant Liability.
      "transactionRef": "cW5m837DjswX"
}

Sample Response (Success)

{
    "transactionIdentifier": "GTB|WEB|VNA|23-05-2016|66603|999591", // Transaction unique identifier.
    "tokenExpiryDate": "2004", // Card or Token expiry date in YYMM format.
    "cardType": "Visa", // Type of the card.
    "transactionRef": "ESBDEV10003", // Unique transaction reference number.
    "token": "5123453847245380", // Card Number or Token.
    "panLast4Digits": "0002", // PAN Last four digit.
    "balance": "" // Monetary balance of payment instrument.
}

Tokenized Payments

To accept payment with token without One Time Password (OTP) make a request to this endpoint.

Endpoint

POST

/api/v3/purchases

Sample Request

{
  "customerId": "1407002510",
  "amount": "100",
  "transactionRef": "ESBDEV10001",
  "currency":"NGN",                      
  "authData":"OcjtrW9m1NXZXSS17GVJeerPz2PAtDtJerTobtO6FuRf9gcfOWUzCvql5rJzpRQ
  sjfOq0UbcwMAH92F/RdcGv0sxlfHQy3eA2dhO6t7V79FtJ+E1pIbeKNjbH+NFSdXwx5BBKR33DP
  A+NI3m9fWNSYchpAPzeQ/QmqMuR1FPhf6fFQxLPj6oZnVIABbA0++s1hQsqc00bpWDpkyIjNCJP
  MfatVxELUH1G27g0HNJRGZSVZC8yS8qR9ewCnpPzU1ABc2pQSXTtECNqai/lXcQe3in7HnwRXmO
  UIMT+3F5cQwEnNcCGl90v26p9fhuzy0hBNzlsSr7c20xih935sAqMg=="
}
REQUEST PARAMETERS
Parameters Description
customerId Email, mobile number, BVN etc to uniquely identify the customer.
amount Amount in Naira.
currencyCode ISO Currency code.
transactionRef Unique transaction reference number (Max 20 chars).
authData Authentication Data.

Sample Response (Success)

{
  "transactionIdentifier": "FBN|WEB|VNA|23-05-2016|66597|570518",
  "amount": "100.00",
  "transactionRef": "ESBDEV10001",
  "message": "Approved by Financial Institution"
}

Sample Response (Failure)

{
  "errors": [
  {"code": "10409",
  "message": "Payment already completed"}], 
  "transactionRef": "ESBDEV10001"
}

Querying a Transaction

To confirm the status of a completed transaction from Interswitch, make a request to the endpoint below. To make a request to this endpoint, pass the transaction details as request parameters or include them in the request header.

Endpoint

GET

/collections/api/v1/gettransaction.json?

Method 1 (Request Parameter)

If you want to use this method to query a transaction, pass the transaction details (merchantcode, transactionreference and amount) via the request parameter. See a sample request below:

Sample Request

/collections/api/v1/gettransaction.json?merchantcode=MX187&transactionreference=933437251484&amount=66666600

Response Message (Success)

{
    "Amount": 66666600,
    "CardNumber": "",
    "MerchantReference": "933437251484",
    "PaymentReference": "UBA|API|MX187|25-07-2018|249510|719456",
    "RetrievalReferenceNumber": "000647661227",
    "SplitAccounts": [],
    "TransactionDate": "2018-07-25T06:57:24",
    "ResponseCode": "00",
    "ResponseDescription": "Approved by Financial Institution",
    "AccountNumber": "9999999999"
}

Response Message (Failure)

{
    "Amount": 0,
    "SplitAccounts": [],
    "ResponseCode": "Z1",
    "ResponseDescription": "Amount Inconsistency"
}


Method 2 (Request Header)

If you want to use this method to query a transaction, pass the transaction details (transactionRef and amount) via the request header and make a GET request to this endpoint /api/v3/purchases. See a sample request below:

JavaScript

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9==
-ejQxMMh15U59fWIQ
Timestamp: 1361281946
Nonce: 634968823463411609
Signature: 2cFwCfkgRR7mlIOlcjTQXCUYpLmtlKJkCb8RUzIX0-k=
SignatureMethod: SHA-256Sample response (Success)
Amount: 100.00
transactionRef: ESBDEV50001tttt76838

Response Message (Success)

{
  "amount": "100.00",
  "transactionRef": "ESBDEV50001tttt76838",
  "transactionDate": "2016-07-12T06:51:31",
  "message": "Approved by Financial Institution"
}

Response Message (Failure)

{
    "Amount": 0,
    "SplitAccounts": [],
    "ResponseCode": "20031",
    "ResponseDescription": "Invalid value for Product id or Merchant Code"
}

Pay with QR

This endpoint is used to generate a QR string for a transaction.

Endpoint

POST

/collections/api/v1/sdk/qr/generates

Sample Request

{
  "amount": 10000,
  "currencyCode": "566",
  "merchantTransactionReference": "2222aaa1123bc"
}
REQUEST PARAMETERS
Parameters Description
amount amount in kobo
currencyCode 566 for naira (ISO 2417 Numeric)
merchantTransactionReference If the value supplied is for an existing incomplete(non successful) transaction, a QR would be generated for that transaction. If the refernece does not match an existing transaction, a new transaction would be created and QR generated.

Sample Response (Success)

{ 
  "qrCodeId": "4077131255285",
  "qrCodeIdMVisa": "4077131255285",
  "rawQRData": "000201021340771312552855204539953035665406100.
  005802NG5904sadd6004sdsd621705132222aaa1123bc6304FEA4",
  "transactionReference": "2222aaa1123bc"
}

Sample Response (Failure)

{ 
  "code": "10400",
  "description": "Please provide the transactionReference"
}
RESPONSE MESSAGE DESCRIPTION
Parameters Description
qrCodeId The merchant ID tied to the QR scheme
rawQRData The raw string that is supposed to be encoded in the QR image to be displayed. It's up to client to use whatever library they want to generate the QR image.
transactionReference The transaction reference for the transaction

Pay with USSD

The endpoints below grant your customers access to make payments with Unstructured Supplementary Service Data (USSD).

Get Supported USSD Banks

This endpoint gives you a list of all supported USSD Banks

Endpoint

GET

/collections/api/v1/ussd/issuers/NG

Sample Response (Success)

[ 
  {"name": "Fidelity Bank","code": "FBP","cbnCode": "FBP"},
  {"name": "Guaranty Trust Bank","code": "GTB","cbnCode": "GTB"},
  {"name": "Keystone Bank","code": "KSB","cbnCode": "KSB"},
  {"name": "Providus Bank","code": "UMB","cbnCode": "UMB"},
  {"name": "Quickteller","code": "QUICKTELLER","cbnCode": "QUICKTELLER"}
]
RESPONSE MESSAGE DESCRIPTION
Parameters Description
name The name of the bank
code The bankCode of the bank. This is the value you use in the generate call
cbnCode The CBN code for the bank.

Generate USSD

This endpoint is used to generate USSD string for transaction.

Endpoint

POST

/collections/api/v1/ussd/generate

Sample Request

{
  "amount": 10000,
  "bankCode":"GTB",
  "merchantTransactionReference": "bb12222zzaaz"
}
REQUEST PARAMETER
Parameters Description
amount amount in kobo
bankCode Interswitch domain code for the bank you are generating a USSD string for.
merchantTransactionReference If the value supplied is for an existing incomplete(non successful) transaction, a USSD string would be generated for that transaction. If the reference does not match an existing transaction, a new transaction would be created and USSD stringgenerated.

Sample Response (Success)

{
  "reference": "74677",
  "bankShortCode": "*737*6*74677#",
  "transactionReference": "bb12222zzaaz",
  "responseCode": "00",
  "defaultShortCode": "*322*419*051691201*74677#"
}

Sample Response (Failure)

{
  "code": "10400",
  "description": "Please provide the transactionReference"
}
RESPONSE PARAMETER DESCRIPTION
Parameters Description
responseCode The response code for the request. 00 means it was successful. 10400 means an invalid parameter was supplied. 10500 means something wrong happened that we weren't expecting, try again.
bankShortCode This is the USSD short code for the bank the customer selected for the transaction.
transactionReference The transaction reference for the transaction.
reference The actual USSD reference for the transaction.
defaultShortCode The Quickteller USSD short code for the transaction.

Transaction Status

This endpoint is used to get payment status.

Endpoint

GET

/collections/api/v1/gettransaction.json

Sample Request

api/v1/gettransaction.json?merchantcode=MX33&transactionreference=Test10101&amount=10000
RESPONSE MESSAGE DESCRIPTION
Parameters Data type Required Description
merchantcode String False The merchant code (either productid or merchant must be sent)
transactionreference String True The transaction reference of the transaction.
amount String true The amount send in the transaction in minor format

Sample Response (Success)

{
  "Amount": 10000,
  "CardNumber": "",
  "MerchantReference": "Test10101",
  "SplitAccounts": [],
  "TransactionDate": "2016-08-05T12:00:00",
  "ResponseCode": "Z1",
  "ResponseDescription": "Transaction Not Completed"
}

Sample Response (Failure)

{ 
  "Amount": 0,
  "SplitAccounts": [],
  "ResponseCode": "Z1",
  "ResponseDescription": "Amount Inconsistency"
}