Introduction

The ability to check your balance enquiry or change your pin in possible with your client ID and Secret key.

Sample Requests

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

Developer Console

In order to get started that, follow the steps below to get your Client ID and Secret Key from our Developer Console:

  • Create an account on our Developer Console if you've not already done so.
  • Login to the Developer Console.
  • Click on Create Project, add the required information and click on Create.
  • Click on your newly created project and copy your Client ID and Secret Key.

Balance Enquiry

This API can be used to check your balance.

Endpoint

GET

https://sandbox.interswitchng.comapi/v1/cards/balances
REQUEST PARAMETERS
Parameters Description
Client ID Application ID. Navigate to `https://developer.interswitchgroup.com` for your application secret
Secret Application secret. Navigate to `https://developer.interswitchgroup.com` for your application secret
Content-Type The MIME type of the body of the request
Authorization Describes the Realm and Identity of the user requesting access to resource.
Signature Must be represented in base 64. The signature is calculated from a combination defined data elements separated by the '&' character.
Timestamp Request timestamp in epoch (unix). It must be in seconds and NOT milliseconds. e.g. 1440071245.
Nonce A unique generated value for each request. It should not be repeated. Length should NOT be more than 64 characters.
TERMINAL_ID Terminal Id provided by Interswitch.
AUTH_DATA Click on Additional Header to add this. This header contains the combination of the card pan, pin and expiry date all in a single block of encrypted string.
PRODUCT_CODE Identifies the calling client
oldauthdata The encrypted data of the PAN, original PIN and expiry date of the card
newauthdata The encrypted data of the PAN, new PIN and expiry date of the card.

Sample Response (Success)

{
    "balance":"100,000,000.00"
}

Sample Response (Failure)

{   "errors"=>[{
    "code"=>"E38",
    "message"=>"Request payload is invalid"}],
    "error"=>{"code"=>"E38",
    "message"=>"Request payload is invalid"}
}

Pin Change

This API can be used to change your pin.

Endpoint

PUT

https://sandbox.interswitchng.com/api/v1/cards/pinchange
REQUEST PARAMETERS
Parameters Description
Client ID Application ID. Navigate to `https://developer.interswitchgroup.com` for your application secret
Secret Application secret. Navigate to `https://developer.interswitchgroup.com` for your application secret
Content-Type The MIME type of the body of the request
Authorization Describes the Realm and Identity of the user requesting access to resource.
Signature Must be represented in base 64. The signature is calculated from a combination defined data elements separated by the '&' character.
Timestamp Request timestamp in epoch (unix). It must be in seconds and NOT milliseconds. e.g. 1440071245.
Nonce A unique generated value for each request. It should not be repeated. Length should NOT be more than 64 characters.
TERMINAL_ID Terminal Id provided by Interswitch..
AUTH_DATA Click on Additional Header to add this. This header contains the combination of the card pan, pin and expiry date all in a single block of encrypted string.
PRODUCT_CODE Identifies the calling client
oldauthdata The encrypted data of the PAN, original PIN and expiry date of the card
newauthdata The encrypted data of the PAN, new PIN and expiry date of the card.

Sample Request

{
    "oldAuthData":"P+sCbEq14u8ambv7kanN9WO==",
    "newAuthData":"felhSObyLrqk8hcSrNTBbHZw==",
    "terminalId":"4QTL0001",
    "productCode": "0123345"
}

Sample Response (Failure)

{
    "errors"=>[{
    "code"=>"55",
    "message"=>"Failed",
    "statusCode"=>"55",
    "statusMessage"=>"Failed"}],
    "error"=>{
    "code"=>"55",
    "message"=>"Failed",
    "statusCode"=>"55",
    "statusMessage"=>"Failed"}
} 

Sample Code

// Timestamp
TimeZone lagosTimeZone = TimeZone.getTimeZone("Africa/Lagos");  
Calendar calendar = Calendar.getInstance(lagosTimeZone);  
long timestamp = calendar.getTimeInMillis() / 1000;

// Nonce
UUID uuid = UUID.randomUUID();
String nonce = uuid.toString().replaceAll("-", "");

// Signature Method
String signatureMethod = "SHA1";

// Signature
String httpMethod = "POST"; // HTTP Method of the resource that is being called
String encodedResourceUrl = "RESOURCE_URL"; // put the resource URL here
String clientId = "CLIENT_ID"; // put your client Id here
String clientSecretKey = "CLIENT_SECRET_KEY"; // put your client secret here
String signatureCipher = httpMethod + "&" + encodedResourceUrl + "&" +
 timestamp + "&" + nonce + "&" + clientId + "&" + clientSecretKey;
MessageDigest messageDigest = MessageDigest.getInstance(signatureMethod);  
byte[] signatureBytes = messageDigest.digest(signatureCipher.getBytes());  
String signature = new String(Base64.encodeBase64(signatureBytes));

// Setting HTTP Header values
String resourceUrl = "https://sandbox.interswitchng.com/passport/oauth/token";
HttpPost post = new HttpPost(resourceUrl);  
post.setHeader("TIMESTAMP", timestamp);  
post.setHeader("NONCE", nonce);
post.setHeader("SIGNATURE_METHOD", signatureMethod);  
post.setHeader("SIGNATURE", signature)