Payment Cryptography Data Plane

2026/07/15 - Payment Cryptography Data Plane - 4 updated api methods

Changes  Adds support for UnionPay session key derivation to the GenerateAuthRequestCryptogram, VerifyAuthRequestCryptogram, GenerateMac, and VerifyMac APIs.

GenerateAuthRequestCryptogram (updated) Link ¶
Changes (request) 
{'SessionKeyDerivationAttributes': {'UnionPay': {'ApplicationTransactionCounter': 'string',
                                                 'PanSequenceNumber': 'string',
                                                 'PrimaryAccountNumber': 'string'}}}

Generates an Authorization Request Cryptogram (ARQC) for an EMV chip payment card authorization. For more information, see Generate auth request cryptogram in the Amazon Web Services Payment Cryptography User Guide.

ARQC generation uses an Issuer Master Key (IMK) for application cryptograms (TR31_E0_EMV_MKEY_APP_CRYPTOGRAMS) to derive a session key, which is then used to generate the cryptogram from the provided transaction data (when applicable). To use this operation, you must first create or import an IMK-AC key by calling CreateKey or ImportKey. The KeyModesOfUse should be set to DeriveKey for the IMK-AC encryption key.

For information about valid keys for this operation, see Understanding key attributes and Key types for specific data operations in the Amazon Web Services Payment Cryptography User Guide.

Cross-account use: This operation supports cross-account use when the key has a resource-based policy that grants access. For more information, see Resource-based policies.

Related operations:

  • VerifyAuthRequestCryptogram

See also: AWS API Documentation

Request Syntax

client.generate_auth_request_cryptogram(
    KeyIdentifier='string',
    TransactionData='string',
    MajorKeyDerivationMode='EMV_OPTION_A'|'EMV_OPTION_B',
    SessionKeyDerivationAttributes={
        'EmvCommon': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'ApplicationTransactionCounter': 'string'
        },
        'Mastercard': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'ApplicationTransactionCounter': 'string',
            'UnpredictableNumber': 'string'
        },
        'Emv2000': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'ApplicationTransactionCounter': 'string'
        },
        'Amex': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string'
        },
        'Visa': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string'
        },
        'UnionPay': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'ApplicationTransactionCounter': 'string'
        }
    }
)
type KeyIdentifier:

string

param KeyIdentifier:

[REQUIRED]

The keyARN of the IMK-AC (TR31_E0_EMV_MKEY_APP_CRYPTOGRAMS) that Amazon Web Services Payment Cryptography uses to generate the ARQC.

type TransactionData:

string

param TransactionData:

[REQUIRED]

The transaction data that Amazon Web Services Payment Cryptography uses for ARQC generation. The same transaction data is used for ARQC verification by the issuer using VerifyAuthRequestCryptogram.

type MajorKeyDerivationMode:

string

param MajorKeyDerivationMode:

[REQUIRED]

The method to use when deriving the major encryption key for ARQC generation within Amazon Web Services Payment Cryptography.

type SessionKeyDerivationAttributes:

dict

param SessionKeyDerivationAttributes:

[REQUIRED]

The attributes and values to use for deriving a session key for ARQC generation within Amazon Web Services Payment Cryptography.

  • EmvCommon (dict) --

    Parameters to derive session key for an Emv common payment card for ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

    • ApplicationTransactionCounter (string) -- [REQUIRED]

      The transaction counter that is provided by the terminal during transaction processing.

  • Mastercard (dict) --

    Parameters to derive session key for a Mastercard payment card for ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

    • ApplicationTransactionCounter (string) -- [REQUIRED]

      The transaction counter that is provided by the terminal during transaction processing.

    • UnpredictableNumber (string) -- [REQUIRED]

      A random number generated by the issuer.

  • Emv2000 (dict) --

    Parameters to derive session key for an Emv2000 payment card for ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

    • ApplicationTransactionCounter (string) -- [REQUIRED]

      The transaction counter that is provided by the terminal during transaction processing.

  • Amex (dict) --

    Parameters to derive session key for an Amex payment card for ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

  • Visa (dict) --

    Parameters to derive session key for a Visa payment cardfor ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

  • UnionPay (dict) --

    Parameters to derive session key for a UnionPay payment card for Authorization Request Cryptogram (ARQC) generation and verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN). If not used, enter 00.

    • ApplicationTransactionCounter (string) -- [REQUIRED]

      The transaction counter that the terminal provides during transaction processing. This value is in hexadecimal format. For example, enter a decimal counter of 109 as 006D.

