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:


posEntryModeActual method used to enter the cardholder account number and card expiration date.Mandatory
offlineVerificationMethodThe Offline verification Method indicates what method was successfully performed on the terminal to assess the authenticity of the cardholder at POS device. Mandatory
cardholderPresentIndicatorIndicates whether the cardholder is physically present or not present during the transaction.
Default value: true
cardPresentIndicatorSpecifies if the actual payment card is present at the time of the transaction. This is typically used to differentiate between card-present and card-not-present transactions.
Default value: true
singleTapPinPerformedIndicates if single Tap Pin was performed after scheme response.
Default value false
offlineIndicatorSpecifies if the transaction was processed offline. Useful for situations where network connectivity is intermittent or unavailable.
Default value
onlineReasonThe 'onlineReason' field within the 'terminalRequestData' object specifies the reason why a card-present transaction is being processed online. The values of this field assist the processing system in understanding why the transaction is not occurring offline (i.e., directly at the terminal), enabling more accurate transaction processing and risk assessment.Optional
attendanceContextSpecifies the attendance condition during the transaction - ATTENDED if the transaction was supervised by a staff member,
Default value: ATTENDED
emvDataElectronic Verification Method data. This field is mandatory if 'posEntryMode' is either 'contactless' or 'contact'. Required EMV tags can vary per scheme.
Format: Base64 encode string.
approvalCodeIf terminal has approved the transaction in offline mode, then 6-digit approval code (also known as authorization code) must be sent by the request.Conditional


terminalProviderThe vendor that provided the terminal to merchant.Mandatory
serialNumberThe unique identifier assigned by the manufacturer to the POS device or terminal.Mandatory
softwareProviderThe entity that provides the software running on the POS device or terminal.Optional
softwareVersionThe version number of the software installed on the POS device or terminal.Optional
capabilitiessee below-
modelThe specific model or version of the POS device or terminal.Mandatory


cardholderVerificationCapabilitiesSpecifies the different capabilities the point-of-sale (POS) device or terminal has for verifying a cardholder's authenticity. These capabilities includeMandatory
cardReadingCapabilitiesIndicates the various methods by which the device can read card informationMandatory
terminalTypeIndicates the type of the terminal based on its functionalities and usageOptional
pinCapabilityDescribes the capability of the device to accept PIN entry for transactionsMandatory
featuresAdditional features that are available on the used POS Device.
More values to be added in the future.


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

valuevalue of the Personal Iientification number of a card known by the cardholder.Conditional
formatCodeFormat code of the used PIN, present if online PIN was used. Our gateway supports AES and TDES.Conditional
keysee key-


Key used for SRED and PIN data.

indexIn case of DUKPT, this field contains the KSN. There might be other key derivation algorithms not requiring an index.Conditional
nameName of the used keyConditional
versionVersion of the used keyConditional
derivationAlgoRepresents the algorithm used for key derivation. Possible values include 'DUKPT2009', which
stands for the Derived Unique Key Per Transaction (DUKPT) algorithm as specified in ANSI X9.24-2009 Annex A, and 'AESDUKPT128ECB', representing the AES DUKPT ECB algorithm with a key length of 128 bits as defined in ANSI X9.24-3-2017 Annex.
encryptionAlgoApplied encryption algorithm.Conditional

paymentCard (ref as PaymentCardWithTrackData)

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

numberPayment card number. Can also be an IBAN for Sepa Direct Debit transactions.Mandatory
expiryDateExpiry date of the used card printed on the card.Optional
securityCodeCard verification value/number.Optional
brandBrand of the useed card. Can be sent in case of dual branded card to determine the chosen brandOptional
bicBank identifier code (BIC) for Sepa Direct Debit.Optional
bankCodeBank code for Sepa Direct Debit.Optional
cardFunctionUsed to send the type of card such as CREDIT, DEBIT or PREPAIDOptional
cardholderNameName of the cardholder. Note - Only supported with request payload.Optional
bin6 or 8 digit Bank Identification Number of the used card (depending of the length of the card)Optional
last4The last 4 numbers of a payment card.Optional
One of:
Contains the track of data encoded on the magnetic strip of the card.Optional


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.

reversalReasonReason set by the terminal to cancel the referenced transaction.Conditional

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:

encryptedDataThis field holds the encrypted information from the card, such as track1/2/3, card number, expiry date, card code, and/or the name of the cardholder. The data is encrypted and then transformed into a Base64-encoded string. Specifically, the plaintext card data is converted into a UTF-8 JSON block, padded according to the Padded80 standard, and then encrypted. The resultant encrypted data is encoded using Base64. The formula for this transformation is base64(encrypt(Padded80(UTF-8(json-block.plainCardData)))).Mandatory (for PRODUCTION)
keySee keyMandatory (for PRODUCTION)


Before encyrption
"paymentMethod": {
	"paymentCard": {
		"number": "4935460000000008",
		"expiryDate": {
			"month": "12",
			"year": "24"
		"securityCode": "123"
After encryption
"encryptedData": "x8/+EUJ+ZhzKDxDnakkdfOuVDxy8RpveqZNOcfYf/s0xEDLCpYwp8X0Yil034PJLRHV8LSVR2TOO50VK90Y3GjvT1nv9e6GqTBqxYiLg02FyD5sie4fZ0r3FTVlF7Gee",
 	"key": {
		"derivationAlgo": "DUKPT2009",
		"version": "20160913",
		"encryptionAlgo": "AES128CBC",
		"index": "EAEQEREBA4AADw==",
		"name": "TotalTestKey"


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.

emvDataIt includes the EMV data from the issuer response and it is Base64 encoded.
Tags that will be mapped to the response (if present):
8A, issuerAuthorizationResponseCode8A
91, issuerAuthenticationData91
71, issuerScriptTemplate171
72, issuerScriptTemplate272

Want a quick overview?