payment-utils

Algorithmic crypto and payment-card utilities derived from the browser-side logic used by paymentcardtools.com.

This package is intentionally narrow in scope:

• Pure, reusable calculators and generators
• Payment-card cryptography helpers
• Hashing, MAC, PIN, CVV, ARQC, and validation utilities

It does not aim to ship the original website UI, static lookup tables, or CLI wrappers.

Requirements

• Node.js >=22
• ESM import style

Install

npm install payment-utils

Usage

All public functions are exported from the package root.

import {
  calculateCvv,
  calculateVisaPvv,
  runDesCalculator,
  validateLuhnPan,
} from "payment-utils";

const cvv = calculateCvv({
  pan: "4761739001010010",
  expiry: "2512",
  serviceCode: "101",
  cvkA: "0123456789ABCDE0",
  cvkB: "FEDCBA9876543210",
});

const pvv = calculateVisaPvv({
  pan: "4761739001010010",
  pin: "1234",
  pvki: "1",
  pvk: "0123456789ABCDEFFEDCBA9876543210",
});

const encrypted = runDesCalculator({
  data: "0123456789ABCDEF",
  key: "0123456789ABCDEFFEDCBA9876543210",
  operation: "encrypt",
  mode: "ecb",
});

const isValid = validateLuhnPan("4761739001010010");

Conventions

• Hex inputs are expected as hexadecimal strings without separators.
• Numeric inputs such as PANs, service codes, dates, and amounts are expected as digit strings unless noted otherwise.
• Functions throw Error when an input has an invalid length, invalid characters, or unsupported option values.
• Unless a function explicitly returns an object, it returns a string.

Available Tools

Symmetric Crypto

runAesCalculator(options)

Encrypts or decrypts AES data in ECB or CBC mode.

Options:

• data: hex string
• key: hex string
• operation: "encrypt" or "decrypt"; default "encrypt"
• mode: "ecb" or "cbc"; default "ecb"
• paddingMethod: 1 or 2; default 1
• iv: 16-byte hex IV for CBC; default 00000000000000000000000000000000

Returns:

• Hex string

Notes:

• Encryption pads using ISO 9797 method 1 or 2.
• Decryption requires a non-empty multiple of 16 bytes.
• When decrypting with paddingMethod: 2, trailing ISO 9797 method 2 padding is stripped from the returned value.

runDesCalculator(options)

Encrypts or decrypts DES / 3DES-style block data in ECB or CBC mode.

Options:

• data: hex string
• key: hex string
• operation: "encrypt" or "decrypt"; default "encrypt"
• mode: "ecb" or "cbc"; default "ecb"
• paddingMethod: 1 or 2; default 1
• iv: 8-byte hex IV for CBC; default 0000000000000000

Returns:

• Hex string

Notes:

• Encryption pads using ISO 9797 method 1 or 2.
• Decryption requires a non-empty multiple of 8 bytes.
• When decrypting with paddingMethod: 2, trailing ISO 9797 method 2 padding is stripped from the returned value.

runBitwiseCalculator(options)

Performs small bitwise operations on hex strings.

Options:

• operation: "xor", "and", "or", or "not"
• dataA: hex string, up to 8 bytes
• dataB: hex string, required for "xor", "and", and "or", and must match dataA length

Returns:

• Hex string

runBase64Calculator(options)

Encodes or decodes Base64 data.

Options:

• data: input string
• operation: "encode" or "decode"; default "encode"
• mode: "text" or "hex"; default "text"

Returns:

• String

Notes:

• In "text" mode, input or output is treated as UTF-8 text.
• In "hex" mode, input or output is treated as hexadecimal data.

Hashing And MAC

calculateSha1(options)

Computes a SHA-1 digest.

Options:

• data: input string
• mode: "text" or "hex"; default "text"

Returns:

• Uppercase hex digest string

calculateSha256(options)

Computes a SHA-256 digest.

Options:

• data: input string
• mode: "text" or "hex"; default "text"

Returns:

