📘

Available soon

While Terminal-to-Host connections typically use DUKPT encryption, Host-to-Host connections may also make use of the so called Master-Session Key (MSK) encryption for PIN and PAN.

There are two parts that need to be followed in order to use MSKs:

1. Offline exchange of zone master keys between Fiserv and you as an integrator (separate keys for PAN and PIN)
2. Periodic rotation of session keys and encryption of transaction data using the session key during the flow

Pre-Requisites

• Two AES 256-bit Master Keys (Zone Master Key or Transport Key) (one for SRED, one for PIN) must be exchanged offline between you and Fiserv
• The labels for masterKeyLabel and sessionKeyLabel have been agreed

Session Key Management

Key Import

To start using encrypted transactions, you’ll need to import a session key using the Key Management API. This API is secured with TLS 1.2 or higher, and requires both Mutual Authentication and Basic Authorization.

• The session keys must be AES 128-bit, formatted in TR-31 key block format, and encrypted using a Zone Master Key (ZMK) that is identified by a label called masterKeyLabel.
• You’ll need to generate two types of session keys:
  • For PIN encryption: Use KeyUsage ZPK (Zone PIN Key). This key should be AES 128-bit, in TR-31 format, and encrypted under the PIN master key (pin masterKeyLabel).
  • For SRED encryption: Use KeyUsage DEK (Data Encryption Key). This key should also be AES 128-bit, in TR-31 format, and encrypted under the PAN master key (pan masterKeyLabel).

API Endpoint

Endpoint: POST .../key-management/keys/import

Request parameters:

Example:

{
    "requestType": "ImportKeyRequest",
    "keyType": "PAN",
    "masterKeyLabel": "ZMK_PAN_XXX_YYY",
    "sessionKeyLabel": "DEK_XX_XXYY",
    "sessionKey": "B0080P0TN00N000041664BFCB3C43B151D024BFECFB43BD789CB666C16BB04028873D6F5B6C1D42F",
    "sessionKeyCheckValue": "CE1CDE"
}

{
    "type": "importKeyResponse",
    "clientRequestId": "6af17b4f-3e07-44f9-9b09-cf84ab3b485d",
    "keyType": "PAN",
    "masterKeyLabel": "ZMK_PAN_XXX_YYY",
    "sessionKeyLabel": "DEK_XX_XXYY",
    "sessionKeyId": "1201",
    "sessionKeyCheckValue": "CE1CDE"
}

Exception scenarios:

🚧

Additional note

In case of a timeout during the Import Key process, it is recommended to initiate a Get Keys request to retrieve the keys associated with the session key label and confirm whether the import was successful at IPG.
Additionally, to avoid potential conflicts, it is advised not to perform multiple successful Import Key requests within a short time frame.

Session Key Rotation

Once the session key is successfully imported, the sessionKeyId returned in the response becomes the active key. This key can then be used for PAN re-encryption or PIN translation.
The gateway maintains up to three session keys per sessionKeyLabel, each one identified by sessionkeyid in the response.

How it works

• The gateway maintains 3 static Key IDs (e.g., 1001, 1002, 1003).

• Each Key ID has a version (e.g., 1.0, 2.0, 3.0).

• When a new key is imported:

  • It is added to the Key ID with the lowest version.
  • That Key ID is then rotated to have the highest version.
  • The previous highest version is downgraded accordingly.

• The Key ID with the highest version is always the active key used for encryption.

  

Retrieve Session Key Details

To retrieve details of a specific session key, use the following endpoint:

API Endpoint

Endpoint:

GET .../keys/{sessionKeyId}

Example:

{
    "type": "getKeyResponse",
    "clientRequestId": "testuuid",
    "key": {
        "keyType": "PAN",
        "sessionKeyLabel": "DEK_XX_XXYY",
        "sessionKeyId": "99",
        "sessionKeyCheckValue": "5AB19C",
        "version": "2.0"
    }
}

Retrieve All Session Keys

To retrieve all session keys associated with a specific sessionKeyLabel, use the following endpoint:

sessionKeyid with the highest version is the active key to be used for transactions.

API Endpoint

Endpoint:

GET .../key-mgmt/session-keys/keys/sessionKeyLabel={sessionKeyLabel}

Example:

{
    "type": "getKeysResponse",
    "clientRequestId": "TestKeyMgmt",
    "apiTraceId": "aGHOa5LKbwclIS3C4oh6pQAAATo",
    "keys": [
        {
            "keyType": "PAN",
            "sessionKeyLabel": "DEK_XX_XXYY",
            "sessionKeyId": "25",
            "sessionKeyCheckValue": "0DDC0A",
            "version": "3.0"
        },
        {
            "keyType": "PAN",
            "sessionKeyLabel": "DEK_XX_XXYY",
            "sessionKeyId": "26",
            "sessionKeyCheckValue": "2990D4",
            "version": "1.0"
        },
        {
            "keyType": "PAN",
            "sessionKeyLabel": "DEK_XX_XXYY",
            "sessionKeyId": "27",
            "sessionKeyCheckValue": "E3AFC6",
            "version": "2.0"
        }
    ]
}

Transaction Processing

The usage of master session keys in the various submission components is described here:

SOAP API: link