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.

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.

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.

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

{ 
  "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"
}

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

{
 "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.
}

{
  "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.
}

{
    "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:

{
    "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.
}

{
  "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.
}

{
  "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.

{
  "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:

{
    "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.
}

{
  "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.
}

{
  "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.

{
    "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.

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

{
    "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.

{ 
  "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.

{
  "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.

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

{
  "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.

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

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

{
  "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.

{
    "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.
}

{
  "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.
}

 {
  "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.

{
    "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.
}

{
    "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.
}

{
  "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.

{
  "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

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

{
  "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:

---

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.

{
 "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.

{
  "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.
}

{
  "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

{
    "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.

{
    "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.

{
 "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.
}

{
  "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.
}

{
  "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.

{
    "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"
}

{
    "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.

{
  "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.

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

{
  "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.

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:

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

{
    "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"
}

{
    "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

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

{
    "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.

{
  "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.

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

{ 
  "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

[ 
  {"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.

{
  "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.

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

{
  "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.

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

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

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

---