rtype:

dict

returns:

Response Syntax

{
    'KeyArn': 'string',
    'KeyCheckValue': 'string',
    'AuthRequestCryptogram': 'string'
}

Response Structure

  • (dict) --

    • KeyArn (string) --

      The keyARN of the IMK-AC that Amazon Web Services Payment Cryptography uses for ARQC generation.

    • KeyCheckValue (string) --

      The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

      Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

    • AuthRequestCryptogram (string) --

      The Authorization Request Cryptogram (ARQC) generated by Amazon Web Services Payment Cryptography using the specified key and transaction data.

GenerateMac (updated) Link ¶
Changes (request) 
{'GenerationAttributes': {'EmvMac': {'SessionKeyDerivationMode': {'UNION_PAY'}}}}

Generates a Message Authentication Code (MAC) cryptogram within Amazon Web Services Payment Cryptography.

You can use this operation to authenticate card-related data by using known data values to generate MAC for data validation between the sending and receiving parties. This operation uses message data, a secret encryption key and MAC algorithm to generate a unique MAC value for transmission. The receiving party of the MAC must use the same message data, secret encryption key and MAC algorithm to reproduce another MAC value for comparision.

You can use this operation to generate a DUPKT, CMAC, HMAC or EMV MAC by setting generation attributes and algorithm to the associated values. The MAC generation encryption key must have valid values for KeyUsage such as TR31_M7_HMAC_KEY for HMAC generation, and the key must have KeyModesOfUse set to Generate.

For information about valid keys for this operation, see Understanding key attributes and Key types for specific data operations in the Amazon Web Services Payment Cryptography User Guide.

Cross-account use: This operation supports cross-account use when the key has a resource-based policy that grants access. For more information, see Resource-based policies.

Related operations:

  • VerifyMac

See also: AWS API Documentation

Request Syntax

client.generate_mac(
    KeyIdentifier='string',
    MessageData='string',
    GenerationAttributes={
        'Algorithm': 'ISO9797_ALGORITHM1'|'ISO9797_ALGORITHM3'|'CMAC'|'HMAC'|'HMAC_SHA224'|'HMAC_SHA256'|'HMAC_SHA384'|'HMAC_SHA512'|'AS2805_4_1',
        'EmvMac': {
            'MajorKeyDerivationMode': 'EMV_OPTION_A'|'EMV_OPTION_B',
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'SessionKeyDerivationMode': 'EMV_COMMON_SESSION_KEY'|'EMV2000'|'AMEX'|'MASTERCARD_SESSION_KEY'|'VISA'|'UNION_PAY',
            'SessionKeyDerivationValue': {
                'ApplicationCryptogram': 'string',
                'ApplicationTransactionCounter': 'string'
            }
        },
        'DukptIso9797Algorithm1': {
            'KeySerialNumber': 'string',
            'DukptKeyVariant': 'BIDIRECTIONAL'|'REQUEST'|'RESPONSE',
            'DukptDerivationType': 'TDES_2KEY'|'TDES_3KEY'|'AES_128'|'AES_192'|'AES_256'
        },
        'DukptIso9797Algorithm3': {
            'KeySerialNumber': 'string',
            'DukptKeyVariant': 'BIDIRECTIONAL'|'REQUEST'|'RESPONSE',
            'DukptDerivationType': 'TDES_2KEY'|'TDES_3KEY'|'AES_128'|'AES_192'|'AES_256'
        },
        'DukptCmac': {
            'KeySerialNumber': 'string',
            'DukptKeyVariant': 'BIDIRECTIONAL'|'REQUEST'|'RESPONSE',
            'DukptDerivationType': 'TDES_2KEY'|'TDES_3KEY'|'AES_128'|'AES_192'|'AES_256'
        }
    },
    MacLength=123
)
type KeyIdentifier:

string

param KeyIdentifier:

[REQUIRED]

The keyARN of the MAC generation encryption key.

type MessageData:

string

param MessageData:

[REQUIRED]

The data for which a MAC is under generation. This value must be hexBinary.

type GenerationAttributes:

dict

param GenerationAttributes:

[REQUIRED]

The attributes and data values to use for MAC generation within Amazon Web Services Payment Cryptography.

  • Algorithm (string) --

    The encryption algorithm for MAC generation or verification.

  • EmvMac (dict) --

    Parameters that are required for MAC generation or verification using EMV MAC algorithm.

    • MajorKeyDerivationMode (string) -- [REQUIRED]

      The method to use when deriving the master key for EMV MAC generation or verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN), a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

    • SessionKeyDerivationMode (string) -- [REQUIRED]

      The method of deriving a session key for EMV MAC generation or verification.

    • SessionKeyDerivationValue (dict) -- [REQUIRED]

      Parameters that are required to generate session key for EMV generation and verification.

      • ApplicationCryptogram (string) --

        The cryptogram provided by the terminal during transaction processing.

      • ApplicationTransactionCounter (string) --

        The transaction counter that is provided by the terminal during transaction processing.

  • DukptIso9797Algorithm1 (dict) --

    Parameters that are required for MAC generation or verification using DUKPT ISO 9797 algorithm1.

    • KeySerialNumber (string) -- [REQUIRED]

      The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

    • DukptKeyVariant (string) -- [REQUIRED]

      The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

    • DukptDerivationType (string) --

      The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

  • DukptIso9797Algorithm3 (dict) --

    Parameters that are required for MAC generation or verification using DUKPT ISO 9797 algorithm3.

    • KeySerialNumber (string) -- [REQUIRED]

      The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

    • DukptKeyVariant (string) -- [REQUIRED]

      The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

    • DukptDerivationType (string) --

      The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

  • DukptCmac (dict) --

    Parameters that are required for MAC generation or verification using DUKPT CMAC algorithm.

    • KeySerialNumber (string) -- [REQUIRED]

      The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

    • DukptKeyVariant (string) -- [REQUIRED]

      The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

    • DukptDerivationType (string) --

      The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

type MacLength:

integer

param MacLength:

The length of a MAC under generation.

rtype:

dict

returns:

Response Syntax

{
    'KeyArn': 'string',
    'KeyCheckValue': 'string',
    'Mac': 'string'
}

Response Structure

  • (dict) --

    • KeyArn (string) --

      The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses for MAC generation.

    • KeyCheckValue (string) --

      The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

      Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

    • Mac (string) --

      The MAC cryptogram generated within Amazon Web Services Payment Cryptography.

VerifyAuthRequestCryptogram (updated) Link ¶
Changes (request) 
{'SessionKeyDerivationAttributes': {'UnionPay': {'ApplicationTransactionCounter': 'string',
                                                 'PanSequenceNumber': 'string',
                                                 'PrimaryAccountNumber': 'string'}}}

Verifies Authorization Request Cryptogram (ARQC) for a EMV chip payment card authorization. For more information, see Verify auth request cryptogram in the Amazon Web Services Payment Cryptography User Guide.

