Common Elements

Merchant MAC – Message Authentication Code

To authenticate transaction messages on gateway to/from the merchant link, the merchant system should be able to calculate and verify message authentication codes for at least the transactions passed through cardholder browser redirects. Messages that are sent directly to e-Commerce Gateway ("Reversal") may be mutually authenticated with SSL client/server certificates and do not require MAC; if they are not mutually authenticated, MAC for these messages is mandatory.

MAC is calculated over all fields generated by the merchant system as defined in corresponding format tables (visible and hidden fields generated by the merchant system) except the MAC field ("P_SIGN") itself.

In order to generate or verify the message authentication field, the merchant system must assemble a MAC source string; all field values from the format tables are prefixed with the decimal field length in ASCII and concatenated in a specified order. If the field is not present, the '-' character is added to the message in its place.

Authorization message example: MAC source string will contain the following field values - AMOUNT,

CURRENCY, ORDER, DESC, MERCH_NAME, MERCH_URL, MERCHANT, TERMINAL, EMAIL, TRTYPE, COUNTRY, MERCH_GMT, TIMESTAMP, NONCE, BACKREF. Suppose that we have a transaction with following fields:

Field	Length	Value
AMOUNT	5	11.48
CURRENCY	3	USD
ORDER	6	771446
DESC	16	IT Books. Qty: 2
MERCH_NAME	17	Books Online Inc.
MERCH_URL	14	www.sample.com
MERCHANT	15	123456789012345
TERMINAL	8	99999999
EMAIL	19	pgw@mail.sample.com
TRTYPE	1	1
COUNTRY	0
MERCH_GMT	0
TIMESTAMP	14	20030105153021
NONCE	16	F2B2DD7E603A7ADA
BACKREF	33	https://www.sample.com/shop/reply

The MAC source string for this example is:

511\.483USD677144616IT Books. Qty: 217Books Online Inc.

14www.sample.com1512345678901234589999999919pgw@mail.sample.com

11--142003010515302116F2B2DD7E603A7ADA33https://www.sample.com/shop/reply

Line breaks are inserted for visibility only. This string is 190 bytes long.

After the MAC source string is assembled, the merchant system must apply a cryptographic algorithm to generate the message authentication code. Gateway supports various cryptographic algorithms and the system administrator may specify which algorithm will be used for a particular merchant terminal.

The merchant system must implement the chosen algorithm either in hardware or software form and be fully responsible for the secure storage and usage of corresponding cryptographic keys. An effective key length must be at least 112 bits for symmetric cryptographic algorithms and 1024 bits for RSA algorithm.

You can use the algorithm below to calculate the MAC value.

Algorithm: RSA Signature Calculation for Message Authentication Code

Inputs:

• data: Transaction data (dictionary, JSON, or another structured format)

• private_key: Private key provided by the payment gateway

• hash_algorithm: Hashing algorithm to be used (e.g., SHA-256)

Steps:

1. Serialize and Hash Data:
   1. Serialize the data into a canonical format (e.g., JSON) if necessary.
   2. Hash the serialized data using the specified hash_algorithm (e.g., SHA-256) to create a digest.
2. Sign the Digest with RSA Private Key:
   1. Use the RSA private key to sign the digest:
   2. Initialize an RSA signing object with the private key and chosen hashing algorithm.
   3. Sign the hashed data to create the RSA signature.
3. Return or Use the Signature:
   1. The resulting RSA signature is the Message Authentication Code (MAC) in RSA.
   2. This MAC can be used for authentication or integrity checks in the payment transaction.

Python Example (using cryptography library)

The below code in Python show how to generate the MAC using RSA:

from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization
import json  # Ensure to import the json module for serialization

def calculate_rsa_signature(data, private_key, hash_algorithm):
    # Serialize and hash data
    serialized_data = json.dumps(data).encode('utf-8')
    hashed_data = hashes.Hash(hash_algorithm())
    hashed_data.update(serialized_data)
    digest = hashed_data.finalize()

    # Sign the digest using RSA private key
    signature = private_key.sign(
        digest,
        padding.PSS(
            mgf=padding.MGF1(hashes.SHA256()),
            salt_length=padding.PSS.MAX_LENGTH
        ),
        hashes.SHA256()
    )

    # Return the RSA signature
    return signature.hex()

# Usage
transaction_data = {
    "amount": 100.50,
    "merchant_id": "123456789",
    "timestamp": "2023-12-11T15:30:00Z"
}
private_key = load_private_key_from_file('private_key.pem')  # Load your private key here (provide the implementation for load_private_key_from_file)
hash_algorithm = hashes.SHA256

rsa_signature = calculate_rsa_signature(transaction_data, private_key, hash_algorithm)
print("Generated RSA Signature (MAC):", rsa_signature)

Additional information for the EMVCo 3DS v2 protocol

The merchant system may provide specific transaction data for extended 3DS v2 processing. Sending of this data is optional, Acquirer's 3DS module is to check the version of 3DS protocol and apply this data accordingly.

Field	Size	Description
M_INFO	35000	Optional set of 3DS v2 related data, sent by merchant. Must be a Base64-encoded string of JSON-formatted “parameter”:”value data. The full set of available data can be taken from the EMVCo web site, “3-D Secure – Protocol and Core Functions Specification” document, AReq message description. All of the parameters in this set are optional.

Below is an example of data prepared for the M_INFO field.

{
   "browserLanguage":"en",
   "browserColorDepth":"32",
   "browserScreenHeight":"1920",
   "browserScreenWidth":"1080",
   "browserTZ":"0",
   "browserUserAgent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
}

The data below has to be converted to a single string and Base64-encoded.

Below is the list of parameters which can be sent for 3DS v2 processing.

Field	Description
Cardholder Billing Address City Field Name: billAddrCity	The city of the Cardholder billing address associated with the card used for this purchase.
Cardholder Billing Address Country Field Name: billAddrCountry	The country of the Cardholder billing address associated with the card used for this purchase.
Cardholder Billing Address Line 1 Field Name: billAddrLine1	First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
Cardholder Billing Address Line 2 Field Name: billAddrLine2	Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
Cardholder Billing Address Line 3 Field Name: billAddrLine3	Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
Cardholder Billing Address Postal Code Field Name: billAddrPostCode	ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase.
Cardholder Billing Address State Field Name: billAddrState	The state or province of the Cardholder billing address associated with the card used for this purchase.
Cardholder Email Address Field Name: email	The email address associated with the account that is entered by the Cardholder.
Cardholder Home Phone Number Field Name: homePhone	The home phone number provided by the Cardholder.
Cardholder Mobile Phone Number Field Name: mobilePhone	The mobile phone number provided by the Cardholder
Cardholder Shipping Address City Field Name: shipAddrCity	City portion of the shipping address requested by the Cardholder.
Cardholder Shipping Address Country Field Name: shipAddrCountry	Country of the shipping address requested by the Cardholder.
Cardholder Shipping Address Line 1 Field Name: shipAddrLine1	First line of the street address or equivalent local portion of the shipping address requested by the Cardholder
Cardholder Shipping Address Line 2 Field Name: shipAddrLine2	Second line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
Cardholder Shipping Address Line 3 Field Name: shipAddrLine3	Third line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
Cardholder Shipping Address Postal Code Field Name: shipAddrPostCode	The ZIP or other postal code of the shipping address requested by the Cardholder.
Cardholder Shipping Address State Field Name: shipAddrState	The state or province of the shipping address associated with the card being used for this purchase.
Cardholder Work Phone Number Field Name: workPhone	The work phone number provided by the Cardholder.