Card Encryption

This documentation provides a comprehensive overview for developers on implementing Advanced Encryption Standard (AES) encryption for card data in payment systems. The purpose is to ensure secure transmission of sensitive cardholder information and compliance with relevant security standards.

Rationale for AES Encryption in Card Processing

AES encryption is widely recognised for its effectiveness in securing sensitive data, such as cardholder information, during electronic payment transactions. Encrypting card details before transmission reduces the risk of data interception and unauthorised access.

Prerequisites

Developers should ensure the following prior to implementation:

• Access to the clientKey and clientIV generated by the HydrogenPay API.
• Use of a reliable cryptographic library, such as CryptoJS for JavaScript.
• Secure management of encryption keys and initialisation vectors (IVs).

Card Data Structure

The card data to be encrypted should follow this JSON structure:

{
  "cardNumber": "5060990580000217499",
  "expiryYear": "30",
  "expiryMonth": "50",
  "cvv": "111"
}

Encryption Algorithm and Mode

• Algorithm: AES (Advanced Encryption Standard)
• Mode: CBC (Cipher Block Chaining)
• Padding: PKCS7 (default in CryptoJS)
• Key and IV: Both must be Base64-decoded before use

Implementation Example (JavaScript with CryptoJS)

Import CryptoJS

Ensure the CryptoJS library is included in the project:

import CryptoJS from "crypto-js";

Encryption Function

The following function performs AES encryption on card data:

function encryptCardData(cardData, base64Key, base64IV) {
    const jsonData = JSON.stringify(cardData);
    const parsedKey = CryptoJS.enc.Base64.parse(base64Key);
    const parsedIV = CryptoJS.enc.Base64.parse(base64IV);
    const encrypted = CryptoJS.AES.encrypt(
        CryptoJS.enc.Utf8.parse(jsonData),
        parsedKey,
        {
            iv: parsedIV,
            mode: CryptoJS.mode.CBC,
            padding: CryptoJS.pad.Pkcs7
        }
    );
    return encrypted.toString(); // Returns Base64-encoded ciphertext
}

Parameters:

• cardData: Object containing the card information.
• base64Key: AES key received from the API, in Base64 format.
• base64IV: IV received from the API, in Base64 format.

Usage Example:

const cardData = {
    cardNumber: "5060990580000217499",
    expiryYear: "30",
    expiryMonth: "50",
    cvv: "111"
};

const encryptedCardDetails = encryptCardData(cardData, clientKey, clientIV);

Security Considerations

• Keys and IVs should never be exposed in client-side code or logs.
• Encrypted card data must be transmitted only over secure channels, such as HTTPS.
• Compliance with PCI DSS requirements for handling cardholder data is essential.

Integration with HydrogenPay API

The encrypted card details should be provided in the cardDetails field of the purchase API request, as specified in the HydrogenPay documentation.

Troubleshooting

• If decryption fails, ensure the key and IV are correctly Base64-decoded before use.
• Confirm that the cryptographic library uses PKCS7 padding.
• Verify that the encrypted string is not altered during transmission, for example through URL encoding.