ARQC generation is done outside of Amazon Web Services Payment Cryptography and is typically generated on a point of sale terminal for an EMV chip card to obtain payment authorization during transaction time. For ARQC verification, you must first import the ARQC generated outside of Amazon Web Services Payment Cryptography by calling ImportKey. This operation uses the imported ARQC and an major encryption key (DUKPT) created by calling CreateKey to either provide a boolean ARQC verification result or provide an APRC (Authorization Response Cryptogram) response using Method 1 or Method 2. The ARPC_METHOD_1 uses AuthResponseCode to generate ARPC and ARPC_METHOD_2 uses CardStatusUpdate to generate ARPC.

For information about valid keys for this operation, see Understanding key attributes and Key types for specific data operations in the Amazon Web Services Payment Cryptography User Guide.

Cross-account use: This operation supports cross-account use when the key has a resource-based policy that grants access. For more information, see Resource-based policies.

Related operations:

  • VerifyCardValidationData

  • VerifyPinData

See also: AWS API Documentation

Request Syntax

client.verify_auth_request_cryptogram(
    KeyIdentifier='string',
    TransactionData='string',
    AuthRequestCryptogram='string',
    MajorKeyDerivationMode='EMV_OPTION_A'|'EMV_OPTION_B',
    SessionKeyDerivationAttributes={
        'EmvCommon': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'ApplicationTransactionCounter': 'string'
        },
        'Mastercard': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'ApplicationTransactionCounter': 'string',
            'UnpredictableNumber': 'string'
        },
        'Emv2000': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'ApplicationTransactionCounter': 'string'
        },
        'Amex': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string'
        },
        'Visa': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string'
        },
        'UnionPay': {
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'ApplicationTransactionCounter': 'string'
        }
    },
    AuthResponseAttributes={
        'ArpcMethod1': {
            'AuthResponseCode': 'string'
        },
        'ArpcMethod2': {
            'CardStatusUpdate': 'string',
            'ProprietaryAuthenticationData': 'string'
        }
    }
)
type KeyIdentifier:

string

param KeyIdentifier:

[REQUIRED]

The keyARN of the major encryption key that Amazon Web Services Payment Cryptography uses for ARQC verification.

type TransactionData:

string

param TransactionData:

[REQUIRED]

The transaction data that Amazon Web Services Payment Cryptography uses for ARQC verification. The same transaction is used for ARQC generation outside of Amazon Web Services Payment Cryptography.

type AuthRequestCryptogram:

string

param AuthRequestCryptogram:

[REQUIRED]

The auth request cryptogram imported into Amazon Web Services Payment Cryptography for ARQC verification using a major encryption key and transaction data.

type MajorKeyDerivationMode:

string

param MajorKeyDerivationMode:

[REQUIRED]

The method to use when deriving the major encryption key for ARQC verification within Amazon Web Services Payment Cryptography. The same key derivation mode was used for ARQC generation outside of Amazon Web Services Payment Cryptography.

type SessionKeyDerivationAttributes:

dict

param SessionKeyDerivationAttributes:

[REQUIRED]

The attributes and values to use for deriving a session key for ARQC verification within Amazon Web Services Payment Cryptography. The same attributes were used for ARQC generation outside of Amazon Web Services Payment Cryptography.

  • EmvCommon (dict) --

    Parameters to derive session key for an Emv common payment card for ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

    • ApplicationTransactionCounter (string) -- [REQUIRED]

      The transaction counter that is provided by the terminal during transaction processing.

  • Mastercard (dict) --

    Parameters to derive session key for a Mastercard payment card for ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

    • ApplicationTransactionCounter (string) -- [REQUIRED]

      The transaction counter that is provided by the terminal during transaction processing.

    • UnpredictableNumber (string) -- [REQUIRED]

      A random number generated by the issuer.

  • Emv2000 (dict) --

    Parameters to derive session key for an Emv2000 payment card for ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

    • ApplicationTransactionCounter (string) -- [REQUIRED]

      The transaction counter that is provided by the terminal during transaction processing.

  • Amex (dict) --

    Parameters to derive session key for an Amex payment card for ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

  • Visa (dict) --

    Parameters to derive session key for a Visa payment cardfor ARQC verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

  • UnionPay (dict) --

    Parameters to derive session key for a UnionPay payment card for Authorization Request Cryptogram (ARQC) generation and verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN). If not used, enter 00.

    • ApplicationTransactionCounter (string) -- [REQUIRED]

      The transaction counter that the terminal provides during transaction processing. This value is in hexadecimal format. For example, enter a decimal counter of 109 as 006D.

