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 devsupport@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;
	}
}
Transact API - EncryptedCardData logic with C#
using System;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

public class RsaEncryptionService
{
    public string EncryptCardDetails(object cardObject, string base64PublicKey)
    {
        try
        {
            // Serialize the card object to JSON
            string jsonData = JsonSerializer.Serialize(cardObject);
            byte[] dataToEncrypt = Encoding.UTF8.GetBytes(jsonData);

            // Decode the Base64-encoded public key
            byte[] publicKeyBytes = Convert.FromBase64String(base64PublicKey);

            using (RSA rsa = RSA.Create())
            {
                // Import the public key in SubjectPublicKeyInfo (X.509) format
                rsa.ImportSubjectPublicKeyInfo(publicKeyBytes, out _);

                // Encrypt the data using OAEP padding
                byte[] encryptedData = rsa.Encrypt(dataToEncrypt, RSAEncryptionPadding.OaepSHA1);

                // Return the encrypted data as a Base64-encoded string
                return Convert.ToBase64String(encryptedData);
            }
        }
        catch (Exception ex)
        {
            Console.Error.WriteLine($"Error while encrypting card data: {ex.Message}");
            return null;
        }
    }
}
Transact API - EncryptedCardData logic with Node Js
const crypto = require('crypto');

function encryptCardDetails(cardObject, rsaPublicKeyBase64) {
    try {
        const publicKeyDer = Buffer.from(rsaPublicKeyBase64, 'base64');
        const publicKeyPem = `-----BEGIN PUBLIC KEY-----\n${rsaPublicKeyBase64.match(/.{1,64}/g).join('\n')}\n-----END PUBLIC KEY-----`;

        const buffer = Buffer.from(JSON.stringify(cardObject), 'utf8');
        const encrypted = crypto.publicEncrypt(
            {
                key: publicKeyPem,
                padding: crypto.constants.RSA_PKCS1_PADDING
            },
            buffer
        );

        return encrypted.toString('base64');
    } catch (e) {
        console.error('Error While Encrypting Card Data:', e);
        return null;
    }
}
Transact API - EncryptedCardData logic with Python
import base64
import json
from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend

def encrypt_card_details(card_object, rsa_public_key_base64):
    try:
        public_key_der = base64.b64decode(rsa_public_key_base64)
        public_key = serialization.load_der_public_key(public_key_der, backend=default_backend())

        json_data = json.dumps(card_object).encode('utf-8')
        encrypted = public_key.encrypt(
            json_data,
            padding.PKCS1v15()
        )
        return base64.b64encode(encrypted).decode('utf-8')
    except Exception as e:
        print("Error While Encrypting Card Data:", e)
        return None
Transact API - EncryptedCardData logic with PHP
function encryptCardDetails(array $cardObject, string $rsaPublicKeyBase64): ?string {
    try {
        // Convert base64-encoded DER key to PEM format
        $rsaPublicKeyPem = "-----BEGIN PUBLIC KEY-----\n" .
            chunk_split($rsaPublicKeyBase64, 64, "\n") .
            "-----END PUBLIC KEY-----";

        // Load public key
        $publicKey = openssl_pkey_get_public($rsaPublicKeyPem);
        if (!$publicKey) {
            throw new Exception("Invalid RSA Public Key");
        }

        // Convert card object to JSON
        $jsonData = json_encode($cardObject);

        // Encrypt the data
        if (!openssl_public_encrypt($jsonData, $encryptedData, $publicKey, OPENSSL_PKCS1_PADDING)) {
            throw new Exception("Encryption failed: " . openssl_error_string());
        }

        // Return base64-encoded encrypted string
        return base64_encode($encryptedData);
    } catch (Exception $e) {
        error_log("Error While Encrypting Card Data: " . $e->getMessage());
        return null;
    }
}

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.

Last updated on

On this page