• Uppercase hex digest string

calculateHmac(options)

Computes an HMAC digest.

Options:

• data: input string
• key: input string
• algorithm: "sha1" or "sha256"; default "sha1"
• mode: "text" or "hex"; default "text"

Returns:

• Uppercase hex digest string

calculateMacIso9797Alg3(options)

Computes an ISO 9797-1 Algorithm 3 MAC using a double-length key.

Options:

• data: hex string
• key: 16-byte hex key
• paddingMethod: 1 or 2; default 1

Returns:

• 8-byte MAC as a hex string

Card Security Values

calculateCvv(options)

Calculates a card verification value from PAN, expiry, service code, and CVKs.

Options:

• pan: 13 to 19 digits
• expiry: 4 digits in YYMM
• serviceCode: 3 digits
• cvkA: 8-byte hex key
• cvkB: 8-byte hex key

Returns:

• 3-digit CVV string

calculateDcvv(options)

Calculates dynamic CVV using an ATC and MDK.

Options:

• pan: 13 to 19 digits
• expiry: 4 digits in YYMM
• serviceCode: 3 digits
• atc: 2-byte hex transaction counter
• mdk: 16-byte hex master derivation key

Returns:

• 3-digit dCVV string

calculateCavv(options)

Calculates a CAVV v7 payload and returns both hex and Base64 forms.

Options:

• pan: 16 digits
• authenticationResultsCode: 1 digit
• authenticationMethod: 2 digits
• keySet: 2 digits
• eci: 2 digits
• seed: 2-byte hex value
• transactionDate: date-like value accepted by the package date formatter
• amount: 12 digits
• currencyCode: 3 digits
• protocolVersion: 1 digit
• key: 16-byte hex key

Returns:

{
  hex: "....",
  base64: "...."
}

calculateSpaAavCvc2(options)

Calculates the SPA AAV / CVC2 value and returns the Base64-encoded payload.

Options:

• merchantName: string
• pan: 16 digits
• mode: SPA mode accepted by the upstream normalization logic
• acsId: 1 to 2 digits
• authenticationMethod: 1 digit
• sequenceNumber: 4-byte hex value
• keyIndex: 1 to 2 digits
• key: 16-byte hex key

Returns:

• Base64 string

PIN Tools

buildIso9564Format0PinBlock(options)

Builds an ISO 9564 format 0 clear PIN block.

Options:

• pan: 13 to 19 digits
• pin: 4 to 12 digits

Returns:

• 8-byte hex PIN block

isLuhnOptionalWarning(pan)

Checks whether the supplied PAN fails Luhn validation. This mirrors the UI behavior used to show an optional warning, not a hard failure.

Arguments:

• pan: 13 to 19 digits

Returns:

• Boolean

buildIso9564Format1PinBlock(options)

Builds an ISO 9564 format 1 clear PIN block.

Options:

• pin: 4 to 12 digits

Returns:

• 8-byte hex PIN block

extractPinFromPinBlock(options)

Extracts a PIN from a clear or encrypted PIN block.

Options:

• pinBlock: 8-byte hex PIN block
• pan: 13 to 19 digits
• pek: optional 16-byte hex PIN encryption key; when present, the block is decrypted before parsing

Returns:

{
  pin: "1234",
  format: "0",
  clearPinBlock: "0412FFFFFFFFFFFF"
}

Notes:

• Supports format 0 and 1.
• Throws if the format nibble is unsupported or the block padding is invalid.

calculateVisaPvv(options)

Calculates a Visa PVV.

Options:

• pan: 13 to 19 digits
• pin: 4 to 12 digits
• pvki: 1 digit
• pvk: 16-byte hex key

Returns:

• 4-digit PVV string

findPinsForPvv(options)

Brute-forces all 4-digit PIN values that match a target PVV.

Options:

• pvv: 4 digits
• pan: 13 to 19 digits
• pvki: 1 digit
• pvk: 16-byte hex key

Returns:

• Array of matching 4-digit PIN strings