type AuthResponseAttributes:

dict

param AuthResponseAttributes:

The attributes and values for auth request cryptogram verification. These parameters are required in case using ARPC Method 1 or Method 2 for ARQC verification.

  • ArpcMethod1 (dict) --

    Parameters that are required for ARPC response generation using method1 after ARQC verification is successful.

    • AuthResponseCode (string) -- [REQUIRED]

      The auth code used to calculate APRC after ARQC verification is successful. This is the same auth code used for ARQC generation outside of Amazon Web Services Payment Cryptography.

  • ArpcMethod2 (dict) --

    Parameters that are required for ARPC response generation using method2 after ARQC verification is successful.

    • CardStatusUpdate (string) -- [REQUIRED]

      The data indicating whether the issuer approves or declines an online transaction using an EMV chip card.

    • ProprietaryAuthenticationData (string) --

      The proprietary authentication data used by issuer for communication during online transaction using an EMV chip card.

rtype:

dict

returns:

Response Syntax

{
    'KeyArn': 'string',
    'KeyCheckValue': 'string',
    'AuthResponseValue': 'string'
}

Response Structure

  • (dict) --

    • KeyArn (string) --

      The keyARN of the major encryption key that Amazon Web Services Payment Cryptography uses for ARQC verification.

    • KeyCheckValue (string) --

      The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

      Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

    • AuthResponseValue (string) --

      The result for ARQC verification or ARPC generation within Amazon Web Services Payment Cryptography.

VerifyMac (updated) Link ¶
Changes (request) 
{'VerificationAttributes': {'EmvMac': {'SessionKeyDerivationMode': {'UNION_PAY'}}}}

Verifies a Message Authentication Code (MAC).

You can use this operation to verify MAC for message data authentication such as . In this operation, you must use the same message data, secret encryption key and MAC algorithm that was used to generate MAC. You can use this operation to verify a DUPKT, CMAC, HMAC or EMV MAC by setting generation attributes and algorithm to the associated values.

For information about valid keys for this operation, see Understanding key attributes and Key types for specific data operations in the Amazon Web Services Payment Cryptography User Guide.

Cross-account use: This operation supports cross-account use when the key has a resource-based policy that grants access. For more information, see Resource-based policies.

Related operations:

  • GenerateMac

See also: AWS API Documentation

Request Syntax

