API Integration Guide

Rewards integration

Flow

Detailed Step

Get authorization token - Client Authentication

Post authorization and receipt of access token listed of the EnkashApi’s can be invoked.

For every API call, set request headers and authorization token.

Get cardAccount details api will be called to check card account details.

Create and allocate fund api will be called to fund user.

NOTE:

Partners are expected to mandatorily send “encrypted” requests with the use of encryption logic shared, which are used to check API integrity between Distribution Platform server and Partner.

The code will always be 0, in case of SUCCESS transaction and HTTP status code will be 200. And for all the other failure transactions, response code will be 1 and For all the error responses, please find below the references -
{
"response_code": 1,
"response_message": "Insufficient balance in card account",
"payload": "Insufficient balance in card account"
}

OtbBalance field is the reward Card balance, from which the person can buy/redeem rewards.

APIs

API	Function
Get Card Account Details	This API is used for fetching a particular card account details. Like balance, account id
Create And Allocate point	This API is used to create a reward card along with allocating points to the employee, as well as, it can be used to re-allocate points to an existing reward card user.
SSO LOGIN	This API facilitates the generation of a sign-in token for reward card holders. This token allows users to bypass the usual login and OTP verification steps, enabling them to directly access the EnKash Redeem Rewards Page.
Get Transaction details	This API is used for fetching a List of transaction details and fetch the status of transaction
Search Enkash Card	This API is used for fetching a card details of a user
Bulk Create Card / Allocate Points	This is used to create users and allocate reward points as well to the users in BULK

How to integrate the SSO with Enkash?

Retrieve the User {access_token} by passing the required fields in the SSO LOGIN (Single Sign On) API.

Integrate the below URL with the Redeem functionality on the partner’s portal(FOR EMPLOYEE FLOW)
URL - https://invoice-uat.enkash.in/sso/{access_token}/employee_rewards/{partner}
{access_token) - represents the token which has been generated by the partner for a user.
{partner} - The integrating partner name (Eg - HRMS)
Example URL : https://invoice-uat.enkash.in/sso/aF5V6hPScEd9mCowJmbZFKk5Xg/employee_rewards/hrms
This URL will redirect the user to Enkash Rewards Platform .

For HR Admin single sign on, integrate the below URL:
URL - https://invoice-uat.enkash.in/sso/{access_token}/reward_account/{partner}
For HR admin also, kindly pass the enkash card ID for HR / company admin which is generated upon client onboarding

For Production environment , replace - {invoice-uat.enkash.in} with {home.enkash.com}

HTTP CODES

Code	Message	Description
200	Success	The API has been successfully executed
400	BAD_REQUEST	Indicates the request is invalid or a mandatory parameter must have been missing.
422	UNPROCESSABLE_ENTITY	Indicates that the api couldn't be processed given the request conditions.
404	NOT_FOUND	Indicates somewhere in the code, API couldn’t fetch the required entity from the database. (returned null)
500	Internal Server Error	Indicates an error occurred on Enkash Server

Encryption of Request

APIs shared have an encryption/decryption mechanism set on them. To pass a request as an encrypted request. Kindly follow the below steps in Java.
Make an encryption class and follow the below steps.

Encryption using AES Algorithm with ECB Mode and PKCS5 padding:

Import the required libraries in Java:

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Arrays;
import javax.crypto.Cipher;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

Create an Encryption Function:

Implement the encrypt function to perform encryption. This function takes two parameters: the string to be encrypted (strToEncrypt) and a secret key (secret) for encryption.

public static String encrypt(String strToEncrypt, String secret) {
try {
if (CommonUtil.isEmpty(strToEncrypt))
return "";

SecretKeySpec secretKeySpec = getKeySpec(secret);

Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec);

byte[] encryptedBytes = cipher.doFinal(strToEncrypt.getBytes(StandardCharsets.UTF_8));

return Base64.getEncoder().encodeToString(encryptedBytes);
} catch (Exception e) {
LOGGER.error("Error while encrypting: " + e.getMessage());
}
return null;
}

Generate a SecretKeySpec

private static SecretKeySpec getKeySpec(String secretKey) throws NoSuchAlgorithmException {
byte[] key = secretKey.getBytes(StandardCharsets.UTF_8);
MessageDigest sha = MessageDigest.getInstance("SHA-256");
key = sha.digest(key);
key = Arrays.copyOf(key, 16); // Use only the first 128 bits for AES-128
return new SecretKeySpec(key, "AES");
}

Call the encrypt function to get the encrypted data

String stringToEncrypt = "This is a confidential message.";
String secretKey = "YourSecretKey123";

String encryptedData = encrypt(stringToEncrypt , secretKey);

Now pass the above encryptedData in the API request, It will return an encrypted Response. To Decrypt the response, make a method for decrypt logic like this:-

public static String decrypt(String strToDecrypt, String secret) {
try {
if (CommonUtil.isEmpty(strToDecrypt))
return "";
SecretKeySpec secretKeySpec = getKeySpec(secret);
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
cipher.init(Cipher.DECRYPT_MODE, secretKeySpec);
return new String(cipher.doFinal(Base64.getDecoder().decode(strToDecrypt)));

} catch (Exception e) {
LOGGER.error("Error while decrypting: " + e.getMessage());
}
return null;
}

To get the decrypted response, execute the below operation.

String response = "This is a confidential message.";
String secretKey = "YourSecretKey123";

String decryptedData = decrypt(response, secretKey);

NOTE- Pass the input String without any double quotes(“ “) and the encrypted string should not have any trailing whitespaces.

API Integration Guide

Rewards integration#

Flow#

Detailed Step#

APIs#

How to integrate the SSO with Enkash?#

HTTP CODES#

Encryption of Request#

Import the required libraries in Java:#

Create an Encryption Function:#

Generate a SecretKeySpec#

Call the encrypt function to get the encrypted data#

Now pass the above encryptedData in the API request, It will return an encrypted Response. To Decrypt the response, make a method for decrypt logic like this:-#

To get the decrypted response, execute the below operation.#