2. KnowSystem
  3. REST API

REST API

Authorisation Header

When interfacing with the Gateway endpoints, merchants can include the AuthenticationKey and AuthenticationToken in the headers for both transaction status queries and transaction submissions.

AuthenticationKey

The key consists of the username. The key and username must be in lowercase

The Username must be encoded to base64 i.e bWVyY2hhbnRwcm9maWxlPTYxNjk1NA

AuthenticationToken

The token consists of:

AuthenticationSecret

This is the secret key generated by the merchant within Backoffice, which the merchant has to store on the merchant’s system.Once the secret is generated, it remains readable in plain text for a couple of minutes, after which it is hashed.  Merchant must copy the secret immediately after the secret is generated.

 If the merchant loses their secret, a new one will have to be generated

Resource

·        Query Transaction Status & Submission of Transactions endpoint

o    REST endpoints can be referenced 

Data

  • Payload that gets posted to the PosPort URL
    • Applies to the POST method

QueryString

Query string to retrieve transactions

o   /api/transactions?applicationid={applicationid}

o   /api/transactions/{requestid}

·        only to the GET Method

Timestamp

Calculated as follows:

Timestamp

 

private static Int32 UnixTimeStampUTC()

{

    Int32 unixTimeStamp;

    DateTime currentTime = DateTime.Now;

    DateTime zuluTime = currentTime.ToUniversalTime();

    DateTime unixEpoch = new DateTime(1970, 1, 1);

    unixTimeStamp = (Int32)(zuluTime.Subtract(unixEpoch)).TotalSeconds;

    return unixTimeStamp;

}

Calculating the Token


/// <summary>

///

/// </summary>

/// <param name="sharedSecret"></param>

/// <param name="resource"></param>

/// <param name="queryString"></param>

/// <param name="data"></param>

/// <param name="time"></param>

/// <returns></returns>

public static string GenerateAuthenticationToken(string sharedSecret, string resource, string queryString, string data, string time)

{

    byte[] sourceBytes = Encoding.UTF8.GetBytes(time)

        .Concat(Encoding.UTF8.GetBytes(resource))

        .Concat(Encoding.UTF8.GetBytes(queryString))

        .Concat(Encoding.UTF8.GetBytes(data))

        .ToArray();

    return GetHmacSha256(Encoding.ASCII.GetBytes(sharedSecret), sourceBytes);

}

 

/// <summary>

///

/// </summary>

/// <param name="sharedSecret"></param>

/// <param name="source"></param>

/// <returns></returns>

public static string GetHmacSha256(byte[] sharedSecret, byte[] source)

