Clear Card Encryption API

Prerequisites

For Sandbox (UAT)

  • Users must be onboarded on the iPOSpays sandbox (UAT) environment as a merchant.

  • A valid CloudPOS TPN is required.

For Production (Live)

  • Users must be onboarded on the iPOSpays production environment as a merchant.

  • A valid CloudPOS TPN is required.

If your application is accessing or handling clear card data, the third-party software or integrating application must be PCI compliant. This is mandatory to ensure the security and compliance of cardholder data.


How to Generate an Authentication Token

To access the Clear Card Encryption API, you must first generate a valid JWT-based authentication token using the iPOSpays Authentication Token API.

Step 1: Access the Authentication Token API

Refer to the official documentation to understand the request structure and response handling:

Step 2: Prepare Your API Credentials

Before making a request, ensure that you have the following credentials, which are issued by iPOSpays:

{
  "apiKey": "your_api_key_here",           // Required: Your assigned API key
  "secretKey": "your_secret_key_here",     // Required: Your assigned secret key
  "scope": "PaymentTokenization"           // Required: Use "PaymentTokenization" for Clear Card Encryption API
}

The apiKey and secretKey are issued by iPOSpays. If you do not have access to these keys, contact your Dejavoo representative or email support@dejavoo.io.

Step 3: Set the Scope Appropriately

  • For using the Clear Card Encryption API, set the scope to: "PaymentTokenization"

  • Other APIs may require different scopes (e.g., "BatchReport" or "CardLookUp")

Step 4: Use the Token in Your API Requests

Once you receive the token from the authentication API, include it in the request header of your Clear Card Encryption API calls for authorization.


Encrypt Card Data with Public Key

To securely encrypt cardholder data, you must first encrypt the raw card details (PAN, expiry, and CVV) using the public key provided by iPOSpays.Once encrypted, the result is referred to as the encryptedCardData.

Sample Card Object
{
  "ccNumber" : "4242424242424242",
  "ccExpiry" : "1029",
  "ccCvv" : "999"
}
Transact API - Sample Code for encryptCardData logic with java
 public String encryptCardDetails(Object cardObject) throws Exception {
		
		String rsaPublicKey = "";//Key will be provided by Dejavoo in secure 
		
	    try {
	        byte[] keyBytes = Base64.getDecoder().decode(rsaPublicKey);
	        X509EncodedKeySpec keySpec = new X509EncodedKeySpec(keyBytes);
	        PublicKey publicKey = KeyFactory.getInstance("RSA").generatePublic(keySpec);
	        Cipher cipher = Cipher.getInstance("RSA");
	        cipher.init(Cipher.ENCRYPT_MODE, publicKey);
	        byte[] encryptedBytes = cipher.doFinal(new ObjectMapper().writeValueAsString(cardObject).getBytes(StandardCharsets.UTF_8));
	        logger.info("Plain Card Encrypted Successfully!!!!");
	        return Base64.getEncoder().encodeToString(encryptedBytes);
	    } catch (Exception e) {
	        logger.error("Error While Encrypting Card Data : "+e);
	    }
		return rsaPublicKey;
	}
}

You must then send this encryptedCardData to the iPOS Transact API for transaction.


Error Response Code & Messages

For a complete list of error codes and their explanations, please visit our Error Codes Reference Page.