client.verify_mac(
    KeyIdentifier='string',
    MessageData='string',
    Mac='string',
    VerificationAttributes={
        'Algorithm': 'ISO9797_ALGORITHM1'|'ISO9797_ALGORITHM3'|'CMAC'|'HMAC'|'HMAC_SHA224'|'HMAC_SHA256'|'HMAC_SHA384'|'HMAC_SHA512'|'AS2805_4_1',
        'EmvMac': {
            'MajorKeyDerivationMode': 'EMV_OPTION_A'|'EMV_OPTION_B',
            'PrimaryAccountNumber': 'string',
            'PanSequenceNumber': 'string',
            'SessionKeyDerivationMode': 'EMV_COMMON_SESSION_KEY'|'EMV2000'|'AMEX'|'MASTERCARD_SESSION_KEY'|'VISA'|'UNION_PAY',
            'SessionKeyDerivationValue': {
                'ApplicationCryptogram': 'string',
                'ApplicationTransactionCounter': 'string'
            }
        },
        'DukptIso9797Algorithm1': {
            'KeySerialNumber': 'string',
            'DukptKeyVariant': 'BIDIRECTIONAL'|'REQUEST'|'RESPONSE',
            'DukptDerivationType': 'TDES_2KEY'|'TDES_3KEY'|'AES_128'|'AES_192'|'AES_256'
        },
        'DukptIso9797Algorithm3': {
            'KeySerialNumber': 'string',
            'DukptKeyVariant': 'BIDIRECTIONAL'|'REQUEST'|'RESPONSE',
            'DukptDerivationType': 'TDES_2KEY'|'TDES_3KEY'|'AES_128'|'AES_192'|'AES_256'
        },
        'DukptCmac': {
            'KeySerialNumber': 'string',
            'DukptKeyVariant': 'BIDIRECTIONAL'|'REQUEST'|'RESPONSE',
            'DukptDerivationType': 'TDES_2KEY'|'TDES_3KEY'|'AES_128'|'AES_192'|'AES_256'
        }
    },
    MacLength=123
)
type KeyIdentifier:

string

param KeyIdentifier:

[REQUIRED]

The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses to verify MAC data.

type MessageData:

string

param MessageData:

[REQUIRED]

The data on for which MAC is under verification. This value must be hexBinary.

type Mac:

string

param Mac:

[REQUIRED]

The MAC being verified.

type VerificationAttributes:

dict

param VerificationAttributes:

[REQUIRED]

The attributes and data values to use for MAC verification within Amazon Web Services Payment Cryptography.

  • Algorithm (string) --

    The encryption algorithm for MAC generation or verification.

  • EmvMac (dict) --

    Parameters that are required for MAC generation or verification using EMV MAC algorithm.

    • MajorKeyDerivationMode (string) -- [REQUIRED]

      The method to use when deriving the master key for EMV MAC generation or verification.

    • PrimaryAccountNumber (string) -- [REQUIRED]

      The Primary Account Number (PAN), a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • PanSequenceNumber (string) -- [REQUIRED]

      A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

    • SessionKeyDerivationMode (string) -- [REQUIRED]

      The method of deriving a session key for EMV MAC generation or verification.

    • SessionKeyDerivationValue (dict) -- [REQUIRED]

      Parameters that are required to generate session key for EMV generation and verification.

      • ApplicationCryptogram (string) --

        The cryptogram provided by the terminal during transaction processing.

      • ApplicationTransactionCounter (string) --

        The transaction counter that is provided by the terminal during transaction processing.

  • DukptIso9797Algorithm1 (dict) --

    Parameters that are required for MAC generation or verification using DUKPT ISO 9797 algorithm1.

    • KeySerialNumber (string) -- [REQUIRED]

      The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

    • DukptKeyVariant (string) -- [REQUIRED]

      The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

    • DukptDerivationType (string) --

      The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

  • DukptIso9797Algorithm3 (dict) --

    Parameters that are required for MAC generation or verification using DUKPT ISO 9797 algorithm3.

    • KeySerialNumber (string) -- [REQUIRED]

      The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

    • DukptKeyVariant (string) -- [REQUIRED]

      The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

    • DukptDerivationType (string) --

      The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

  • DukptCmac (dict) --

    Parameters that are required for MAC generation or verification using DUKPT CMAC algorithm.

    • KeySerialNumber (string) -- [REQUIRED]

      The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

    • DukptKeyVariant (string) -- [REQUIRED]

      The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

    • DukptDerivationType (string) --

      The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

type MacLength:

integer

param MacLength:

The length of the MAC.

rtype:

dict

returns:

Response Syntax

{
    'KeyArn': 'string',
    'KeyCheckValue': 'string'
}

Response Structure

  • (dict) --

    • KeyArn (string) --

      The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses for MAC verification.

    • KeyCheckValue (string) --

      The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

      Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.