Encrypt PIN

Some APIs require the merchant PIN to be encrypted before it is sent in the request body. Use this page to generate an encrypted PIN and to review implementation examples in different languages.

Use your HesabPay API key as the encryption key when encrypting the PIN. The API key should be handled as a secret and must not be exposed in client-side code.

Interactive Encryptor

PIN Encryption Key Encrypt PIN

Encrypted PIN

Enter a PIN and encryption key, then click Encrypt PIN.

Copy

Algorithm

The encryption process uses AES-CBC with a 32-byte key. The key is derived by taking the first 32 bytes of the provided key and padding with zero bytes if it is shorter. A random 16-byte IV is generated for every encryption. The final value is:

base64(iv + ciphertext)

Code Examples

Python

import base64
from Crypto.Cipher import AES
from Crypto.Random import get_random_bytes
from Crypto.Util.Padding import pad

def encrypt_pin(data, key):
    key = key.encode("utf-8")[:32]
    key = key.ljust(32, b"\0")

    iv = get_random_bytes(16)
    cipher = AES.new(key, AES.MODE_CBC, iv)
    padded_data = pad(data.encode("utf-8"), AES.block_size)

    ciphertext = cipher.encrypt(padded_data)
    encrypted_data = base64.b64encode(iv + ciphertext).decode("utf-8")
    return encrypted_data

Node.js

import crypto from 'crypto';

function normalizeKey(key) {
  const keyBuffer = Buffer.alloc(32);
  Buffer.from(key, 'utf8').copy(keyBuffer, 0, 0, 32);
  return keyBuffer;
}

function encryptPin(pin, key) {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-cbc', normalizeKey(key), iv);
  const ciphertext = Buffer.concat([
    cipher.update(pin, 'utf8'),
    cipher.final(),
  ]);

  return Buffer.concat([iv, ciphertext]).toString('base64');
}

PHP

<?php
function encryptPin($pin, $key) {
    $normalizedKey = substr($key, 0, 32);
    $normalizedKey = str_pad($normalizedKey, 32, "\0");

    $iv = random_bytes(16);
    $ciphertext = openssl_encrypt(
        $pin,
        'AES-256-CBC',
        $normalizedKey,
        OPENSSL_RAW_DATA,
        $iv
    );

    return base64_encode($iv . $ciphertext);
}
?>

Browser JavaScript

const encoder = new TextEncoder();

function normalizeKey(keyText) {
  const keyBytes = encoder.encode(keyText);
  const normalized = new Uint8Array(32);
  normalized.set(keyBytes.slice(0, 32));
  return normalized;
}

async function encryptPin(pin, keyText) {
  const iv = crypto.getRandomValues(new Uint8Array(16));
  const key = await crypto.subtle.importKey(
    'raw',
    normalizeKey(keyText),
    { name: 'AES-CBC' },
    false,
    ['encrypt']
  );

  const ciphertext = new Uint8Array(
    await crypto.subtle.encrypt({ name: 'AES-CBC', iv }, key, encoder.encode(pin))
  );

  const combined = new Uint8Array(iv.length + ciphertext.length);
  combined.set(iv, 0);
  combined.set(ciphertext, iv.length);

  return btoa(String.fromCharCode(...combined));
}