This guide is designed to help developers securely handle card data within payment systems by using Advanced Encryption Standard (AES) encryption. The aim is to protect sensitive cardholder information during transmission and ensure compliance with industry security standards.

Why Use AES Encryption for Card Payments?

AES is a trusted method for safeguarding sensitive information, including cardholder data, in digital payment processes. By encrypting card details before they are sent, you significantly lower the risk of interception or unauthorised access.

What You Need Before You Start

Before implementing AES encryption, make sure you have:

Access to the clientKey and clientIV generated by the HydrogenPay API.
A reliable cryptographic library, such as CryptoJS for JavaScript.
A secure approach for managing your encryption keys and initialisation vectors (IVs).

Card Data Format

The card information you need to encrypt should be structured as follows:

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

Encryption Details

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

How to Implement (JavaScript Example Using CryptoJS)

Step 1: Import CryptoJS

Add the CryptoJS library to your project:

import CryptoJS from "crypto-js";

Step 2: Encrypt Card Data

Here’s a function that encrypts your 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: An object containing the card details.
base64Key: The AES key from the API, in Base64 format.
base64IV: The IV from the API, in Base64 format.

Example Usage:

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

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

Security Best Practices

Never expose your keys or IVs in client-side code or logs.
Always transmit encrypted data over secure channels like HTTPS.
Make sure you comply with PCI DSS requirements when handling cardholder data.

Integrating with HydrogenPay API

When making a purchase API request, include the encrypted card details in the cardDetails field, as outlined in the HydrogenPay documentation.

Troubleshooting Tips

If decryption fails, double-check that your key and IV are Base64-decoded correctly.
Ensure your cryptographic library uses PKCS7 padding.
Confirm the encrypted string remains unchanged during transmission.