Transactions initiated from POS device

Request types

For transactions initiated from a physical device (terminal) the following request types need to be used:

• PaymentTerminalSaleTransaction
• PaymentTerminalCreditTransaction,
• PaymentTerminalPreAuthTransaction

For secondary transactions such as linked refunds and reversals the standard primary request types have to be used.

Relevant elements

Transactions initiated from a physical device must contain additional data elements:

terminalRequestData

device

capabilities

pin

In case cardholder has authenticated himself via PIN and PIN should be checked by issuer, the following elements need to be sent.

key

Key used for SRED and PIN data.

paymentCard (ref as PaymentCardWithTrackData)

This object encapsulates PaymentCard data and contanis track1, track2 and track3 data.

ReversalReason

In case of a technical reversal (or auto void) terminal needs to include the reason for the reversal.
This reason can be sent in secondary transactions with request type 'VoidTransaction' and will get forwarded to the authorization system.

Encryption of card data

For initial testing card data can be sent in clear format. But in general our gateway expects the card data and related elements such as track data or card expiry date to be encrypted.

In this context Fiserv will share one or more base derivation key(s) (BDK) and the respective key serial numbers (KSN) that can be used to derive the Initial PIN Encryption Key(s) (IPEK). These will be needed to derive a unique key per transaction (=DUKPT).

The data encapsulated under paymentCard needs to be encrypted und put under the paymentCardProtectedelment in the payload:

Example

"paymentMethod": {
	"paymentCard": {
		"number": "4935460000000008",
		"expiryDate": {
			"month": "12",
			"year": "24"
		},
		"securityCode": "123"
	} 
},

"encryptedData": "x8/+EUJ+ZhzKDxDnakkdfOuVDxy8RpveqZNOcfYf/s0xEDLCpYwp8X0Yil034PJLRHV8LSVR2TOO50VK90Y3GjvT1nv9e6GqTBqxYiLg02FyD5sie4fZ0r3FTVlF7Gee",
 	"key": {
		"derivationAlgo": "DUKPT2009",
		"version": "20160913",
		"encryptionAlgo": "AES128CBC",
		"index": "EAEQEREBA4AADw==",
		"name": "TotalTestKey"
		}
	}
},

MAC'ing

As an additional security mechanism can be applied to authenticate the origin and nature of a message. To make use of this feature one additional header needs to be sent.

Format for the message authentication value (MAC) of the complete payload follows this pattern:

<MAC>;<derivation algo>;<mac algo>;<key index>[;<key name>][;<key version>].

Derivation Algo: This refers to the algorithm used for key derivation. The options are 'DUKPT2009'
which represents the Derived Unique Key Per Transaction (DUKPT) algorithm, as defined by
ANSI X9.24-2009 Annex A, and 'AESDUKPT128ECB', which signifies the AES DUKPT ECB algorithm with a
key length of 128 bits, as defined in ANSI X9.24-3-2017 Annex.

Mac Algo: This points to the algorithm used for Message Authentication Code (MAC).
There are two options:

• 'RetailSHA256MAC' indicates the Retail-CBC-MAC using SHA-256 (Secure Hash standard)
  and an ASN.1 Object Identifier: id-retail-cbc-mac-sha-256.
• SHA256CMACwithAES128' represents the CMAC (Cipher-based Message Authentication Code) as defined by NIST 800-38B-May 2005. This option employs the Advanced Encryption Standard block cipher with a 128-bit
  cryptographic key, as approved by FIPS 197 - November 6, 2001. The CMAC algorithm is computed on
  the SHA-256 digest of the message.

The rest of the parameters include the 'key index', 'key name' (optional), and 'key version' (optional),
which are not specified here but contribute to the full formatting of the header parameter.

Response handling

For transactions initiated from a terminal the gateway sends the standardized responses.

In case of successful transaction (HTTP code 200) the response may include EMV data that was included by the issuer in the response.