REST API

Requirements

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.
The Gateway endpoints are the same for Live & Test
For integration purposes, a test applicationID must be used, while the LIVE application iD must be use real payments
Optional Headers: Authentication of the user using AuthenticationToken & AuthenticationKey can be set in the headers

Authentication

When interfacing with the iVeri Gateway, there are 2 forms of authentication that are supported.

Digest Authentication (Optional): Adding AuthenticationKey and AuthenticationToken in the headers and adding the certificateID in the body of the transaction or enquiry request
1. if the merchant opts to use Digest Authentication they need to request this through iVeri support at assist@iveri.co.za
Legacy Authentication : No Authentication headers are required only the certificateID is expected in the body of the transaction or enquiry request

AuthenticationKey

The key, value refers to the “certificateid” and actual certificateID generated in Backoffice

The certificateid value must be encoded to base64 i.e bWVyY2hhbnRwcm9maWxlPTYxNjk1N

AuthenticationKeyType AuthenticationKeyIdentifier
certificateid de3022ce-15a2-4702-a46b-cc9710463135

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 system. Once the secret is generated, it remains readable in plain text for a couple of minutes, after which it is hashed.

Note: 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

Data

Payload that gets posted to the Gateway URL

Note: The payload would only be required if the merchant is preforming a financial transaction or enquiry

QueryString

POST Method - a merchant can query by merchant ReferenceNumber, TransactionIndex, requestID or MerchantTrace

Note: The QueryString would only apply if the merchant is querying a transaction or set of transactions

Timestamp

Calculated as follows:

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;

}

/// </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>

/// <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: POST
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.

Acquiring Bank	Gatway Address
Nedbank Merchants	https://portal.nedsecure.co.za/
CSC acquiring bank merchants	https://portal.cscacquiring.com/
CBZ Bank merchants	https://portal.host.iveri.com/
I&M Bank merchants	https://portal.host.iveri.com/
CIM Merchants	https://portal.merchant.cim.mu

Endpoint Overview

Endpoints in Detail

EndPoint	Purpose	Usage
Live and Test: /api/transactions HTTP Method: POST	Submit transactions to iVeri Gateway endpoint	1. Mandatory: Card processing transactions to the Gateway 2. Optional: AuthenticationToken and AuthenticationKey can be included in the Authentication headers 3. Optional: Querying Transaction Status
Live and Test: /api/merchant/bins HTTP Method: GET	Returns the current bin list used by the gateway in determining whether to prompt for PIN entry on POS devices when the card service code incorrectly identifies this requirement.