Authentication

To ensure the security & integrity of your data, you must authenticate each API call by passing the following headers:

Header	Description
developer_key	Your static API key shared by Eko
secret-key	Dynamic security key, to be generated before every request
secret-key-timestamp	The request timestamp, used to generate the secret-key
request_hash	[Only for financial transactions] See the guide below.

How to get the developer_key?

Production developer_key will be shared after the following is done:

Organisation's KYC is completed on Eko's platform (visit https://connect.eko.in).
The UAT developer_key can be obtained from the platform credentials section.

How to generate the secret-key & secret-key-timestamp?

Eko will provide an access_key. It must be kept a secret on your backend. If compromised, it can be regenerated.
1. The access_key will be shared to you over email, after completing your organisation's KYC at https://connect.eko.in
2. For UAT, use the following access_key: d2fe1d99-6298-4af2-8cc5-d97dcf46df30
Encode the access_key using base64 encoding.
Get the current timestamp (in milliseconds since UNIX epoch). It will be used as the secret-key-timestamp. (Check currentmillis.com to understand the timestamp format)
Compute the signature by hashing salt and base64 encoded key using Hash-based message authentication code HMAC and SHA256
Encode the signature using base64 encoding technique. This encoded value is your secret-key.

<?php

$access_key = "d2fe1d99-6298-4af2-8cc5-d97dcf46df30"; // DO NOT STORE IT HERE. Read it from env or configuration files

// Encode it using base64
$encodedKey = base64_encode($access_key);

// Get current timestamp in milliseconds since UNIX epoch as STRING
// Check out https://currentmillis.com to understand the timestamp format
$secret_key_timestamp = (int)(round(microtime(true) * 1000));

// Computes the signature by hashing the salt with the encoded key 
$signature = hash_hmac('SHA256', $secret_key_timestamp, $encodedKey, true);

// Encode it using base64
$secret_key = base64_encode($signature);

//Display
echo "secret-key: " . $secret_key. "\n";
echo "secret-key-timestamp: " . $secret_key_timestamp . "\n";

?>

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.Date;

public class Main {
    public static final String HMAC_SHA256 = "HmacSHA256";

    public static void activateEKyc() {
        try {
            String secret_key = "";
            String secret_key_timestamp = "";
            String request_hash = "";

            // Initializing key

            
            String access_key = "d2fe1d99-6298-4af2-8cc5-d97dcf46df30"; // DO NOT STORE IT HERE. Read it from env or configuration files
            
            String encodedKey = Base64.getEncoder().encodeToString(access_key.getBytes(StandardCharsets.UTF_8));

            // Get secret_key_timestamp: current timestamp in milliseconds since UNIX epoch as STRING
            // Check out https://currentmillis.com to understand the timestamp format
            Date date = new Date();
            secret_key_timestamp = String.valueOf(date.getTime());

            // Computes the signature by hashing the salt with the encoded key
            Mac sha256_HMAC = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec signature = new SecretKeySpec(encodedKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA256);

            sha256_HMAC.init(signature);

            // Encode it using base64 to get secret-key
            secret_key = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(secret_key_timestamp.getBytes(StandardCharsets.UTF_8)));

            
            String utility_acc_no = "831882579383";
            String amount = "100";
            String user_code = "34097002";
            String concatenatedString = secret_key_timestamp + utility_acc_no + amount+ user_code;
            byte[] hash = sha256_HMAC.doFinal(concatenatedString.getBytes(StandardCharsets.UTF_8));
            request_hash = Base64.getEncoder().encodeToString(hash);

            System.out.println("secret-key: " + secret_key);
            System.out.println("secret-key-timestamp: " + secret_key_timestamp);
            System.out.println("request_hash: " + request_hash);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) {
        activateEKyc();
    }
}

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Security.Cryptography;
using System.Text;
using System.Configuration;

namespace RechargePortal.Models
{
    public class SequrityKeys
    {
        public string secret_key { get; set; }
        public string secret_key_timestamp { get; set; }
    }

    public class Eko
    {
        public string Unique_Order_No { get; set; }
        public string Secrect_Key { get; set; }
        public string secretKeyTimestamp { get; set; }
        public string HashKey { get; set; }

        #region Get Security Key
        public static SequrityKeys GetSequrityKeys
        {
            get
            {
                SequrityKeys objSequrityKeys = new SequrityKeys();

                // call GenerateSequrityKeys static mathod
                objSequrityKeys = GenerateSequrityKeys();

                return objSequrityKeys;
            }
        }
        #endregion

        
        #region Generate Security Key
        private static SequrityKeys GenerateSequrityKeys()
        {
            SequrityKeys sequrityKey = new SequrityKeys();
            sequrityKey.secret_key = "";
            sequrityKey.secret_key_timestamp = "";

            try
            {
                string access_key = "d2fe1d99-6298-4af2-8cc5-d97dcf46df30"; // DO NOT STORE IT HERE. Read it from env or configuration files
                var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(access_key);
                var encodedKey = System.Convert.ToBase64String(plainTextBytes);
                DateTime epoch = new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
                long dateTimeInMilliseconds = (long)(DateTime.UtcNow - epoch).TotalMilliseconds;
          sequrityKey.secret_key_timestamp = dateTimeInMilliseconds.ToString();

                sequrityKey.secret_key = CalcHMACSHA256Hash(dateTimeInMilliseconds.ToString(), encodedKey);

            }
            catch (Exception ex)
            {
                // Write Exception handling code here....   
            }


            return sequrityKey;
        }


        public static string GenerateHash(string message,string timespan)
        {
            SequrityKeys sequrityKey = new SequrityKeys();
            sequrityKey.secret_key = "";
            sequrityKey.secret_key_timestamp = "";
            string hash = "";
            try
            {
                string key = ConfigurationManager.AppSettings["SecretKey"];
                var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(key);
                var encodedKey = System.Convert.ToBase64String(plainTextBytes);
                hash= CalcHMACSHA256Hash(message, encodedKey);

            }
            catch (Exception ex)
            {
                // Write Exception handling code here....   
            }


            return hash;
        }
        #endregion

        #region Cal hash Mac Eko
        public static string CalcHMACSHA256Hash(string message, string secret)
        {
            try
            {
                secret = secret ?? "";
                var encoding = new System.Text.ASCIIEncoding();
                byte[] keyByte = encoding.GetBytes(secret);
                byte[] messageBytes = encoding.GetBytes(message);
                using (var hmacsha256 = new HMACSHA256(keyByte))
                {
                    byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
                    return Convert.ToBase64String(hashmessage);
                }
            }
            catch (Exception ex)
            {
                // write exception handling code here
                return "";
            }

        }

        #endregion

    }
}

 // CALLING METHOD :

Eko ek = new Models.Eko();

                ek.Unique_Order_No = Uniqurorderno.ToString();

                SequrityKeys ks = Eko.GetSequrityKeys;

                ek.Secrect_Key = ks.secret_key;

                ek.secretKeyTimestamp = ks.secret_key_timestamp;

 

                if (interactiontypeid == 221) // for money transfer

                {

                    string requsetHsh = ek.secretKeyTimestamp + bankMaster.CustomerID + bankMaster.recipientid + amount;

                    ek.HashKey = Eko.GenerateHash(requsetHsh, ek.secretKeyTimestamp);

                }

                else if (interactiontypeid == 149) // for bank addd

                {

                    string requsetHsh = ek.secretKeyTimestamp;

                    ek.HashKey = Eko.GenerateHash(requsetHsh, ek.secretKeyTimestamp);

                }

import hmac
import base64
import hashlib
import time

secret_key_timestamp = str(int(round(time.time()*1000)))
key = 'd2fe1d99-6298-4af2-8cc5-d97dcf46df30' # DO NOT STORE IT HERE. Read it from env or configuration files
dig = hmac.new(
   base64.b64encode(key), secret_key_timestamp, hashlib.sha256
).digest()
secret_key = base64.b64encode(dig).decode()


// Initializing key in some variable. You will receive this key from Eko via email

let key = "d2fe1d99-6298-4af2-8cc5-d97dcf46df30"; // DO NOT STORE IT HERE. Read it from env or configuration files
 
// Encode it using base64

let encodedKey = Buffer.from(key).toString('base64');
 
// Get current timestamp in milliseconds since UNIX epoch

let secretKeyTimestamp = Date.now();
 
// Computes the signature by hashing the salt with the encoded key 

let hmac = require('crypto').createHmac('sha256', Buffer.from(encodedKey, 'base64'));

hmac.update(secretKeyTimestamp.toString());

let signature = hmac.digest('base64');
 
// Display

console.log("secret-key: " + signature);

console.log("secret-key-timestamp: " + secretKeyTimestamp);

❗️
Note:

The secret-key-timestamp must match with the current time.

If you are using .NET, you should not send overly specific time stamps, due to differing interpretations of how extra time precision should be dropped. To avoid overly specific time stamps, manually construct dateTime objects with no more than millisecond precision.

How to generate the request_hash?

The request_hash header is only required for financial transactions for a certain amount which needs to be debited from your Eko wallet or your agent's Eko wallet (E-value).

It is used to encode critical parameters of your financial transaction such as amount, agent, recipient, etc. It ensures that the values have been validated on your server and they have not been tampered with.

Before generating the request hash you need to generate a string by concatenating some parameters in a particular order. You cannot change the sequence.

For example, sequence of concatenated string for Bill Payments = secret_key_timestamp + utility_acc_no + amount + user_code

After generating the concatenated string please follow the following procedure :

Encode your authenticator password using base64. Authenticator password will be the access_key which you have used for the secret-key generation.
1. For UAT, the access_key is "d2fe1d99-6298-4af2-8cc5-d97dcf46df30".
After encoding the key, you need to hmac the concatenated string and encoded_key using hmac256.
After hmac , you need to again encode the result using the base64.

Final result after encoding will be the request_hash.

Sample Code to Generate request_hash:

Note: The following example generates the request_hash for the Bill Payment API by concatenating secret_key_timestamp, utility_acc_no, amount, and user_code (in the same order). For APIs, a different set of parameters may be required. See the corresponding API docs for details.

<?php

const HMAC_SHA256 = 'sha256';

function generateRequestHashForBillPay()
{
	try {
    	$access_key = 'd2fe1d99-6298-4af2-8cc5-d97dcf46df30'; // DO NOT STORE IT HERE. Read it from env or configuration files
    	$encodedKey = base64_encode($access_key);
    	$timestamp = round(microtime(true) * 1000);
     	$secret_key_timestamp = (string) $timestamp;

    	$secret_key = base64_encode(hash_hmac(HMAC_SHA256, $secret_key_timestamp, $encodedKey, true));

    	$utility_acc_no = '151627591';
    	$amount = '50';
    	$user_code = '20810200';

    	$concatenatedString = $secret_key_timestamp . $utility_acc_no . $amount . $user_code;
    	$request_hash = base64_encode(hash_hmac(HMAC_SHA256, $concatenatedString, $encodedKey, true));

    	echo "secret-key: $secret_key\n";
    	echo "secret-key-timestamp: $secret_key_timestamp\n";
    	echo "request_hash: $request_hash\n";
	} catch (Exception $e) {
    	echo $e->getMessage();
	}
}

activateEKyc();
?>

import base64
import hashlib
import hmac
import time

HMAC_SHA256 = 'sha256'

def generate_request_hash_for_billpay():
    try:
        access_key = 'd2fe1d99-6298-4af2-8cc5-d97dcf46df30' # DO NOT STORE IT HERE. Read it from env or configuration files
        encoded_key = base64.b64encode(access_key.encode()).decode()
        timestamp = round(time.time() * 1000)
        secret_key_timestamp = str(timestamp)

        secret_key = base64.b64encode(
            hmac.new(encoded_key.encode(), secret_key_timestamp.encode(), hashlib.sha256).digest()
        ).decode()

        utility_acc_no = '151627591'
        amount = '50'
        user_code = '20810200'

        concatenated_string = secret_key_timestamp + utility_acc_no + amount + user_code
        request_hash = base64.b64encode(
            hmac.new(encoded_key.encode(), concatenated_string.encode(), hashlib.sha256).digest()
        ).decode()

        print(f"secret-key: {secret_key}")
        print(f"secret-key-timestamp: {secret_key_timestamp}")
        print(f"request_hash: {request_hash}")

    except Exception as e:
        print(str(e))

activate_ekyc()

How to get the developer_key?

How to generate the secret-key & secret-key-timestamp?

❗️Note:

How to generate the request_hash?

Sample Code to Generate request_hash:

❗️
Note: