Encrypt card data using script

August 21, 2024

If you are in the testing phase and do not yet have an HSM (Hardware Security Module), you can request Kushki to provide you the test keys so that, through a library, you can encrypt transaction data and make requests in Postman to the Kushki API, thereby accelerating the implementation of your solution.

The following steps will show how to generate a transaction request with the Kushki POS using cardtool to encrypt the transactional data.

Previous requirements

To perform the encryption using the script and to obtain the data to be included in the request, you need the following elements:

• BDK (in TR-31 format) provided by Kushki’s Information Security team..
• BDK (in TR-31 format) of PIN, also provided by Kushki’s Information Security team. This is used only for online PIN transactions.
• A pair of credentials for transaction processing, including your private key and your public key.
• Key Serial Number (KSN) of your terminal, you can get a KSN sample and just modify the counter each time you perform a new transaction.
• Install Python.
• Install the cardtool tool. link to the tool: https://pypi.org/project/cardtool/

1. Variable Preparation

To perform the execution you must place the following data in the configuration files of your script setting.yml and cards-out.json

The configuration should be set as shown in the following image:

Execute the following commands:

python3 -m venv .env
source .env/bin/activate
!pip3 install cardtool

2. Obtain the Plaintext Key

To perform the encryption of the PIN and card data, it is necessary to first obtain the Plaintext key from the key provided by security in TR-31 format.

To do this, execute the following command:

cardtool decrypt-key -kbpk <your_key_block_protection_key> -kcv <key_check_value> YOUR_KEY_BLOCK

The result of this form will be a response like this:

Plaintext Key: ABCD1234AB01CD23F126FBAB02621ADA

This value will be used for the next command, where we will execute the encryption of the data and PIN.

3. Script execution to obtain encrypted data

Now that you have configured the settings.yaml file and installed the necessary dependency, let’s execute the following command:

cardtool gen-card -cfg setting.yml -fmt json cards-out.json

When executing the command, we will obtain the cards-out.json file as output, this file will contain the necessary information to include in the body of your example request:

4. Transaction Payload

To execute the payload test of a transaction we recommend using Postman, where we already have a collection that you can find in this link. This collection can assist with testing and validation during the implementation.

Once you have the encrypted card and PIN information, simply include it in the body of the request and send it.