{

    HMACSHA256 hashString = new HMACSHA256(sharedSecret);

    var hashbytes = hashString.ComputeHash(source);

    StringBuilder digestBuilder = new StringBuilder();

    foreach (byte b in hashbytes)

    {

        digestBuilder.Append(b.ToString("x2"));

    }

    return digestBuilder.ToString();

REST Endpoints

 

On all endpoints the following applies:

  • Method: Only GET, POST methods are supported
  • Format: JSON


Submission of transactions to the correct Gateway endpoint relates to the acquiring bank that holds the merchant agreement. To submit transactions to the iVeri Gateway, merchants can connect to following end points.

Endpoint Overview

Endpoints in Detail

 
/api/merchant/authenticate
Returns the current server time, in UTC, formatted as yyyyMMddHHmmssfff. This time can be used to check the client time against that of the server. A deviation of five minutes or less is allowed between the client and server time.

yyyy – four-digit year
MM – two-digit month
dd – two-digit day
HH – Hour formatted as 24-Hour time
mm – two-digit minutes 
ss – two-digit seconds
fff – current millisecond

Example
Monday, 7th October 2013, 17:02:45 PM would be formatted as 20131007150245442.

JSON Response:
20131007150245442

/api/merchant/configuration
Returns the user parameters as configured in the BackOffice website.

The user parameters consist of list of applications selected for the user
list of currencies selected for the user list of permissions selected for the user

JSON Response:

{
"Applications": [{
"Description": "mPress test application",
"ApplicationID": "1d76a36f-f10e-4388-87f4-4675c78a5511",
"CertificateID": "4c96973f-71dd-4044-802d-6e234effe8f2",
"Mode": "Live"
},
{
"Description": "mPress test application",
"ApplicationID": "1d76a36f-f10e-4388-87f4-4675c78a5511",
"CertificateID": "7dcb6189-bfad-414b-b4ed-ea9d5875ea12",
"Mode": "Live"
}],
"Currencies": [{
"Format": "SCA,.R ",
"DecimalPlaces": 2,
"Code": "ZAR"
}],
"Permissions": [{
"Name": "AUTHORISATION",
"Allowed": "true"
},
{
"Name": "REFUND",
"Allowed": "true"
},
{
"Name": "SALE",
"Allowed": "true"
}]
}

NB. If no applications are returned in the response configuration, you will need to contact the administrator of the usergroup and request the necessary configuration changes to be made to the respective user.


Application list

You will need to select only one of the applications returned.
The application id, certificate id and mode will be used when performing a transaction to the gateway. The description is returned for display use only and not when performing the transaction

NB: You cannot simply switch to mode test using an application id received for mode live. You will need to download the configuration each time you change between test and live.

Permissions list

The permissions returned in the list relate to the transaction types that the user can perform using the REST API. If the “Allowed” value for any of the transaction types is set to “false”, that transaction option should not be presented to the user.

In all cases irrespective of the allowed transaction types, the void transaction type is allowed.

/api/transactions

Submit a transaction to the gateway.
JSON Request: 
Sample request for an mPress SDK (Card Present) implementation
{
"Version": "2.0",
"CertificateID": "{7dcb6189-bfad-414b-b4ed-ea9d5875ea12}",
"ProductType": "Enterprise",
"ProductVersion": "mPress",
"Direction": "Request",
"Transaction": {
"ApplicationID": "{1d76a36f-f10e-4388-87f4-4675c78a5511}",
"Command": "Debit",
"Mode": "Live",
"MerchantReference": "{11f1167c-9112-46ca-a69d-b0e856271f4b}",
"MerchantTrace": "{76c8813c-09ad-4b48-bbf5-4a4b320d6659}",
"DeviceMake": "Miura",
"DeviceSerialNumber": "02000567",
"EMV_ApplicationIdentifier": null,
"EMV_ApplicationInterchangeProfile": null,
"EMV_ApplicationTransactionCounter": null,
"EMV_ApplicationVersion": null,
"EMV_AuthorisationRequestCryptogram": null,
"EMV_CardHolderVerificationMethodResult": null,
"EMV_CardSequenceNumber": null,
"EMV_CryptogramInformationData": null,
"EMV_IssuerApplicationData": null,
"EMV_TerminalCapabilities": null,
"EMV_TerminalType": null,
"EMV_TerminalVerificationResult": null,
"EMV_UnpredictableNumber": null,
"EMV_TransactionStatusInformation": null,
"Currency": "ZAR",
"KeySerialNumber": "FF … 14",
"Track2KeySerialNumber": "FF … 44",
"Track2": "37E ... C155",
"PINBlock": "1F … 6F",
"Amount": "2500",
"ExpiryDate": "816",
"CardSecurityCode": null
}
}


/api/merchant/bins
Returns the current bin list used by the gateway in determining whether to prompt for PIN entry while using a POS device when the card service code incorrectly identifies this requirement.

JSON Response:

[{
"BIN": "201010",
"IsOnlineOnly": 1,
"IsPinCard": 2,
"MaxLength": 20
},
{
"BIN": "225050",
"IsOnlineOnly": 1,
"IsPinCard": 2,
"MaxLength": 20
},
{
"BIN": "3045",
"IsOnlineOnly": 1,
"IsPinCard": 2,
"MaxLength": 20
},]

The section “16.6.4 Determining if a card is PIN based” of the iVeri Client Developers Guide, describes how the bin list together with the card's service code is used in determining whether to prompt for PIN.


JSON Response:
{
"Version": "2.0",
"Direction": "Response",
"Transaction": {
"MerchantTrace": "76c8813c-09ad-4b48-bbf5-4a4b320d6659",
"Amount": "2500",
"AuthorisationCode": "660156",
"Currency": "ZAR",
"ExpiryDate": "082016",
"MerchantReference": "11f1167c-9112-46ca-a69d-b0e856271f4b",
"Terminal": "11111111",
"TransactionIndex": "{63D6D3F5-1F1B-46CE-B0EC-AD6F092F51B3}",
"MerchantName": "iVeri",
"MerchantUSN": "2169017345",
"Acquirer": "NedbankPostilion",
"AcquirerReference": "31008:00660156",
"AcquirerDate": "20131007",
"AcquirerTime": "184550",
"DisplayAmount": "R 25.00",
"BIN": "504931",
"Association": "MasterCard",
“CardType": "Unknown Card Type",
"Issuer": "Unknown Issuer",
"Jurisdiction": "Local",
"PANMode": "Swiped,PIN,EncryptedTrack2",
"ReconReference": "00660156",
"CardHolderPresence": "CardPresent",
"MerchantAddress": "MERCHANT ADDRESS",
"MerchantCity": "Johannesburg",
"MerchantCountryCode": "ZA",
"MerchantCountry": "South Africa",
"ApplicationID": "{1D76A36F-F10E-4388-87F4-4675C78A5511}",
"Command": "Debit",
"Mode": "Live",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"Result": {
"Status": "0",
"AppServer": "QAGW2012APP1",
"DBServer": "QAGW2012DB1",
"Gateway": "QA"
},
"PAN": "5049........0023"
}
}


JSON Request:
Sample request for an eCommerce/CNP transaction 
{
"Version": "2.0",
"CertificateID": "{7dcb6189-bfad-414b-b4ed-ea9d5875ea12}",
"ProductType": "Enterprise",
"ProductVersion": "mPress",
"Direction": "Request",
"Transaction": {
"ApplicationID": "{1d76a36f-f10e-4388-87f4-4675c78a5511}",
"Command": "Debit",
"Mode": "Live",
"MerchantReference": "{11f1167c-9112-46ca-a69d-b0e856271f4b}",
"MerchantTrace": "{76c8813c-09ad-4b48-bbf5-4a4b320d6659}", 
"Currency": "ZAR", 
"Amount": "2500",
"ExpiryDate": "816",
"CardSecurityCode": null,
“PAN”: ”4242424242424242”

}
}

JSON Response:
{
"Version": "2.0",
"Direction": "Response",
"Transaction": {
"MerchantTrace": "76c8813c-09ad-4b48-bbf5-4a4b320d6659",
"Amount": "2500",
"AuthorisationCode": "660156",
"Currency": "ZAR",
"ExpiryDate": "082016",
"MerchantReference": "11f1167c-9112-46ca-a69d-b0e856271f4b",
"Terminal": "11111111",
"TransactionIndex": "{63D6D3F5-1F1B-46CE-B0EC-AD6F092F51B3}",
"MerchantName": "iVeri",
"MerchantUSN": "2169017345",
"Acquirer": "NedbankPostilion",
"AcquirerReference": "31008:00660156",
"AcquirerDate": "20131007",
"AcquirerTime": "184550",
"DisplayAmount": "R 25.00",
"BIN": "504931",
"Association": "MasterCard",
“CardType": "Unknown Card Type",
"Issuer": "Unknown Issuer",
"Jurisdiction": "Local",
"PANMode": "Swiped,PIN,EncryptedTrack2",
"ReconReference": "00660156",
"CardHolderPresence": "CardPresent",
"MerchantAddress": "MERCHANT ADDRESS",
"MerchantCity": "Johannesburg",
"MerchantCountryCode": "ZA",
"MerchantCountry": "South Africa",
"ApplicationID": "{1D76A36F-F10E-4388-87F4-4675C78A5511}",
"Command": "Debit",
"Mode": "Live",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"Result": {
"Status": "0",
"AppServer": "QAGW2012APP1",
"DBServer": "QAGW2012DB1",
"Gateway": "QA"
},
"PAN": "4242........4242"
}
}


/api/transactions?applicationid={applicationid}
Returns the application transaction history for the last 7 days.
The JSON Response is a list of transaction responses.

/api/transactions/{requestid}
Returns transaction details for a particular transaction identified by the requestid.

JSON Response:
{
"Version": "2.0",
"Direction": "Response",
"Transaction": {
"MerchantTrace": "76c8813c-09ad-4b48-bbf5-4a4b320d6659",
"Amount": "2500",
"AuthorisationCode": "660156",
"Currency": "ZAR",
"ExpiryDate": "082016",
"MerchantReference": "11f1167c-9112-46ca-a69d-b0e856271f4b",
"Terminal": "11111111",
"TransactionIndex": "{63D6D3F5-1F1B-46CE-B0EC-AD6F092F51B3}",
"MerchantName": "iVeri",
"MerchantUSN": "2169017345",
"Acquirer": "NedbankPostilion",
"AcquirerReference": "31008:00660156",
"AcquirerDate": "20131007",
"AcquirerTime": "184550",
"DisplayAmount": "R 25.00",
"BIN": "504931",
"Association": "MasterCard",
“CardType": "Unknown Card Type",
"Issuer": "Unknown Issuer",
"Jurisdiction": "Local",
"PANMode": "Swiped,PIN,EncryptedTrack2",
"ReconReference": "00660156",
"CardHolderPresence": "CardPresent",
"MerchantAddress": "MERCHANT ADDRESS",
"MerchantCity": "Johannesburg",
"MerchantCountryCode": "ZA",
"MerchantCountry": "South Africa",
"ApplicationID": "{1D76A36F-F10E-4388-87F4-4675C78A5511}",
"Command": "Debit",
"Mode": "Live",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"Result": {
"Status": "0",
"AppServer": "QAGW2012APP1",
"DBServer": "QAGW2012DB1",
"Gateway": "QA"
},
"PAN": "5049........0023"
}
}

api/transactions/{requestid}/receipt
Upload a Cardholder signature to be added to a MerchantReceipt linked to a transaction identified by the requestid.

JSON Request:
{
"Version": "2.0",
"CertificateID": "{7dcb6189-bfad-414b-b4ed-ea9d5875ea12}",
"Direction": "Request",
"Enquiry": {
"ApplicationID": "{1d76a36f-f10e-4388-87f4-4675c78a5511}",
"Command": "Debit",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"CardholderName", "Russel King",
"SignatureImageFormat", "jpeg",
"SignatureImage", "hexified image data"
}
}

Requirements (REST API)

 

  • Merchant profile that contains credentials to login to the merchant portal - Backoffice
  • Merchant must login to Backoffice and request a certificate, only the certificate ID is required.