RSA encryption is used to generate a session id that will be used to authenticate requests between Paymentology and the cardholder. The generated session id should be passed in api header.

AES encryption(AES/GCM/NoPadding) will be used for encrypting sensitive datas like pin, pan, cvv as a part of api response in v2 paysecure web services. And corresponding AES decryption to be used in client side for response decryption. Random key (session key) should be generated for each api request and shared under the RSA key pair that is considered stronger than conventional triple DES algorithm.(https://simple.wikipedia.org/wiki/Advanced_Encryption_Standard)

Depending upon size of session key (that client generate from their end) that will be used to encrypt with rsa public key encryption could be:

256 bits key represent AES 256
192 bits key represent AES 192
128 bits key represent AES 128

Version 2 web services are more secure in terms of

AES/GCM/NoPadding mode
SecureRandom way to generate IV in api side for creating encrypted response

PaySecure V2 supports both 1024-bit (deprecated) and 2048-bit RSA key pairs. The API automatically detects which key size was used based on the Base64-decoded session ID ciphertext length:

128 bytes → 1024-bit RSA key (deprecated)
256 bytes → 2048-bit RSA key

No additional header or parameter is needed — the server resolves the correct private key automatically.

V2 now uses RSA/None/OAEPWithSHA-512AndMGF1Padding with 2048-bit keys as the recommended configuration. RSA/None/OAEPWithSHA-1AndMGF1Padding with 1024-bit keys is deprecated but still supported — the API automatically detects which padding scheme was used.

Migration Guide

Migration to 2048-bit keys with SHA-512 is recommended for existing integrations and fully backward-compatible. New integrations should use 2048-bit keys with SHA-512 from the start. Existing integrations using 1024-bit keys with SHA-1 continue to work without changes.

To migrate to 2048-bit RSA keys with SHA-512:

Request a new 2048-bit RSA public key from Paymentology.
Replace the existing 1024-bit public key with the new 2048-bit key in your integration.
Java: Change the cipher from RSA/None/OAEPWithSHA-1AndMGF1Padding to RSA/None/OAEPWithSHA-512AndMGF1Padding.
JavaScript (forge): Replace forge.md.sha1.create() with forge.md.sha512.create() in both the md and mgf parameters.
No server-side configuration is needed — the API automatically detects the key size and padding scheme used.

PIN Format

Pin format ISO-2 (Format 2) is used for pin block.

Example : 243456FFFFFFFFF

Reference : https://www.eftlab.com/knowledge-base/complete-list-of-pin-blocks#:~:text=The%20ISO%2D1%20PIN%20block,is%20truncated%20on%20the%20right

FOR V2

Session-Id Generation Java Example

Generate 32 bytes random value and encode as base64 string termed as session key.
The base64 encoded string should be encrypted with rsa public key.

Sample source code


String rsaPublicKey  = " "; // 2048-bit RSA public key (Base64-encoded)

KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
keyGenerator.init(256); //key size defines AES encryption. Eg AES 256, AES 128, AES 192
SecretKey key = keyGenerator.generateKey();
String sessionKey = Base64.getEncoder().encodeToString(key.getEncoded());

AsymmetricCryptography ac = new AsymmetricCryptography(
    "RSA/None/OAEPWithSHA-512AndMGF1Padding");
PublicKey publicKey = ac.getPublickey(rsaPublicKey);

// session key has to be base64 encoded before encrypting with rsa public key
// This is the session-id that needs to be passed into header on api request
String sessionId = ac.encryptTextPublicKey(sessionKey, publicKey);

AsymmetricCryptography class reference


public class AsymmetricCryptography {

  private Cipher cipher;

  static {
    Security.addProvider(new org.bouncycastle.jce.provider.BouncyCastleProvider());
  }

  public AsymmetricCryptography(String algo) throws NoSuchAlgorithmException, NoSuchPaddingException {
    this.cipher = Cipher.getInstance(algo);
  }

  public PublicKey getPublickey(String base64) throws InvalidKeySpecException, NoSuchAlgorithmException {
    byte[] keyBytes = java.util.Base64.getDecoder().decode(base64);
    X509EncodedKeySpec spec = new X509EncodedKeySpec(keyBytes);
    KeyFactory kf = KeyFactory.getInstance("RSA");
    return kf.generatePublic(spec);
  }

  // session key has to be base64 encoded before encrypting with rsa public key
  public String encryptTextPublicKey(String sessionKey, PublicKey key) throws NoSuchAlgorithmException, NoSuchPaddingException,
      IllegalBlockSizeException, BadPaddingException, InvalidKeyException {
    this.cipher.init(Cipher.ENCRYPT_MODE, key);
    return Base64.encodeBase64String(cipher.doFinal(sessionKey.getBytes(StandardCharsets.UTF_8)));
  }
}

PIN/CVV encrypt example


// IV generation
SecureRandom secureRandom = new SecureRandom();
byte[] iv = new byte[16];
secureRandom.nextBytes(iv);
IvParameterSpec IV = new IvParameterSpec(iv);
String iv_payload = new String(BASE64EncoderStream.encode(iv)); // The value is passed in request payload

byte[] decodedKey = Base64.getDecoder().decode(sessionKey); // Use session key generated at first step
SecretKey Aeskey = new SecretKeySpec(decodedKey, 0,  decodedKey.length, "AES");

String CVV2= "024";
// In case pin it should be pin block format.
// 246784FFFFFFFFFF
// 2 = ISO FORMAT, 4 = Pin length , 6784 = Actual pin, FFFFFFF = Padding
Cipher Aesecipher = Cipher.getInstance("AES/GCM/NoPadding");
Aesecipher.init(Cipher.ENCRYPT_MODE, Aeskey, IV);
byte[] utf8 = CVV2.getBytes("UTF8");
byte[] enc = Aesecipher.doFinal(utf8);
String CVV2_enc = new String(BASE64EncoderStream.encode(enc));// pass encrypted cvv2 in request

Decryption example


String secret = "+AyrdXnhXhc=";  // encrypted cvv2 in response
String iv = "Xb6qbV2L6d1F92YU";  // IV value generated in payapi while decrypting cvv

Cipher Aesdcipher = Cipher.getInstance("AES/GCM/NoPadding");
byte[] iv1= Base64.getDecoder().decode(iv);
IvParameterSpec iv_spec = new IvParameterSpec(iv);
byte[] decodedKey = Base64.getDecoder().decode(sessionKey); // SESSION-KEY is the key generated at client side and passed during request i.e. 32 character random string
SecretKey Aeskey = new SecretKeySpec(decodedKey, 0, decodedKey.length, "AES");

// initialize the ciphers with the given key
Aesdcipher.init(Cipher.DECRYPT_MODE, Aeskey, iv_spec);
byte[] dec = BASE64DecoderStream.decode(secret.getBytes());
byte[] utf8 = Aesdcipher.doFinal(dec);
String decrypted_cvv2 = new String(utf8, "UTF8");   // Final decrypted cvv2

Javascript example


//Required js
//https://cdnjs.cloudflare.com/ajax/libs/sjcl/1.0.8/sjcl.min.js
//https://cdnjs.cloudflare.com/ajax/libs/forge/1.3.1/forge.min.js

//Use sjcl.random to create session key in hex
//If hex string = 32 then AES 128 GCM used for encrypt/decrypt
//If hex string = 48 then AES 192 GCM used for encrypt/decrypt
//If hex string = 64 then AES 256 GCM used for encrypt/decrypt
let KeyPart1 = sjcl.codec.hex.fromBits(sjcl.random.randomWords(2, 0));
let KeyPart2 = sjcl.codec.hex.fromBits(sjcl.random.randomWords(2, 0));
let KeyPart3 = sjcl.codec.hex.fromBits(sjcl.random.randomWords(2, 0));
let KeyPart4 = sjcl.codec.hex.fromBits(sjcl.random.randomWords(2, 0));
let sessioKey = KeyPart1 + KeyPart2 + KeyPart3 + KeyPart4;
console.log("session-key - "  + sessioKey);

// session key to be base64 encoded before encrypting with RSA public key
let b64map = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
let b64pad = "=";
let i;
let c;
let ret = " ";
for (i = 0; i + 3 <= sessioKey.length; i += 3) {
  c = parseInt(sessioKey.substring(i, i + 3), 16);
  ret += b64map.charAt(c >> 6) + b64map.charAt(c & 63);
}
if (i + 1 == sessioKey.length) {
  c = parseInt(sessioKey.substring(i, i + 1), 16);
  ret += b64map.charAt(c << 2);
}
else if (i + 2 == sessioKey.length) {
  c = parseInt(sessioKey.substring(i, i + 2), 16);
  ret += b64map.charAt(c >> 2) + b64map.charAt((c & 3) << 4);
}
while ((ret.length & 3) > 0) ret += b64pad;

console.log("base64 encoded session key - "  + ret);


// RSA-OAEP SHA-512 encryption to generate session id
let publicKey = forge.pki.publicKeyFromPem("-----BEGIN PUBLIC KEY-----" + "RSA PUBLIC" + "-----END PUBLIC KEY-----");
let buffer = forge.util.createBuffer(ret);
let binaryString = buffer.getBytes();
let encrypted = publicKey.encrypt(binaryString, 'RSA-OAEP', {
  md: forge.md.sha512.create(),
  mgf: forge.mgf.mgf1.create(forge.md.sha512.create())
});
console.log("Session-id - " + forge.util.encode64(encrypted));


// encrypt pin/cvv
let iv = forge.random.getBytesSync(16);
let key_bytes = forge.util.hexToBytes(sessioKey);

let cipher = forge.cipher.createCipher("AES-GCM", key_bytes);
cipher.start({ iv: iv });
cipher.update(forge.util.createBuffer("241432FFFFFFFFFF"));
cipher.finish();
let tag = cipher.mode.tag.data;
let encoded = cipher.output.data;
let encryptedPin = forge.util.encode64(encoded + tag);
console.log("EncryptedPin_TO_SEND_IN_REQUEST - " + encryptedPin);
console.log("IV_TO_SEND_IN REQUEST - " + forge.util.encode64(iv));

// decrypt pin
let iv_bytes = forge.util.createBuffer(forge.util.decode64(forge.util.encode64(iv))).getBytes();
let decryptedPinBase64 = forge.util.decode64(encryptedPin);

let tag_bytes = forge.random.getBytesSync(16);
let decipher = forge.cipher.createDecipher("AES-GCM", key_bytes);
decipher.start({
  iv: iv_bytes,
  tag: tag_bytes
});
decipher.update(forge.util.createBuffer(decryptedPinBase64));
decipher.finish();
let decryptedBytes = decipher.output.getBytes();
let decryptedPin = decryptedBytes.substr(0, decryptedBytes.length > 16 ? decryptedBytes.length - 16 : decryptedBytes.length);

console.log("Decrypted Pin - " + decryptedPin);

Difference between Paysecure V1 and V2

Secure Initialization Vector (IV): In V2, a secure random method is used to generate the initialization vector (IV) for the encryption of the API response. This ensures that the IV is unpredictable, making it harder for attackers to mount a successful attack.
Stronger AES Algorithm: In V2, AES/GCM/NoPadding is used for encryption of sensitive data, which is a stronger algorithm than the AES/CBC/PKCS5PADDING used in V1. AES/GCM/NoPadding offers better authentication and integrity checks and is less susceptible to attacks like padding oracle attacks.
V2 uses RSA-OAEP with SHA-512 and 2048-bit keys for session ID generation. SHA-1 with 1024-bit keys is deprecated but still supported for backward compatibility — the API automatically detects which padding scheme and key size was used.
Both V1 and V2 now support 1024-bit and 2048-bit RSA key pairs. The API automatically detects the key size from the ciphertext length.