AWS.PaymentCryptography reference

Alias

Source: src/AWS/PaymentCryptography/Alias.ts

A friendly name for an AWS Payment Cryptography Key. Aliases give keys a stable, human-readable identifier that survives key rotation — the alias can be repointed to a new key without touching consumers.

Alias: Creating Aliases

Alias attached to a key

import * as PaymentCryptography from "alchemy/AWS/PaymentCryptography";

const key = yield* PaymentCryptography.Key("DataKey", { keyAttributes: { ... } });
const alias = yield* PaymentCryptography.Alias("DataKeyAlias", {
  keyArn: key.keyArn,
});

Alias with an explicit name

const alias = yield* PaymentCryptography.Alias("DataKeyAlias", {
  aliasName: "alias/payments/data-encryption",
  keyArn: key.keyArn,
});

DecryptData

Source: src/AWS/PaymentCryptography/DecryptData.ts

Runtime binding for payment-cryptography:DecryptData — decrypts ciphertext under a Key. Provide DecryptDataHttp on the Function to satisfy this service.

DecryptData: Decrypting Data

// init
const decrypt = yield* PaymentCryptography.DecryptData(key);

// runtime
const result = yield* decrypt({
  CipherText: cipherText,
  DecryptionAttributes: {
    Symmetric: { Mode: "CBC", InitializationVector: "00000000000000000000000000000000" },
  },
});

EncryptData

Source: src/AWS/PaymentCryptography/EncryptData.ts

Runtime binding for payment-cryptography:EncryptData — encrypts hex-encoded plaintext under a Key. Provide EncryptDataHttp on the Function to satisfy this service.

EncryptData: Encrypting Data

// init
const encrypt = yield* PaymentCryptography.EncryptData(key);

// runtime
const result = yield* encrypt({
  PlainText: "31323334353637383930313233343536",
  EncryptionAttributes: {
    Symmetric: { Mode: "CBC", InitializationVector: "00000000000000000000000000000000" },
  },
});

GenerateAs2805KekValidation

Source: src/AWS/PaymentCryptography/GenerateAs2805KekValidation.ts

Runtime binding for payment-cryptography:GenerateAs2805KekValidation — generates AS2805 Key Encryption Key (KEK) validation data (random key send/receive components) under a KEK Key, used during AS2805 node key establishment in Australian payment networks. Provide GenerateAs2805KekValidationHttp on the Function to satisfy this service.

GenerateAs2805KekValidation: AS2805 Key Establishment

// init
const generateKekValidation =
  yield* PaymentCryptography.GenerateAs2805KekValidation(kek);

// runtime
const validation = yield* generateKekValidation({
  KekValidationType: "KEKS",
  RandomKeySendVariantMask: mask,
});

GenerateAuthRequestCryptogram

Source: src/AWS/PaymentCryptography/GenerateAuthRequestCryptogram.ts

Runtime binding for payment-cryptography:GenerateAuthRequestCryptogram — generates an Authorization Request Cryptogram (ARQC) for AS2805 terminal transactions under an EMV issuer master Key. Provide GenerateAuthRequestCryptogramHttp on the Function to satisfy this service.

GenerateAuthRequestCryptogram: EMV Cryptograms

// init
const generateArqc =
  yield* PaymentCryptography.GenerateAuthRequestCryptogram(issuerMasterKey);

// runtime
const generated = yield* generateArqc({
  TransactionData: transactionDataHex,
  MajorKeyDerivationMode: "EMV_OPTION_A",
  SessionKeyDerivationAttributes: {
    EmvCommon: { PrimaryAccountNumber: pan, PanSequenceNumber: "00", ApplicationTransactionCounter: "0001" },
  },
});

GenerateCardValidationData

Source: src/AWS/PaymentCryptography/GenerateCardValidationData.ts

Runtime binding for payment-cryptography:GenerateCardValidationData — generates card validation values (CVV/CVV2, dCVV, CSC) under a Card Verification Key (CVK) Key. Provide GenerateCardValidationDataHttp on the Function to satisfy this service.

GenerateCardValidationData: Card Validation Data

// init
const generateCvv2 = yield* PaymentCryptography.GenerateCardValidationData(cvk);