calculateIbm3624Pin(options)

Calculates an IBM 3624 natural PIN.

Options:

• pan: 13 to 19 digits
• decimalizationTable: 16 digits
• pinLength: PIN length used to truncate the natural PIN
• pdk: 8-byte hex PIN derivation key

Returns:

• PIN string

calculateIbm3624PinOffset(options)

Calculates an IBM 3624 PIN offset.

Options:

• intermediatePin: digit string
• customerSelectedPin: digit string

Returns:

• Offset string

EMV And Payment Cryptogram Tools

deriveUdk(options)

Derives a unique derived key from a master key and PAN data.

Options:

• masterKey: 16-byte hex key
• pan: 13 to 19 digits
• panSequenceNumber: 1-byte hex value
• method: derivation method; default "a"
• parity: key parity mode; default "odd"

Returns:

• 16-byte hex derived key

calculateArqcCvn10(options)

Calculates Visa CVN 10 ARQC and ARPC values.

Options:

• pan: 16 digits
• panSequenceNumber: 1 digit; default "0"
• amountAuthorized: 12 digits
• amountOther: 12 digits
• countryCode: 3 digits
• tvr: 5-byte hex TVR
• currencyCode: 3 digits
• transactionDate: date-like value accepted by the package date formatter
• transactionType: 2 digits
• unpredictableNumber: 4-byte hex value
• aip: 2-byte hex value
• atc: 2-byte hex value
• cvr: 4-byte hex value
• responseCode: response code consumed by the ARPC generation logic
• imk: 16-byte hex issuer master key

Returns:

{
  arqc: "....",
  arpc: "...."
}

calculateArqcCvn18(options)

Calculates Visa CVN 18 ARQC and ARPC values.

Options:

• pan: 16 digits
• panSequenceNumber: 1 digit; default "0"
• amountAuthorized: 12 digits
• amountOther: 12 digits
• countryCode: 3 digits
• tvr: 5-byte hex TVR
• currencyCode: 3 digits
• transactionDate: date-like value accepted by the package date formatter
• transactionType: 2 digits
• unpredictableNumber: 4-byte hex value
• aip: 2-byte hex value
• atc: 2-byte hex value
• iad: 7 to 32 bytes of hex data
• csu: 4-byte hex value
• imk: 16-byte hex issuer master key

Returns:

{
  arqc: "....",
  arpc: "...."
}

calculateArqcMchip(options)

Calculates Mastercard M/Chip ARQC and ARPC values for supported application versions.

Options:

• pan: 16 to 19 digits
• panSequenceNumber: 1 digit; default "0"
• amountAuthorized: 12 digits
• amountOther: 12 digits
• countryCode: 3 digits
• tvr: 5-byte hex TVR
• currencyCode: 3 digits
• transactionDate: date-like value accepted by the package date formatter
• transactionType: 2 digits
• unpredictableNumber: 4-byte hex value
• aip: 2-byte hex value
• atc: 2-byte hex value
• cvr: 6-byte hex value
• arpcResponseCode: 2-byte hex value
• version: "16", "17", "20", or "21"; default "16"
• imk: 16-byte hex issuer master key
• cumulativeOfflineTransactionAmount: required for versions "17" and "21"; 12 digits
• consecutiveOfflineTransactionsNumber: required for versions "17" and "21"; 1 to 2 digits

Returns:

{
  arqc: "....",
  arpc: "...."
}

Validation

validateLuhnPan(pan)

Validates a PAN with the Luhn algorithm.

Arguments:

• pan: 13 to 19 digits

Returns:

• Boolean

generateLuhnCheckDigit(panWithoutCheckDigit)

Generates the Luhn check digit for a numeric payload.

Arguments:

• panWithoutCheckDigit: digit string

Returns:

• Single-digit string

Development

Run the test suite with:

npm test

The repository also includes:

• datasets/: captured tool fixtures used by tests
• test/: dataset-backed automated tests
• upstream/js/: mirrored upstream browser scripts used as implementation references

License

MIT