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.
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:
iPOSpays Authentication Token API
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.
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;
}
}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;
}
}
}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;
}
}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 Nonefunction 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.
Error Codes & Messages
What made this section helpful for you?
What made this section unhelpful for you?
On this page
- API Docs