// runtime
const generated = yield* generateCvv2({
  PrimaryAccountNumber: "9123456789012345",
  GenerationAttributes: {
    CardVerificationValue2: { CardExpiryDate: "0130" },
  },
});

GenerateMac

Source: src/AWS/PaymentCryptography/GenerateMac.ts

Runtime binding for payment-cryptography:GenerateMac — computes a Message Authentication Code over hex-encoded message data under a Key. Provide GenerateMacHttp on the Function to satisfy this service.

GenerateMac: Generating MACs

// init
const generateMac = yield* PaymentCryptography.GenerateMac(macKey);

// runtime — MessageData is hex-encoded
const result = yield* generateMac({
  MessageData: "31323334353637383930313233343536",
  GenerationAttributes: { Algorithm: "HMAC" },
});

GenerateMacEmvPinChange

Source: src/AWS/PaymentCryptography/GenerateMacEmvPinChange.ts

Runtime binding for payment-cryptography:GenerateMacEmvPinChange — generates the issuer-script MAC (and re-encrypted PIN block) for an EMV PIN change command. Binds three Keys: the new PIN encryption key (PEK) the changed PIN is encrypted under, and the secure-messaging integrity and confidentiality issuer master keys. Provide GenerateMacEmvPinChangeHttp on the Function to satisfy this service.

GenerateMacEmvPinChange: EMV PIN Change

// init
const generatePinChangeMac = yield* PaymentCryptography.GenerateMacEmvPinChange(
  newPinPek,
  secureMessagingIntegrityKey,
  secureMessagingConfidentialityKey,
);

// runtime
const result = yield* generatePinChangeMac({
  NewEncryptedPinBlock: newEncryptedPinBlock,
  PinBlockFormat: "ISO_FORMAT_0",
  MessageData: messageDataHex,
  DerivationMethodAttributes: { Emv2000: { ... } },
});

GeneratePinData

Source: src/AWS/PaymentCryptography/GeneratePinData.ts

Runtime binding for payment-cryptography:GeneratePinData — generates PIN-related data (PIN, PVV, PIN block) under a PIN generation Key (e.g. a Visa PVK) and returns the PIN block encrypted under a PIN encryption Key (PEK). Provide GeneratePinDataHttp on the Function to satisfy this service.

GeneratePinData: PIN Data

// init
const generatePin = yield* PaymentCryptography.GeneratePinData(pvk, pek);

// runtime
const generated = yield* generatePin({
  GenerationAttributes: { VisaPin: { PinVerificationKeyIndex: 1 } },
  PrimaryAccountNumber: "9123456789012345",
  PinBlockFormat: "ISO_FORMAT_0",
});
// generated.EncryptedPinBlock + generated.PinData.VerificationValue

GetPublicKeyCertificate

Source: src/AWS/PaymentCryptography/GetPublicKeyCertificate.ts

Runtime binding for payment-cryptography:GetPublicKeyCertificate — exports the public-key certificate (and its root certificate chain) of an asymmetric key pair Key, e.g. to share the public verification key with a partner. The private key never leaves the service. Provide GetPublicKeyCertificateHttp on the Function to satisfy this service.

GetPublicKeyCertificate: Public Key Certificates

// init
const getPublicKeyCertificate =
  yield* PaymentCryptography.GetPublicKeyCertificate(signKey);

// runtime — both fields are base64-encoded certificates
const { KeyCertificate, KeyCertificateChain } =
  yield* getPublicKeyCertificate();

Key

Source: src/AWS/PaymentCryptography/Key.ts

An AWS Payment Cryptography key — a managed cryptographic key with TR-31 attributes (algorithm, class, usage, modes of use) used for data encryption, MAC generation/verification, and other payment-domain cryptographic operations.

The key ARN is auto-assigned by the service; attach an Alias for a stable human-readable identifier. Deletion schedules the key for removal after a waiting window (minimum 3 days) during which it can be restored.

Key: Creating Keys

Symmetric data-encryption key

import * as PaymentCryptography from "alchemy/AWS/PaymentCryptography";

const key = yield* PaymentCryptography.Key("DataKey", {
  keyAttributes: {
    keyAlgorithm: "AES_128",
    keyClass: "SYMMETRIC_KEY",
    keyUsage: "TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY",
    keyModesOfUse: { encrypt: true, decrypt: true, wrap: true, unwrap: true },
  },
});

