Clear Card Encryption
API Docs

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.

Generate Auth Token

End Points

The API Key and Secret Key are issued at the ISV level, not per merchant, so they can be used to authenticate all of your merchants.

Post head request
{
    "apiKey": "dakey_tKf9gua1wSGBRbXYLpt7ugYn2cm-9X1C",
    "secretKey": "dskey_EdnqZe0STrqhQO3qwvDlNgnuXpNL5YWv",
    "scope": "PaymentTokenization"  
}
Response 
{
  "responseCode": "00",
  "responseMessage": "Success",
  "createdDt": "1749532846158",
  "token": "eyJhbGciOiJSUzI1NiJ9.eyJzY29wZSI6InBheW1lbnRUb2tlbml6ZSIsInVuaXF1ZUlkIjoiNzQxYzFiM2YtMTUyYS0xMWYwLWI3YTMtMTZhOTc1NjBiMjc1IiwiaWF0IjoxNzQ0ODA3NzAyLCJleHAiOjE3NDQ4OTQxMDJ9.WUXSxe3e4fMY43qmkVC5wpzzpnj78G590E-tG9O1yZD7RhCu2L2giQOSb6qrfpH6w11iP-n2_ZfpZXu0He66Rge-6FyjKAW0wE5Dz-VLrFsZWxSHaIQLMbm900BPqNo_hBhstfESbO_UA-4uQItfBF5lg8PD1cDhS5K5N6tp1yFOEEflQOUysxvven8rLcg2XnimWJDaH-d-i6-tN9RgFgZCj-ZgAfqW4U3NH3MjcvlCASA-mTTnkJ_PvNBC9HRXBl862-Tgzb9AvZVYgc8qypIWD3QkROpwUmlXoCHfIQFlyQFSPp9rcHiFXy73RrMTppmDMzgsPWpzNKAuXpw4bw"
}

Auth Token Error Responses

{
  "errorCode": "AUTH_ERR_001",
  "errorMessage": "API Key is required."
}
 
{
  "errorCode": "AUTH_ERR_002",
  "errorMessage": "Secret Key is required."
}
 
{
  "errorCode": "AUTH_ERR_003",
  "errorMessage": "Scope is required."
}
 
{
  "errorCode": "AUTH_ERR_004",
  "errorMessage": "Invalid Credentials, Please Contact Support Team."
}
 
{
  "errorCode": "AUTH_ERR_005",
  "errorMessage": "Invalid scope provided. Please use a valid scope."
}

Refresh Auth Token

End Points

The generated token used for transactions remains valid for 24 hours. Make sure to refresh the token daily before initiating any transactions.

Post head request
{ 
  "refreshToken": true ,
  "token" : "eyJhbGciOiJSUzI1NiJ9.eyJzY29wZSI6InBheW1lbnRUb2tlbml6ZSIsInVuaXF1ZUlkIjoiNzQxYzFiM2YtMTUyYS0xMWYwLWI3YTMtMTZhOTc1NjBiMjc1IiwiaWF0IjoxNzQ0MjkxMzEzLCJleHAiOjE3NDQzNzc3MTN9.E2Rrf9D4ZvM9t-llUAPttVR2_paCxXnYW1rL0z1-g3DnekRsBJLlbT3efm0ecKnO6PZI1AXJNrMx3tM-0cjGvSOiT1-PeqRMSWib7c2yxqN-fkM9gYQlSpvwMPY5GZ5X2JJ2XAt5f4KwyzVsYoFRYutf2ADRj8f_gPFfouyrQH-v0EjGCe1qx1lr_IupXPDfjYzys9w1MNMqUTp9ZJEt8hav5NFFBddQf_Tf5sfynmhAP2DB_UgaINhS16KzQG3mpGzMk6NqWk8iCa2HbTUJBVJB7ZQmoaKsW95mUaXwSwR2w9pMUeM0ME1P-VHDMjQ9RbA86MDoHi1DUm-3OwJkvA"
}
Response
{
  "responseCode": "00",
  "responseMessage": "Success",
  "createdDt": "1749532846158",
  "token": "eyJhbGciOiJSUzI1NiJ9.eyJzY29wZSI6InBheW1lbnRUb2tlbml6ZSIsInVuaXF1ZUlkIjoiNzQxYzFiM2YtMTUyYS0xMWYwLWI3YTMtMTZhOTc1NjBiMjc1IiwiaWF0IjoxNzQ0ODA4MDg1LCJleHAiOjE3NDQ4OTQ0ODV9.APh5_tkBTT62dK783mzIVVdvXJxaYySGU20ZwWNBwu9lIGZ6hJ-zXEXCuPg6cTjbOSZViu3OEvsGvlrEN_nrnqgNIqYRIXmgtz6VS4BVp5yfP_XrMviO1F184AZIK_UlC598O_nKYMcjg-1wTaQQY7By4SCO0RFVXeN4YFm7X4YOAz8g3-Y9LCTpNXKftjEl8RbTkkWsKQjGFuNhTcnrJFSmY0AnPban8v4SUtGdH7nKWXsXwrV4HCJ6AipWcJ1XULwm521VDyYw4Y-ldGJ7kciOi-Oho7sDNDi0HeHwTuCQvSj2SfRRNXiXDhDDveU6-Sw3DJOQRre8LYNtabRzdg"
}

Refresh Token Error Responses

{
  "errorCode": "AUTH_ERR_006",
  "errorMessage": "Invalid Token, Please try with a Valid Token."
}
 
{
  "errorCode": "AUTH_ERR_007",
  "errorMessage": "Invalid Token, Please try with a Valid Token."
}
 
{
  "errorCode": "AUTH_ERR_008",
  "errorMessage": "Invalid Signature."
}
 
{
  "errorCode": "AUTH_ERR_009",
  "errorMessage" :  "Refresh Token needs to be true in the Header."
}

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.

iPOS Transact - SaleiPOS Transact - Pre Auth

Error Response Code & Messages

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

Error Codes & Messages
Clear Card EncryptionMigrate to iPOSpays