HMAC key for MAC generation and verification

const macKey = yield* PaymentCryptography.Key("MacKey", {
  keyAttributes: {
    keyAlgorithm: "HMAC_SHA256",
    keyClass: "SYMMETRIC_KEY",
    keyUsage: "TR31_M7_HMAC_KEY",
    keyModesOfUse: { generate: true, verify: true },
  },
});

Key: Managing Key State

const key = yield* PaymentCryptography.Key("DataKey", {
  keyAttributes: { ... },
  enabled: false,
});

Key: Using Keys at Runtime

// init
const encrypt = yield* PaymentCryptography.EncryptData(key);

return {
  fetch: Effect.gen(function* () {
    // runtime — PlainText is hex-encoded
    const result = yield* encrypt({
      PlainText: "31323334353637383930313233343536",
      EncryptionAttributes: { Symmetric: { Mode: "CBC" } },
    });
    return HttpServerResponse.json({ cipherText: result.CipherText });
  }),
};

ReEncryptData

Source: src/AWS/PaymentCryptography/ReEncryptData.ts

Runtime binding for payment-cryptography:ReEncryptData — decrypts ciphertext under the incoming Key and re-encrypts it under the outgoing Key entirely inside the service; the plaintext never leaves AWS Payment Cryptography. At least one side must be a DUKPT Base Derivation Key or a dynamic (TR-31 wrapped) key — the service rejects plain symmetric-to-symmetric re-encryption with ValidationException: KeyUsages not allowed for this operation. Provide ReEncryptDataHttp on the Function to satisfy this service.

ReEncryptData: Re-Encrypting Data

// init — incoming BDK, outgoing symmetric data key
const reEncrypt = yield* PaymentCryptography.ReEncryptData(bdk, workingKey);

// runtime
const translated = yield* reEncrypt({
  CipherText: dukptCipherTextHex,
  IncomingEncryptionAttributes: {
    Dukpt: { KeySerialNumber: ksn, Mode: "CBC" },
  },
  OutgoingEncryptionAttributes: {
    Symmetric: { Mode: "CBC", InitializationVector: iv },
  },
});

TranslateKeyMaterial

Source: src/AWS/PaymentCryptography/TranslateKeyMaterial.ts

Runtime binding for payment-cryptography:TranslateKeyMaterial — translates an ECDH-derived TR-31 wrapped key block into a TR-31 key block wrapped under a Key Encryption Key, without importing the short-lived key into the service. The key identifiers live in nested request structures (IncomingKeyMaterial.DiffieHellmanTr31KeyBlock.PrivateKeyIdentifier, OutgoingKeyMaterial.Tr31KeyBlock.WrappingKeyIdentifier), so the caller supplies the full request; bind every Key the request references so the Function is granted the action on each. Provide TranslateKeyMaterialHttp on the Function to satisfy this service.

TranslateKeyMaterial: Key Material Translation

// init — grant on every key the request references
const translateKeyMaterial =
  yield* PaymentCryptography.TranslateKeyMaterial(ecdhPrivateKey, caKey, kek);
const ecdhPrivateKeyArn = yield* ecdhPrivateKey.keyArn;
const caKeyArn = yield* caKey.keyArn;
const kekArn = yield* kek.keyArn;

// runtime
const translated = yield* translateKeyMaterial({
  IncomingKeyMaterial: {
    DiffieHellmanTr31KeyBlock: {
      PrivateKeyIdentifier: yield* ecdhPrivateKeyArn,
      CertificateAuthorityPublicKeyIdentifier: yield* caKeyArn,
      // ...
    },
  },
  OutgoingKeyMaterial: { Tr31KeyBlock: { WrappingKeyIdentifier: yield* kekArn } },
});

TranslatePinData

Source: src/AWS/PaymentCryptography/TranslatePinData.ts

Runtime binding for payment-cryptography:TranslatePinData — translates an encrypted PIN block from one PIN encryption Key (and ISO 9564 format) to another without the PIN ever leaving the service. This is the core acquirer operation for forwarding PIN blocks between networks. Provide TranslatePinDataHttp on the Function to satisfy this service.

TranslatePinData: PIN Data

// init
const translatePin = yield* PaymentCryptography.TranslatePinData(pek, partnerPek);

// runtime
const translated = yield* translatePin({
  IncomingTranslationAttributes: {
    IsoFormat0: { PrimaryAccountNumber: pan },
  },
  OutgoingTranslationAttributes: {
    IsoFormat0: { PrimaryAccountNumber: pan },
  },
  EncryptedPinBlock: encryptedPinBlock,
});

VerifyAuthRequestCryptogram

Source: src/AWS/PaymentCryptography/VerifyAuthRequestCryptogram.ts

Runtime binding for payment-cryptography:VerifyAuthRequestCryptogram — verifies an Authorization Request Cryptogram (ARQC) during EMV transaction processing under an issuer master Key, optionally producing the Authorization Response Cryptogram (ARPC). A mismatch fails with the typed VerificationFailedException. Provide VerifyAuthRequestCryptogramHttp on the Function to satisfy this service.

VerifyAuthRequestCryptogram: EMV Cryptograms

// init
const verifyArqc =
  yield* PaymentCryptography.VerifyAuthRequestCryptogram(issuerMasterKey);

// runtime
const verified = yield* verifyArqc({
  TransactionData: transactionDataHex,
  AuthRequestCryptogram: arqc,
  MajorKeyDerivationMode: "EMV_OPTION_A",
  SessionKeyDerivationAttributes: {
    EmvCommon: { PrimaryAccountNumber: pan, PanSequenceNumber: "00", ApplicationTransactionCounter: "0001" },
  },
  AuthResponseAttributes: { ArqcMethod1: { AuthResponseCode: "0000" } },
});

VerifyCardValidationData

Source: src/AWS/PaymentCryptography/VerifyCardValidationData.ts

Runtime binding for payment-cryptography:VerifyCardValidationData — verifies card validation values (CVV/CVV2, dCVV, CSC) under the same Card Verification Key (CVK) Key used to generate them. A mismatch fails with the typed VerificationFailedException. Provide VerifyCardValidationDataHttp on the Function to satisfy this service.

VerifyCardValidationData: Card Validation Data

// init
const verifyCvv2 = yield* PaymentCryptography.VerifyCardValidationData(cvk);

// runtime
const outcome = yield* verifyCvv2({
  PrimaryAccountNumber: "9123456789012345",
  VerificationAttributes: {
    CardVerificationValue2: { CardExpiryDate: "0130" },
  },
  ValidationData: cvv2,
}).pipe(
  Effect.map(() => "valid"),
  Effect.catchTag("VerificationFailedException", () =>
    Effect.succeed("invalid"),
  ),
);

VerifyMac

Source: src/AWS/PaymentCryptography/VerifyMac.ts

Runtime binding for payment-cryptography:VerifyMac — verifies a Message Authentication Code against hex-encoded message data under a Key. A mismatched MAC fails with the typed VerificationFailedException. Provide VerifyMacHttp on the Function to satisfy this service.

VerifyMac: Verifying MACs

// init
const verifyMac = yield* PaymentCryptography.VerifyMac(macKey);

// runtime — MessageData and Mac are hex-encoded
yield* verifyMac({
  MessageData: "31323334353637383930313233343536",
  Mac: mac,
  VerificationAttributes: { Algorithm: "HMAC" },
});

VerifyPinData

Source: src/AWS/PaymentCryptography/VerifyPinData.ts

Runtime binding for payment-cryptography:VerifyPinData — verifies an encrypted PIN block against PIN verification data (e.g. a Visa PVV) using a PIN verification Key (PVK) and the PIN encryption Key (PEK) the block is encrypted under. A mismatch fails with the typed VerificationFailedException. Provide VerifyPinDataHttp on the Function to satisfy this service.

VerifyPinData: PIN Data

// init
const verifyPin = yield* PaymentCryptography.VerifyPinData(pvk, pek);

// runtime
const outcome = yield* verifyPin({
  VerificationAttributes: {
    VisaPin: { PinVerificationKeyIndex: 1, VerificationValue: pvv },
  },
  EncryptedPinBlock: encryptedPinBlock,
  PrimaryAccountNumber: "9123456789012345",
  PinBlockFormat: "ISO_FORMAT_0",
}).pipe(
  Effect.map(() => "valid"),
  Effect.catchTag("VerificationFailedException", () =>
    Effect.succeed("invalid"),
  ),
);