eSocket.POS

eSocket.POS Developer Guide

Postilion ®
ACI Worldwide, Inc
2022-10-14
Version: v3.0.00.814546-r4.3


Introduction

Purpose of this document

The eSocket.POS Developer Guide serves as the primary technical reference document for developers using the eSocket.POS application programming interface (API) or the XML interface.

Intended audience

This document is intended for application developers involved in the development of POS applications using the eSocket.POS API or XML interface.

Additional information on eSocket.POS implementation, configuration, and operation can be found in the eSocket.POS User Guide .

Organization of this document

This document is organized into sections as follows:

  • Introduction

  • Interface specification

  • Java API

  • XML interface

  • Implementing/extending eSocket.POS components

  • Diagnostic tools

The following resources provide information related to the subjects discussed in this document.

  • eSocket.POS User Guide

The following international standards publications may also be useful.

  • ISO 3166 (1988): Codes for the Representation of Names of Countries

  • ISO 4217 (1990): Codes for the Representation of Names of Currencies and Funds

  • ISO 7813 (1995): Identification cards – Financial transaction cards

  • ISO 8583 (1987): Financial transaction card originated messages – Interchange message specifications

  • ISO/IEC 7816-5 (1994): Identification cards – Integrated circuit(s) cards with contacts – Part 5: Numbering system and registration procedure for application identifiers

Contacts

Please contact your primary support provider for further information or feedback.

Overview - eSocket.POS

eSocket.POS provides an application programming interface (API) and an XML message interface. These help enable rapid application development to provide EFT functionality to a Point-of-Sale (POS) system.

eSocket.POS is one of the many ways consumer transactions can be introduced into a Postilion system. Typically, this provides a multi-lane retailer with a way of interfacing their POS application with an upstream Postilion system.

Postilion is a comprehensive electronic commerce and funds transfer system. It is designed to deliver consumer transactions at every level of an EFT network. The Postilion family of products provides for custom-made electronic commerce solutions over a wide range of environments.

A more detailed introduction to the eSocket.POS application can be found in the eSocket.POS User Guide .

Protecting sensitive cardholder information

The theft of cardholder data is a major concern for all participants in the payments industry. The Payment Card Industry Security Standards Council (PCI SSC) has developed a set of requirements known as the Payment Card Industry Software Security Framework(PCI SSF).

As part of the requirements, the PCI SSF states that the sensitive cardholder data must be rendered unreadable anywhere that it is stored. This includes data on portable media, backup media, in logs, and data received from or stored by wireless networks. It is the responsibility of the POS developer to follow the standards defined by the PCI SSF to help protect sensitive card holder. For example, when it is necessary to present a PAN for purposes such as tracing, the PAN must be masked.

Additionally, the PCI SSC has defined a set of best practices called the Secure Sofware Standard (S3). This standard is aimed at assisting software vendors to create secure payment applications.

For more information, refer to the PCI web site: https://www.pcisecuritystandards.org/ .

1. Interface specification

1.1. Interface specification - Overview

This section defines the eSocket.POS interface as follows:

  • The different transactions are explained, together with instructions on how their properties should be set.

  • The different administrative methods or messages are described.

  • Descriptions of all the properties for the different transactions are detailed.

  • Events and Callback are described in general terms.

  • An overview of gift card transactions is provided.

  • The mapping between the eSocket.POS interface and the underlying ISO 8583 transaction is described.

Refer to the relevant sections for further information on the two ways in which the eSocket.POS interface can be implemented:

  • the Java API

  • the XML interface

1.2. Interface Specification - Transactions

1.2.1. EspTransaction

Transactions are performed using an EspTransaction object in the API, or an Esp:Transaction element in the XML interface. The properties should be set according to the rules set out in the following table.

(Properties that are sub-elements with their own properties are shown in bold text, while properties that are not elements appear in a normal font. See Object and Property Conditions for an explanation of the Cond and Rsp columns)

Property Cond Rsp Description

TerminalId

M

A

TransactionId

M

A

Type

M

A

MessageType

O

C

Can be set to indicate AUTH, REFERRAL, ADMIN_REQUEST or CONFIRM message type in requests. Value in response is set based on the request value.

Note: This property may only be set to ADMIN_REQUEST if the Type property is set to ADMIN.

ForceOnline

O

-

Reversal

C

T

Must be set to true for a reversal. The default (if this property is not set) is false .

Reversal Type

O

C

Defaults to ADVICE (offline).

DateTime

O

A

LocalDate

O

A

LocalTime

O

A

ExtendedTransactionType

O

H

This property might not be set if the type property is set to CARD_ACTIVATE, CARD_DEACTIVATE, or LOAD.

This property might not be set to '3100' - card activate or '3101' - card deactivate, if the message type is set to ADMIN_REQUEST.

This property might be set to '2111' - register device or '2112' - advance encryption key, if the message type is set to ADMIN_REQUEST.

This property must be set to '7116' for the credit admin payment on account with cash transactions.

This property must be set to '7117' for the credit admin payment on account with check transactions.

This property must be set to '1000' for the credit admin express application transaction.

AmountTransactionFee

O

H

CardVerificationResult

O

H

BusinessDate

O

H

RetrievalRefNr

O

C

This property can be used to identify the sequence of transactions to which this transaction is chained. This is useful in the case where the sequence identifier is common between the transactions or has a format which is not compatible with Transaction Id 's n6 format.

ReceivingInstIdCode

O

C

PosOperatorId

O

-

CardNumber

CG

G

If eSocket.POS does not read the card, either the Track2 or the CardNumber and ExpiryDate properties must be set. If eSocket.POS is configured to mask sensitive data, it will send the first 6 digits and the last 4 digits of this field in the clear and will mask the middle remainder of the field. For a message type of "CONFIRM": if the PAN component is configured to encrypt the PAN, this field won’t be set if eSocket.POS is restarted. For advice responses to the POS if eSocket.POS is configured with point-to-point encryption, this field won’t be set in the response.

ExpiryDate

CG

A

If eSocket.POS does not read the card, either the Track2 or the CardNumber and ExpiryDate properties must be set. For advice responses to the POS if eSocket.POS is configured with point-to-point encryption, this field won’t be set in the response.

ExtendedAuthorizationNumber

C

C

Should be sent in a referral when an authorization number is provided, for instance after calling an authorization center. Will be present in a response if set by the authorizer of the transaction and the value is longer than the standard field (AuthorizationNumber) and up to 8 characters in length.

StartDate

O

G

Will be returned if the EffectiveDate component has been configured in the response pipeline in eSocket.POS and the card configuration indicates that either effective (start) date validation is required or that an effective date is available. Note that returning the effective date is a UK requirement.

CardSequenceNumber

O

T

Cvv2

O

-

Track1

O

TCG

If the card is configured to mask sensitive data, this field won’t be set in the response. If the Message Type is "CONFIRM" and eSocket.POS has been restarted, this field won’t be set in the response, even if it is configured not to mask this field.

Track2

CG

TCG

If eSocket.POS does not read the card, either the Track2 or the CardNumber and ExpiryDate properties must be set. If eSocket.POS is configured to mask sensitive data, it will send the first 6 digits and the last 4 digits of the PAN in Track2 in the clear and will mask the middle remainder of the PAN as well as the service restriction code and discretionary data in the response. If the Message Type is "CONFIRM" and eSocket.POS has been restarted, this field won’t be set in the response, even if it is configured not to mask this field.

Track3

O

CG

In general not returned, unless eSocket.POS declines the transaction. If eSocket.POS is configured to mask sensitive data, this field won’t be set in the response.

PanEntryMode

O

A

If not set, this value will be set based on the presence or absence of Track2 .

PosCondition

O

A

If not set, the default value of '00' - Normal Presentment will be assumed.

TransactionAmount

G

A

Required unless eSocket.POS inserts the amount. On a transaction with an accepted DCC offer, this will be in the source/local currency.

CashbackAmount

CG

T

Required for a transaction involving cashback, unless the Cashback component has been configured to insert the cashback amount.

GratuityAmount

OG

H

Required for a transaction involving gratuity, unless the Gratuity component has been configured.

CurrencyCode

O

A

Mandatory for some configurations where the PAN component is placed before the Amount component; the CurrencyCode might be required to allow a fallback transaction. On a transaction with an accepted DCC offer, this will be the source/local currency code.

ExtendedPaymentPeriod

CG

T

Required for a transaction involving an extended payment period, unless the Extended Payment component will insert the extended payment period.

Account

G

A

Required if eSocket.POS is not configured with an Account component. Optional otherwise.

PinData

O

-

Required if PIN entry and encryption is performed by the POS.

PinKeySequenceNr

C

-

Required if PinData is present.

FinalAmount

O

T

CardholderInformation

-

H

PrivateData

O

G

ResponseCode

O

A

ActionCode

-

A

MessageReasonCode

O

A

AuthorizationNumber

C

C

Should be sent in a referral when an authorization number is provided, for instance after calling an authorization center. Will be present in a response if set by the authorizer of the transaction.

AuthorizingAgent

-

C

Will be present if the authorizer of the transaction was not the card issuer.

AuthorizationProfile

-

T

AuthorizationToken

C

C

Should be sent when a token-based authentication is used by the upstream entity.

CardholderAddress

O

T

Will be ignored unless PostalCode property is also set.

PostalCode

O

T

AddressVerificationResult

-

H

CtlsPinBypass

O

C

Should be sent when the PIN was bypassed for the contactless transaction.

ServiceRestrictionCode

-

CG

Will be returned if Track 2 Data is available. Won’t be set in the response if eSocket.POS is configured to mask sensitive data.

CardProductName

-

G

Will be returned if this card product is configured in eSocket.POS.

CardholderName

-

G

Will be returned if set up by a response pipeline component in eSocket.POS.

MerchantId

-

G

Will be returned if set up by a response pipeline component in eSocket.POS.

ReferralTelephone

-

C

Will be provided in a referral authorization response if a referral telephone number is available for this card.

SignatureData

O

G

May be provided in the response if set up by a pipeline component.

SignatureFormat

O

G

May be provided in the response if set up by a pipeline component.

SignatureRequired

-

G

May be provided in the response if set up by a pipeline component.

RPS

-

G

Will be present if the RPS component is configured and transaction is Rapid Payment Service.

FallbackType

-

G

Will be present if the FallbackIndicator component is configured. Or if it was received in the request.

FallbackReason

-

G

Will be present if provided by the FallbackIndicator component. Or if it was received in the xml request.

EmvAmount

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag. EMV Tag ID: 9F02 Note: In the request, EmvAmount and EmvAmountAuthorized are the same.

EmvAmountOther

O

C

Will be provided in the response if available when an EMV card was used and a cashback amount was requested. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F03

EmvAmountAuthorized

O

C

Will be provided in the response if available when an EMV card was used and a cashback amount was requested. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F02. Note: In the response, if this field does not exist, it will be set to EmvAmount.

EmvApplicationIdentifier

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 4F

EmvApplicationInterchangeProfile

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 82

EmvApplicationLabel

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 50

EmvApplicationPreferredName

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag This field will only be supplied in the xml interface if all characters can be represented as ASCII. EMV Tag ID: 9F12 Note: This field has been deprecated - please use either EmvApplicationPreferredNameRaw or EmvApplicationPreferredNameInternational.

EmvApplicationPreferredNameRaw

-

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F12

EmvApplicationPreferredNameInternational

-

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag. This field will only be provided if the Java Virtual Machine (JVM) in which eSocket.POS is running supports conversion from ISO/IEC 8859 using the code page specified by the EmvIssuerCodeTableIndexEmvIssuerCodeTableIndex. EMV Tag ID: 9F12

EmvApplicationTransactionCounter

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F36

EmvApplicationUsageControl

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F07

EmvApplicationVersionNumber

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F08

EmvAuthorizationResponseCode

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 8A

EMVCardSequenceNumber

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 5F34

EmvCryptogram

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F26

EmvCryptogramInformationData

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F27

EmvCvmList

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 8E

EmvCvmResults

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F34

EmvInterfaceDeviceSerialNumber

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F1E

EmvIssuerActionCodeDefault

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F0D

EmvIssuerActionCodeDenial

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F0E

EmvIssuerActionCodeOnline

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F0F

EmvIssuerApplicationData

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F10

EmvIssuerCodeTableIndex

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F11

EmvIssuerScriptResults

O

C

Will be provided in the response if available when an EMV card was used.

EmvTerminalActionCodeDefault

-

C

Will be provided in the response if available when an EMV card was used.

EmvTerminalActionCodeDenial

-

C

Will be provided in the response if available when an EMV card was used.

EmvTerminalActionCodeOnline

-

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag

EmvTerminalApplicationVersionNumber

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F09

EmvTerminalCapabilities

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F33

EmvTerminalCountryCode

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F1A

EmvTerminalTransactionQualifiers

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F66

EmvTerminalType

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F35

EmvTerminalVerificationResult

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 95

EmvTransactionCategoryCode

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F53

EmvTransactionCurrencyCode

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 5F2A

EmvTransactionDate

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9A

EmvTransactionSequenceCounter

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F41

EmvTransactionStatusInformation

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9B

EmvTransactionType

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9C

EmvUnpredictableNumber

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F37

EmvFormFactorIndicator

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F6E

EmvCustomerExclusiveData

O

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F7C

EmvAdditionalTerminalCapabilities

-

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F40

EmvTransactionTime

-

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 9F21

EmvApplicationPriorityIndicator

-

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 87

EmvIssuerCountryCode

-

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 5F28

EmvApplicationExpiryDate

-

C

Will be provided in the response if available when an EMV card was used. Or if it was received in the Esp:Transaction request or as part of the TlvIccDataExtended structured data tag EMV Tag ID: 5F24

EmvIssuerAuthenticationData

-

C

Will be provided in the response if it was returned by the upstream entity after online issuer authentication. EMV Tag ID: 91

EmvIssuerScriptTemplate1

-

C

Will be provided in the response if it was returned by the upstream entity after online issuer authentication. EMV Tag ID: 71

EmvIssuerScriptTemplate2

-

C

Will be provided in the response if it was returned by the upstream entity after online issuer authentication. EMV Tag ID: 72

StructuredData

O

HG

- Name

M

A

- Value

M

A

- Flags

O

G

- - DoNotPersist

O

G

PosStructuredData

O

HG

- Name

M

A

- Value

M

A

PurchasingCardData

O

G

May be set in order to send level 2 and 3 details for a transaction involving a purchasing card. Within this element, all attributes are optional.

NOTE: At this time only the PurchasingCardData.InvoiceNumber field is returned in the response.

Balance

-

H

- AccountType

-

H

- AmountType

-

H

- CurrencyCode

-

H

- Sign

-

H

- Amount

-

H

- SequenceNumber

-

H

- DateTime

O

H

- TerminalId

-

H

- TransactionType

-

H

- To Account type

-

H

- Account Id 1

-

H

- Account Id 2

-

H

- AuthorizationId

-

H

- Surcharge

-

H

- PreviousBalance

O

C

PassThruPanReference

O

-

Aimed at P2PE scenarios where the device/PED implements a P2PE scheme supported by ACI, yet eSocket.POS does not drive the device/PED (e.g. fuel forecourts).

- Scheme

M

-

This subfield is only mandatory if the PanReference field is present.

- Ksn

O

-

- Data

O

-

- SensitiveDataBlock

O

-

- WhitelistFileName

O

-

- MaxReliableBinLength

O

-

- TlvMapping

O

-

ChainedTransactionId

O

C

Will be provided in the response if the chained transaction information could be retrieved.

Rank

M

-

Indicates which set of logical devices will be used.

SignatureStandAloneDynamicText

O

C

Stand alone dynamic text that will be displayed on the screens that host the check box prompts.

SignatureImagePassedInResponse

O

C

Indicates whether or not the image should be included in the transaction response.

SignatureImageFormat

O

C

The format of the image to be returned in the response, if requested in the SignatureImagePassedInResponse field.

SignatureScrollableText

O

C

This field will be used to populate the scrollable text area on the free text screens.

SignatureImageSequence

O

C

The sequence number to associate with the image. If more than one image is associated with a single transaction, this value will differentiate between them. Only to be set for a signature capture transaction.

SignatureOriginalFormat

O

C

The format of the image in the user interface request. Only to be set for a signature capture transaction.

SignatureImageCategory

O

C

The category of the image. Only to be set for a signature capture transaction.

SignatureImageEncrypted

O

C

Indicates whether the image in the user interface message request is encrypted. Only to be set for a signature capture transaction.

SignatureCheckbox1Text

O

C

Dynamic text label associated with the first check box on forms.

SignatureCheckbox2Text

O

C

Dynamic text label associated with the second check box on forms.

SignatureCheckbox3Text

O

C

Dynamic text label associated with the third check box on forms.

SignatureCheckbox1State

O

C

The state of the first check box after user input.

SignatureCheckbox2State

O

C

The state of the second check box after user input.

SignatureCheckbox3State

O

C

The state of the third check box after user input.

SignatureButtonValue

O

C

Indicates the button input collected from the user.

SignaturePromptName

O

C

The name of the prompt. Only to be set for a signature capture transaction.

EbtResponseText

O

C

The full response text as sent by the EBT provider.

EbtBeginningFoodStampAccountBalance

O

C

The beginning food stamp account balance.

EbtEndingFoodStampAccountBalance

O

C

The ending food stamp account balance.

EbtAvailableFoodStampAccountBalance

O

C

The available food stamp account balance.

EbtBeginningCashBenefitsAccountBalance

O

C

The beginning cash benefits account balance.

EbtEndingCashBenefitsAccountBalance

O

C

The ending cash benefits account balance.

EbtAvailableCashBenefitsAccountBalance

O

C

The available cash benefits account balance.

EbtCaseNumber

O

C

EBT case number.

EbtVoucherNumber

O

C

EBT voucher number.

RtsTotalHealthcareAmount

C

-

The total amount for the healthcare transaction . If extended transaction type is set to "7111 - Healthcare Benefit", then this field should be set.

RtsPrescriptionAmount

O

-

The amount for the prescription component of the healthcare transaction.

RtsOpticalAmount

O

-

The amount for the optical component of the healthcare transaction.

RtsDentalAmount

O

-

The amount for the dental component of the healthcare transaction.

RtsClinicAmount

O

-

The amount for the clinic component of the healthcare transaction.

LdFolioNr

O

T

Lodging (e.g. hotel, motel) transactions: The lodging facility’s internal invoice or billing identification reference number.

LdFacilityPhoneNr

O

T

Lodging (e.g. hotel, motel) transactions: The local phone number of the lodging facility at which the cardholder stayed.

LdDateArrival

O

T

Lodging (e.g. hotel, motel) transactions: The date on which the cardholder checked in at the lodging facility.

LdDateDeparture

O

T

Lodging (e.g. hotel, motel) transactions: The date on which the cardholder checked out of the lodging facility.

LdAmountRoomRate

O

T

Lodging (e.g. hotel, motel) transactions: The daily room charges, exclusive of taxes and fees.

LdAmountRoomTax

O

T

Lodging (e.g. hotel, motel) transactions: The daily room tax amount.

LdAmountPhoneCharges

O

T

Lodging (e.g. hotel, motel) transactions: The total amount of phone calls charged to the room.

LdAmountRestaurantAndRoomService

O

T

Lodging (e.g. hotel, motel) transactions: The total amount of restaurant and/or room service food charged to the room.

LdAmountBarAndMinibar

O

T

Lodging (e.g. hotel, motel) transactions: The total amount of bar and in-room "mini-bar" items charged to the room.

LdAmountLaundryAndDryCleaning

O

T

Lodging (e.g. hotel, motel) transactions: The total amount of laundry and dry cleaning items charged to the room.

LdAmountGiftShop

O

T

Lodging (e.g. hotel, motel) transactions: The total amount of gift shop and speciality shop items charged to the room.

LdAmountOtherServices

O

T

Lodging (e.g. hotel, motel) transactions: The total amount of miscellaneous items/services charged to the room, not specified elsewhere.

LdAmountOtherServicesIndicator

O

T

Lodging (e.g. hotel, motel) transactions: Indicates the type of charges provided in LdAmountOtherServices.

LdAmountBillingAdjustment

O

T

Lodging (e.g. hotel, motel) transactions: The amount of any additional charges incurred after the cardholder’s departure.

LdProgramCode

O

T

Lodging (e.g. hotel, motel) transactions: A code allocated by the acquirer that identifies special circumstances.

LdCustomerServicePhoneNr

O

T

Lodging (e.g. hotel, motel) transactions: The customer service number that the cardholder may call to resolve questions or disputes.

LdNumberInParty

O

T

Lodging (e.g. hotel, motel) transactions: The number of guests.

LdNameOfGuest

O

T

Lodging (e.g. hotel, motel) transactions: The name of the guest.

PosDataCode

O

A

AvailableOfflineSpendingAmount

-

C

The Visa Available Offline Spending Amount value, if available on the card.

APM

O

-

The Alternative Payment Method.

PaymentBrand

O

-

The Payment Brand.

QRCodeData

O

-

The QR code data in QR code transactions (e.g. a URL, identification number or transactional data string). This field takes precedence over the BarcodeData field in request messages.

QRCodeHostRef

O

-

An additional transaction reference received from the host system in QR code transaction response messages.

QRCodeImage

O

-

The QR code image encoded in Base64.

QRCodeTranId

O

-

The QR code transaction ID received from the host system. This field should be set in refund requests for consumer-presented QR code transactions, if required. It should also be sent in merchant-presented QR code transaction status requests.

QRCodeType

O

-

The QR code type in the QR code transactions.

BarcodeData

O

-

The barcode data. e.g. 0123456789. This field will be ignored in request messages if the QRCodeData field is set.

Quantity

O

-

Can be set to indicate the quantity of items purchased in consumer-presented QR code transaction requests.

TransactionName

O

-

Can be set to indicate the name of the Transaction in consumer-presented QR code transaction requests.

StoreId

O

-

Can be set to indicate the store ID in consumer-presented QR code transaction requests.

Memo

O

-

Can be set to indicate the memo in consumer-presented QR code transaction requests.

DccStatusCode

-

C

The dynamic currency conversion (DCC) status code.

DccProviderRoutingId

-

C

An identifier for the external entity that provided the currency conversion information which represents a DCC offer.

DccRate

-

C

The exchange rate used when performing currency conversion from the amount in the source currency to the amount in the target currency.

DccSrcCurrCode

-

C

Numeric code of the currency being converted from.

DccSrcCurrAlphaCode

-

C

Alphabetic code of the currency being converted from.

DccSrcCurrMinorUnits

-

C

The number of digits following the decimal separator.

DccTgtCurrCode

-

C

Numeric code of the currency being converted to.

DccTgtCurrAlphaCode

-

C

Alphabetic code of the currency being converted to.

DccTgtCurrMinorUnits

-

C

The number of digits following the decimal separator.

DccProvider

-

C

The currency conversion service provider.

DccRateSrc

-

C

The source of conversion data.

DccTimestamp

-

C

Time the conversion was performed in Coordinated Universal Time (UTC).

DccMargRate

-

C

Numeric value representing the foreign exchange markup rate as a fraction.

DccCommRate

-

C

Numeric value representing the foreign exchange commission rate as a fraction.

DccDccDiffOverECB

-

C

Numeric value representing the foreign exchange markup, it compare the DCC exchange rate to the European Central Bank rate as a fraction.

DccSrcAmt

-

C

Amount of the transaction in the currency being converted from.

DccTgtAmt

-

C

Amount of the transaction in the currency being converted to.

DccExpTimestamp

-

C

The offer expiration date and time in Coordinated Universal Time (UTC).

DccRcptTxt1

-

C

Additional disclaimer information required for printing on receipts.

DccRcptTxt2

-

C

Additional disclaimer information required for printing on receipts.

DccAcqId

-

C

The dynamic currency conversion specific acquirer identifier.

DccCardAcceptorId

-

C

The dynamic currency conversion specific card acceptor identifier.

DccTermId

-

C

The dynamic currency conversion specific terminal identifier.

NetworkLabel

-

H

The Credit or Debit network that processed the transaction.

PayeeNameAndAddress

O

H

Payee name and address contains identification and billing information for a payee.

AdditionalPayeeInformation

O

H

Contains additional payee name and address details.

AccountData

O

H

Contains account details needed for a credit application.

DisplayData

O

H

The status response from ADS based on the processor specification.

PrintData

O

H

The status response that contains information about the account.

MerchantOpcSelection

G

T

Indicates whether the merchant or cardholder OPC selection mode should be applied.

FinalAuthIndicator

O

T

Indicates whether the amount requested is a pre-authorization, normal authorization or the final amount.

EspCardInfo

G

G

Contains additional card details, as configured in eSocket.POS.

FleetData

G

-

Can be set to send details for a transaction involving a fleet card. Within this element, all attributes are optional.

FleetDataRsp

-

H

Set in response to send details to the pump from the acquirer for a transaction involving a fleet card. Within this element, all attributes are optional.

PosGeographicDataLatitude

O

H

An optional PosGeographicDataLatitude field can be attached to a transaction.

PosGeographicDataLongitude

O

H

An optional PosGeographicDataLongitude field can be attached to a transaction.

TerminalAddress

O

H

An optional TerminalAddress field can be attached to a transaction.

DoNotDisplay

O

-

Set to disable the welcome and transaction outcome displays on a device.

1.2.2. EspInquiry

Inquiries are performed using an EspInquiry object in the API, or an Esp:Inquiry element in the XML interface. The properties should be set according to the rules set out in the following table.

(Properties that are sub-elements with their own properties are shown in bold text, while properties that are not elements appear in a normal font. See Object and Property Conditions for an explanation of the Cond and Rsp columns)

Property Cond Rsp Description

TerminalId

M

A

TransactionId

M

A

Type

M

A

DateTime

O

A

LocalDate

O

A

LocalTime

O

A

ExtendedTransactionType

O

H

For an account inquiry for a credit admin status application transaction received from the POS, set this property to '7007'. For a customer linked account inquiry for a credit account lookup transaction received from the POS, set this property to '7001'.

AmountTransactionFee

O

H

AuthorizationNumber

C

C

Should be sent in a referral when an authorization number is provided, for instance after calling an authorization center. Will be present in a response if set by the authorizer of the transaction.

AuthorizationToken

C

C

Should be sent when a token-based authentication is used by the upstream entity.

CardholderAddress

O

T

Will be ignored unless PostalCode property is also set.

CtlsPinBypass

O

C

Should be sent when the PIN was bypassed for the contactless transaction.

PostalCode

O

T

CardVerificationResult

O

H

BusinessDate

O

H

RetrievalRefNr

O

C

ReceivingInstIdCode

O

C

PosOperatorId

O

-

CardNumber

CG

TG

If eSocket.POS does not read the card, either the Track2 or the CardNumber and ExpiryDate properties must be set. In a check verification or check guarantee transaction, the card number should be set to 19 zeros if no check/cheque card is to be used. If eSocket.POS is configured to mask sensitive data, eSocket.POS will send the first 6 digits and the last 4 digits of this field in the clear and will mask the middle remainder of the field.

ExpiryDate

CG

T

If eSocket.POS does not read the card, either the Track2 or the CardNumber and ExpiryDate properties must be set.

ExtendedAuthorizationNumber

C

C

Should be sent in a referral when an authorization number is provided, for instance after calling an authorization center. Will be present in a response if set by the authorizer of the transaction and the value is longer than the standard field (AuthorizationNumber) and up to 8 characters in length.

CardSequenceNumber

O

T

Cvv2

O

-

OriginalMessageType

O

-

Used for transaction inquiries to provide the MessageType of the original transaction that should be retrieved.

OriginalTransactionType

O

-

Used for transaction inquiries to provide the Type of the original transaction that should be retrieved.

EspTransaction

O

C

Will be returned in the response of a transaction inquiry with the transaction data if the transaction is found

Track1

O

CG

Will be returned if this inquiry type was CARD_READ and the data for this track is available. If the card is configured to mask sensitive data, this field won’t be set in the response.

Track2

CG

TG

If eSocket.POS does not read the card, either the Track2 or the CardNumber and ExpiryDate properties must be set. If eSocket.POS is configured to mask sensitive data, it will send the first 6 digits and the last 4 digits of the PAN in track2 in the clear and will mask the middle remainder of the PAN as well as the service restriction code and discretionary data in the response.

Track3

O

CG

Will be returned if this inquiry type was CARD_READ and the data for this track is available. If eSocket.POS is configured to mask sensitive data, this field won’t be set in the response.

PanEntryMode

O

A

May be set if the CardNumber is set. Should not be set otherwise. If not set, this value will be set by the PAN component based on the presence or absence of Track2 .

PosCondition

O

A

If not set, the default value of '00' - Normal Presentment will be assumed.

CurrencyCode

O

T

CardholderInformation

-

H

PrivateData

O

G

ResponseCode

O

A

ActionCode

-

A

MessageReasonCode

-

A

Account

O

A

Must be set if eSocket.POS is not configured with an Account component. Optional otherwise.

PinData

O

-

Required if PIN entry and encryption is performed by the POS

PinKeySequenceNr

C

-

Required if PIN data is present

TransactionAmount

C

T

May be required in check verification or check guarantee requests.

ServiceRestrictionCode

-

C

Will be returned if Track 2 Data is available.

CardProductName

-

G

Will be returned if this card product was configured in eSocket.POS.

CardholderName

-

G

Will be returned if set up by a response pipeline component in eSocket.POS.

MerchantId

-

G

Will be returned if set up by a response pipeline component in eSocket.POS.

ChequeNumber

O

G

This property is deprecated. Rather use an EspCheck object for a check verification or check guarantee transaction.

ChequeAccountNumber

O

G

This property is deprecated. Rather use an EspCheck object for a check verification or check guarantee transaction.

ChequeInstitutionCode

O

G

This property is deprecated. Rather use an EspCheck object for a check verification or check guarantee transaction.

Balance

-

C

Will be present in the response to a Balance Inquiry, an Available Funds Inquiry or else a Mini-statement Inquiry.

- AccountType

-

C

Will be present in the response to a Balance or Available Funds Inquiry. May be present in a Mini-statement Inquiry.

- AmountType

-

C

Will be present in the response to a Balance or Available Funds Inquiry.

- CurrencyCode

-

C

Will be present in the response to a Balance or Available Funds Inquiry. May be present in a Mini-statement Inquiry.

- Sign

-

C

Will be present in the response to a Balance or Available Funds Inquiry.

- Amount

-

C

Will be present in the response to a Balance or Available Funds Inquiry. May be present in a Mini-statement Inquiry.

- SequenceNumber

-

H

May be present in a Mini-statement Inquiry.

- DateTime

O

H

May be present in a Mini-statement Inquiry. Also used to filter transactions for a transaction inquiry

- TerminalId

-

H

May be present in a Mini-statement Inquiry.

- TransactionType

-

H

May be present in a Mini-statement Inquiry.

- To Account type

-

H

May be present in a Mini-statement Inquiry.

Account Id 1

-

H

May be present in a Mini-statement Inquiry.

- Account Id 2

-

H

May be present in a Mini-statement Inquiry.

- AuthorizationId

-

H

May be present in a Mini-statement Inquiry.

- Surcharge

-

H

May be present in a Mini-statement Inquiry.

PurchasingCardData

O

G

May be set in order to send level 2 and 3 details for a transaction involving a purchasing card. Within this element, all attributes are optional. Note: At this time only the PurchasingCardData.InvoiceNumber field is returned in the response.

StructuredData

O

HG

- Name

M

A

- Value

M

A

- Flags

O

G

- -DoNotPersist

O

G

PosStructuredData

O

HG

- Name

M

A

- Value

M

A

PassThruPanReference

O

-

Aimed at P2PE scenarios where the device/PED implements a P2PE scheme supported by ACI, yet eSocket.POS does not drive the device/PED (e.g. fuel forecourts).

- Scheme

M

-

This subfield is only mandatory if the PanReference field is present.

- Ksn

O

-

- Data

O

-

- SensitiveDataBlock

O

-

- WhitelistFileName

O

-

- MaxReliableBinLength

O

-

- TlvMapping

O

-

PassThruVolatileP2peData

O

-

Aimed at P2PE scenarios where the device/PED implements a P2PE scheme supported by ACI, yet eSocket.POS does not drive the device/PED (e.g. fuel forecourts).

- Scheme

M

-

This subfield is only mandatory if the PassThruVolatileP2peData field is present.

- Ksn

O

-

- Data

O

-

- SensitiveDataBlock

O

-

- WhitelistFileName

O

-

- MaxReliableBinLength

O

-

- TlvMapping

O

-

ChainedTransactionId

O

C

Will be provided in the response if the chained transaction information could be retrieved.

EmvAmount

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F02

EmvAmountOther

-

C

Will be provided in the response if available when an EMV card was used and a cashback amount was requested.

EMV Tag ID: 9F03

EmvApplicationIdentifier

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 4F

EmvApplicationInterchangeProfile

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 82

EmvApplicationLabel

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 50

EmvApplicationPreferredName

-

C

Will be provided in the response if available when an EMV card was used. This field will only be supplied in the xml interface if all characters can be represented as ASCII. Note: This field has been deprecated - please use either EmvApplicationPreferredNameRaw or EmvApplicationPreferredNameInternational.

EMV Tag ID: 9F12

EmvApplicationPreferredNameRaw

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F12

EmvApplicationPreferredNameInternational

-

C

Will be provided in the response if available when an EMV card was used. This field will only be provided if the Java Virtual Machine (JVM) in which eSocket.POS is running supports conversion from ISO/IEC 8859 using the code page specified by the EmvIssuerCodeTableIndex.

EMV Tag ID: 9F12

EmvApplicationTransactionCounter

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F36

EmvApplicationUsageControl

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F07

EmvApplicationVersionNumber

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F26

EmvAuthorizationResponseCode

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F27

EmvCryptogram

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 8E

EmvCryptogramInformationData

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F34

EmvCvmList

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F1E

EmvCvmResults

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F0D

EmvInterfaceDeviceSerialNumber

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F0E

EmvIssuerActionCodeDefault

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F0F

EmvIssuerActionCodeDenial

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F10

EmvIssuerActionCodeOnline

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F11

EmvIssuerApplicationData

-

C

Will be provided in the response if available when an EMV card was used.

EmvIssuerCodeTableIndex

-

C

Will be provided in the response if available when an EMV card was used.

EmvIssuerScriptResults

-

C

Will be provided in the response if available when an EMV card was used.

EmvTerminalActionCodeDefault

-

C

Will be provided in the response if available when an EMV card was used.

EmvTerminalActionCodeDenial

-

C

Will be provided in the response if available when an EMV card was used.

EmvTerminalActionCodeOnline

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F09

EmvTerminalApplicationVersionNumber

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F33

EmvTerminalCapabilities

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F1A

EmvTerminalCountryCode

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 9F35

EmvTerminalType

-

C

Will be provided in the response if available when an EMV card was used.

EMV Tag ID: 95

EmvTerminalVerificationResult

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F53

EmvTransactionCategoryCode

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 5F2A

EmvTransactionCurrencyCode

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9A

EmvTransactionDate

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F41

EmvTransactionSequenceCounter

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9B

EmvTransactionStatusInformation

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9C

EmvTransactionType

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F37

EmvUnpredictableNumber

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F6E

EmvFormFactorIndicator

O

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F7C

EmvCustomerExclusiveData

O

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F40

EmvAdditionalTerminalCapabilities

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F21

EmvTransactionTime

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 87

EmvApplicationPriorityIndicator

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 5F28

EmvIssuerCountryCode

-

C

Will be provided in the response if available when an EMV card was used. EMV Tag ID: 5F24

EmvApplicationExpiryDate

-

C

Will be provided in the response if available when an EMV card was used.

EbtResponseText

O

C

The full response text as sent by the EBT provider.

EbtBeginningFoodStampAccountBalance

O

C

The beginning food stamp account balance.

EbtEndingFoodStampAccountBalance

O

C

The ending food stamp account balance.

EbtAvailableFoodStampAccountBalance

O

C

The available food stamp account balance.

EbtBeginningCashBenefitsAccountBalance

O

C

The beginning Cash Benefits account balance.

EbtEndingCashBenefitsAccountBalance

O

C

The ending Cash Benefits account balance.

EbtAvailableCashBenefitsAccountBalance

O

C

The available Cash Benefits account balance.

EbtCaseNumber

O

C

EBT Case Number.

EbtVoucherNumber

O

C

EBT Voucher Number.

PosDataCode

O

A

AvailableOfflineSpendingAmount

-

C

The Visa Available Offline Spending Amount value, if available on the card.

PayeeNameAndAddress

O

H

The payee name and address object contains identification and billing information for the payee.

AdditionalPayeeInformation

O

H

Contains additional payee name and address details.

AccountData

O

H

Contains account details needed for a credit application.

DisplayData

O

H

The status response from ADS based on the processor specification.

PrintData

O

H

The status response containing information about the account.

EspCardInfo

G

G

Contains additional card details, as configured in eSocket.POS.

TerminalStatus

G

G

Contains information regarding the status of eSocket.POS that serves the terminal.

1.2.3. EspMerchandise

Merchandise transactions, including telephone prepay, are performed using an EspMerchandise object in the API, or an Esp:Merchandise __ element in the XML interface. The properties should be set according to the rules set out in the following table.

(Properties that are sub-elements with their own properties are indicated in bold text, while properties that are not elements appear in a normal font. Please refer to Object and Property Conditions for an explanation of the Cond and Rsp columns of this table.)

Property Cond Rsp Description

TerminalId

M

A

TransactionId

M

A

Type

M

A

DateTime

O

A

LocalDate

O

A

LocalTime

O

A

ExtendedTransactionType

O

H

AmountTransactionFee

O

H

AuthorizationNumber

C

C

Should be sent in a referral when an authorization number is provided, for instance after calling an authorization center. Will be present in a response if set by the authorizer of the transaction.

ExpiryDate

O

T

RetrievalRefNr

O

C

AuthorizationToken

C

C

Should be sent when a token-based authentication is used by the upstream entity.

ReceivingInstIdCode

O

C

NetworkId

-

A

ProductId

M

A

Required if the merchandise type is REQUEST or PROCURE.

ProductType

O

C

UserId

CG

H

For merchandise requests requiring the user to be identified, either the UserId or the Track2 property must be set, or these must be obtained by eSocket.POS.

Track2

CG

-

For merchandise requests requiring the user to be identified, either the UserId or the Track2 property must be set, or these must be obtained by eSocket.POS.

TransactionAmount

O

G

TenderAmount

O

-

TenderType

O

-

TenderSerialNumber

O

-

CardholderInformation

-

H

PrivateData

O

G

ResponseCode

-

A

ActionCode

-

A

MessageReasonCode

O

A

TranSequenceNumber

O

H

May be set in a request if the Type is CONFIRM or REVERSE. In this case it should match the value in the original REQUEST or PROCURE response.

HostResponseCode

-

H

ResponseMsg

-

H

ItemPin

-

H

ItemSerialNumber

-

H

ItemExpiryDate

-

H

ItemAmount

-

H

ItemTaxAmount

-

H

NetworkName

-

H

ProductName

-

H

ItemMessage

-

H

DescriptiveValue

-

H

IssuerName

-

H

IssuerId

-

H

IssuerRegistrationNr

-

H

IssuerTelephoneNr

-

H

ConsumerAddress

-

H

ConsumerId

-

H

ConsumerName

-

H

ItemBalance

-

H

- ProductCode

-

H

- ProductName

-

H

- ExpiryDate

-

H

- Quantity

-

H

- QuantityDescription

-

H

Token

-

H

- TokenDescription

-

H

- TokenValue

-

H

StructuredData

O

HG

- Name

M

A

- Value

M

A

- Flags

O

G

- -DoNotPersist

O

G

PosStructuredData

O

HG

- Name

M

A

- Value

M

A

ChainedTransactionId

O

C

Will be provided in the response if the chained transaction information could be retrieved.

1.2.4. EspCheck

Check/Cheque transactions are performed using an EspCheck object in the API, or an Esp:Check element in the XML interface. The properties should be set according to the rules set out in the following table.

(Properties that are sub-elements with their own properties are indicated in bold text, while properties that are not elements appear in a normal font. Please refer to Object and Property Conditions for an explanation of the Cond and Rsp columns of this table.)

Property Cond Rsp Description

TerminalId

M

A

TransactionId

M

A

Type

M

A

MessageType

O

C

Can be set to indicate AUTHADV, TRANREQ or CONFIRM message type in requests. Value in response is set based on the request value.

Reversal

C

T

Must be set to true for a reversal. The default (if this property is not set) is false .

DateTime

O

A

Reversal Type

O

C

Defaults to ADVICE (offline).

DateTime

O

A

LocalDate

O

A

LocalTime

O

A

ExtendedTransactionType

O

H

AmountTransactionFee

O

H

AuthorizationNumber

C

C

Should be sent in a referral when an authorization number is provided, for instance after calling an authorization center. Will be present in a response if set by the authorizer of the transaction.

AuthorizationToken

C

C

Should be sent when a token-based authentication is used by the upstream entity.

AuthorizationProfile

-

A

BusinessDate

O

H

RetrievalRefNr

O

C

PosOperatorId

O

-

CardNumber

C

TC

Should be set if a check ID card is used. Will be present in the response if this property was present in the request or eSocket.POS populated the value while processing the request. If eSocket.POS is configured to mask sensitive data, it will send the first 6 digits and the last 4 digits of the CardNumber

ExpiryDate

C

TC

Should be set if a check ID card is used. Will be present in the response if this property was present in the request or eSocket.POS populated the value while processing the request.

CardSequenceNumber

O

TCG

May be set if the CardNumber or Track2 is set. Should not be set otherwise.

Track2

C

TCG

Must be set if CardNumber and ExpiryDate are not set and a check ID card is used. Optional otherwise. Will be present in the response if this property was present in the request or eSocket.POS populated the value while processing the request. If eSocket.POS is configured to mask sensitive data, it will send the first 6 digits and the last 4 digits of the PAN in track2 in the clear and will mask the middle remainder of the PAN as well as the service restriction code and discretionary data in the response.

PanEntryMode

O

A

May be set if the CardNumber is set. Should not be set otherwise. If not set, this value will be set by the PAN component based on the presence or absence of track 2 data .

CurrencyCode

O

T

PrivateData

O

G

ResponseCode

O

A

ActionCode

-

A

MessageReasonCode

O

A

TransactionAmount

M

A

ServiceRestrictionCode

-

C

Will be returned if Track 2 Data is available.

MerchantId

-

G

Will be returned if set up by a response pipeline component in eSocket.POS.

CheckType

O

CheckIdCard

O

H

Should be set to true if this is a Check ID Card transaction. Default is false .

IdCrossChecked

O

H

Should be set to true if the ID was validated against a second ID. Default is false .

SupervisorId

O

H

CheckNr

O

H

TransitNr

O

H

AccountNr

O

H

UnformattedMICR

O

H

DriversLicenseNr

C

H

Must be set if a driver’s license is used as the form of identification.

DriversLicenseStateCode

O

H

GenericIdNr

C

H

Must be set if a generic ID is used as the form of identification.

GenericIdType

O

H

StructuredData

O

HG

- Name

M

A

- Value

M

A

- Flags

O

G

- -DoNotPersist

O

G

PosStructuredData

O

HG

- Name

M

A

- Value

M

A

PurchasingCardData

O

-

May be set in order to send level 2 and 3 details for a transaction involving a purchasing card. Within this element, all attributes are optional.

ChainedTransactionId

O

C

Will be provided in the response if the chained transaction information could be retrieved.

MICRKeyedOrScanned

O

H

DriversLicenseDateOfBirth

O

H

DriversLicenseKeyedOrScanned

O

H

DriversLicenseExpirationDate

O

H

MICRLineFormatCode

O

H

CustomerName

O

H

CustomerPhoneNumber

O

H

CustomerAddress

O

H

CustomerCity

O

H

CustomerState

O

H

CustomerZip

O

H

CheckIssuedDate

O

H

TruncationTransactionID

O

H

MICRSequenceNr

O

H

TruncationIndicator

O

H

ServiceCharge

O

H

DenialNr

O

H

SettlementCode

O

H

ProprietaryResponseInfo

O

H

1.2.5. EspReconciliation

Batch Cutovers are performed using an EspReconciliation object in the API, or an Esp:Reconciliation element in the XML interface. The properties should be set according to the rules set out in the following table.

(Properties that are sub-elements with their own properties are indicated in bold text, while properties that are not elements appear in a normal font. Please refer to Object and Property Conditions for an explanation of the Cond and Rsp columns of this table.)

Property Cond Rsp Description

TerminalId

M

A

TransactionId

M

A

SettlementCurrencyCode

O

C

PrivateData

O

G

DateTime

O

A

LocalDate

O

A

LocalTime

O

A

PosStructuredData

O

HG

- Name

M

A

- Value

M

A

ResponseCode

-

A

ActionCode

-

A

MessageReasonCode

-

A

9670 - ' Batch Totals Not Available ', if there was any condition that the totals was not retrieved from Postilion Realtime

NumberOfCredits

O

C

In the request, contains the Number of Credit transactions processed by the terminal in the batch, if available.

In the response, contains the Number of Credit transactions processed by Postilion Realtime for this terminal, if available.

NumberOfCreditsReversal

O

C

In the request, contains the Number of Reversal Credit transactions processed by the terminal in the batch, if available.

In the response, contains the Number of Reversal Credit transactions processed by Postilion Realtime for this terminal, if available.

NumberOfDebits

O

C

In the request, contains the Number of Debit transactions processed by the terminal in the batch, if available.

In the response, contains the Number of Debit transactions processed by Postilion Realtime for this terminal, if available.

NumberOfDebitsReversal

O

C

In the request, contains the Number of Debit Reversal transactions processed by the terminal in the batch, if available.

In the response, contains the Number of Debit Reversal transactions processed by Postilion Realtime for this terminal, if available.

NumberOfInquiries

O

C

In the request, contains the Number of Inquiry transactions processed by the terminal in the batch, if available.

In the response, contains the Number of Inquiry transactions processed by Postilion Realtime for this terminal, if available.

NumberOfAuthorizations

O

C

In the request, contains the Number of Authorization transactions processed by the terminal in the batch, if available.

In the response, contains the Number of Authorization transactions processed by Postilion Realtime for this terminal, if available.

AuthorizationToken

C

C

Should be sent when a token-based authentication is used by the upstream entity.

CreditsAmount

O

C

In the request, contains the total amount of all Credit transactions processed by the terminal in the batch, if available.

In the response, contains the total amount of all Credit transactions processed by Postilion Realtime for this terminal, if available.

CreditsReversalAmount

O

C

In the request, contains the total amount of all Credit Reversal transactions processed by the terminal in the batch, if available.

In the response, contains the total amount of all Credit Reversal transactions processed by Postilion Realtime for this terminal, if available.

DebitsAmount

O

C

In the request, contains the total amount of all Debit transactions processed by the terminal in the batch, if available.

In the response, contains the total amount of all Debit transactions processed by Postilion Realtime for this terminal, if available.

DebitsReversalAmount

O

C

In the request, contains the total amount of all Debit Reversal transactions processed by the terminal in the batch, if available.

In the response, contains the total amount of all Debit Reversal transactions processed by Postilion Realtime for this terminal, if available.

NetSettlementAmount

O

C

In the request, contains the net of all gross debit and gross credit amounts for transactions processed by the terminal in the batch, if available.

In the response, contains the net of all gross debit and gross credit amounts for transactions processed by Postilion Realtime for this terminal, if available.

Amount

M

A

Sign

M

A

StructuredData

O

HG

- Name

M

A

- Value

M

A

- Flags

O

G

- -DoNotPersist

O

G

1.2.6. EspNetwork

Network Management is performed using an EspNetwork object in the API, or an Esp:Network element in the XML interface. The properties should be set according to the rules set out in the following table.

(Properties that are sub-elements with their own properties are indicated in bold text, while properties that are not elements appear in a normal font. Please refer to Object and Property Conditions for an explanation of the Cond and Rsp columns of this table.)

Property Cond Rsp Description

TerminalId

M

A

TransactionId

M

A

DateTime

O

A

LocalDate

O

A

LocalTime

O

A

ResponseCode

-

A

ActionCode

-

A

MessageReasonCode

-

A

PrivateData

O

G

SecurityInfo

O

H

NetworkMngInfoCode

M

H

ReceivingInstIdCode

G

A

Required if the message will be sent to Transaction Manager, unless this is populated by a pipeline component.

MerchantId

-

G

Will be returned if set up by a response pipeline component in eSocket.POS.

StructuredData

O

HG

- Name

M

A

- Value

M

A

- Flags

O

G

- -DoNotPersist

O

G

PosStructuredData

O

HG

- Name

M

A

- Value

M

A

EAuthorizationToken

C

C

Should be sent when a token-based authentication is used by the upstream entity.

EspPosData

O

H

Contains data passed from the Point-of-Service (POS) system.

- PosTerminalId

M

A

- PosSequenceNumber

M

A

- PosOperatorId

M

A

1.3. Interface Specification - Administrative

1.3.1. EspAdmin

Administrative functions are performed using the init , close and closeAll methods in the API, or an Esp:Admin element in the XML interface. The properties should be set according to the rules set out in the following table.

(Please refer to Object and Property Conditions for an explanation of the Cond and Rsp columns of this table.)

Property Cond Rsp Description

TerminalId

M

A

Action

M

A

ActionCode

-

A

MessageReasonCode

-

A

Register

O

-

One or more register elements

- Type

M

-

- EventId

M

-

1.3.2. EspEvent

Callbacks are performed using the onEvent method in the API, or an Esp:Event element in the XML interface. The properties should be set according to the rules set out in the following table.

(Please refer to Object and Property Conditions for an explanation of the Cond and Rsp columns of this table.)

Property Cond Rsp Description

TerminalId

M

-

EventId

M

-

EventData

O

-

1.3.3. EspCallback

Callbacks are performed using the callback method in the API, or an Esp:Callback element in the XML interface. The properties should be set according to the rules set out in the following table.

(Please refer to Object and Property Conditions for an explanation of the Cond and Rsp columns of this table.)

Property Cond Rsp Description

TerminalId

M

A

EventId

M

A

EventData

O

-

ResponseData

-

A

1.3.4. EspError

Errors are reported using Java exceptions in the API, or an Esp:Error element in the XML interface. The properties of the Esp:Error element will be set according to the rules set out in the following table.

(Please refer to Object and Property Conditions for an explanation of the Cond and Rsp columns of this table.)

Property Cond Rsp Description

TerminalId

-

C

Will be set if available in the request that resulted in the error.

TransactionId

-

C

Will be set if available in the request that resulted in the error.

ActionCode

-

A

1 / DECLINE

ResponseCode

-

A

30 - Format error

MessageReasonCode

-

A

9791 - Administrative response

Description

-

C

Will be set if available in the Java exception.

1.4. Interface Specification - Properties

1.4.1. Common

Account

Format

n2

Description

The type of the account affected by this transaction.

00 Default – unspecified

10

Savings account

20

Check account

30

Credit account

40

Universal account

50

Investment account

Other values may be used if they are configured in eSocket.POS.

ActionCode

Format

n1 / ans..

Description

The ActionCode defines the action to be taken regarding a transaction.

API value XML Interface value Description

0

APPROVE

Approve

1

DECLINE

Decline

2

RETAIN

Decline and retain card

3

AUTH

Authorization required

AmountTransactionFee

Format

Description

A fee charged to the issuer, for transaction activity, in the currency of the TransactionAmount.

AuthorizationNumber

Format

Description

A code assigned by the authorizing institution indicating approval.

AuthorizationToken

Format

Description

The token used to authenticate the terminal with the upstream entity.

Balance

Lists of balances or mini-statement entries are implemented using an array of BalanceListItem objects in the API, or as Esp:Balance elements in the XML Interface.

  • In a response to a Balance Inquiry or Available Funds Inquiry, each item represents a balance amount. Up to six amounts are supported.

  • In a response to a Mini-statement Inquiry, each item represents a recent transaction on the account, followed by the current balance(s) of the account.

  • Balance List values may also be present in the response to a transaction request if provided by the host. In this case they provide information about current account balances.

Properties

Name Type

AccountId1

String

AccountId2

String

AccountType

String

Amount

String

AmountType

String

AuthorizationId

String

CurrencyCode

String

DateTime

String

SequenceNumber

String

Sign

String

Surcharge

String

TerminalId

String

ToAccountType

String

TransactionType

String

AccountId1

Format

Description

The ID of the first account involved in a transaction contained in a line in the mini-statement represented by this balance list item.

AccountId2

Format

Description

The ID of the second account involved in a transaction contained in a line in the mini-statement represented by this balance list item.

AccountType

Format

n2

Description

The type of the account for this balance list item.

00 Default – unspecified

10

Savings account

20

Check account

30

Credit account

40

Universal account

50

Investment account

Amount

Format

Description

The amount of the balance list item. Values are expressed in the minor denomination.

AmountType

Format

n2

Description

The type of the amount for this balance list item.

01 Ledger balance

02

Available balance

20

Remaining this cycle

40

Cash

53

Approved

90

Available credit

91

Credit limit

AuthorizationId

Format

n6

Description

The authorization ID involved in a transaction contained in a line in the mini-statement represented by this balance list item.

CurrencyCode

Format

n3

Description

The currency of the balance list item. See ISO 4217 (1990): Codes for the Representation of Names of Currencies and Funds.

DateTime

Format

Description

The date and time of the transaction contained in a line in the mini-statement represented by this balance list item.

SequenceNumber

Format

n6

Description

The sequence number for a line in the mini-statement represented by this balance list item.

Sign

Format

x1

Description

The sign of the balance list item. 'C' for credit, 'D' for debit.

Surcharge

Format

n8

Description

The surcharge involved in a transaction contained in a line in the mini-statement represented by this balance list item.

TerminalId

Format

n8

Description

The terminal ID of the transaction contained in a line in the mini-statement represented by this balance list item.

ToAccountType

Format

n2

Description

The type of account to which a transfer transaction was made, as contained in a line in the mini-statement represented by this balance list item.

00 Default - unspecified

10

Savings account

20

Check account

30

Credit account

40

Universal account

50

Investment account

TransactionType

Format

n2

Description

Indicates the type of the transaction, represented by the first two digits of the ISO 8583:1997 Processing Code, contained in a line in the mini-statement represented by this balance list item.

BusinessDate

Format

Description

The month and day for which financial totals are reconciled between the acquirer and the issuer.

CardholderInformation

Format

Description

Contains cardholder related response information. This information is typically returned by the authorizer of the transaction.

CardholderName

Format

Description

The name of the cardholder, as contained in Track 1 data on the card.

CardNumber

Format

Description

The primary account number (PAN) identifying the cardholder and the card issuer. Typically, this number is embossed on the front of the card and encoded on Track 2 of the magnetic stripe.

CardProductName

Format

Description

The name of the card product, as configured in eSocket.POS.

CardSequenceNumber

Format

n3

Description

A number distinguishing between separate cards with the same primary account number or primary account number extended. Pad with leading zeros if required.

CardVerificationResult

Format

Description

Contains the result of a transaction involving card verification. Possible values are:

A ATC outside allowed range (applicable when ATC value is dynamic [varying] value)

B

Virtual Card Number (expiration date expired)

E

Contactless CVV not verified - invalid unpredictable number

M

CVV2 valid (match), CVV valid or not available

N

CVV2 invalid (non-match), CVV valid or not available

P

Unable to process CVV2, CVV valid or not available

S

CVV2 should be on the card

U

Issuer unregistered to process CVV2, CVV valid or not available

V

Unable to process CVV or contactless CVV

X

CVV or contactless CVV valid

Y

CVV or contactless CVV invalid

ChainedTransactionId

Format

Description

The identifier of a transaction (either by TransactionId or RetrievalRefNr ) already performed, within the eSocket.POS retention period, that will be linked to the current transaction.

Usage

This property must be set for transactions that need to be chained.

  • For chaining transactions from the same terminal, by Transaction Id , the identifier must consist of 6 numeric characters not starting with "0".

  • For chaining transactions from the same or different terminals, by RetrievalRefNr , the identifier must consist of 12 alphanumeric characters padded with spaces.

  • The transaction being linked to must have occurred within the retention period as configured for the Transaction Cleaner component (Refer to the eSocket.POS User Guide for the Transaction Cleaner component parameters).

Note : For messages that are part of the same transaction, use the TransactionId property instead of ChainedTransactionId . For example, a request followed by a reversal for that request.

CurrencyCode

Format

n3

Description

The currency of the transaction amount. See ISO 4217 (1990): Codes for the Representation of Names of Currencies and Funds.

Cvv2

Format

n3 or n4

Description

The printed CVV2 value that was manually entered when the magnetic stripe could not be read. For gift card transactions, this field might contain the gift card PIN.

DateTime

Format

Description

The date and time, expressed in Coordinated Universal Time (UTC), when this message is sent.

Field 127.51 - Extended Authorization ID Response

Format

Description

This is a Postilion specific addition to the ISO 8583 standard. The extended authorization ID response is a code which verifies that authorization was approved by an authorizing entity. If the node interfaces can accept an 8 digit authorization ID then this field should be checked first. If this field is not present then the authorization ID response can be retrieved from field 38.

ExtendedTransactionType

Format

n4

Description

A code used to further distinguish between transactions with the same type.

ExpiryDate

Format

Description

The year and month after which the card expires.

FleetData

FleetData Card Data is implemented using a FleetData object in the API, or an Esp:FleetData element in the XML interface.

"Fleet" is a shortened form of "vehicle fleet". A "vehicle fleet" is a set of vehicles and the drivers of these vehicles, managed by a company that uses this fleet to generate profit.
Some examples:

  • A petroleum company will have a fleet of trucks that deliver fuel to their customers.

  • A transport company will have a fleet of trucks to deliver goods to their customers.

  • A taxi company will have a fleet of cars to transport passengers.

Properties

Name

Type

OilBrandName

String

ServiceType

String

VehicleUsage

String

Odometer

String

VehicleReg

String

DriverId

String

PromptCode

String

RestrictionCode

String

PrivateData

String

PurchaseType

String

Prompt

Array of Prompt objects

DriverId

Format

Description

The number assigned to the driver by the employer for purposes of tracking fuel purchases.

Odometer

Format

Description

The reading of the total distance traveled by the vehicle.

OilBrandName

Format

Description

The acquirer’s abbreviation for the brand name of the card acceptor’s oil company.

PrivateData

Format

Description

Private data from the POS to be passed between the POS and an upstream entity, or vice versa. This will not be interpreted by eSocket.POS except optionally by a custom component.

Prompt

A Prompt Item is implemented using a Prompt object in the API, or an Esp:Prompt element in the XML interface.

Properties

Name Type

UserId

String

VehicleId

String

Department

String

DriverLicense

String

CustomerData

String

JobId

String

ContractNumber

String

PIN

String

TripNumber

String

UnitNumber

String

TrailerId

String

TrailerHours

String

MaintenanceId

String

Hubometer

String

EmployeeNumber

String

DriverLicenseState

String

VehicleLicense

String

VehicleLicenseState

String

TrailerLicense

String

TrailerLicenseState

String

FleetId

String

CustomData

String

VehicleTag

String

DriverLicenseLocation

String

DriverLicenseName

String

DriverDateOfBirth

String

VehicleVINNumber

String

PumpNumber

String

TractorNumber

String

ContractNumber

Format

Description

The contract number.

CustomerData

Format

Description

Any customer data.

Department

Format

Description

The department number.

DriverLicense

Format

Description

The driver license number.

Hubometer

Format

Description

The fleet hubometer number.

JobId

Format

Description

The job identification number.

MaintenanceId

Format

Description

The fleet maintenance identification.

PIN

Format

Description

The vehicle PIN number.

TrailerHours

Format

Description

The fleet trailer hours number.

TrailerId

Format

Description

The fleet trailer identification.

TripNumber

Format

Description

The fleet trip number.

UnitNumber

Format

Description

The fleet unit number.

UserId

Format

Description

The user identification number.

VehicleId

Format

Description

The vehicle identification number.

PromptCode

Format

n1

Description

Contains a code read from a card that indicates terminal prompts that occur at the point-of-service.

Valid values:

  • 0 - Reserved for future use

  • 1 - Prompts for identification number and odometer reading

  • 2 - Prompts for vehicle number and odometer reading

  • 3 - Prompts for driver number and odometer reading

  • 4 - Prompts for odometer reading only

  • 5 - No prompts issued

  • 6-8 - Reserved for future use

  • 9 - Reserved for client-specifc use

PurchaseType

Format

a1

Description

The type of products purchased.

Valid values:

  • F - Fuel

  • N - Non-fuel

  • B - Both

RestrictionCode

Format

Description

Contains the restriction code that applies to the transaction.

ServiceType

Format

Description

The type of service received at the card acceptor location.

Valid values:

  • 0 - Reserved for future use

  • 1 - Self-service

  • 2 - Full service

  • 3 - Only non-fuel products purchased

  • 4-7 - Reserved for future use

  • 8-9 - Reserved for client-specific use

VehicleReg

Format

Description

The registration number of the rented or fleet vehicle.

VehicleUsage

Format

a1

Description

The type of service received at the card acceptor location.

Valid values:

  • P - Private

  • B - Business

LocalDate

Format

Description

The local date at which the transaction takes place.

LocalTime

Format

Description

The local time at which the transaction takes place.

MerchantId

Format

Description

The merchant identifier.

MessageReasonCode

Format

n4

Description

In a reversal, a code that provides the receiver of a reversal message with the reason that the reversal was sent.

4000 Customer cancellation

4021

Timeout waiting for response

In a response, a code that provides further information regarding the reason for the response.

Stand-in performed by eSocket.POS:

1006 Under floor limit

1007

Stand-in processing at acquirer’s option (under offline limit)

EMV responses:

9620 EMV offline approved

9621

EMV offline declined

9622

EMV approved after online

9623

EMV declined after online

Rejections due to system malfunctions and unspecified errors:

9600 System malfunction

9601

System malfunction - null action

9602

Component error request pipeline

9603

Component error response pipeline

9604

Database error

Rejections due to device conditions:

9630 Customer cancellation

9631

Operator cancellation

9632

Card removed prematurely

9635

Customer timeout

9636

Card reader retries exceeded

9637

No supported EMV applications

9638

Cardholder verification failure

9639

ICC Blocked

9640

ICC Transaction failed

9641

Device failure

9642

Fatal printer error

9643

Card still in slot

9644

Card insert retries exceeded

Processing and network conditions:

8601 Abort and Retry

8602

Retry Abort

9650

Issuer disconnected

9651

Issuer timeout before response

9652

Configuration out of date

9654

Issuer timeout before response; a reversal advice has been generated

9655

Issuer timeout before response; a reversal advice has not been generated

9656

Issuer disconnected before response; a reversal advice has been generated

9657

Issuer disconnected before response; a reversal advice has not been generated

9660

Signature did not match

9665

Loyalty Timeout

9666

Loyalty Failed

9670

Batch Totals not available

9680

Key change in progress

Rejections due to missing data:

9700 Missing transaction amount

9701

Missing card number

9702

Missing expiry date

9703

Missing PIN data

9704

Missing processing code

9705

Missing account

9706

Missing cashback amount

9707

Missing currency code

9708

Missing merchandise data

9709

Missing effective date

9710

Missing card sequence number

9711

Missing check/cheque data

9712

Missing Signature Data

9713

Missing EMV Data

9714

Missing RFID PIN

9715

Missing barcode data

9716

Missing card acceptor ID

Rejections due to missing data in database:

9717 Missing OPC data

9720

Original transaction not found

9721

Duplicate transaction

Rejections due to message conditions:

9750 Expired card

9751

No supported accounts

9752

No supported accounts for manual entry

9753

Card number failed Luhn check

9754

Card not yet effective

9755

No supported accounts for ICC fallback

9756

Not valid for transaction

9757

Consecutive usage not allowed

9758

Declined because of CVV or AVS failure

9759

Card number format invalid

9760

Purchase amount exceeds maximum allowed value

9761

Cashback amount exceeds maximum allowed value

9762

Transaction amount exceeds maximum allowed value

9763

Card sequence number format invalid

9764

Inconsistent data on the chip

9765

Inconsistent data track 2

9766

Invalid track 2 data

9768

Null P2PE Luhn check

9770

Cashback amount exceeds transaction amount

9771

Cashback amount present in non-cashback transaction

9772

Cashback not permitted to cardholder

9773

Cashback account type is invalid.

9774

Cashback currency code is invalid

9777

Refund Amount exceeds Maximum Refund amount

9778

Cash Advance amount exceeds maximum Cash Advance amount

9794

OPC retries exceeded

9795

No OPC available for reselection

9796

OPC selection failed

9797

OPC confirmation failed

Other values:

9789 Reversal for Advice not allowed

9790

Upstream response

9791

Administrative response

9792

Advice response

9793

Suspected format error in advice - may not be resent

9799

Unknown

9800 to 9999

Values reserved for use in customized components.

PinData

Format

Description

The PIN data contains the encrypted PIN of the cardholder. The PIN is encrypted into 8 bytes, and the 8-byte binary data is represented in 16 hexadecimal characters.

PinKeySequenceNr

Format

Description

Contains the PIN key sequence number formatted according to the DUKPT (Derived Unique Key Per Transaction) scheme. The 8-byte or 10-byte binary data is represented in 16 or 20 hexadecimal characters respectively.

PanEntryMode

Format

n2

Description

A code identifying the actual method used to capture the card number and expiry date.

00 Unknown

01

Manual (i.e. via key pad)

02

Magnetic stripe (possibly constructed manually)

03

Bar code

04

Optic Character Recognition (OCR)

05

Integrated circuit card (ICC)

07

Integrated circuit card (ICC) (Contactless Read)

90

Magnetic stripe as read from Track 2

91

Magnetic stripe (Contactless Read)

95

Integrated circuit card (ICC), Track 2 possibly constructed manually

99

Required during P2PE transactions, forcing TM to retrieve card details from the original transaction

PosCondition

Format

n2

Description

A code that describes the condition under which the transaction takes place at the point of service.

Any 2-digit value may be set, according to the Postilion Transaction Manager Interface Specification based on the ISO8583 standard. Typically one of the following codes will be applicable:

00 Normal presentment

01

Customer not present

03

Merchant suspicious

06

Pre-authorized request

17

Returned item

21

Manual reversal

41

Partial approval supported

In addition to the codes above, the following code may be received in a response:

11 Suspected fraud
PosOperatorId

Format

Description

Specifies the cashier that performed the transaction.

PosStructuredData

POS Structured Data is implemented using a PosStructuredData object in the API, or one or more Esp:PosStructuredData elements in the XML interface.

POS Structured Data consists of one or more Name / Value pairs which can be used to carry custom information between the POS and eSocket.POS or an upstream entity.

Note: It is recommended that new implementations use StructuredData rather than PosStructuredData.

Properties

Name Type

Name

String

Value

String

Name

Format

Description

The name of a Value carried in StructuredData or PosStructuredData.

Reserved names

The following names are reserved for use by the eSocket.POS API, and cannot be used within StructuredData . The data carried under these names can be accessed through other elements in the eSocket.POS interface specification. There are no restrictions on these names being used in PosStructuredData.

  • CardProductName

  • CardholderName

  • CheckData

  • EmvApplicationLabel

  • EmvApplicationPreferredName

  • EmvApplicationVersionNumber

  • EmvIssuerCodeTableIndex

  • EmvTransactionStatusInformation

  • PosPrivateData

  • PosStructuredData

  • PurchasingCardData

  • Rank

  • ReferralAuthorized

  • SignatureData

  • SignatureFormat

  • SignatureRequired

  • StartDate

  • Rcs:DisplayData

  • Rcs:PrintData

The following names are reserved for internal eSocket.POS use, and cannot be used within StructuredData . There are no restrictions on these names being used in PosStructuredData.

  • CallbackSinkPrivateData

  • PanReference

  • ResponseDisplay

  • TlvPurchasingCardData

  • _StatusUpdate

  • Events

  • EspSupportedFeatures

  • OfflineAuthAllowed

  • eSP:Encoding

  • SinkRspCode

  • SinkMessageReasonCode

Value

Format

Description

The value associated with a Name in StructuredData or PosStructuredData.

PurchasingCardData

Purchasing Card Data is implemented using a PurchasingCardData object in the API, or an Esp:PurchasingCardData element in the XML interface.

Purchasing Card Data, also known as Level 2 and 3 data, provides additional information on a transaction done using a purchasing card, which is typically a card issued to an employee for the purposes of covering business-related expenditure. This provides the employer with further information relating to the purchases done using this card. Level 2 data includes information relating to the transaction as a whole, while level 3 data, also known as line item detail, provides details of the individual items purchased in the transaction.

For gift card transactions, the product code (UPC) applicable to the entire transaction can be sent via the ProductCode field of the first LineItem. It is important, though, that the product code is the only field present in the Purchasing Card Data for gift card transactions.

Properties

Name Type

CustomerCode

String

CardAcceptorTaxId

String

CardAcceptorVatNr

String

CardAcceptorRefNr

String

CorporationVatNr

String

CustomerVatNr

String

MerchantOrderNumber

String

InvoiceNumber

String.

Note
This field might be returned in the Esp:Transaction response returned to the Point of Sale (POS).

OrderDate

String

PurchaseDate

String

CustomerBillingCode

String

PurchaseOrderNumber

String

TaxExempt

Boolean

CommodityCode

String

Description

String

DiscountAmount

String

ShippingAmount

String

DutyAmount

String

TaxCollected

Boolean

TotalAmount

String

Comment

String

PrivateData

String

LineItem

Array of LineItem objects

Contact

Array of up to 4 Contact objects

TaxAmount

Array of up to 4 TaxAmount objects

CardAcceptorRefNr

Format

Description

A reference number supplied by the merchant to facilitate merchant communication and record keeping.

CardAcceptorTaxId

Format

Description

The merchant’s federal tax or VAT ID number.

CardAcceptorVatNr

Format

Description

The VAT number of the card acceptor location, used to identify the card acceptor when reporting taxes.

Comment

Format

Description

A text comment relating to this transaction.

CommodityCode

Format

Description

A code assigned by the card acceptor that best categorizes the goods or services purchased.

CorporationVatNr

Format

Description

The corporation’s VAT number.

Contact

A contact is implemented using a Contact object in the API, or an Esp:Contact element in the XML interface.

A contact contains details about an authorized person or company to be contacted for shipping or billing purposes.

Properties

Name Type

Type

String

PostalCode

String

Name

String

Telephone

String

Address

String

City

String

State

String

Country

String

ShippingWarehouse

String

Address

Format

Description

The street address of the company or authorized person to contact.

City

Format

Description

The city of the company or authorized person to contact.

Country

Format

an3

Description

The ISO country code of the company or authorized person to contact.

Name

Format

Description

The name of the company or authorized person to contact.

PostalCode

Format

Description

The ZIP or postal code for this contact.

State

Format

Description

The state code of the company or authorized person to contact.

Telephone

Format

Description

The telephone number of the company or authorized person to contact.

Type

Format

Description

The type of contact. Values can include BILL_FROM, BILL_TO, SHIP_FROM and SHIP_TO.

CustomerBillingCode

Format

Description

A customer code supplied by the merchant.

CustomerCode

Format

Description

A code identifying the customer, supplied by the cardholder to the card acceptor.

CustomerVatNr

Format

Description

The VAT number of the customer, used to identify the customer when reporting taxes.

Description

Format

Description

A description of the purchase transaction.

DiscountAmount

Format

Description

The discount amount applied to this transaction. Amounts are given in the minor denomination.

DutyAmount

Format

Description

The duty amount to be paid on the total purchase. Amounts are given in the minor denomination.

InvoiceNumber

Format

Description

A unique invoice number associated with the transaction provided by the card acceptor.

MerchantOrderNumber

Format

Description

The merchant’s order number.

LineItem

A Line Item is implemented using a LineItem object in the API, or an Esp:LineItem element in the XML interface.

A line item contains level 3 data related to an item purchased using a purchasing card. Level 3 data corresponds to a single line on an invoice, i.e. an individual item purchased, so a single purchase may contain multiple line items.

Properties

Name Type

CommodityCode

String

CustomerItemCode

String

Description

String

Discount

boolean

DiscountAmount

String

DiscountRate

String

ItemNumber

String

PrivateData

String

ProductCode

String

Quantity

String

QuantityExponent

String

SupplyType

String

TotalAmount

String

TotalAmountType

String

UnitOfMeasure

String

UnitPrice

String

UnitPriceExponent

String

VatReferenceNr

String

Sign

String

InvoiceDiscountTreatment

String

DiscountAmountSign

String

LineItemDetailIndicator

String

TaxAmount

Array of up to 4 TaxAmount objects

ItemizedDiscount

Array of ItemizedDiscount objects

CommodityCode

Format

Description

Merchant supplied code or stock keeping unit (SKU) relating to the item purchased.

CustomerItemCode

Format

Description

Customer supplied code relating to the item purchased.

Description

Format

Description

Description of the individual item purchased.

Discount

Format

Description

Indicates whether a discount is applied.

DiscountAmount

Format

Description

The discount amount applied to this item. Amounts are given in the minor denomination.

DiscountRate

Format

n5

Description

The discount rate applied to this item. Three decimal places are implied.

ItemNumber

Format

Description

Line number for this item in the invoice.

PrivateData

Format

Description

A data element that can be used to pass proprietary data between two institutions.

ProductCode

Format

Description

Universal product code (UPC) of the item purchased.

Quantity

Format

Description

Quantity of item purchased.

QuantityExponent

Format

an1

Description

The number of decimal places implied in the Quantity. If not present, zero is assumed.

Sign

Format

x1

Description

The sign of a line item: 'C' for credit, or 'D' for debit. This sign applies to the TotalAmount for the line item, as well as to all TaxAmounts associated with the item. If the sign is omitted, 'D' will be assumed.

SupplyType

Format

n2

Description

Indicates the type of supply. Supported values are Goods (00) or Services (01).

TaxAmount

A tax amount is implemented by a TaxAmount object in the API, or an Esp:TaxAmount element in the XML interface.

Each entry contains information about a tax amount applied to a transaction or line item. Up to four tax amounts can be associated with each purchase or line item, and each should have a different type.

Properties

Name Type

Amount

String

CardAcceptorTaxId

String

Description

String

Included

boolean

Rate

String

RateExponent

String

Type

String

Amount

Format

Description

The tax amount. Amounts are given in the minor denomination.

CardAcceptorTaxId

Format

Description

An identification number used by the card acceptor with the tax authority in relationship to a specific tax amount.

Description

Format

Description

A description of the purpose of the tax amount, for example 'Freight' or 'Alternate Tax'.

Included

Format

Description

Indicates whether the tax amount is included in the final amount for this purchase or line item.

Rate

Format

Description

The tax rate. The number of decimal places is given by the RateExponent property.

RateExponent

Format

n1

Description

The number of decimal placed implied in the tax rate. If this is omitted, the number of decimals is assumed to be zero.

Type

Format

Description

The type of this tax amount. The first two digits are defined as follows:

Type Description

00

Unknown

01

Federal/National Sales Tax

02

State Sales Tax

03

City Sales Tax

04

Local Sales Tax

05

Municipal Sales Tax

06

Other Tax

10

Value Added Tax (VAT)

11

Goods and Services Tax (GST)

12

Provincial Sales Tax (PST)

20

Room Tax

21

Occupancy Tax

22

Energy Tax

The last four digits are optional and can be used to further define tax categories applicable to specific domestic processing arrangements in certain locations.

TotalAmount

Format

Description

The total amount for this item. Amounts are given in the minor denomination.

TotalAmountType

Format

Description

Indicates whether the tax amount is included in the total amount (GROSS) or excluded (NET).

UnitOfMeasure

Format

Description

The unit of measure code.

UnitPrice

Format

Description

The price for one unit of the product. Prices are given in the minor denomination.

VatReferenceNr

Format

Description

Reference number used to identify the VAT invoice or tax receipt.

OrderDate

Format

Description

The date of order.

PrivateData

Format

Description

A data element that can be used to pass proprietary data between two institutions.

PurchaseDate

Format

Description

The date of purchase or invoice.

PurchaseOrderNumber

Format

Description

The buyer’s purchase order number.

ShippingAmount

Format

Description

The freight or shipping amounts to be paid. Amounts are given in the minor denomination.

TaxCollected

Format

Description

Indicates whether tax was collected for this transaction or not.

TaxExempt

Format

Description

Indicates whether the buyer is tax exempt or not.

TotalAmount

Format

n12

Description

The total purchase amount for this transaction. Amounts are given in the minor denomination.

PrivateData

Format

Description

Any data proprietary to the system for this item.

ReceivingInstIdCode

Format

Description

A code identifying the financial institution that should receive this request. This code may be used to route the transaction to the correct sink node on the upstream Postilion system.

ResponseCode

Format

an2

Description

A code that defines the disposition of a transaction.

The list below defines a number of possible responses. Other codes not on this list may be received depending if they are set by the upstream Postilion or host system.

00 Approved or completed successfully

01

Refer to card issuer

02

Refer to card issuer, special condition

03

Invalid merchant

04

Pick-up card

05

Do not honor

06

Error

07

Pick-up card, special condition

08

Honor with identification

09

Request in progress

10

Approved, partial

11

Approved, VIP

12

Invalid transaction

13

Invalid amount

14

Invalid card number

15

No such issuer

16

Approved, update track 3

17

Customer cancellation

18

Customer dispute

19

Re-enter transaction

20

Invalid response

21

No action taken

22

Suspected malfunction

23

Unacceptable transaction fee

24

File update not supported

25

Unable to locate record

26

Duplicate record

27

File update edit error

28

File update file locked

29

File update failed

30

Format error

31

Bank not supported

32

Completed partially

33

Expired card, pick-up

34

Suspected fraud, pick-up

35

Contact acquirer, pick-up

36

Restricted card, pick-up

37

Call acquirer security, pick-up

38

PIN tries exceeded, pick-up

39

No credit account

40

Function not supported

41

Lost card

42

No universal account

43

Stolen card

44

No investment account

51

Not sufficient funds

52

No check account

53

No savings account

54

Card expired or not yet effective

55

Incorrect PIN

56

No card record

57

Transaction not permitted to cardholder

58

Transaction not permitted on terminal

59

Suspected fraud

60

Contact acquirer

61

Exceeds withdrawal limit

62

Restricted card

63

Security violation

64

Original amount incorrect

65

Exceeds withdrawal frequency

66

Call acquirer security

67

Hard capture

68

Response received too late

75

PIN tries exceeded

77

Intervene, bank approval required

78

Intervene, bank approval required for partial amount

90

Cut-off in progress

91

Issuer or switch inoperative

92

Routing error

93

Violation of law

94

Duplicate transaction

95

Reconcile error

96

System malfunction

98

Exceeds cash limit

RetrievalRefNr

Format

Description

A reference number supplied to assist in locating this transaction on another system.

ServiceRestrictionCode

Format

n3

Description

An identification of geographic/service availability. Contains:

The area of usage and whether the card has additional read facilities

1

International card

2

International card - integrated circuit facilities

5

National use only

6

National use only - integrated circuit facilities

9

Test card - online authorization mandatory

The authorization processing requirements for this card

0 Normal authorization

2

Online authorization mandatory

4

Online authorization mandatory

The range of services available and PIN requirements

0 PIN required

1

No restrictions - normal cardholder verification

2

Goods and services only

3

PIN required, ATM only

5

PIN required, goods and services only at POS, cash at ATM

6

PIN required if PIN pad present

7

PIN required if PIN pad present, goods and services only at POS, cash at ATM

StartDate

Format

Description

The year and month when the card becomes effective.

StructuredData

Structured Data is implemented using an EspStructuredData object in the API, or one or more Esp:StructuredData elements in the XML interface.

Structured Data consists of one or more Name / Value pairs, with associated flags, which can be used to carry custom information between the POS and eSocket.POS or an upstream entity.

Properties

Name Type

Name

String

Value

String

Flags **

DoNotPersist

Boolean

Sensitive

Boolean

Compress

Boolean

Encrypt

Boolean

Persist until authorized

Boolean

eSocket.POS defines the following Name/Value pairs for this field:

Name Value Description

Prompts

An XML string conforming to the Prompts DTD

A set of prompts to be presented to the customer/operator.

SignatureLineItemTextCount

A numeric value indicating the number of line items that are present

The number of line items present in the signature capture request.

SignatureLineItemText

A string value containing the line item to be displayed

The line items present in the signature capture request. Each line must be specified as a separate field and suffixed by the line number.

EMV_CA_PKF

A string value containing the EMV public key components.

A set of semicolon-separated records containing the EMV public key components unique to each card association.

EMV_FILE_VERSION

A string value containing the EMV public key file version.

A string value containing the EMV public key file version.

eSocket.POS defines the following Name/Value pairs that are used for TransArmor Encryption:

Name Value Description Message Type

TRANSARMOR_ENC_BLK

A string value containing a TransArmor-encrypted data block

The TransArmor-encrypted data block containing the track data destined for First Data.

Request

TRANSARMOR_SEC_LVL_IND

A string value containing TransArmor security level indicator

The security level indicator of the TransArmor-encrypted data.

Request/Response

TRANSARMOR_ENC_TYPE

A string value containing TransArmor-encryption type

The encryption type of the TransArmor-encrypted data.

Request/Response

TRANSARMOR_KEY_ID

A string value containing the TransArmor data encryption key ID

The key ID of the TransArmor-encrypted data encryption type.

Request/Response

TRANSARMOR_TOKEN

A string value containing the TransArmor token

The value of the TransArmor token supplied by First Data.

Request/Response

TRANSARMOR_TOKEN_EXPIRY_DATE

A string value containing TransArmor token expiry date

The value of the TransArmor token expiry date supplied by First Data.

Request/Response

TRANSARMOR_TOK_TYPE

A string value containing TransArmor token type

The type of the TransArmor token.

Request/Response

Masking StructuredData Fields

The masking of any StructuredData field can now be achieved with the addition of a metadata StructuredData element into the main StructuredData element. This metadata element contains the addresses of the fields that will be masked.

A StructuredData element may contain:

  • regular text

  • tlvs, which can be a single tlv or a sequence of contiguous tlvs

  • embedded StructuredData elements(which can contain any of the elements above, including additional embedded StructuredData elements)

Any field in any of these data elements can be addressed, and thus be masked in the trace.

In order to achieve this, an additional StructuredData must be utilized as the metadata StructuredData element, containing the addresses of all the fields that must be masked. This metadata StructuredData element must be populated in the following manner:

StructuredData metadata = new StructuredData();
metadata.put("field address 1", "x");
metadata.put("field address 2", "x");
...
metadata.put("field address n", "x");

Where "field address n" is a sequence of field names "field1/field2/../fieldn" which together, target a particular field. It must be understood that field2 belongs in field1 , field3 belongs in field2 etc. Any field can be used in an address, but only tlv and StructuredData fields can contain other fields. The field address is added to the metadata as the key , while any short String can be added as the value , for example "x" as indicated in the example above. The value cannot be null . Once the metadata is defined, simply add it to the regular data StructuredData element, with key "eSocketPOS:Metadata" , and the value being the output of "metadata.toMsgString()" :

static final String META_DATA  = "eSocketPOS:Metadata";
//the regular StructuredData
StructuredData regularStructuredData = new StructuredData();
...
//the metadata StructuredData
StructuredData metadata = new StructuredData();
metadata.put("field address 1", "x");
metadata.put("field address 2", "x");
...
metadata.put("field address n", "x");
//add the metadata to the regular data StructuredData
regularStructuredData.put(META_DATA, metadata.toMsgString());

Examples

Consider an ISO8583 message with a single field, bit 127.22 , which is StructuredData . In the trace it would be appear as:

0100:
   [LLLLLVAans 99999 535] 127.022.Regular1
       [TRUE]    
   [LLLLLVAans 99999 535] 127.022.TLV1
       [8C02125F200334570046789]
   [LLLLLVAans 99999 535] 127.022.TLV2
       [8C04ABCD]
   [LLLLLVAans 99999 535] 127.022.Regular2
       [1]
   [LLLLLVAans 99999 535]  127.022.Embedded1
       [18Regular3211A sunny day19Embedded224214TLV5185F2802ZA18Regular4213Raining again14TLV42315F2D03eng5F2009Bob Smith500342314TLV3184F040123]
   [LLLLLVAans 99999 535] 127.022.Regular5
       [123]

The message is comprised of:

  • a regular text entry "Regular1" : "TRUE"

  • a multiple tlv entry "TLV1" : "8C 02 12, 5F20 03 345, 70 04 6789"

  • a single tlv entry "TLV2" : "8C 04 ABCD"

  • a regular text entry "Regular2" : "1"

  • an embedded StructuredData entry: "Embedded1" :

    • a regular text entry "Regular3":"A sunny day"

    • a single tlv entry "TLV3" : "4F 04 0123"

    • a multiple tlv entry "TLV4" : "5F2D 03 eng, 5F20 09 Bob Smith, 50 03 423"

    • an embedded _ StructuredData _ entry: "Embedded2" :

      • a regular text entry "Regular4":"Raining again"

      • a single tlv entry "TLV5" : "5F28 02 ZA"

  • a regular text entry "Regular5" : "123"

Example 1

To mask "Regular1", place "Regular1" into the metadata element, to produce:

0100:
   [LLLLLVAans 99999 535] 127.022.Regular1
       [****]
...

Example 2

To mask "TLV2", place "TLV2" into the metadata element, to produce:

0100:
...    
   [LLLLLVAans 99999 535] 127.022.TLV2
       [********]
...

But if you add the emv tag 8C to the TLV2 address, as in "TLV2/8C" , then this will mask out the tlv value, and leave the tag and length intact, to produce:

0100:
...
   [LLLLLVAans 99999 535] 127.022.TLV2
       [8C04****]
...

Example 3

To mask out a particular tlv in a tlv sequence, as in the case of masking emv tag "5F20" in field "TLV1", add "TLV1/5F20" to the metadata to produce:

0100:
...
   [LLLLLVAans 99999 535] 127.022.TLV1
       [8C02125F2003***70046789]
...

Example 4

To mask out a regular field in an embedded StructuredData element, as in the case of masking "Regular3" in embedded StructuredData element "Embedded1", add "Embedded1/Regular3" to the metadata to produce:

0100:
...
   [LLLLLVAans 99999 535] 127.022.Embedded1
       [18Regular3211***********19Embedded224214TLV5185F2802ZA18Regular4213Raining again14TLV42315F2D03eng5F2009Bob Smith500342314TLV3184F040123]
...

Or if you’d like to mask the entire tlv sequence in "TLV4", add "Embedded1/TLV4" to the metadata to produce:

0100:
...
   [LLLLLVAans 99999 535] 127.022.Embedded1
       [18Regular3211A sunny day19Embedded224214TLV5185F2802ZA18Regular4213Raining again14TLV4231*******************************14TLV3184F040123]
...

Example 5

To mask out the emv tag "TLV5" found in embedded StructuredData element "Embedded2", add "Embedded1/Embedded2/TLV5/5F28" to the metadata to produce:

0100:
...
   [LLLLLVAans 99999 535] 127.022.Embedded1
       [18Regular3211A sunny day19Embedded224214TLV5185F2802**18Regular4213Raining again14TLV42315F2D03eng5F2009Bob Smith500342314TLV3184F040123]
...

Example 6

Finally, to indicate how multiple addresses affect the masking of the StructuredData field, the following fields will be masked:

  • "Regular1"

  • "TLV2"

  • "TLV1/70"

  • "TLV1/8C"

  • "Embedded1/TLV3"

  • "Embedded1/Embedded2/Regular4"

to produce:

0100:
   [LLLLLVAans 99999 535] 127.022.Regular1
       [****]
   [LLLLLVAans 99999 535] 127.022.TLV1
       [8C02**5F20033457004****]
   [LLLLLVAans 99999 535] 127.022.TLV2
       [********]
   [LLLLLVAans 99999 535] 127.022.Regular2
       [1]    
   [LLLLLVAans 99999 535] 127.022.Embedded1
       [18Regular3211A sunny day19Embedded224214TLV5185F2802ZA18Regular4213*************14TLV42315F2D03eng5F2009Bob Smith500342314TLV318********]
   [LLLLLVAans 99999 535] 127.022.Regular5
       [123]
   [LLLLLVAans 99999 535] 127.022.eSocketPOS:Metadata
           [18Regular311x17TLV1/8C11x14TLV211x228Embedded1/Embedded2/Regular411x17TLV1/7011x214Embedded1/TLV311x]

As you can see, the "eSocketPOS:Metadata" is also part of the trace, since it’s an element of the StructuredData .

Notes

As far as persisting Esp:StructuredData

  • the metadata field eSocketPOS:Metadata is not persisted

  • all masked fields are removed from Esp:StructuredData and are not persisted

Flags

Flags allow:

  • Structured Data (field 127.22) values to be excluded from being persisted to the eSocket.POS database

  • Individual XML elements to be marked as Sensitive . This will result in the complete masking of values for such elements in trace files and events.

Flags are implemented using a Flags object in the API. In the XML interface, individual flags are supported directly as attributes of the Esp:StructuredData element.

Properties

Name Type

DoNotPersist

boolean

Sensitive

boolean

Compress

boolean

Encrypt

boolean

Persist until authorized

boolean

DoNotPersist

Format

Set to TRUE to prevent a single Name / Value pair in Structured Data from being persisted to the eSocket.POS database.

Usage examples:

	import postespos.core.message.bitmap.HashtableMessage.Flags;
	StructuredData sd = new StructuredData();
	sd.put("A name", "A value", new Flags().setDoNotPersist()) ; //which will enable/set the flag to true by default or
	sd.put("A name", "A value", new Flags().setDoNotPersist(false)) ; //in order to set the flag explicitly to true/fals
	and then
	Flags flags = sd.getFlags(someKey); if(flags.getDoNotPersist() ) \{...

Example 2: (This can be used when an attribute level XML fields don’t need to be persisted in the database)

	import postespos.core.message.bitmap.HashtableMessage.Flags;
	Flags flags = new Flags();
	flags. *setDoNotPersist()* ; //which will enable/set the flag to true by default
	Hashtable ht = new Hashtable();
	and then
	ht.put("DriverLicenseName", flags);
	sd = setStructuredData(sd, Field.FLEET_DATA, fleet_data.constructXMLString(), flags, ht);
Sensitive

Format

Set to TRUE to mark an element as sensitive, causing its value to be masked in trace files.

Sensitive can be specified for multiple fields within the Esp:StructuredData element. The values of these fields will then be masked in the trace.

This attribute may be used for either a top-level element, which will cause the entire XML string to be masked, or for any number of nested XML elements, which will result in the only those element values being masked.

Usage examples:

	import postespos.core.message.bitmap.HashtableMessage.Flags;
	StructuredData sd = new StructuredData();
	sd.put("A name", "A value",
	new Flags().setSensitive()) ; //which will enable/set the flag to true by default or
	sd.put("A name", "A value", new Flags().setSensitive(false)) ; //in order to set the flag explicitly to true/false and then
	Flags flags = sd.getFlags(someKey); if(flags. *getSensitive()* ) \{...
*Example 2:* (This can be used when an attribute or tree node level XML fields need to be sensitized)
	import postespos.core.message.bitmap.HashtableMessage.Flags;
	Flags flags = new Flags();
	flags. *setSensitive()* ; //which will enable/set the flag to true by default
	Hashtable ht = new Hashtable();
	and then
	ht.put("DriverLicenseName", flags);
	sd = setStructuredData(sd, Field.FLEET_DATA, fleet_data.constructXMLString(), flags, ht);
Compress [Not yet supported]

Format

It will be designed so that an element’s Compress attribute can be set to TRUE to mark it to be compressed.

EMV_CA_PKF

Format

Description

The EMV_CA_PKF file contains the EMV public key components unique to each card association. This response field can contain multiple semicolon-delimited (;) records. Columns within each record will be comma-delimited (,). Two separator characters in direct succession, without any characters in between, indicates an empty column. This field, if returned, will be specified as part of EspStructuredData .

Each record is composed of the following columns:

|Name |Format |Description

|Expiration Date |MMDDYYYY |The expiration date of the public key record

|Certificate Authority Hash Algorithm Indicator |Numeric |This column identifies the hash algorithm used in the digital signature scheme.
It will always be 01 (SHA-1).

|Certificate Authority Public Key Algorithm Indicator |Numeric |This column identifies the digital signature algorithm.
It will always be 01 (RSA).

|Registered Application Identifier 'RID' |ASCII Hex |The RID that applies to this public key

|Key Index |ASCII Hex |The Key Index that applies to this public key

|Key Modulus |ASCII Hex |The Key Modulus that applies to this public key

|Key Exponent |ASCII Hex |The value of the modulus portion of the public key. Valid values are: * 010001 * 02 * 03

|Key Checksum |ASCII Hex |The Key Checksum that applies to this public key

EMV_FILE_VERSION

Format

n28

Description

Contains the identifier for the EMV CA Public Key File. This field, if returned, will be specified as part of EspStructuredData.

Encrypt [Not yet supported]

Format

It will be designed so that an element’s Encrypt attribute can be set to TRUE to mark it to be encrypted.

Persist until authorized

Format

Set to TRUE to mark an element to be persisted until authorized.

Persist until authorized can be specified for multiple fields within the Esp:StructuredData element. The values of these fields will then be persisted until the transaction is authorized, after which they will be removed.

This attribute may be used for either a top-level element, which will affect all fields, or for any number of nested XML elements.

Usage examples:

	import postespos.core.message.bitmap.HashtableMessage.Flags;
	StructuredData sd = new StructuredData();
	sd.put("A name", "A value", new Flags().setPersistUntilAuthorized()); //which will enable/set the flag to true by default or
	sd.put("A name", "A value", new Flags().setPersistUntilAuthorized(false)) ; //in order to set the flag explicitly to true/false
	and then Flags flags = sd.getFlags(someKey); if(flags.getPersistUntilAuthorized()) \{...

Example 2: (This can be used when an attribute or tree node level XML fields need to be persisted until authorized)

	import postespos.core.message.bitmap.HashtableMessage.Flags;
	Flags flags = new Flags();
	flags. *setPersistUntilAuthorized()* ; //which will enable/set the flag to true by default
	Hashtable ht = new Hashtable();
	and then
	ht.put("DriverLicenseName", flags);
	sd = setStructuredData(sd, Field.FLEET_DATA, fleet_data.constructXMLString(), flags, ht);
TerminalId

Format

Description

The terminal ID of this terminal, as configured in the eSocket.POS database.

Track1

Format

Description

The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813, including field separators but excluding the begin sentinel, end sentinel and longitudinal redundancy check characters.

Track2

Format

Description

The information encoded on Track 2 of the magnetic stripe as defined in ISO 7813, including field separators but excluding the begin sentinel, end sentinel and longitudinal redundancy check characters. The field separator can be either a "=" or a "D" character.

Note: When using TransArmor non-format-preserving encryption (see the "PAN Encryption" parameter on the PAN pipeline component in the eSocket.POS User Guide), the full track data should be encrypted in structured data field TRANSARMOR_ENC_BLK , while obfuscated track data should be supplied in this field as follows:

For cards with BINs starting with "59":

First 6 digits (BIN) of the PAN

Obfuscation characters, e.g. zeroes

Last 4 digits of the PAN

Field separator, i.e. "=" or a "D"

Country Code (3 digits)

Expiry Date (YYMM)

Service Restriction Code (3 digits)

Obfuscation characters, e.g. zeroes (to original length)

For all other cards:

First 6 digits (BIN) of the PAN

Obfuscation characters, e.g. zeroes

Last 4 digits of the PAN

Field separator, i.e. "=" or a "D"

Expiry Date (YYMM)

Service Restriction Code (3 digits)

Obfuscation characters, e.g. zeroes (to original length)

Track3

Format

Description

The information encoded on Track 3 of the magnetic stripe, excluding the begin sentinel, end sentinel and longitudinal redundancy check characters.

TransactionId

Format

n6

Description

A number that uniquely identifies a transaction from this terminal within the eSocket.POS transaction retention period.

Usage

If a terminal sends more than one message for the same transaction (for instance, a request followed by a reversal), they should have the same transaction ID.

The transaction retention period is defined as a user parameter for the Transaction Cleaner component. A Transaction ID may only be reused once the cleaner has removed the original transaction from the database.

Transaction IDs beginning with zero should not be used. These are reserved for internal use by eSocket.POS.

TransactionAmount

Format

Description

The amount applicable to a transaction. Values are expressed in the minor denomination.

TlvIccDataExtended

Format

ans

Description

It is a structured data (SD) tag used to send additional non sensitive EMV tags to the upstream entity. These EMV tags are sent in a TLV formatted structure which is set in Structured Data (field 127.22) under the key 'TlvIccDataExtended'.

If another application is driving the card read, this SD tag can be sent with the EMV data in the xml request sent to eSocket.POS. Only standard non-sensitive EMV tags are supported.

Sensitive EMV tags set in this tag are ignored.

If a given EMV tag set in this field is also set in the Esp:Transaction , the value in Esp:Transaction overrides the one in this tag.

If a given EMV tag set in this field has a corresponding ICC DATA field, its value will also be populated in its corresponding ICC DATA field.

If a given EMV tag set in this field has a corresponding Iso8583 field, its value will also be populated in its corresponding Iso8583 field.

This field is sent upstream as received in the request.

Data in this field is validated as per the format/length defined in Esp:Transaction . If a given EMV tag in this field does not comply with the format or length required, the transaction will be declined with the error specifying the field with the wrong format/length.

The transaction is immediately declined if this field is populated with a malformed TLV string.

Example

<Esp:StructuredData name="TlvIccDataExtended" value="9F34030103029F3303E0B0C88A023030" />

1.4.2. EspTransaction

AddressVerificationResult

Format

a1

Description

The result of address verification (AVS). Possible values are:

A Address matches, postal/ZIP code does not

E

Error

N

Neither address nor postal/ZIP code matches

R

Retry

U

Unavailable

Y

Address and postal/ZIP code matches

Z

postal/ZIP code matches, address does not

AuthorizingAgent

Format

Description

A code identifying the authorizing agent institution.

If eSocket.POS approves the transaction on stand in, the authorizing agent is set to '051916'.

AuthorizationProfile

Format

an2

Description

It provides additional information on the conditions under which authorization was performed.

  • The authorization reason (position 1).

0 Unknown.

1

The transaction was authorized by the card issuer.

2

Online stand-in. The transaction amount was below the local limits.

3

Timeout stand-in. The Sink Node did not respond to a request.

4

Offline stand-in. The Sink Node was not available.

5

The use of this authorization type has been deprecated.

9

The transaction was authorized by Visa.

A

Declined by the Sink Node, not sent to the remote entity. This is not forwarded to the Source Node.

B

Declined by the Sink Node after an approved response was received from the remote entity. This is not forwarded to the Source Node.

  • The authorization type (position 2).

0 Unknown.

1

Transaction authorized against cardholder record at card issuer.

2

Transaction authorized using card issuer limits.

3

Transaction authorized using card acceptor (merchant) limits.

4

Transaction authorized using card issuer balances.

5

Authorized using card issuer velocity limits.

If the Authorization Reason field is set to 9 (Authorized by Visa), the values of this field are defined in the following Visa manual: V.I.P. System Technical Reference Vol. 2, Field and Code Descriptions, Additional Response Data (Field 44), Response Source/Reason Code (Field 44.1)

CardholderAddress

Format

Description

The cardholder address, for use in address verification (AVS).

CashbackAmount

Format

Description

The cashback amount applicable to a transaction. Values are expressed in the minor denomination.

For example, if the customer buys goods to the value of $50 and asks for $20 cashback, the Amount property would be $70 and the cashback amount would be $20.

The cashback amount must be less than or equal to the amount of the transaction.

DccStatusCode

Format

a3

Description

Details the dynamic currency conversion (DCC) processing performed on the transaction if applicable. This field consists of the following sub-fields:

Position

Subfield

Description

1

DCC allowed

Indicates whether DCC is allowed on this transaction. At the start of the transaction eSocket.POS sets this flag based on configuration and prescreening. The host can update this flag based on its configuration and prescreening. Valid values:

  • Y - Yes - DCC is allowed for this transaction.

  • N - No - DCC is not allowed for this transaction.

  • U - Undetermined - the flag has not been set.

2

DCC Available

Indicates whether a DCC offer has been retrieved successfully for this transaction. Valid values:

  • Y - Yes - A DCC offer has been retrieved successfully for this transaction.

  • N - No - The DCC provider is unavailable or cannot return a DCC offer for this transaction.

  • U - Undetermined - the flag has not been set.

3

DCC Accepted

Indicates whether the DCC offer has been accepted for this transaction. Valid values:

  • Y - Yes - The DCC offer has been accepted for this transaction. For a sale transaction, this indicates that the cardholder has accepted the DCC offer.

  • N - No - The DCC offer has not been accepted.

  • U - Undetermined - the flag has not been set.

DccProviderRoutingId

Format

Description

An identifier for the external entity that provided the currency conversion information which represents a DCC offer. This identifier is used by the host when routing financial transactions that represent an accepted DCC offer to an acquirer that has a relationship with the currency conversion provider. The host requires this field to be set.

DccRate

Format

Description

The exchange rate used when performing currency conversion from the amount in the source currency to the amount in the target currency. Examples: 4.9880; 61.41170; 110.86980; 1538.70010; 25073.8100; 0.00003988201

DccSrcCurrCode

Format

n3

Description

Numeric code of the currency being converted from.

DccSrcCurrAlphaCode

Format

a3

Description

Alphabetic code of the currency being converted from.

DccSrcCurrMinorUnits

Format

n1

Description

The number of digits following the decimal separator.

DccTgtCurrCode

Format

n3

Description

Numeric code of the currency being converted to.

DccTgtCurrAlphaCode

Format

a3

Description

Alphabetic code of the currency being converted to.

DccTgtCurrMinorUnits

Format

n1

Description

The number of digits following the decimal separator.

DccProvider

Format

Description

The currency conversion service provider.

DccRateSrc

Format

Description

The source of conversion data.

DccTimestamp

Format

Description

Time the conversion was performed in Coordinated Universal Time (UTC), formatted as an ISO date string. Example: 20150729T15:35

DccMargRate

Format

Description

Numeric value representing the foreign exchange markup rate as a fraction. Used for the purposes of receipt printing and to meet regulatory requirements. Examples: 0.035; 0.00157

DccDiffOverECB

Format

Description

Numeric value representing the foreign exchange markup, it compare the DCC exchange rate to the European Central Bank rate as a fraction. Used for the purposes of receipt printing and to meet regulatory requirements. Examples: 0.0035; 0.000157; -0.005

DccIsEEA

Format

a2

Description

EEA (European Economic Area) indicator

DccCommRate

Format

Description

Numeric value representing the foreign exchange commission rate as a fraction. Used for the purposes of receipt printing and to meet regulatory requirements. Examples: 0.035; 0.00157

DccSrcAmt

Format

n12

Description

Amount of the transaction in the currency being converted from. The value must be expressed in the minor denomination (e.g. cents) and must be 12 digits in length, left padded with zeroes. Example: 000000013567

DccTgtAmt

Format

n12

Description

Amount of the transaction in the currency being converted to. The value must be expressed in the minor denomination (e.g. cents) and must be 12 digits in length, left padded with zeroes. Example: 000000013567

DccExpTimestamp

Format

Description

The offer expiration date and time in Coordinated Universal Time (UTC), formatted as an ISO date string. Example: 20150730T15:35

DccRcptTxt1

Format

Description

Additional disclaimer information required for printing on receipts.

Note: The text returned may contain the placeholder value, ${n}. This value allows for the transmission of line breaks in a format-agnostic manner. The Point of Sale consuming these fields will convert the placeholder value into to the specific system-appropriate line break.

DccRcptTxt2

Format

Description

Additional disclaimer information required for printing on receipts.

Note: The text returned may contain the placeholder value, ${n}. This value allows for the transmission of line breaks in a format-agnostic manner. The Point of Sale consuming these fields will convert the placeholder value into to the specific system-appropriate line break.

DccAcqId

Format

Description

The dynamic currency conversion specific acquirer identifier.

DccCardAccptrId

Format

Description

The dynamic currency conversion specific card acceptor identifier.

DccTermId

Format

Description

The dynamic currency conversion specific terminal identifier.

EmvAmount

Format

n12

EMV Tag ID

9F02

Description

The amount of the transaction.

EmvAmountOther

Format

n12

EMV Tag ID

9F03

Description

Secondary amount associated with the transaction, representing a cashback amount.

EmvApplicationIdentifier

Format

EMV Tag ID

4F

Description

Identifies the application on the ICC as described in ISO/IEC 7816-5. (Field value: translate binary EMV value of up to 16 bytes to hex string of up to 32 characters.)

EmvApplicationInterchangeProfile

Format

EMV Tag ID

82

Description

Indicates the capabilities of the ICC to support specific functions in the application. (Field value: translate 2 byte binary EMV value to 4 byte hex string.)

EmvApplicationLabel

Format

EMV Tag ID

50

Description

Descriptive name of the application on the EMV card.

EmvApplicationPreferredName

Format

EMV Tag ID

9F12

Description

Preferred mnemonic associated with the AID. This property has been deprecated. Please use either EmvApplicationPreferredNameRaw or EmvApplicationPreferredNameInternational instead.

EmvApplicationPreferredNameRaw

Format

Description

Preferred mnemonic associated with the AID in hexadecimal.

EmvApplicationPreferredNameInternational

Format

Description

Preferred mnemonic associated with the AID.

EmvApplicationTransactionCounter

Format

Description

Counter maintained by the application in the ICC. (Incrementing the ATC is managed by the ICC). (Field value: translate 2 byte binary EMV value to 4 byte hex string.)

EmvApplicationUsageControl

Format

Description

Indicates the issuer’s specified restrictions on the geographic usage and services allowed for the application. (Field value: translate 2 byte binary EMV value to 4 byte hex string.

EmvApplicationVersionNumber

Format

EMV Tag

9F08

Description

Version number assigned by the payment system for the application as maintained by the ICC card. (Field value: translate 2 byte binary EMV value to 4 byte hex string.)

EmvAuthorizationResponseCode

Format

an2

EMV Tag ID

8A

Description

Code returned by the issuer or generated by the terminal if it did not receive an online response from the issuer.

EmvCryptogram

Format

EMV Tag ID

9F26

Description

The cryptogram generated by the ICC. Consists of one of the following: Authorization Request Cryptogram (ARQC) for an authorization request, Application Authentication Cryptogram (AAC) for a declined transaction, or Transaction Certificate (TC) for an approved transaction. (Field value: translate 8 byte binary EMV value to 16 byte hex string.)

EmvCryptogramInformationData

Format

ans2 EMV Tag ID

9F27

Description

Indicates the type of cryptogram returned by the ICC (ARQC, AAC or TC) and the actions to be performed by the terminal. (Field value: translate 1 byte binary EMV value to 2 byte hex string.)

EmvCvmList

Format

EMV Tag ID

8E

Description

Identifies the cardholder verification methods (CVMs) supported by the application. (Field value: translate 252 byte binary EMV value to 504 byte hex string.)

EmvCvmResults

Format

EMV Tag ID

9F34

Description

Cardholder verification method (CVM) results indicating the results of the last CVM performed. (Field value: translate 3 byte binary EMV value to 6 byte hex string.)

EmvInterfaceDeviceSerialNumber

Format

an8

EMV Tag ID

9F1E

Description

A unique and permanent serial number assigned to the interface device (IFD) by the terminal manufacturer.

EmvIssuerActionCodeDefault

Format

EMV Tag ID

9F0D

Description

Specifies the issuer’s conditions that cause a transaction to be rejected if it might have been approved online, but the terminal is unable to process the transaction online.

EmvIssuerActionCodeDenial

Format

EMV Tag ID

9F0E

Description

Specifies the issuer’s conditions that cause the denial of a transaction without attempt to go online.

EmvIssuerActionCodeOnline

Format

EMV Tag ID

9F0F

Description

Specifies the issuer’s conditions that cause a transaction to be transmitted online.

EmvIssuerApplicationData

Format

EMV Tag ID

9F10

Description

Proprietary application data for transmission from the ICC to the issuer. May contain the following subfields: Scheme Discretionary Data, Issuer Discretionary Data, Derivation Key Index, Cryptogram Version Number, Card Verification Results, DAC. The layout of this field is specific to the issuer. (Field value: translate binary EMV value of up to 16 bytes to hex string of up to 32 characters.)

EmvIssuerCodeTableIndex

Format

n2

EMV Tag ID

9F11

Description

Indicates the code table according to ISO/IEC 8859 for displaying the Application Preferred Name .

EmvIssuerScriptResults

Format

Description

Indicates the result of the terminal script processing. (Field value: translate binary EMV value to hex string.)

EmvTerminalActionCodeDefault

Format

Description

Specifies the terminal’s conditions that cause a transaction to be rejected if it might have been approved online, but the terminal is unable to process the transaction online.

EmvTerminalActionCodeDenial

Format

Description

Specifies the terminal’s conditions that cause the denial of a transaction without attempt to go online.

EmvTerminalActionCodeOnline

Format

Description

Specifies the terminal’s conditions that cause a transaction to be transmitted online.

EmvTerminalApplicationVersionNumber

Format

EMV Tag ID

9F09

Description

Version number assigned by the payment system for the application as maintained by the terminal. (Field value: translate 2 byte binary EMV value to 4 byte hex string.)

EmvTerminalCapabilities

Format

EMV Tag ID

9F33

Description

Indicates the card data input, CVM, and security capabilities of the terminal. (Field value: translate 3 byte binary EMV value to 6 byte hex string.)

EmvTerminalCountryCode

Format

n3

EMV Tag ID

9F1A

Description

Indicates the country of the terminal, represented according to ISO 3166.

EmvTerminalTransactionQualifiers

Format

EMV Tag ID

9F66

Description

Indicates the terminal transaction qualifiers for the transaction. (Field value: translate 4 byte binary EMV value to 8 byte hex string.)

EmvTerminalType

Format

n2

EMV Tag ID

9F35

Description

Indicates the environment of the terminal, its communications capability, and its operational control.

EmvTerminalVerificationResult

Format

EMV Tag ID

95

Description

Status of the different functions as seen from the terminal. (Field value: translate 5 byte binary EMV value to 10 byte hex string.)

EmvTransactionCategoryCode

Format

EMV Tag ID

9F53

Description

Defines the type of transaction for which authorization is being requested. Used in risk management.

EmvTransactionCurrencyCode

Format

n3 EMV Tag ID

5F2A

Description

Indicates the currency code of the transaction according to ISO 4217.

EmvTransactionDate

Format

EMV Tag ID

9A

Description

The local date on which the transaction was authorized.

EmvTransactionSequenceCounter

Format

EMV Tag ID

9F41

Description

Counter maintained by the terminal and incremented by one for each transaction.

EmvTransactionStatusInformation

Format

EMV Tag ID

9B

Description

Indicates the functions performed in a transaction. (Field value: translate 2 byte binary EMV value to 4 byte hex string.)

EmvTransactionType

Format

n2

EMV Tag ID

9C

Description

Indicates the type of the transaction, represented by the first two digits of the ISO 8583:1997 Processing Code.

EmvUnpredictableNumber

Format

EMV Tag ID

9F37

Description

Value to provide uniqueness to the generation of the cryptogram. (Field value: translate 4 byte binary EMV value to 8 byte hex string.)

EmvAdditionalTerminalCapabilities

Format

EMV Tag ID

9F40

Description

Indicates the transaction type, terminal data input, and terminal data output capabilities of the terminal.(Field value: translate 5 byte binary EMV value to 10 byte hex string.)

EmvTransactionTime

Format

n6

EMV Tag ID

9F21

Description

Local time that the transaction was authorized in HHMMSS format.

EmvApplicationPriorityIndicator

Format

n2

EMV Tag ID

87

Description

The priority of the selected EMV application.

EmvIssuerCountryCode

Format

n3

EMV Tag ID

5F28

Description

The ISO country code of the card issuer.

EmvFormFactorIndicator

Format

EMV Tag ID

9F6E

Description

Contains indicators about the attributes of cardholder’s device and the technology used for communication between the cardholder’s device and the acquiring POS device. (Field Value: translate n byte binary EMV value to 2n byte hex string.)

EmvCustomerExclusiveData

Format

EMV Tag ID

9F7C

Description

Available for the issuer’s discretionary use. (Field value: translate 32 byte variable binary EMV value to 64 byte variable hex string.)

ApplicationExpiryDate

Format

EMV Tag ID

5F24

Description

The year, month, and day after which the EMV application expires.

EmvIssuerAuthenticationData

Format

EMV Tag ID

91

Description

Data sent to the ICC (Integrated circuit cards) after online issuer authentication

EmvIssuerScriptTemplate1

Format

EMV Tag ID

71

Description

Contains proprietary issuer data for transmission to the ICC (Integrated circuit cards) before the second GENERATE AC command

EmvIssuerScriptTemplate2

Format

EMV Tag ID

72

Description

Contains proprietary issuer data for transmission to the ICC (Integrated circuit cards) after the second GENERATE AC command

ExtendedPaymentPeriod

Format

Description

The number of months that the cardholder prefers to pay for this item if permitted by the card issuer.

FallbackReason

Format

n1

Description

Indicates the conditions under which fallback has occurred. For contact ICC to contact magnetic stripe fallback scenarios, this field can be used to distinguish between a technical fallback (chip card read failure) and a non-technical fallback (no supported applications).

1 Card unreadable

2

Chip error

3

No supported applications

FallbackType

Format

n1

Description

Indicates the type of fallback that occurred when either the magnetic stripe or the chip on the card could not be read.

0 No fallback

1

Fallback from contact ICC

2

Fallback from magnetic stripe

3

Fallback from contactless

FinalAmount

Format

Description

The final amount applicable to a transaction. Values are expressed in the minor denomination.

ForceOnline

Format

Description

Set to true if the transaction should be forced online, i.e. eSocket.POS should not perform stand-in. Set to false if eSocket.POS may perform stand-in depending on configuration and transaction details.

If not set, this property defaults to false .

GratuityAmount

Format

Description

The gratuity/tip amount applicable to a transaction. Values are expressed in the minor denomination.

For example, if the customer buys goods to the value of $50 and offers gratuity/tip for $20, then the amount property would $70 and the gratuity amount would be $20.

MessageType

Format

Description

Defines the message type of the transaction, which must be one of the following values:

AUTH Request authorization online, but do not debit or credit the cardholder’s account (ISO 8583 message type 0100).

CONFIRM

Advise that a change should be applied to the cardholder’s account, after the transaction has been completed. This will typically be preceded by an online authorization or an offline authorization such as a telephone referral, or else by the merchant’s own decision to force approval of the transaction (ISO 8583 message type 0220).

ADMIN_REQUEST

Send an Administration request online (ISO 8583 message type 0600). This value may only be set if the Type property is set to 'ADMIN'.

REFERRAL

Advice that a change should be applied to the cardholder’s account where the transaction has already been authorized by an offline referral process, but electronic signature capture or other customer interaction is still required following the referral (ISO 8583 message type 0220).

REFERRED

Note that the REFERRED message type is deprecated and the REFERRAL message type should be used instead.

Used for transactions with Type of 'PURCHASE' where the transaction has already been authorized by an offline referral process, but electronic signature capture or other customer interaction is still required following the referral. A MessageType of CONFIRM would normally be used here, but CONFIRM generates an advice message to eSocket.POS, for which device interaction is not supported. To solve this, a REFERRED message is treated as a request internally by eSocket.POS, but is then mapped to an ISO 8583 0220 advice message by the Referral Advice component before being sent online.

Notes:

  • A REFERRED transaction must have either Track2 or CardNumber and ExpiryDate set.

  • A REFERRED transaction may be used standalone, e.g. it may be sent from different terminal from the one which sent the original request.

  • Following a 0200 request (i.e. where MessageType was not set), a REFERRED transaction must be sent standalone. It should not be linked to the original request using the TransactionId , as this will cause it to be declined as a duplicate.

If the MessageType property is not set, a single online message will be used combining the authorization and financial legs of the transaction (ISO 8583 message type 0200).

PostalCode

Format

Description

The cardholder’s postal code, for use in address verification (AVS).

PassThruPanReference/PassThruVolatileP2peData

The Pass-through PAN Reference/Pass-through Volatile P2PE Data are implemented using PassThruPanReference/PassThruVolatileP2peData objects in the API, or Esp:PassThruPanReference/Esp:PassThruVolatileP2peData elements in the XML interface. The layout of these objects/elements are identical.

The Pass-through PAN Reference/Pass-through Volatile P2PE Data contain the P2PE data in scenarios where the device or PED implements a P2PE scheme supported by ACI, yet eSocket.POS does not drive the device or PED (for example, fuel forecourts). In these cases, the P2PE data will pass through eSocket.POS unmodified, without any processing performed on it.

Note the following:

  • While passing through eSocket.POS, P2PE Data are carried in the following structured data fields with the appropriate flags as indicated below:

  • Depending on the P2PE scheme involved:

    • Either field PassThruVolatileP2peData, or both fields PassThruVolatileP2peData and PassThruPanReference, are populated.

    • Not all the properties listed below are applicable or (when applicable) necessarily populated. See the Object and Property Conditions defined for these properties on the EspTransaction page.

Important
For dual message pair purchases, to ensure PCI compliance, the PassThruVolatileP2peData can only be present in the authorization (MessageType="AUTH"), not the completion (MessageType="CONFIRM"). The PassThruPanReference (when available) should be present in both messages.
Properties
Name Type

Scheme

String

Ksn

String

Data

String

SensitiveDataBlock

String

WhitelistFileName

String

MaxReliableBinLength

String

TlvMapping

Array of TLVMapping objects

Scheme

Format

Description

The P2PE Scheme Name (for example, "S1 3DES DUKPT" - which is the ACI standard triple-DES DUKPT P2PE scheme)

Ksn

Format

Description

The Key Sequence Number, encoded in capitalized hex. This value is a copy of the Ksn value from the SensitiveDataBlock.

Data

Format

Description

The Persisted Encrypted Sensitive Data Block or Volatile Encrypted Sensitive Data Block produced by the PED/device, with base64 encoding applied to it after it has been received from the PED.

SensitiveDataBlock

Format

Description

The Sensitive Data Key Block produced by the PED/device, with base64 encoding applied to it after it has been received from the PED. For the standard ACI standard triple-DES DUKPT P2PE scheme, this field is required in scenarios where P2PE transactions originate from a device/PED that is not driven by eSocket.POS, e.g. fuel forecourts. It is also required for custom P2PE schemes.

WhitelistFileName

Format

Description

The symbolic name of the whitelist file loaded on the device/PED. The host uses this name to validate the hash of the whitelist file on the PED against the hash of the whitelist file at the host. In other words, this field must match the name of a whilelist file loaded on the host.

Note:

Depending on the P2PE scheme, the whitelist hash is present in either the Data field (i.e. the Persisted/Volatile Encrypted Sensitive Data Block), or the SensitiveDataBlock field.

MaxReliableBinLength

Format

n..

Description

The number of starting digits of the PAN that are visible based on the P2PE scheme’s obfuscation scheme.

Note:

  • For the standard ACI standard triple-DES DUKPT P2PE scheme, in scenarios where P2PE transactions originate from a device/PED that is not driven by eSocket.POS (e.g. fuel forecourts), the host automatically sets this field based on the obfuscation scheme in the SensitiveDataBlock field, if absent:

    Obfuscation scheme Value

    S1

    6

    S3 (PAN length 16 or more)

    8

    S8

    8

    F1

    6

    F2

    6

    F3

    8

    F4

    6

    F5

    6

  • This field should be identical between the PassThruPanReference and PassThruVolatileP2peData fields.

TlvMapping
TlvMapping

If applicable to the P2PE scheme and available from the device/PED, the TLV mapping describes the encoding used for the TLV fields in the Data field (i.e. the Persisted/Volatile Encrypted Sensitive Data Block). The host assumes the default encoding of A / AN / ANS for each of the TLV values defined in the encrypted block (except for the whitelist-related tags). Typically, the device/PED will encode TLV values 57, 9F6B, 9F20 and 5A in the EMV specified binary formats. To indicate binary formatting (encoding) for these tags, the following tag value pairs needs to be populated in this field:

Tag name Value

57

B

9F6B

B

9F20

B

5A

B

Note:

  • The tag names should be hex strings. A value of B indicates binary for each of these tags.

  • For the standard ACI standard triple-DES DUKPT P2PE scheme, in scenarios where P2PE transactions originate from a device/PED that is not driven by eSocket.POS (e.g. fuel forecourts), the host automatically sets this field to the values in the previous table, if absent.

  • This field should be identical between the PassThruPanReference and PassThruVolatileP2peData fields.

Properties
Name Type Format

TagName

String

an..

TagValue

String

a..3

Rank

Format

n..

Description

Represents which set of logical devices the point of sale (POS) intends to communicate with.

RPS

Format

n1

Description

Has a value of 1 if the transaction is a rapid payment service transaction.

ReferralTelephone

Format

Description

The telephone number to be used in case an authorization response is returned with a referral response code.

SignatureData

Format

Description

Contains a representation of a customer signature which was captured electronically. Binary data will be translated to hex characters - e.g. the byte 255 (0xFF) will be translated to the two-character string 'FF'.

SignatureFormat

Format

Description

Indicates the format of the electronically-captured customer signature. For example, SIG, CMP, FBP, VBC.

SignatureRequired

Format

Description

Indicates whether a signature is required for this transaction or not.

Reversal

Format

Description

A value of true marks this transaction as a reversal. The Type property must also be set to define what type of transaction is being reversed.

Reversal Type
Format
Description

Indicates if a reversal can be online or offline. It can be set to ADVICE (offline) or REQUEST (online). If not set, the default is ADVICE.

Type

Format

ans.. / object : EspTransaction.Type

Description

Defines the type of the transaction, which must be one of the following values:

PURCHASE Used to request a purchase of goods and services

REFUND

Used to refund an amount to a customer’s account

DEPOSIT

Used to deposit funds to a cardholder’s account Used for Credit Admin Payment on Account with Cash/Check transactions for which appropriate ExtendedTranType must be set.Refer EspTransaction for ExtenedTranType values.

ADMIN

Used for administration advices, or for administration requests when the MessageType is set to 'ADMIN_REQUEST'.

DEBIT_ADJUSTMENT

Used to reverse funds deposited to a cardholder’s account, for example if a check used for a deposit is returned unpaid

CREDIT_ADJUSTMENT

Used to reverse funds withdrawn from a cardholder’s account.

CARD_ACTIVATE

Used to activate a gift card

CARD_DEACTIVATE

Used to deactivate a gift card

LOAD

Used to deposit funds to a gift card account

UNLOAD

Used to remove the remaining balance from the gift card account, keeping the account status active

CARD_ACTIVATE_REFUND

Used to activate and load funds to a gift card account.

QR_CODE_INITIATE

Used to initiate merchant-presented QR code transactions and to retrieve the QR code that customers should scan using their mobile devices.

QR_CODE_STATUS_REQUEST

Used to determine whether customers have completed payment for merchant-presented QR code transactions using their mobile devices after scanning a QR code, and to retrieve the transaction details from the host system once payment has completed.

TOKEN_LOOKUP

Used to retrieve a token generated for a transaction sent online from the store-and-forward queue.

The following values are deprecated and should preferably not be used:

AUTH Used to request authorization for a purchase (instead, use PURCHASE and set the MessageType to AUTH)

CONFIRM

Used to confirm an existing authorization or to notify of a completed transaction (instead, use PURCHASE and set the MessageType to CONFIRM)

REFERRAL

Used to send advice of a transaction that was approved through a referral process (instead, use PURCHASE and set the MessageType to REFERRAL)

SignatureButtonValue

Format

Description

Indicates the button input collected from the user.

'ACCEPT' - Accept/Done/Ok (Positive Response)

'CANCEL' - Cancel/Decline (Negative Response)

'CLEAR' - Clear

SignatureCheckbox1State

Format

Description

The state of the first check box after user input.

'TRUE' - Indicates the user selected this option

'FALSE' - Indicates the user did not change the state of this option

SignatureCheckbox1Text

Format

Description

Dynamic text label associated with the first check box on forms.

SignatureCheckbox2State

Format

Description

The state of the second check box after user input.

'TRUE' - Indicates the user selected this option

'FALSE' - Indicates the user did not change the state of this option

SignatureCheckbox2Text

Format

Description

Dynamic text label associated with the second check box on forms.

SignatureCheckbox3State

Format

Description

The state of the third check box after user input.

'TRUE' - Indicates the user selected this option

'FALSE' - Indicates the user did not change the state of this option

SignatureCheckbox3Text

Format

Description

Dynamic text label associated with the third check box on forms.

SignatureImageFormat

Format

Description

The format of the image to be returned in the response.

JPEG

PNG

TIFF

ASCII

SignatureImagePassedInResponse

Format

Description

Indicates whether or not the image should be included in the transaction response.

Must be set to TRUE or FALSE

SignatureScrollableText

Format

Description

This field will be used to populate the scrollable text area on the free text screens.

The following special character mark-ups are supported:

Special Character Mark-up

New Line

${newline}

Carriage Return

${carriagereturn}

SignatureStandAloneDynamicText

Format

Description

Stand alone dynamic text that will be displayed on the screens that host the check box prompts.

SignatureImageCategory

Format

Description

The category of the image.

SignatureImageEncrypted

Format

Description

Indicates whether the image in the user interface message request is encrypted.

Must be set to TRUE or FALSE

SignatureImageSequence

Format

Description

The sequence number to associate with the image. If more than one image is associated with a single transaction, this value will differentiate between them.

SignatureOriginalFormat

Format

Description

The format of the image in the user interface request.

JPEG

PNG

TIFF

ASCII

SignaturePromptName

Format

Description

The name or ID of the prompt.

SignatureLineItemTextCount

Format

n2

Description

The number of line items in the signature capture request.

SignatureLineItemText

Format

Description

The line items present in the signature capture request. Each line must be specified as a separate field and suffixed by the line number. The number of lines in the message is specified using the SignatureLineItemTextCount field. These fields should be specified as part of EspStructuredData.

For example, if there are 3 Signature Line Items, they would be specified as follows:

  SignatureLineItemText1="line item 1"
  SignatureLineItemText2="line item 2"
  SignatureLineItemText3="line item 3"
  SignatureLineItemTextCount="3"
EBT available cash benefits account balance

Format

Description

The available cash benefits account balance.

The field begins with one of the following signs:

  • C - credit

  • D - debit

  • U - unknown

The sign is followed by the numeric value which are expressed in the minor denomination, for example: D12345678901.

EBT beginning cash benefits account balance

Format

Description

The beginning cash benefits account balance.

The field must begin with one of the following signs:

  • C - credit

  • D - debit

  • U - unknown

The sign is followed by the numeric value which is expressed in the minor denomination, for example, D12345678901.

EBT ending cash benefits account balance

Format

Description

The ending cash benefits account balance.

This field must begin with one of the following signs:

  • C - credit

  • D - debit

  • U - unknown

The sign is followed by the numeric value which is expressed in the minor denomination, for example, D12345678901.

EBT beginning food stamp account balance

Format

Description

The beginning food stamp account balance.

The field must begin with one of the following signs:

  • C - credit

  • D - debit

  • U - unknown

The sign is followed by the numeric value which is expressed in the minor denomination, for example, D12345678901.

EBT ending food stamp account balance

Format

Description

The ending food stamp account balance.

This field must begin with one of the following signs:

  • C - credit

  • D - debit

  • U - unknown

The sign is followed by the numeric value which is expressed in the minor denomination, for example, D12345678901.

EBT available food stamp account balance

Format

Description

The available food stamp account balance.

The field begins with one of the following signs:

  • C - credit

  • D - debit

  • U - unknown

The sign is followed by the numeric value which are expressed in the minor denomination, for example: D12345678901.

EBT case number

Format

Description

EBT case number. For reversals, the EBT case number received in the original authorization response.

EBT response text

Format

Description

The full response text as sent by the EBT provider.

EBT voucher number

Format

Description

EBT voucher number. For offline transactions with referrals, the EBT voucher number in the referral.

Rts total healthcare amount

Format

n11

Description

The total amount of the healthcare benefits component of the transaction.

The numeric value is expressed in the minor denomination, for example, 12345678901.

Rts prescription amount

Format

n11

Description

The prescription amount contributing to the total healthcare benefits component of the transaction.

The numeric value is expressed in the minor denomination, for example, 12345678901.

Rts optical amount

Format

n11

Description

The optical amount contributing to the total healthcare benefits component of the transaction.

The numeric value is expressed in the minor denomination, for example, 12345678901.

Rts dental amount

Format

n11

Description

The dental amount contributing to the total healthcare benefits component of the transaction.

The numeric value is expressed in the minor denomination, for example, 12345678901.

Rts clinic amount

Format

n11

Description

The clinic amount contributing to the total healthcare benefits component of the transaction.

The numeric value is expressed in the minor denomination, for example, 12345678901.

LdAmountBarAndMinibar

Format

n12

Description

The total amount (in the minor denomination) of bar and in-room "mini-bar" items charged to the room.

LdAmountBillingAdjustment

Format

n12

Description

The amount (in the minor denomination) of any additional charges incurred after the cardholder’s departure from the lodging facility.

LdAmountGiftShop

Format

n12

Description

The total amount (in the minor denomination) of gift shop and speciality shop items charged to the room.

LdAmountLaundryAndDryCleaning

Format

n12

Description

The total amount (in the minor denomination) of laundry and dry cleaning items charged to the room.

LdAmountOtherServices

Format

n12

Description

The total amount (in the minor denomination) of miscellaneous items/services charged to the room, not specified elsewhere.

LdAmountOtherServicesIndicator

Format

Description

Indicates the type of charges provided in LdAmountOtherServices. Values are provided by the acquirer.

LdAmountPhoneCharges

Format

n12

Description

The total amount (in the minor denomination) of phone calls charged to the room.

LdAmountRestaurantAndRoomService

Format

n12

Description

The total amount (in the minor denomination) of restaurant and/or room service food charged to the room.

LdAmountRoomRate

Format

n12

Description

The daily room charges (in the minor denomination), exclusive of taxes and fees.

LdAmountRoomTax

Format

n12

Description

The daily room tax amount (in the minor denomination).

LdCustomerServicePhoneNr

Format

Description

The customer service number that the cardholder may call to resolve questions or disputes.

LdDateArrival

Format

Description

The date on which the cardholder checked in at the lodging facility.

LdDateDeparture

Format

Description

The date on which the cardholder checked out of the lodging facility.

LdFacilityPhoneNr

Format

Description

The local phone number of the lodging facility at which the cardholder stayed.

LdFolioNr

Format

Description

The lodging facility’s internal invoice or billing identification reference number.

LdProgramCode

Format

Description

A code allocated by the acquirer that identifies special circumstances, e.g. "frequent customer" or "no show".

LdNumberInParty

Format

Description

The number of guests as a value between 1 and 999.

LdNameOfGuest

Format

Description

The name of the guest.

AvailableOfflineSpendingAmount

Format

n12

Description

The Visa Available Offline Spending Amount.

QRCodeType

Format

Description

Indicates the QR code type.

The following QR code types are supported:

  • ALIPAY_CPQRC - AliPay consumer-presented QR code

  • PAYPAL_CPQRC - PayPal consumer-presented QR code

  • VENMO_CPQRC - Venmo consumer-presented QR code

  • ACI_URL_MPQRC - URL-based merchant-presented QR code issued by ACI

QRCodeData

Format

Description

The string data encoded in a QR code image . This may be a URL, an identification number or a proprietary data string containing transactional information. This field takes precedence over the BarcodeData field.

QRCodeHostRef

Format

Description

An additional QR code transaction reference that may optionally be returned by the host system for receipt printing and reporting purposes.

QRCodeImage

Format

Description

The QR code image, encoded in Base64.

QRCodeTranId

Format

Description

The QR code transaction ID.

APM

Format

Description

The alternative payment method used in a transaction that may be returned by the host system for receipt printing and reporting purposes.

PaymentBrand

Format

Description

The payment brand used in a transaction that may be returned by the host system for receipt printing and reporting purposes.

BarcodeData

Format

Description

The barcode data. This field will be ignored for QR code transactions if the QRCodeData field is set.

TransactionName

Format

Description

Indicates the name of the transaction.

StoreId

Format

Description

Indicates the store ID.

Memo

Format

Description

Indicates the memo for the transaction.

NetworkLabel

Format

Description

Identifies the payment network used for routing the transaction.

FinalAuthIndicator

Format

n1

Description

This field is used to indicate whether the amount requested is a pre-authorization, normal authorization or the final amount.

Possible values are:

0 Normal Authorization (The authorization amount can be different from the final transaction amount)

1

Final Authorization (The authorization amount is the final amount that the customer agrees to pay)

2

Pre-authorization (The authorization amount can be an estimate when the final amount is not yet known, which is typical for hotel, auto rental, e-commerce, and restaurant transactions)

DoNotDisplay

Format

Description

Set to TRUE if the transaction should not display welcome or the transaction outcome on the device.

If not set, this property defaults to FALSE .

Note : This property only applies to transaction type ADMIN and message type ADMIN_REQUEST.

1.4.3. EspInquiry

ChequeAccountNumber

Format

Description

The check/cheque account number in a check verification or check guarantee message.

This property is deprecated. Rather use an EspCheck object for a check verification or check guarantee transaction.

ChequeNumber

Format

Description

The check/cheque Number in a check verification or check guarantee message.

This property is deprecated. Rather use an EspCheck object for a check verification or check guarantee transaction.

ChequeInstitutionCode

Format

Description

The check/cheque institution code (for example, branch code or sort code) in a check verification or check guarantee message.

This property is deprecated. Rather use an EspCheck object for a check verification or check guarantee transaction.

EspCardInfo

EspCardInfo data is implemented by the EspCardInfo object in the API, or an Esp:EspCardInfo element in the XML interface.

EspCardInfo data contains information regarding a card, as configured in eSocket.POS. The various card details are listed in the table that follows:

Properties

Field

Type (Element, Attribute)

Description

CardProductName

Attribute

The name of the card product

EspAccount

Element

Details on Accounts that are associated with this card

Extracted

Element

Custom card information that is extracted from the card that is being read

EspAccount

EspAccount data is implemented by the EspAccount object in the API, or an Esp:EspAccount element in the XML interface.

EspAccount data contains information regarding an account, as configured in eSocket.POS. The various account details are listed in the table that follows:

Properties

Field

Format

Type (Element, Attribute)

Description

Type

n..2

Attribute

Type of Account

Name

ans..

Attribute

Name of the Account

EmvFallbackAllowed

Boolean

Attribute

Indicates if fallback from EMV to magstripe is allowed

DefaultPreauthAmountMsr

n..12

Attribute

Default pre-authorization amount allowed for magstripe transactions

DefaultPreauthAmountEmv

n..12

Attribute

Default pre-authorization amount allowed for contact EMV transactions

DefaultPreauthAmountCtls

n..12

Attribute

Default pre-authorization amount allowed for contactless transactions

PinRequired

Boolean

Attribute

Indicates if a PIN is required

Extracted

Extracted data is implemented by the Extracted object in the API, or an Esp:Extracted element in the XML interface.

Extracted data contains card information that is extracted from the card that is being processed. The data to be extracted is configurable in eSocket.POS. Refer to the eSocket.POS User Guide for details on configuring PipelineComponentCardProduct. The details of extracted data are listed in the table that follows:

Properties

Field

Format

Type (Element, Attribute)

Description

Name

ans..

Attribute

Name of the extracted data

Value

ans..

Attribute

Value of the extracted data

Error

ans..

Attribute

Error message when data to be extracted is not present

Type

Format

ans.. / object : EspInquiry.Type

Description

Defines the type of the transaction, which must be one of the following values:

BALANCE

Used to check the balance on a cardholder’s account

AVAILABLE_FUNDS

Used to check the available funds on a cardholder’s account

MINI_STATEMENT

Used to view details concerning recent transactions on a cardholder’s account

CARD_READ

Used to request eSocket.POS to read a card and return card details without sending a transaction upstream

GENERAL_INQ

Used to perform account lookup and check the application status for Credit Admin transactions

CARD_VERIFICATION

Used to send the merchant’s intent to store the card details to the network

TRAN_INQUIRY

Used to inquire the status of a transaction sent to eSocket.POS in the case of a network failure or a lost response.

TERMINAL_STATUS

Used to inquire the status of eSocket.POS that serves this terminal.

The following types are deprecated, and an EspCheck object should be used instead of an EspInquiry with these types:

CHEQUE_VERIFICATION

Used to verify a check transaction.

CHEQUE_GUARANTEE

Used to request guarantee of a check transaction.

PayeeNameAndAddress

Payee name and address is implemented using a PayeeNameAndAddress object in the API, or an Esp:PayeeNameAndAddress element in the XML interface.

Payee name and address contains identification and billing information for a payee. This field is used when making a payment to a customer defined payee, where the payee is defined by its address details. A bank, for example, would use these details to post a check to the payee on the bank customer’s behalf.

Properties

Field Format Description

Name

ans35

Name of the payee

AddressLine1

ans35

First address line

AddressLine2

ans35

Second address line

AddressLine3

ans35

Third address line

City

ans35

City payee is located in.

Region

ans20

Region/state the payee’s city is located in.

PostalCode

ans20

Postal code of the payee’s city

CountryCode

a3

3-letter ISO country code

Phone

ans35

Phone number of the payee

AdditionalPayeeInformation

Additional payee information is implemented by the AdditionalPayeeInformation object in the API, or an Esp:AdditionalPayeeInformation element in the XML interface.

Additional payee information can contain additional payee name and address details. It’s an extension of PayeeNameAndAddress

Properties

Field Type (Element, Attribute) Description

PayeeContact

Element

This field contains additional contact information for a payee, such as PatriotPlace, PatriotExpirationDate, etc.

AccountData

Account data is implemented by the AccountData object in the API, or an Esp:AccountData element in the XML interface.

Account data can contain account details that are used for a credit application.

Properties

Field Type (Element, Attribute) Description

Account

Element

This field contains additional account data such as SerialNumber, ReferenceNo, etc.

DisplayData

Format

Description

For Credit Admin transactions, this field is sent back in the response. It contains the text reason why the transaction was declined, if a declined response is sent.

PrintData

Format

Description

For Credit Admin transactions, this field is sent back in the response. It contains current information about the account, such as card number, card expiration date, credit limit, and temporary credit limit.

Each print message consists of three elements:

  • Length of the print message, excluding the length field, expressed as 'LLLL'.

  • The print destination field. (See the table below for supported print destination codes). This field contains the number of print destination codes, print designation code or codes, and printer number.

  • The print message data.

Print destination code Description

A1

Customer receipt

A2

Customer check

C2

Register journal

D3

Register slip

P1

Account number

P2

Expiration date Format YYMM

P3

Credit line Format DDDDDDDDDDDDCC+ Example: $500 = 00000000050000+

P4

Temporary credit line

P5

Payment purchase indicator

P6

Customer service phone number

P7

POS status description

P8

Current account balance Format DDDDDDDDDDDDCC+

P9

Last statement balance Format DDDDDDDDDDDDCC+

Q0

Open to buy Format DDDDDDDDDDDDCC+

Q1

Minimum payment due Format DDDDDDDDDDDDCC+

Q2

Payment due date

Q3

Customer name

Q4

Product name

Q5

In store payment allowed

Q6

APR Format XX.XX

TerminalStatus

Format

Description

This field is sent back in the response. It contains current monitoring information on all the entities monitored for a terminal, and has the following format:

<status_fields>#<hardware_characteristics>#<values>#<misc_info>#<condition>

For example, the following can be returned in the terminal status :

000001000000020300#010101010101#Magnetic Stripe Card Reads12|~1 successful~2 reads|#2|1|243|#1

The individual fields, which are separated by the '#' character, are defined as follows:

  • <status_fields> contains the status of the different monitored entities, in the form of a list of 2-digit status codes. Each code corresponds to the status of a particular entity and has one of the following values:

    Value Meaning

    00

    Entity is OK

    01

    Entity is Suspect

    02

    Entity is Critical

    03

    Entity is Disconnected

    The order in which the status codes appear is as follows:

    Position Entity

    1

    Information store

    2

    Sink

    3

    Smartcard reader

    4

    Magnetic stripe card Reader

    5

    Cheque/check reader

    6

    Display

    7

    Keypad

    8

    PIN pad

    9

    Signature capture device

    10

    Barcode reader

    For example, the status field in the example response given above contains the following value:

    000001000000020300

    That is, the smartcard reader was Suspect (position 3, value of '01'), the keypad was Critical (position 7, value of '02'), and the PIN pad was disconnected (position 8, value of '03').

    Notes:

    • If a certain entity is not present in the current terminal setup, the status code for that entity will be '00' - OK.

    • Status entries can be added in future as new device types or other monitored entities are added to eSocket.POS.

  • <hardware_characteristics> contains hardware related information required by PosConnect. This field is not relevant to POS.

  • <values> contains information used by PosConnect to construct the histograms on the Terminals Monitor console. These histograms indicate values expressed as a proportion of a maximum. This field is formatted as a pipe-delimited ("|") series of values or labels, with proportional values separated by the character '~'. Labels are indicated by a leading '~', whereas values are not. For example, in the given example, the response above this field contains the following:

    Magnetic Stripe Card Reads~1~2|~1 successful~2 reads|

    There are two items here, a values indicator and a label which are separated by the '|'. The first item is a values indicator, since it does not start with a '~' and the second is a label. The resultant histogram from the above example would appear in the Terminals Monitor console as:

    image

    Value bars that could appear in this field include:

    • The number of successful magnetic stripe card swipes out of the total number of magnetic stripe card swipes.

    • The number of successful smartcard reads out of the total number of smartcard reads.

    • The number of successful check reads out of the total number of check reads.

    • The number of successful signature captures out of the total number of signature capture attempts.

    • The number of successful barcode reads out of the total number of barcode read attempts.

    • The number of offline transactions out of the total number of transactions.

    • The number of offline approved transactions out of the total number of offline transactions.

  • <misc_info> contains the following information, separated (and followed) by the pipe character ("|"):

    • The number of transactions in the store and forward queue (SAFQ), which includes the transaction at the head of the queue that is being sent to the host.

    • The "SAFQ not clearing" indicator, i.e. 0 (SAFQ is clearing), 1 (SAFQ is not clearing).

    • If the SAFQ is not clearing, the approximate time in minutes since the transaction at the head of the SAFQ received a response from the host.

    • Contains a single digit representing the limits state of the terminal SAFQ. It has one of the following values:

      Value Condition Description

      0

      NORMAL

      In this state, the monitored values will be less than the SAFQ limits. For limits with a low water mark, the monitored values will not necessarily be less than or equal to the low water mark. In other words, in this state no limit with a lower water mark would have been reached recently without also fully recovering (see the Recovering state).

      1

      LIMIT_REACHED

      One or more of the SAFQ limits will have been reached, i.e. the monitored value(s) will be greater than or equal to the limit(s). Furthermore, the monitored value(s) that reached the limit will not have dipped to a point where it is less than their corresponding limit(s).

      When the state is NORMAL, an incoming transaction that will cause the state to change to LIMIT_REACHED will still be accepted. After the state is changed to LIMIT_REACHED, any subsequent 0100/0200 will be rejected with response code 05 and message reason code 9690.

      2

      RECOVERING

      One or more of the SAFQ limits with a low water mark will recently have been reached (per the LIMIT_REACHED state) and the monitored value(s) that reached the limit will have dipped to a point where it is less than their corresponding configured limits, but greater than or equal to the low water mark(s).

      In this state, any subsequent 0100/0200 will be rejected with response code 05 and message reason code 9690.

      In the example response above, this contains the value:

      2|1|243|1|

      That is, there are currently 2 transactions in the store and forward queue (SAFQ) (including the transaction at the head of the queue that is being sent to the host), the SAFQ is currently not clearing and has been stuck for 243 minutes (i.e. 4 hours and 3 minutes), and the SAFQ is reporting the limits state of 1 (LIMIT_REACHED).

      An example of when the SAFQ is clearing would be:

      3|0||0|

      That is, there are currently 3 transactions in the SAFQ (including the transaction at the head of the queue that is being sent to the host), the SAFQ is clearing, and the SAFQ is reporting the limits state of 0 (NORMAL).

      Note
      In future, further miscellaneous values may be added, separated by pipe characters.
  • <condition> contains a single digit representing the overall status of the terminal. It has one of the following values:

    Value Condition Description

    0

    OK

    The terminal is operating normally.

    2

    Suspect

    The terminal has encountered a number of errors but is still successfully processing transactions.

    1

    Critical

    The terminal is no longer able to process transactions.

    In the example response above, this contains the value:

    1

    That is, the status of the terminal is Critical.

MerchantOpcSelection

Format

n1

Description

Indicates whether the merchant or cardholder OPC selection mode should be applied.

0 Cardholder does the OPC selection

1

Merchant does the OPC selection

1.4.4. EspMerchandise

ConsumerAddress

Format

Description

The consumer address, as returned by the issuer in a prepaid merchandise response.

ConsumerId

Format

Description

The consumer ID, for instance a meter serial number, as returned by the issuer in a prepaid merchandise response.

ConsumerName

Format

Description

The consumer name, as returned by the issuer in a prepaid merchandise response.

DescriptiveValue

Format

Description

A message that describes the value of a merchandise item.

HostResponseCode

Format

Description

The response code generated by a host system in response to a merchandise request.

Since the formatting of the host response code is specific to the host system and is not standardized, the application developer should refer to the response code and action code properties to determine the result of the request.

IssuerName

Format

Description

Name of the issuer of the merchandise item.

IssuerId

Format

Description

Identifier of the issuer of the merchandise item.

IssuerRegistrationNr

Format

Description

Registration number of the issuer of the merchandise item; for instance a tax registration number.

IssuerTelephoneNumber

Format

Description

Telephone number of the issuer of the merchandise item, for query purposes.

ItemAmount

Format

Description

The amount of a merchandise item. Values are expressed in the minor denomination.

ItemBalance

Lists of balances returned in a merchandise response are implemented using an array of MerchandiseBalanceItem objects in the API, or as Esp:ItemBalance elements in the XML Interface.

Properties

Name Type

ProductCode

String

ProductName

String

ExpiryDate

String

Quantity

String

QuantityDescription

String

ItemBalance ExpiryDate

Format

Description

Expiry date of a merchandise balance, returned in a merchandise balance list item in a response to a Merchandise request.

ItemBalance Quantity

Format

Description

The quantity of a merchandise balance, returned in a merchandise balance list item in a response to a Merchandise request.

ItemBalance ProductCode

Format

Description

Product code of a merchandise balance, returned in a merchandise balance list item in a response to a Merchandise request.

ItemBalance ProductName

Format

Description

Product name of a merchandise balance, returned in a merchandise balance list item in a response to a Merchandise request.

ItemBalance QuantityDescription

Format

Description

The descriptive quantity of a merchandise balance, returned in a merchandise balance list item in a response to a Merchandise request.

ItemExpiryDate

Format

Description

The expiry date of a merchandise item.

ItemMessage

Format

Description

Instructions on how to use a merchandise item; for example, how to enter a recharge PIN. Line breaks are denoted by '\|'.

ItemPin

Format

Description

The PIN of a merchandise item, for instance the activation code to be entered for telephone prepay services. If more than one PIN is supplied by the host, this field may contain multiple values separated by commas.

ItemSerialNumber

Format

Description

The serial number of a merchandise item, for example a voucher serial number.

ItemTaxAmount

Format

Description

The tax amount charged on the merchandise item. Values are expressed in the minor denomination.

NetworkId

Format

Description

Identifies the network to supply the requested merchandise.

NetworkName

Format

Description

The descriptive name of the network for a merchandise request.

ProductId

Format

Description

Identifies the merchandise product that is requested.

When using the API, the POS product ID is specified in this field. This POS product ID is mapped to the product ID used by the prepay network based on a mapping defined in the database table esp_merchandise_config .

ProductName

Format

Description

The product name of a merchandise item.

ProductType

Format

Description

Identify the type of merchandise product. The following values are currently supported:

  • TELEPHONE PREPAY

  • ELECTRICITY

  • OTHER

ResponseMsg

Format

Description

A message sent by the host explaining the response code in response to a merchandise request.

TenderAmount

Format

Description

The amount of the tender for a merchandise request. Values are expressed in the minor denomination.

TenderSerialNumber

Format

Description

The tender serial number for a merchandise request, for example a voucher serial number.

TenderType

Format

n2

Description

The type of payment offered as tender for a merchandise request.

00 None

10

Cash

20

Check

30

Credit card

40

Debit card

50

Voucher

60

AutoCash

99

Other

Token

A token returned in a merchandise response are implemented using a MerchandiseToken object in the API, or an Esp:Token element in the XML Interface.

Properties

Name Type

TokenDescription

String

TokenValue

String

TokenDescription

Format

Description

A description of a token returned in a response to a merchandise request.

TokenValue

Format

Description

The value of a token returned in a response to a merchandise request.

TranSequenceNumber

Format

Description

A number that uniquely identifies a merchandise request transaction to the receiver.

Type

Format

ans.. / object : EspMerchandise.Type

Description

Defines the type of the merchandise request, which must be one of the following values:

REQUEST Used to request merchandise

CONFIRM

Used to confirm a previous merchandise request

PROCURE

Used to request and confirm merchandise in a single step

REVERSE

Used to request that merchandise previously purchased should be reversed.

Note that eSocket.POS does a merchandise reversal as an online adjustment using a 0200 request message, not a 0420 advice message. An online request is required because many networks only allow merchandise purchases to be reversed during a limited interval after purchase, after which a reversal request will be declined, whereas an advice could not be declined. A 0200 adjustment is used instead of a 0400 reversal request, because eSocket.POS does not currently support 0400 reversal messages.

UserId

Format

Description

Identifies the user in a merchandise request. For telephone prepay, the user ID would be the MSISDN (phone number) of the user.

1.4.5. EspCheck

AccountNr

Format

Description

The check/cheque account number at the financial institution.

CheckIdCard

Format

Description

A value of true indicates that a check/cheque ID card was used for this transaction.

Check ID cards are issued by the retailer to identify their customer when paying by check. Note that check cards not issued by the retailer, e.g. those issued by a third party such as the bank or financial institution, are not considered as check ID cards.

CheckNr

Format

Description

The check/cheque number in a check verification or check guarantee message.

CheckType

Format

an1

Description

The type of check/cheque that was tendered.

P Personal

L

Payroll

B

Business

G

Government

K

Bank

DriversLicenseNr

Format

Description

The driver’s license number of the person presenting the check/cheque.

DriversLicenseStateCode

Format

Description

The driver’s license state code of the person presenting the check/cheque.

GenericIdNr

Format

Description

The identification number of the person presenting the check/cheque when an ID other than a driver’s license or check ID card is presented .

GenericIdType

Format

Description

The generic identification type of the person presenting the check/cheque.

Examples of possible generic identification types are:

PP Passport

ID

Identity Document

SS

Social Security Number

NI

National Insurance Number

IdCrossChecked

Format

Description

A value of true indicates that the identification presented by the customer was validated by a second identification. This property should be populated based on a second attempt to approve the transaction after receiving a Response Code of 47 - 'Identification Cross Checked Required', which indicates that a second ID is required.

MessageType

Format

Description

Defines the message type of the check verification or check guarantee transaction and must be one of the following values:

TRANREQ A Transaction Request (ISO 8583 message type 0200) may be used to request authorization and is processed in the same manner as an Authorization Request (ISO 8583 message type 0100).

AUTHADV

An Authorization Advice (ISO 8583 message type 0120) advises that a check transaction has been approved. This may be required if a supervisor wishes to override a decline response code.

CONFIRM

A Transaction Advice (ISO 8583 message type 0220) advises that a check transaction has been approved. This may be required if a supervisor wishes to override a decline response code or for the completion of an Electronic Check Conversion (ECC) transaction. It is processed in the same manner as an Authorization Advice (ISO 8583 message type 0120).

If the MessageType property is not set, an authorization message is used (ISO 8583 message type 0100).

SupervisorId

Format

Description

A value identifying the supervisor that initiated the transaction. This would usually be used for an Authorization Advice (ISO 8583 message type 0120) or a Transaction Advice (ISO 8583 message type 0220) when a supervisor overrides a decline response code and forces the transaction to be approved.

TransitNr

Format

Description

The ID of the financial institution that holds the account excluding the transit number check digit. The check/cheque transit number is also referred to as an institution code, a branch code or a sort code.

Type

Format

ans.. / object : EspCheck.Type

Description

Defines the type of the transaction and must be one of the following values:

VERIFICATION Used to verify a check/cheque transaction

GUARANTEE

Used to request guarantee of a check/cheque transaction

ECCVERIFY

Used to verify an Electronic Check Conversion (ECC) transaction.

ECCGUARANTEE

Used to request guarantee of an Electronic Check Conversion (ECC) transaction.

ECC

Used to process an Electronic Check Conversion (ECC) transaction.

UnformattedMICR

Format

Description

The magnetic ink character recognition (MICR) line of a check/cheque.

Special characters should be substituted as follows:

MICR Font

Symbol

Meaning

ASCII Equivalent

E13-B

image

Transit Symbol

T

image

On-Us Symbol

U

image

Amount Symbol

$

image

Dash Symbol

-

CMC-7

image

SI

A

image

SII

B

image

SIII

C

image

SIV

D

image

SV

E

For example, a MICR line from a USA personal check is shown here:

image

This should be supplied to eSocket.POS as follows:

T123456780T 123456789U 3953 $0000000109$
Col 1 Col 2

Cell 1.1

Cell 1.2

Cell 2.1

Cell 2.2

Col1 Col2

C11

C12

MICRKeyedOrScanned

Format

n1

Description

Indicates if the magnetic ink character recognition (MICR) data is keyed or scanned.

0 - Keyed

1

- Scanned

DriversLicenseDateOfBirth

Format

Description

The date of birth as seen on the driver’s license.

DriversLicenseKeyedOrScanned

Format

n1

Description

Indicates if the driver’s license information was keyed or scanned.

0 - Keyed

1

- Scanned

DriversLicenseExpirationDate

Format

Description

The expiration date of the driver’s license.

MICRLineFormatCode

Format

n2

Description

Indicates the format of the magnetic ink character recognition (MICR) data.

CustomerName

Format

Description

Name of the customer, as found on the check.

CustomerPhoneNumber

Format

n10

Description

Phone number of the customer, as found on the check.

CustomerAddress

Format

Description

Street address of the customer on the check.

CustomerCity

Format

Description

City of the customer, as found on the check.

CustomerState

Format

a2

Description

State of the customer, as found on the check.

CustomerZip

Format

Description

Zip code of the customer, as found on the check.

CheckIssuedDate

Format

Description

The date on which the check was issued.

TruncationTransactionID

Format

Description

The truncation transaction identifier of the check.

MICRSequenceNr

Format

Description

The sequence number of the magnetic ink character recognition (MICR) .

TruncationIndicator

Format

a1

Description

Indicator for processing checks via check truncation.

ServiceCharge

Format

ns5

Description

Returned check fee that will be charged if the check bounces. Used for check truncation.

DenialNr

Format

Description

Denial Number or level of risk received by the processing bank for declined transactions.

SettlementCode

Format

n1

Description

Settlement Code returned by Visa to indicate if the transaction is to be settled. Used for Visa eChecks.

1 - Visa Settlement Code

2

- ACH Settlement Code

ProprietaryResponseInfo

Format

Description

Identifies proprietary response information defined by an authorizing agent.

1.4.6. EspReconciliation

CreditsAmount

Format

n16

Description

The total amount of all credit transactions (in the settlement currency), other than reversals, processed since the last settlement cutover

CreditsReversalAmount

Format

n16

Description

The total amount of all reversal credit transactions (in the settlement currency), having a credit effect on the cardholder’s account, processed since the last settlement cutover

DebitsAmount

Format

n16

Description

The total amount of all debit transactions (in the settlement currency), other than reversals, processed since the last settlement cutover

DebitsReversalAmount

Format

n16

Description

The total amount of all reversal debit transactions (in the settlement currency), having a debit effect on the cardholder’s account, processed since the last settlement cutover

NetSettlementAmount

The net of all gross debit and gross credit amounts for a settlement period for a specific terminal. Specified in the settlement currency code.

Properties

Name Type

Amount

String

Sign

String

Amount

Format

n16

Description

The net settlement amount. Amounts are given in the minor denomination of the settlement currency.

Sign

Format

x1

Description

The sign of a Net Settlement Amount: 'C' for credit, or 'D' for debit.

NumberOfCredits

Format

n10

Description

The total number of credit transactions, other than reversals, processed since the last settlement cutover.

NumberOfCreditsReversal

Format

n10

Description

The total number of reversal credit transactions, having a credit effect on the cardholder’s account, processed since the last settlement cutover.

NumberOfDebits

Format

n10

Description

The total number of debit transactions, other than reversals, processed since the last settlement cutover.

NumberOfDebitsReversal

Format

n10

Description

The total number of reversal debit transactions, having a debit effect on the cardholder’s account, processed since the last settlement cutover.

NumberOfAuthorizations

Format

n10

Description

The total number of authorization transactions processed since the last settlement cutover.

NumberOfInquiries

Format

n10

Description

The total number of inquiries processed since the last settlement cutover.

SettlementCurrencyCode

Format

n3

Description

The settlement currency of the transaction amount. See ISO 4217 (1990): Codes for the Representation of Names of Currencies and Funds.

1.4.7. EspNetwork

NetworkMngInfoCode

Format

n3

Description

A code that defines the type of network management needed.

Contact your support provider for a list of additional values. The value below is operational for a standard Postilion installation.

  • 130 - EMV CAPK Download

  • 301 - Echo test

SecurityInfo

Format

Description

In a response, this field provides security related control information. This field is right padded with binary zeros to 48 bytes. The binary data is represented as hexadecimal characters.

For a key change transaction this field contains the encrypted key in the first 8, 16, or 24 bytes, depending on the key length, followed by up to 4 of the most significant bytes of the key check digits. The key check digits are defined to be the value of 8 zero bytes encrypted under the key.

POS Data

Format

Description

POS Data is implemented using an EspPosData object in the API, or an Esp:PosData element in the XML interface.

This field contains data passed from the Point-of-Service (POS) system, e.g. a cash register. This is a fixed length field of 22 alpha numberic special characters consisting of 3 data elements:

Name Type

PosTerminalId

String

PosSequenceNr

String

PosOperatorId

String

1.4.8. Administrative

Action

Format

Description

Indicates the action to be taken as a result of an EspAdmin message.

Possible values:

INIT CLOSE

EventData

Format

Description

Data associated with the event or callback, dependent on the event ID. See the EventId page for details of event data associated with standard eSocket.POS events and callbacks. Also see the relevant device driver and custom component User Guides for details of supported events and callbacks.

EventId

Format

Description

See the Events and Callbacks page for a description of events and callbacks.

The events and callbacks available to an eSocket.POS deployment are limited to those supported by the POS application, the eSocket.POS device driver and the eSocket.POS components used. See the device driver and custom component documentation for further information about the events they support.

It is recommended that the event and callback requirements are discussed in detail during the solution specification phase.

Standard Event IDs

Each event and callback is identified with an Event ID. The following table defines the current set of standard eSocket.POS Event IDs. Whether the Event ID identifies an event or callback is indicated against the Event ID. Certain Event IDs may denote an event or a callback.

The Source column indicates whether the event is normally raised by the POS application, 'generic' eSocket.POS (i.e. the standard eSocket.POS product), an eSocket.POS device driver or an eSocket.POS custom component. *IMPORTANT NOTE: * a standard event may not always be available. For example, where the Source indicates an eSocket.POS device driver this does not mean that every device driver implements this event/callback. Where the Source is the POS application this does not mean that the device driver or pipeline components necessarily handle the event or callback. Where the Source is the standard eSocket.POS product this may rely on a particular eSocket.POS component being used.

Event ID Source Description Event Data Callback Response Data

APPLICATION_SELECTED (event)

eSocket.POS (device driver)

Informs the POS application of the selected EMV application.

The name of the selected EMV application, for example, "Mastercard".

n/a

AUTO_DEVICE_UPDATE (event)

eSocket.POS (device driver or custom components)

Informs the POS that a device update has been initiated.

The data may be used to indicate the type of files which are being downloaded.

NOTE

This event is not currently widely supported.

NOTE

If raised as an event, when the update has completed the DEVICE_UPDATE_STATUS event may be raised. In the meantime the DEVICE_UPDATING event may be raised.

Optionally indicates the type of update which is underway.

Standard values currently include:

  • FIRMWARE - loads firmware only

  • FLASH - loads the flash file only

  • CONFIG - loads configuration such as the card configurations, merchant data, and key index tables

  • SCREENS - loads device screens only

If the update combines more than one of these types then they can be indicated in a pipe delimited string, for example, "FIRMWARE|FLASH|CONFIG|".

n/a

AUTHORIZE (callback)

eSocket.POS (generic)

Requests an authorization from the POS application when eSocket.POS does not have its own online authorization channel to an upstream Postilion system, and the POS has its own method of online authorization.

Refer to the Callback Sink documentation in the eSocket.POS User Guide for further context to this event.

If the Callback Sink does not receive a response to the callback, it will time out and decline the transaction.

A string of key-value pairs denoting the transaction data. See the section below for details.

A string of key-value pairs denoting the response data. See the section below for details.

BARCODE_READ (event)

eSocket.POS (device driver)

Returns a scanned barcode and symbology to the POS.

This event sends the barcode data to the POS application.

For example, BarcodeData =<Base64 string>; Symbology =1; BarcodeStatusCode =0

NOTE

Each data parameter will be delimited with a semi-colon.

n/a

BARCODE_READER (callback)

POS application

Callback used to enable or disable the barcode reader.

The configured device driver must support this functionality.

The following two types of data elements are allowed:

  • Enable: Enables the barcode reader.

    This data element can have the following optional parameters:

    scanMode : <1 or 2> - Specifies whether the device must be enabled for only a single barcode scan (1) or multiple scans (2). The value must be an integer. If not specified, multiple scans (2) is enabled.

    For example, Enable ; scanMode : 1

    NOTE

    Each data parameter must be delimited with a semi-colon.

  • Disable: Disables the barcode reader.

The following are possible responses:

  • scanMode : <1 or 2>
    Returns a value of 1 if the barcode reader is enabled in single read mode is enabled or 2 if enabled for multiple scans.

  • readerEnabled : <true or false>
    Returns the current status of the barcode reader.

  • OK
    For all successful callbacks.

  • Error : <error message>
    For all error conditions.

Examples:

  • Enable response:
    scanMode:1;readerEnabled:true;OK

  • Disable response:
    readerEnabled:false;OK

  • Error response:
    Error : Device failure occurred while processing Callback: BARCODE_READER with data : Enable

CANCEL_CARD_READ (event)

POS application

Cancels a card read attempt.

If attempting a chip or magnetic stripe read then this will be aborted, and the transaction will either fallback or be declined (depending whether the configuration allows fallback for this card).

If fallback from a chip read occurs on a combined reader* it will be to manual PAN entry. On a dual card reader* it may be to magnetic stripe, depending on the reason code that the device driver associates with the event.

This event is used in scenarios where the merchant chooses to allow fallback even in the absence of card misreads. Examples of where this may be the case is where a swipe reader does not report misreads or where there is device failure. Other custom scenarios also exist.

If necessary the event data can be used to stipulate the reason code that is associated with this event.

* On a combined reader the chip and magnetic stripe readers are integrated into a single physical device. On a dual reader the chip and magnetic stripe are read by separate physical devices.

NOTE

This event is not currently widely supported.

Can optionally be set to control the reason code that the device driver associates with this event.

Possible values include:

"3" - Card Read Retries Exceeded. Whether manual PAN entry is allowed depends upon the PAN component configuration. On a dual card reader fallback to magnetic stripe will be attempted rather than fallback directly to magnetic stripe.

"8" - Device Failure. Whether manual PAN entry is allowed depends upon the PAN component configuration. On a dual card reader fallback to magnetic stripe will be attempted rather than fallback directly to manual PAN entry.

"12" - Operator Cancelled. Manual PAN entry will always be allowed. On a dual card reader fallback is directly to manual PAN entry.

n/a

CANCEL_CARD_SWIPE (event)

eSocket.POS (generic)

Informs the POS that a card swipe was cancelled.

None.

n/a

CANCEL_TRAN (event)

POS application

Cancels a transaction at a point where a customer is prompted to interact with one of the POS devices. A successful cancel event results in a transaction declined response with message reason code of operator declined.

NOTE

This event is not the equivalent of a reversal of a transaction.

The data string associated with this event is the TransactionId of the transaction being cancelled.

n/a

CAPK_RETRIEVAL_COMPLETE (event)

eSocket.POS (generic)

Notifies the POS that the CA Public Key (CAPK) file has been retrieved from the host.

None.

n/a

CARD_ERROR (event)

eSocket.POS (device driver)

A general card error occurred after reading the card.

None.

n/a

CARD_INFO (event or callback)

eSocket.POS (custom component)

Provides card-related information to the POS following the card read stage of the transaction. The POS may use this information to:

  • set the display;

  • decide whether to abort the transaction (if used as a callback)

If the transaction is aborted then the response code and message reason code returned to the POS may be set using the callback response data. If not set then appropriate default values will be used.

NOTE

This event is not currently widely supported. In future it may be supported in the standard product.

Card information formatted into delimited name and value pairs, where the name corresponds (where applicable) to the name of the property which exposes the data via the eSocket.POS API.

<name>=<val>;<name2>=<val2>;…​

For example, CardProductName=MasterCard;PinBypassAllowed=1;

Typically the property names may include the following:

  • IssuerIdentificationNumber - the 1st 6 digits of the PAN

  • CardProductName - as configured against the card

  • EncryptedCardNumber - encrypted PAN

  • HashedCardNumber - hashed PAN

  • TokenizedCardNumber - tokenized PAN

  • AccountType - the 2-digit account type

  • PinBypassAllowed - set to "1" if the card product allows PIN bypass; "0" otherwise

Possible responses are:

  • "1" - the transaction must be allowed to continue.

  • "0" - the transaction must be aborted using a default response code and message reason code.

  • "ResponseCode=XX; MessageReasonCode=XXXX" where X represents an integer value - the transaction must be aborted using the ResponseCode and MessageReasonCode provided.

CARD_INSERTED (event)

eSocket.POS (device driver)

A card has been inserted into a card reader.

None.

n/a

CARD_INSERTED_WRONG_WAY (event)

eSocket.POS (device driver)

When the card is inserted but the chip end of the card is not inserted into the terminal.

None.

n/a

CARD_SWIPED (event)

eSocket.POS (device driver)

A card has been swiped.

None.

n/a

CHECK_INSERTED (event)

eSocket.POS (device driver)

A check has been inserted into a check reader.

None.

n/a

CARD_READ (event)a

eSocket.POS (device driver)a

A card has been successfully read.

The data consists of key-value pairs separated by semi-colon characters, where the value for each pair is enclosed in single quotes. The following information may be present in the event data, depending on the component that raised the event:

  • The PAN entry mode (always sent);

  • The obfuscated Track 2 data (optionally sent by the Pre-swipe pipeline component).For non-P2PE transactions and whitelisted cards, clear Track 2 data will be returned if the "Mask Sensitive Data" option is unchecked for the card profile configuration in ConfigServer.

  • The card product name (optionally sent by the Pre-swipe pipeline component).

  • The account type (only sent if the optional parameter CARD_READ_EVENT_MODE is set to 1).

  • The message reason code (only sent if the optional parameter CARD_READ_EVENT_MODE is set to 1 and the 0600 response message is a decline).

  • The message response code (only sent if the optional parameter CARD_READ_EVENT_MODE is set to 1 and the 0600 response message is a decline).

  • The pin entry status (only sent if the optional parameter CARD_READ_EVENT_MODE is set to 1 and quick chip is enabled). Below is the list of different status returned:

    • PinEntered: This status is returned when the pin is entered.

    • PinNotRequired: This status is returned when the pin is not prompted.

    • PinBypass: This status is returned when the pin prompt is bypassed by customer.

      Note: The PinEntryStatus key-pair is not supported for contactless EMV transactions as PIN entry statistics are not available for these transactions when Pre-swipe is enabled.

      An optional user parameter CARD_READ_FIELDS can be used to explicitly configure the list of fields to be sent in the CARD_READ event data. The inclusion of fields still depends upon the respective conditions as described above, even If the CARD_READ_FIELDS parameter is set.

      If the parameter is not set, PanEntryMode, Track2, CardProductName, Account, MessageReasonCode and ResponseCode fields are sent by default.

      An optional user parameter, CARD_READ_EMV_TAGS, can be used to explicitly configure the list of EMV tags to be sent in the CARD_READ event data.

      The inclusion of these fields still depends on the respective conditions described previously, even if the CARD_READ_EMV_TAGS parameter is set.

Examples:

  • PanEntryMode ='05'

  • PanEntryMode ='05'; Track2 ='12345600000008765'; CardProductName ='MyCard'

  • PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard';Account='10'

  • PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard';ResponseCode='05';MessageReasonCode='9631'

  • PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard';Account='10';ResponseCode='05';MessageReasonCode='9631'

  • PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard';PinEntryStatus='PinNotRequired'

  • 5F28='0840';PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard';PinEntryStatus='PinNotRequired'

Further key-value pairs may be included in the event data when custom eSocket.POS extensions are used.

n/a

CARD_REMOVED (event)

eSocket.POS (device driver)

A card has been removed from a card reader.

None.

n/a

CARD_RETRY (event)

eSocket.POS (device driver)

Indicates that the customer should swipe or insert the card again. This may occur during fallback, for instance:

  • to indicate that the magnetic stripe should be used because a chip read failed;

  • to indicate that the smartcard should be used because fallback is not allowed for this transaction

    NOTE

    Not all device drivers use the standard event data for this event.

'MSR' - retry using magnetic stripe reader. 'ICC' - retry using smartcard reader. 'CLESS' - retry using contactless smartcard reader.

n/a

CHECK_CARD_READER (callback)

POS application

Checks whether there is a card present in the reader.

NOTE

This event is not currently widely supported. It is generally not required if the POS registers for the CARD_REMOVED event.

None.

A code which may be one of the following:

  • "0" - card not present in reader

  • "1" - card present in a swipe-and-park reader

  • "2" - card present in motorized reader and not accessible to the user

  • "3" - card present in motorized reader mouth and accessible to the user

  • "4" - card present in pinpad card reader

  • "8" - hybrid reader device error

  • "9" - pinpad reader device error

CONSECUTIVE_USAGE (callback)

eSocket.POS (custom component)

Indicates that the same card (or manually entered card data) has been used in 2 consecutive transactions, and gives the POS the opportunity to decline the transaction.

Depending upon the deployment, the check may only be made under certain conditions, such as only between transactions which are purchases and/or approved and/or made using a magnetic stripe or PKE (PAN Key Entry).

NOTE

This event is not currently widely supported. In future it may be supported in the standard product.

Optionally provides information about the consecutive transactions, such as the transaction type and PAN entry mode. If this data may vary between the 2 transactions then the data can be provided for both, separated with a pipe character as follows:

<tran 1 data>|<tran 2 data>

Where the 'tran data' in each case takes the form of delimited name and value pairs, where the name corresponds to the name of the property which exposes the data via the eSocket.POS API, as follows:

<name>=<val>;<name2>=<val2>;…​

For example, PanEntryMode=02;ResponseCode=00;

"1" to allow the transaction to continue; "0" to abort the transaction.

CLEAR_UNSOLICITED_ CARD_READ (event)

eSocket.POS (custom component or device driver)

Indicates that a magnetic stripe has been read while eSocket.POS was not specifically waiting for a card read, and provides the magstripe data.

This event will only be raised when card data is not sensitive, as determined using the configuration of the card’s mask sensitive data setting.

NOTE

The postilion.esocketpos.eventhandler.MaskSensitiveData property does not have a bearing on whether this event is raised.

Also see UNSOLICITED_CARD_READ and ENCRYPTED_UNSOLICITED_CARD_READ.

NOTE

This event is not currently widely supported. In future it may be supported in the standard product.

The content of the three magnetic stripes, separated by the | character, in the order of <Track1> | <Track2> | <Track3> .

n/a

DATA_REQUIRED (callback) Deprecated: This callback has been deprecated and replaced by the new POS Callback Device callbacks.a

eSocket.POS (generic or custom component)

Requests specified data from the POS. Used by the POS Callback device and certain custom pipeline components.

Typically the data element required, for example, CardNumber, and, optionally, a number of parameters.

The data generally follows the format:

<Data Element>

or

<Data Element>(element_1,element_2,…​)

See the POS Callback Device callbacks section below for details.

The required data.

Alternatively, if the POS returns the string 'CANCEL' in the response, this will have the effect of declining the transaction with a Customer Cancellation response code.

DCC_OFFER_ACCEPTED (event)

eSocket.POS (generic)

Notifies the POS that the dynamic currency conversion (DCC) offer has been accepted by the cardholder.

None.

n/a

DCC_OFFER_DECLINED (event)

eSocket.POS (generic)

Notifies the POS that the dynamic currency conversion (DCC) offer has been declined by the cardholder.

None.

n/a

DEVICE_EXCEPTION (event)

eSocket.POS (device driver)

Notifies the POS of a device exception that occurred while attempting to interact with the card reader device.

NOTE

This event is not currently widely supported.

Error description if available.

n/a

DEVICE_OFFLINE (event)

eSocket.POS (device driver)

Notifies the POS that the device has gone offline.

NOTE

This event is not currently widely supported.

Device information formatted into delimited property name and value pairs, in the format:

<name>=<val>;<name2>=<val2>;…​

The following properties are supported:

  • DeviceTag - the tag associated with the device.

n/a

DEVICE_ONLINE (event)

eSocket.POS (device driver)

Notifies the POS that the device has come online.

NOTE

This event is not currently widely supported.

Device information formatted into delimited property name and value pairs, in the format:

<name>=<val>;<name2>=<val2>;…​

The following properties are supported:

  • DeviceTag - the tag associated with the device.

n/a

DEVICE_SERIAL_NR_AUTHORIZE (callback)

eSocket.POS (generic)

Requests authorization for a device from the POS application when serial number validation is required.

This event is raised when serial number validation has been attempted but further verification may be needed if one of these conditions occur:

  • a device error or disconnect

  • an "unrecognized" serial number not matching a configured allowed serial number value for the terminal

  • device configured for the first time

  • first serial number validation for the configured device

  • the serial number changed

The callback response determines whether the device is authorized for use. If authorized, the device will be made accessible for processing financial data; otherwise the device will not be accessible for processing financial data. This authorization status lasts at least until the next time the serial number is validated.

Device information formatted into delimited property name and value pairs, in the format:

<name>=<val>;<name2>=<val2>;…​

The following properties are supported, of which only the DeviceTag property is always present:

  • DeviceTag - the tag associated with the device.

  • SerialNr* - the serial number for the connected device.

  • UnrecognizedSerialNr - "1" if the serial number was successfully retrieved but does not match an allowed value for the device; "0" or not present otherwise.

  • NewDevice - "1" if no serial numbers have yet been successfully validated for this device; "0" or not present otherwise.

Authorization instructions provided as a delimited property name and value pairs, in the format:

<name>=<val>;<name2>=<val2>;…​

The response data must contain exactly the same properties as the event data. However, if the device is to be authorized then the NewDevice, ReplacedDevice and DisconnectedDevice properties must be set to "0", if present. If the device is to be declined then these properties must be set to "1" - i.e. remain the same as in the request data.

For example, DeviceTag=HypercomEmv;SerialNr=123456; NewDevice=0;

If the SerialNr does not match the value supplied in the callback request then access to the device will be denied and none of the other properties will be applied.

If a null response is provided, or if no response is provided before the callback event times out, then access will be denied.

If the format of the event data is incorrect then the event will be discarded and an error will be logged. No status change will be applied.

NOTE

The format of this data is consistent with the format of the DEVICE_SERIAL_NR_AUTHORIZE event data.

DEVICE_SERIAL_NR_AUTHORIZE (callback) Continued

eSocket.POS (generic)

If the POS is not registered for the callback, then this event is not raised, and default rules apply. See the eSocket.POS User Guide Serial Number Validation page for further details.

The serial number supplied in the callback response must be the same as that supplied in the DEVICE_SERIAL_NR_AUTHORIZE callback, otherwise access will be denied. This supports the POS operator having to type in the serial number of the connected device.

NOTE

This event will be followed by the DEVICE_SERIAL_NR_STATUS event.

NOTE

This event requires the device driver to support this functionality. If not supported then no serial number validation is done and the device is always allowed for use. This functionality is not currently widely supported.

  • ReplacedDevice - "1" if the serial number has changed since the last time the serial number was successfully validated; "0" or not present otherwise.

  • DisconnectedDevice - "1" if a disconnect has been detected since the last time the serial number was successfully validated or if serial number retrieval failed (despite being supported); "0" or not present otherwise.

For example, DeviceTag=HypercomEmv;SerialNr=123456; NewDevice=1;

*Note that if the device is connected but the serial number could not be retrieved then an empty string is provided. In this case the device can be approved or declined as usual.

DEVICE_SERIAL_NR_AUTHORIZE (event)

POS application

Instructs eSocket.POS to authorize a device for use in processing financial data.

This event is useful when the DEVICE_SERIAL_NR_AUTHORIZE callback does not allow long enough for the POS to provide a considered response, for example because approval is required by the store manager. In this circumstance the POS must provide a default response to the callback which must deny access to the device, but this response can be superseded by the instruction provided by this event.

Therefore this event occurs in response to a DEVICE_SERIAL_NR_AUTHORIZE callback from eSocket.POS. It must also be raised within the same eSocket.POS session as the original callback request (i.e. not after a reboot).

This authorization status lasts at least until the next time the serial number is validated.

The event data must echo back the data provided in the original DEVICE_SERIAL_NR_AUTHORIZE callback request. This is so that eSocket.POS can ensure that it does not authorize the device if further conditions have occurred which invalidate the authorization, such as a disconnect. Requiring the serial number to be echoed back also supports the POS operator having to type in the serial number of the connected device.

NOTE

This event will always be followed with a DEVICE_SERIAL_NR_STATUS event and the POS can use the DEVICE_SERIAL_NR_STATUS event to ascertain whether this event was effective.

NOTE

This event requires the device driver to support this functionality. This functionality is not currently widely supported.

Authorization instructions provided as a delimited property name and value pairs, in the format:

<name>=<val>;<name2>=<val2>;…​

The response data must contain exactly the same properties as the original DEVICE_SERIAL_NR_AUTHORIZE callback event data. However the NewDevice, ReplacedDevice and DisconnectedDevice properties must be set to "0" if present, in order to authorize the device.

For example, DeviceTag=HypercomEmv;SerialNr=123456; NewDevice=0;

If the SerialNr does not match the serial number of the connected device, then the event will be discarded and a warning will be logged. This means that the status of the device will remain DECLINED.

NOTE

The format of this data is consistent with the format of the DEVICE_SERIAL_NR_AUTHORIZE callback response data.

n/a

DEVICE_SERIAL_NR_STATUS (event)

eSocket.POS (generic)

This event can be raised either:

  • following a device state change resulting from serial number validation; or

  • whenever the POS initiates or is consulted in serial number validation (via the DEVICE_SERIAL_NR_VALIDATE event or DEVICE_SERIAL_NR_AUTHORIZE callback)

The status reports on whether access will be allowed to the device to process financial data.

NOTE

By receiving this event the POS can ascertain if a DEVICE_SERIAL_NR_AUTHORIZE event or callback response was effective.

NOTE

This event requires the device driver to support this functionality. This functionality is not currently widely supported.

The validation status of a device in the format:

<name>=<val>;<name2>=<val2>;…​

The following properties are provided:

  • DeviceTag - the tag associated with the device.

  • SerialNrAllowed - "1" if device access is allowed following serial number validation; "0" otherwise.

For example, __

DeviceTag=HypercomEmv;SerialNrAllowed=1;

n/a

DEVICE_SERIAL_NR_VALIDATE (event)

POS application

Provides a way for the POS to initiate the device serial number validation process.

When this event is raised, eSocket.POS attempts to retrieve and validate the serial number of the connected device. A resync can optionally be triggered when the connected PED is replaced. Refer to the "Serial Number Validation" page in the eSocket.POS User Guide for more information.

NOTE

Depending on the result of this validation this event may result in the DEVICE_SERIAL_NR_AUTHORIZE callback and the DEVICE_SERIAL_NR_STATUS event being raised.

NOTE

Serial number validation can also occur at fixed intervals and so may not be initiated by this event.

NOTE

This event requires the device driver to support this functionality. This functionality is not currently widely supported.

None.

n/a

DEVICE_UPDATE (event or callback)

POS application

Instructs the device driver that certain files need to be downloaded to the device.

The data may be used to indicate the type of files to be downloaded.

NOTE

This event is not currently widely supported.

NOTE

If raised as an event, when the update has completed the DEVICE_UPDATE_STATUS event may be raised. In the meantime the DEVICE_UPDATING event may be raised.

Also see AUTO_DEVICE_UPDATE.

Optionally indicates the type of update required.

Standard values currently include:

  • FIRMWARE - loads firmware only.

  • FLASH - loads the flash file only.

  • CONFIG - loads configuration such as the card configurations, merchant data and key index tables.

  • SCREENS - loads device screens only.

If a combination of values is to be used they should be supplied as a pipe-delimited string, for example, "FIRMWARE|FLASH|".

If no value is supplied the device driver determines the type of update required.

A completion code which may be one of the following:

  • "0" - failure

  • "1" - success

  • "9" - error

If reporting on multiple update types then the status of each will be reported as follows:

<type>=<status>;<type>=<status>;…​

For example, FIRMWARE=1;FLASH=0;

DEVICE_UPDATE_STATUS (event)

eSocket.POS (device driver)

Reports the completion code after a device has been updated.

May follow a DEVICE_UPDATE or AUTO_DEVICE_UPDATE event.

NOTE

This event is not currently widely supported.

A completion code which may be one of the following:

  • "0" - failure

  • "1" - success

  • "9" - error

If reporting on multiple update types then the status of each will be reported as follows:

<type>=<status>|<type>=<status>|…​

For example, FIRMWARE=1|FLASH=0|

n/a

DEVICE_UPDATING (event)

eSocket.POS (device driver)

A device is being updated.

May intermittently follow a DEVICE_UPDATE or AUTO_DEVICE_UPDATE event and be followed with a DEVICE_UPDATE_STATUS event.

NOTE

This event is not currently widely supported.

Optionally defines the update types as follows:

<type>=<status>|<type>=<status>|…​

For example, FIRMWARE=1|FLASH=0|

n/a

EJECT_CARD (event or callback)

eSocket.POS (custom component) or POS application

Attempts to eject a trapped card from a motorized reader.

NOTE

This event is not currently widely supported.

None.

A completion code which may be one of the following:

  • "0" - failure

  • "1" - success

  • "9" - error

ENCRYPTED_UNSOLICITED_CARD_READ (event)

eSocket.POS (custom component)

Indicates that a magnetic stripe has been read while eSocket.POS was not specifically waiting for a card read, and provides an encrypted or tokenized form of the magnetic stripe data. It may be just the PAN or the whole track data which is encrypted or tokenized.

A variable length format indicator is used to identify the encryption or tokenization mechanism.

The format indicator should be set to a reserved value.

Currently reserved values and their meaning are:

  • WiPro - A WiPro PAN token.

  • PosConnectPCIDSS - PAN encrypted using the standard encryption applied by the PAN component and sent to PosConnect for decryption.

Also see UNSOLICITED_CARD_READ and CLEAR_UNSOLICITED_CARD_READ.

NOTE

This event is not currently widely supported. In future a version of the event may be supported by the standard product.

<encrypted card data>

or

_<format indicator>a

<encrypted card data>_

If the format indicator is formed of more than one element, then these elements should be separated using semi-colons.

NOTE:: The encrypted data must be represented in a hexadecimal format.

NOTE:: The format indicator must not contain a pipe or semi-colon.

n/a

GET_DEVICE_INFO (callback)

POS application

Retrieves device information via a device driver.

The event supports retrieving information about one or multiple devices.

The data returned by this event is determined by the specific driver implementation.

NOTE

This event is not currently widely supported. However, certain device drivers currently expose device data via alternative custom callbacks.

None.

Device information is returned in the same format as structured data (field 127.22), for example:

  • 19SERIAL_NR210884422669916HW_VER149096

Device information returned is driver specific.

NOTE

Returns an empty string if not implemented or if device is not ready when callback is called.

HAND_TO_OPERATOR (callback)

eSocket.POS (device driver)

Indicates to the POS that the payment media (typically the card) and the reader (if required) must be handed to the POS operator.

An example of where this may be used is if only the POS operator is authorized to carry out magnetic stripe swipes or PAN key entry, and a device allows one or both of these.

NOTE

This event is not currently widely supported.

None.

A code indicating whether the POS attendant has successfully obtained the payment media and (if required) the card reader.

Possible values are:

  • "0" - No

  • "1" - Yes

Input (callback)

eSocket.POS (custom component)

Allows the POS to update the transaction amount when Pipeline component Payment Interrupt is configured and the card used is eligible.

The data consists of key-value pairs separated by semi-colon characters.

<name>=<val>;<name2>=<val2>;…​

The following information may be present in the event data, depending on Pipeline component Payment Interrupt configuration:

The available values are

  • PaymentInterrupt=<Card Product Name> : The card product name of the card used for payment, always present.

  • Amount=<Transaction Amount> : Transaction Amount in 12-digit, minor denomination.

  • PAN=<Obfuscated PAN> : PAN will be masked, first 6 digits(BIN) and last 4 digits are visible.

For example, "PaymentInterrupt=DefaultCard;Amount=000000000300;PAN=123456******7890"

Updated transaction amount in 12 digit minor denomination.

For example, "000000000330"

LINE_ITEM_DISPLAY (callback)

POS application

Allows the POS to display the individual line items on the PIN entry device (PED) while the items are being scanned at the POS or the results of a transaction that was processed at the POS.

The following four types of data elements are allowed:

1. lineItemDisplay:start - To start the line item session and get the display configuration of the PED.

This data element can have three optional parameters:

  • scanAhead: <on/off> - to indicate if the customer can swipe the card while the items are being scanned

  • scanAheadMessage : <message> - Custom swipe message displayed in the PED

  • deviceRank : <message> - The device group that should be used in this session. This should be an integer and will default to zero.

  • sendCardData : <true/false> - Indicates whether the obfuscated track 2 data and card product name should be sent in the CARD_READ event raised by eSocket.POS after a card read has occurred. If set to false, only the PAN entry mode will be sent. Defaults to false.

  • tranType : <2-digit ISO8583 transaction type> - Indicates the transaction type when scan-ahead is enabled. For EMV refund scan-ahead, a value of "20" (returns) must be specified. If not specified, the transaction type will be assumed to be "00" (goods and services).

Possible responses are:

  • numberOfLines : <number> ; lengthOfLine : <number> - Display configuration returned for the line item display start callback.

  • ok - for all successful callbacks.

  • Error: <error message> - for all error conditions.

  • scanAheadDataPresent : true/false; ok - for all successful callbacks that handles the display of scanned line item details.

LINE_ITEM_DISPLAY (callback) Continued

POS application

2. lineItemDisplay:itemDetail - To display the scanned items details on the PED. The line item detail data can be in one of the following two formats:

  • __

    additionalInfoItem1 : <value> ; additionalInfoItem2 : <value> ; additionalInfoItem3 : <value> ; additionalInfoItem4 : <value> ; formattedItemDisplayLine : "<item details line 1> " " <item details line 2>" "<subtotal>"

  • __

    itemNum : <value> ; quantity : <value> ; unitPrice : <value> ; lineTotal : <value> ; voided : <value> ; itemDescription : <value> ; subtotal : <value> ; additionalInfoItem1 : <value> ; additionalInfoItem2 : <value> ; additionalInfoItem3 : <value> ; additionalInfoItem4 : <value> ;

3. lineItemDisplay:tranResult - To display the transaction results on the PED. The transaction result data should be specified in the following format:

  • __

    formattedItemDisplayLine : "<item details line 1> "

LINE_ITEM_DISPLAY (callback) Continued

POS application

4. lineItemDisplay:end - To end the line item session. The following optional data element may be specified:

  • resetTran : <true/false> - Indicates whether card details that have been read and cached during scan-ahead should be cleared from eSocket.POS and whether any pending EMV card reads should be aborted if a card has been inserted. For example, if the POS application needs to abort a transaction while eSocket.POS is performing scan-ahead and displaying line items, this data element can be set to true to request the cardholder to remove an EMV card and revert the PED to its idle state. This data element defaults to true when no line item details or transaction results are being displayed on the PED (i.e. when the lineItemDisplay:start callback is immediately followed by a lineItemDisplay:end callback, without lineItemDisplay:itemDetail and lineItemDisplay:tranResult callbacks in-between). Otherwise, it defaults to false .

LOYALTY_INTERRUPT (callback)

eSocket.POS (generic)

Allows eSocket.POS to update the transaction amount when Pipeline component Loyalty is configured and the card used is loyalty eligible.

The data consists of key-value pairs separated by semi-colon characters.

<name>=<val>;<name2>=<val2>;…​

The following information may be present in the event data, depending on Pipeline component Loyalty configuration:

The available values are

  • Identification Support: Always set to 'LoyaltyCard'.

  • Entry Mode: 'ICC' for EMV transactions. 'MagStripe' for magstripe transactions.

  • Loyalty Brand: The loyalty brand configured for the card.

  • Loyalty ID: The Loyalty ID retrieved from the card. This will either be in discretionary data or in a specified EMV tag depending on the card.

  • Identification Type: Always set to 'AccountNumber'.

  • Loyalty Eligibility: 'Y' if the loyalty information was retrieved and validated successfully. 'N' if the validation of the data failed.

Examples:

  • identificationSupport=LoyaltyCard;entryMode=ICC;loyaltyBrand=AAAA;loyaltyIdentifier=12345;identificationType=AccountNumber

  • identificationSupport=LoyaltyCard;entryMode=MagStripe;loyaltyBrand=AAAA;loyaltyIdentifier=12345;identificationType=AccountNumber

  • loyaltyEligibility=N

The POS will send back a response containing one of the following

  • Updated transaction amount in 12 digit minor denomination.Example: "000000001000"

  • "ABORT"Indicates an operator cancellation.

  • "TIMEOUT"Indicates a timeout waiting for input on the POS.

NFC_VAS_ENABLE (callback)

POS application

Enables or disables the near field communication (NFC) value added service (VAS) functionality within the device driver at run-time. This callback will override any configuration setting in the device driver that enables/disables the NFC VAS functionality.

One of the following values:

  • "0" - disable

  • "1" - enable

A completion code which may be one of the following:

  • "0" - failure

  • "1" - success

  • "9" - error

  • "-1" - operation not supported by device driver

NFC_VAS_READ (event)

eSocket.POS (device driver)

Indicates that a near field communication (NFC) value added service (VAS) read has occurred or failed when the customer has tapped an NFC-enabled device on the PED.

The following data elements in name=value pair format, separated by semi-colons:

  • Data - The VAS data received from the NFC device in the clear. This element will not be sent if a read error has occurred.

  • DeviceRspCode - The untranslated device-specific response code returned by the PED, providing additional contextual information on the outcome of the NFC VAS read (optional, sent if available). For information on the values that may be returned, please refer to the PED manufacturer’s device protocol specification.

  • StatusCode - The eSocket.POS status code indicating the success or failure of the VAS read. Possible values include: "0" (failure), "1" (success), "9" (error).

  • VasMerchantId - The VAS merchant ID associated with the VAS data, as configured in ConfigServer. This element may or may not be provided, depending on the information returned by the PED. If provided, the POS application may use it to identify the payment wallet associated with the VAS data.

Example data:

  • Successful read: Data=ABCDE;VasMerchantId=com.retailer.applepay;StatusCode=1;DeviceRspCode=10

  • Error: StatusCode=9;DeviceRspCode=40

n/a

NFC_VAS_SIGNUP (callback)

POS application

Signs up a customer to a merchant’s near field communication (NFC) value added service (VAS) program and loads the VAS information onto the customer’s NFC-enabled device by pointing the device to a particular sign-up URL.

The following data elements should be provided in name=value pair format, separated by semi-colons:

  • VasMerchantId - The VAS merchant ID for which the VAS data should be loaded on the customer’s NFC device. This also identifies the payment wallet (for example, Apple Pay wallet, Android wallet, and so on).

  • Url - The sign-up URL to which the NFC device should connect in order to load VAS information onto the customer’s NFC device. This element is optional. If not specified, the default sign-up URL configured for the VAS merchant ID in ConfigServer will be used. If specified, it must be specified as the last data element in the callback data.

The following data elements in name=value pair format, separated by semi-colons:

  • DeviceRspCode - The untranslated device-specific response code returned by the PED, providing additional contextual information on the outcome of the sign-up process (optional, sent if available). For information on the values that may be returned, please refer to the PED manufacturer’s device protocol specification.

  • StatusCode - The eSocket.POS status code indicating the success or failure of the sign-up process. Possible values include: "0" (failure), "1" (success), "9" (error), "-1" (operation not supported by device driver)

OPC_CONFIRMATION (callback)

eSocket.POS (generic)

Requests OPC confirmation from the POS if merchant OPC selection is enabled.

The data consists of key-value pairs separated by semi-colon characters.

<name>=<val>;<name2>=<val2>;…​

The following information will be present in the event data, if merchant OPC selection is enabled:

The available values are

  • Selected OPC: The OPC that was selected by the POS. e.g selectedOpc=<paymentOptionCode>:<longLabel>

  • Amount: Transaction Amount in 12-digit, minor denomination.

  • Currency Code: Indicates the currency used for the transaction.

For example, "selectedOpc=CCCCC:long3;amount=000000010000;currencyCode=710;"

The POS will send back a response containing one of the following

  • "TRUE".Indicates the OPC selection was confirmed.

  • "CANCEL"Indicates an operator cancellation.

  • No response indicates a timeout waiting for input on the POS.

OPC_SELECTION (callback)

eSocket.POS (generic)

Requests OPC selection from the POS if merchant OPC selection is enabled.

The data consists of key-value pairs separated by semi-colon characters.

<name>=<val>;<name2>=<val2>;…​

The following information will be present in the event data, if merchant OPC selection is enabled:

The available values are

  • Title: The card product name of the card used for payment, always present.

  • OPC List: A list of OPC’s for example,opcList=<paymentOptionCode>:<opcDisplayOrder>:<longLabel>.

  • Is Retry: Indicates whether OPC selection was a re-attempted.

For example, "title=TestCard;opclist=AAAAA:3:long1,BBBBB:1:long2,CCCCC:2:long3;isRetry=0;"

The POS will send back a response containing one of the following

  • "long3".The selected OPC’s long label.

  • "CANCEL"Indicates an operator cancellation.

  • No response indicates a timeout waiting for input on the POS.

PAN_ENTERED (event)

eSocket.POS (device driver)

A card information has been entered manually.

The data consists of key-value pair, where the value is enclosed in single quotes. The following information is present in the event data:

  • The PAN entry mode (always sent);

Examples:

n/a

PAY_AT_TABLE_INIT (callback)

eSocket.POS (device driver)

Initiates the Pay At Table workflow.

NOTE

This event is not currently widely supported.

The following data elements should be provided in name=value pair format, separated by semi-colons:

  • cashierID - The employee ID to be validated by the POS

Example:

  • cashierID=123456789

The following are possible responses:

  • success=<0:1> Returns a value of 1 if the POS successfully validated the employee ID or 0 if the validation failed

  • responseText=<display text> Where <display text> is a response message to be displayed on the PED.

Examples:

  • Successful response: success=1;responseText=Employee ID OK

  • Failure response: success=0;responseText=Invalid Employee ID

PERMIT_FALLBACK_TO_ MAGSTRIPE (callback)

eSocket.POS (device driver)

Suspends processing prior to a fallback to magnetic stripe. The transaction may be either declined or allowed to continue at this stage.

An example of usage is where the merchant requires that only the operator and not the customer may swipe the card.

Likely to be used in conjunction with PERMIT_SWIPE.

NOTE

This callback is used to implement an additional condition for allowing fallback to magnetic stripe and does not prevent fallback from being declined due to any other condition.

NOTE

This event is not currently widely supported.

Also see PERMIT_FALLBACK_TO_PKE.

None.

A code indicating whether fallback to magstripe should be permitted, as follows:

  • "0" - No. The transaction will not fallback to magnetic stripe and will be declined.

  • "1" - Yes. The transaction will be allowed to proceed.

PERMIT_FALLBACK_TO_PKE (callback)

eSocket.POS (custom component)

Suspends processing prior to a fallback to PAN Key Entry. The transaction may be either declined or allowed to continue at this stage.

An example of usage is where the merchant requires that only the operator and not the customer may manually enter the card number.

NOTE

This callback is used to implement an additional condition for allowing fallback to PKE and does not prevent fallback from being declined due to any other condition.

NOTE

This event is not currently widely supported.

None.

A code indicating whether fallback to PKE should be permitted, as follows:

  • "0" - No. The transaction will not fallback to Pan Key Entry and will be declined.

  • "1" - Yes. The transaction will be allowed to proceed.

PERMIT_SWIPE (callback)

eSocket.POS (device driver)

Suspends processing following a card swipe where the transaction would otherwise proceed using magnetic stripe data. Only raised for pure magnetic stripe cards. Depending on the callback response, the transaction may be declined, allowed to continue, or only allowed to continue once the card has been swiped again.

An example of usage is where the merchant requires that only the operator and not the customer may swipe the card.

Likely to be used in conjunction with PERMIT_FALLBACK_TO_MAGSTRIPE.

NOTE

This event is used to implement an additional condition for allowing swiped card data to be used and does not prevent the transaction from being declined due to any other reason.

NOTE

This event is not currently widely supported.

Also see PERMIT_FALLBACK_TO_PKE.

None.

A code indicating how the transaction should proceed, as follows:

  • "0" - No. The transaction will be declined.

  • "1" - Yes. The transaction will be allowed to proceed as usual.

  • "2" - The swiped card data will not be used and the card must be swiped again.

PIN_BYPASS (event)

POS application

Attempts to bypass PIN entry and allow another cardholder verification method, such as signature.

NOTE

The device configuration and the card chip must allow PIN bypass, otherwise the transaction will be declined. If PIN bypass is allowed the card and the device configuration will determine the alternative cardholder verification method.

NOTE

This event may be used in conjunction with a configuration option against the card to determine whether PIN bypass is allowed.

NOTE

This event is only supported by a subset of device drivers.

None.

n/a

PIN_ENTRY (event)

eSocket.POS (device driver)

During PIN entry, indicates the PIN entry status to the POS to facilitate interaction with the POS operator. The event data may indicate that PIN entry is required or (for EMV offline PIN) a completion indicator.

In a standard implementation the following values may be raised:

  • First try - The device has prompted the user to enter their PIN for the first time.

  • Retry - The device has prompted the used to re-enter their PIN.

  • Last try - The device has prompted the user to enter their PIN for the last time before PIN entry will fail.

  • Not available - The card does not support a PIN try counter or no transaction is in progress.

  • Success - PIN entry has completed successfully.

  • Fail - PIN entry has failed and no more attempts are allowed

  • Bypass PIN - The PIN entry stage has been bypassed. This may occur if the device has been instructed (by the device driver) to bypass PIN entry.

n/a

PIN_LOCKED (event or callback)

eSocket.POS (device driver)

Indicates that the card PIN is locked so that the POS display can be updated.

If raised as a callback then a response is required before the transaction will continue. This allows the POS to require the operator to acknowledge the prompt.

NOTE

This event is only supported by a subset of device drivers.

None.

Any response to the callback will result in processing resuming.

PIN_TIMEOUT (event or callback)

eSocket.POS (device driver)

Indicates that PIN entry has timed out so that the POS display can be updated.

If raised as a callback then a response is required before the transaction will continue. This allows the POS to require the operator to acknowledge the prompt.

NOTE

This event is not currently widely supported.

None.

Any response to the callback will result in processing resuming.

POS Callback Device callback (individual event IDs are defined per device command)

Replaces: The deprecated callback DATA_REQUIRED.

eSocket.POS (generic or custom component)

Sends commands to the device (including information retrieval commands), via the POS, in the case where the POS instead of eSocket.POS drives the device/PED. Used by the POS Callback device and certain custom pipeline components.

A JSON representation of the device command. For example, if the event ID is CardReader_GetMerchandiseCardSwipe, the event data will be:

{"merchandiseType":"<merchandise_type>"}

See the POS Callback Device callbacks section below for details..

Any response to the callback will result in processing resuming.

PRE_SWIPE (event or callback)

POS application

Allows the POS to enable and disable the pre-swipe functionality implemented by PipelineComponentPreSwipe .

See the eSocket.POS User Guide for further information.

One of the following values can be specified:

1. Enable: To clear previously pre-swiped data and prompt the customer to swipe their card. At this point the PipelineComponentPreSwipe will start listening for a pre-swipe event.

Optional data that can be specified along with "Enable" are :

  • "send0600Msg : true/false" - Indicates the card details will be stored as is or a 0600 message has to be sent.

  • "scanAheadMessage : <message> " - Custom swipe message displayed to the customer.

  • "sendCardData : <true/false> " - Indicates whether the obfuscated track 2 data and card product name should be sent in the CARD_READ event raised by eSocket.POS after a card read has occurred. If set to false, only the PAN entry mode will be sent. Defaults to false.

  • "tranType : <2-digit ISO8583 transaction type> " - Indicates the transaction type for which pre-swipe should be performed. For EMV refund pre-swipes, a value of "20" (returns) must be specified. If not specified, the transaction type will be assumed to be "00" (goods and services).

  • "readOnly : true/false " - Indicates whether the Pre-swipe mode should be cancelled after reading the card. Default is false.

For example, "Enable ; send0600Msg : true ; scanAheadMessage : Please swipe card ; tranType : 00"; readOnly : true

NOTE

Each data parameter should be delimited with semi-colon.

2. Cancel : to cancel the pre-swipe.

3. Stop_Listen : to stop waiting for a pre-swipe.

n/a

PRE_SWIPE_GET_STATE (callback)

eSocket.POS (generic)

Allows eSocket.POS to retrieve the state of PipelineComponentPreSwipe .

See the eSocket.POS User Guide for further information.

n/a

The possible states that can be returned include the following:

  • "0" - The component is idle and not currently doing any processing. A card read might have already been completed.

  • "1" - The component is currently listening for a card read.

  • "2" - The component is processing an injected 0600 after a card read.

  • "3" - The component is canceling an injected 0600.

  • "4" - The component is waiting for the injected 0600 processing to finish before allowing the 0100/0200 received from the POS to continue.

PRE_SWIPE_CANCELLED (event)

eSocket.POS (generic)

Informs the POS when pre-swipe was enabled but needed to be disabled due to eSocket.POS processing.

The reason for cancellation:

  • "0" - generic error

  • "1" - processing suspended due to a device update, resync or key exchange

  • "2" - pre-swipe cancelled by customer

  • "3" - pre-swipe cancelled by operator

  • "4" - pre-swipe read-only cancellation after successful card read

n/a

PRE_SWIPE_ERROR (event)

eSocket.POS (generic)

Informs the POS that a PRE_SWIPE event failed to enable pre-swipe.

The error type, which may be one of:

  • "0" - generic error

  • "1" - device busy

n/a

PRINT_FORMATTED_ RECEIPT (callback)

eSocket.POS (custom component)

Prompts the POS to print a receipt using the formatted data provided.

NOTE

This event is not currently widely supported.

A formatted string to be used for directly printing on the receipt.

A success indicator which may be one of the following:

  • "0" - success

  • "1" - general error

  • "2" - out of paper

  • "3" - out of toner or ink

  • "4" - paper jam

PRINT_UNFORMATTED_ RECEIPT (callback)*

eSocket.POS (custom component)

Prompts the POS to print a receipt using the data elements provided.

NOTE

This event is not currently widely supported. In future this callback may be supported in the standard product.

Transaction information formatted into delimited name and value pairs, where the name corresponds to the name of the property which exposes the data via the eSocket.POS API.

<name>=<val>;<name2>=<val2>;…​

For example, CardProductName=MasterCard; CardSequenceNumber=001;

Typically the following properties may be included:

  • AuthorizationProfile

  • AuthorizationNumber

  • CardProductName

  • EmvCryptogramInformationData

  • EmvCryptogram

  • EmvApplicationIdentifier

  • EmvCvmResults

  • ExpiryDate

  • MaskedCardNumber

  • MerchantId

  • PanEntryMode

  • ResponseCode

  • StartDate

A success indicator which may be one of the following:

  • "0" - success

  • "1" - general error

  • "2" - out of paper

  • "3" - out of toner or ink

  • "4" - paper jam

PROMPT_<name> (event)

eSocket.POS (generic)

Notifies the POS of a change to the customer display.

The change to the display may be to prompt the customer for some action or advise the customer of an action taken.

Refer to the Prompt events section.

n/a

READ_ERROR (event)

eSocket.POS (device driver)

Indicates that an error occurred while reading the card

None.

n/a

REMOVE_CARD (event)

eSocket.POS (device driver)

Indicates that a card should be removed from a reader.

Optional

  • READ_ERROR: Indicates that the card should be removed because of an error during the read. The customer should retry with another card or fallback to magstripe.

n/a

REVISE_TRAN_DATA

eSocket.POS (custom component)

Allows the POS to review and update transaction data after the transaction has begun and after any card read.

Example uses are:

  • applying discounts to transactions with merchant-specific cards

  • dynamic currency conversion

Transaction information formatted into delimited name and value pairs, where the name corresponds (where applicable) to the name of the property which exposes the data via the eSocket.POS API (if applicable).

<name>=<val>;<name2>=<val2>;…​

For example, TransactionAmount=100;CurrencyCode=840; Type=PURCHASE;

Typically the following properties may be included:

  • TransactionAmount

  • CurrencyCode

  • Type

  • IssuerIdentificationData

  • TokenizedCardNumber or EncryptedCardNumber

Possible responses are:

Either:

  • "1" - the transaction must continue using current data.

  • "0" - the transaction must be aborted using a default response code and message reason code.

  • "ResponseCode=XX; MessageReasonCode=XXXX" where X represents an integer value - the transaction must be aborted using the ResponseCode and MessageReasonCode provided.

Or:

New data to be applied to the transaction in delimited property name and value pairs:

<name>=<val>;<name2>=<val2>;…​

For example, TransactionAmount=100;Type=REFUND;

Typically the following properties may be included:

  • TransactionAmount

  • CurrencyCode

  • Type

RESET_DEVICE (event or callback)

POS application

Reboots the device firmware and software.

NOTE

If raised as an event the RESET_DEVICE_STATUS __ event may be raised by the device driver to indicate that the reset has completed.

NOTE

This event is only supported by a subset of device drivers.

None.

A completion code which may be one of the following:

  • "0" - failure

  • "1" - success

  • "9" - error

RESET_DEVICE_STATUS (event)

eSocket.POS (device driver)

Reports the completion code after a device has been reset.

May be used in conjunction with the RESET_DEVICE event.

NOTE

This event is not currently widely supported.

A completion code which may be one of the following:

  • "0" - failure

  • "1" - success

  • "9" - error

n/a

SAFQ_LIMITS_STATE_CHANGED (event)

eSocket.POS

The eSocket.POS monitoring system detected the store and forward queue (SAFQ) limits state change.

NOTE

This event is not currently widely supported.

The new state which may be one of the following:

  • "0" - NORMAL

  • "1" - LIMIT_REACHED

  • "2" - RECOVERING

n/a

SAF_QUEUE_SIZE (event)

eSocket.POS (custom component)

Returns the number of undelivered transactions in the eSocket.POS store-and-forward queue.

NOTE

This event is not currently widely supported. However, certain implementations provide an alternative custom event. In future this event may be supported in the standard product.

Total number of undelivered transactions in the store-and-forward queue.

n/a

SAFQ_NOT_CLEARING (event)

eSocket.POS

The eSocket.POS monitoring system detected a delay in the delivery of transactions from the store and forward queue (SAFQ) of this terminal. This could be due to the terminal not being signed on, the host being under load, the host sending an invalid response, or another reason. The following action is recommended: Please review the eSocket.POS event log and traces for any errors or warnings. Restart eSocket.POS if this event is raised multiple times. Contact your primary support provider if, after a restart, this event is still being raised.

<SAFQ size>|<approximate time (in minutes) since last SAFQ dequeue>

where:

  • <SAFQ size> is the size of the SAFQ (excluding the last dequeued transaction that is being delivered upstream, if any)

  • <last SAFQ dequeue time period> is the approximate time in minutes a transaction was last dequeued from the SAFQ in order to be sent upstream

For example, 2|243 indicates the SAFQ is not clearing and contains 2 transactions. The last time a transaction was dequeued is approximately 243 minutes (4 hours and 3 minutes) ago.

n/a

SAFQ_CLEARING_AGAIN (event)

eSocket.POS

The eSocket.POS monitoring system detected that transactions from the store and forward queue (SAFQ) of this terminal is being delivered again, after it has been delayed.

None.

n/a

UNSOLICITED_CARD_READ (event)

eSocket.POS (device driver or custom component)

Indicates that a magnetic stripe has been read while eSocket.POS was not specifically waiting for a card read, and provides the (clear or masked) magstripe data.

Also see CLEAR_UNSOLICITED_CARD_READ and ENCRYPTED_UNSOLICITED_CARD_READ.

In a standard implementation the data will be the contents of the three magnetic stripes, separated by the | character, in the order of <Track1> | <Track2> | <Track3> .

NOTE

Track2 data can be masked depending on the eSocket.POS card configuration (the mask sensitive data setting) and the value configured for the postilion.esocketpos.eventhandler.MaskSensitiveData property.

n/a

RESYNC_PENDING (event)

eSocket.POS (generic)

Informs the POS that eSocket.POS wants to resync. This event will be followed by the RESYNC_IN_PROGRESS command.

None.

n/a

RESYNC_IN_PROGRESS (event)

eSocket.POS (generic)

Informs the POS that eSocket.POS resync is in progress. eSocket.POS will be unable to process transactions while the resync is in progress.

None.

n/a

RESYNC_COMPLETED (event)

eSocket.POS (generic)

Informs the POS that a resync completed.

None.

n/a

RESYNC_FAILED (event)

eSocket.POS (generic)

Informs the POS that a resync failed.

None.

n/a

RESTART_REQUIRED (event)

eSocket.POS (generic)

Informs the POS that a restart is required. If eSocket.POS is configured to automatically restart, then the TCP connection will be lost during the restart. This will happen soon after receiving this event. After the connection is restored the POS should initialize the terminal before sending transactions.

None.

n/a

SIGNATURE_PROMPT (event)

eSocket.POS (generic)

Informs the POS that eSocket.POS will attempt to capture the cardholder’s signature.

None.

n/a

PARTIAL_APPROVAL

POS application

Allows the POS to approve or decline the Partial Approval Confirmation.

See the eSocket.POS User Guide for further information.

This callback requests confirmation from the POS for the partially approved transaction amount from the host.

Eg of the callback raised/event data is as follows :

Transaction partially approved for amount (partially approved amount)

Accept ?

Possible responses are:

  • TRUE - Approved Partial approval confirmation.

  • FALSE - Declined Partial approval confirmation.

Prompt events

Prompt events are intended to notify the POS about a change to the customer display. However (if the POS Callback Device is used) these events may in places follow a change in the POS display and not the customer display, in which case they are not so useful. These events are all raised by the standard eSocket.POS product. Note that the Description field describes the standard eSocket.POS component (if any) which will invoke the event.

Event ID Event Data Description

PROMPT_ACCOUNT

List of account types and names, comma separated. for example, 10Savings,20Credit

Indicates that the customer/operator has been presented with a list of accounts and has been requested to select one.

NOTE

This event requires the Account pipeline component to be configured in the request pipeline.

PROMPT_ADDRESS

n/a

Indicates that the customer/operator has been prompted to enter the customer address.

NOTE

This event requires the AVS pipeline component to be configured in the request pipeline.

PROMPT_AMOUNT

The maximum allowed amount for this account.

Indicates that the customer/operator has been prompted to enter the amount for this card transaction.

NOTE

This event requires the Amount pipeline component to be configured in the request pipeline.

PROMPT_AUTHORIZATION_NUMBER

n/a

Indicates that the customer/operator has been prompted for the authorization number provided by the authorizing agency for this transaction.

NOTE

This event is not currently invoked by any standard eSocket.POS component but may be invoked using a custom component.

PROMPT_BALANCE_LIST

n/a

Indicates that the customer/operator has been shown a list of balances.

NOTE

This event requires the FundsInquiryResponse pipeline component to be configured in the request pipeline.

PROMPT_BARCODE

n/a

Indicates that the customer/operator has been prompted to scan barcode.

NOTE

This event requires the a barcode reader to be configured.

PROMPT_CARD_SEQUENCE_NUMBER

n/a

Indicates that the customer/operator has been prompted for the card’s sequence number.

NOTE

This event requires the CardSeqNr pipeline component to be configured in the request pipeline.

PROMPT_CASHBACK_AMOUNT

Maximum allowable cashback amount.

Indicates that the customer/operator has been prompted to enter a cashback amount.

NOTE

This event requires the Cashback pipeline component to be configured in the request pipeline but for EMV transactions it may also be invoked by the device driver.

Also see PROMPT_IS_CASHBACK_REQUIRED.

PROMPT_CASHBACK_SELECTION

The data will consist of the following named parameters:

Name : fixedCashbackOptions Description : Specifies the list of cashback amounts that are available for selection on the PED at the fixed denomination cashback prompt. Value Format : Amount1,Amount2,AmountN

Name : allowNumericEntryFallback Description : Indicates whether the customer may choose to enter a custom cashback amount via a numeric entry screen (i.e. whether the 'Other' option is available for selection). Value Format : 0 - Disallowed. 1 - Allowed.

Format

The above named parameters are specified in the format below. Parameters are delimited by the ';' (semi-colon) character, and within a parameter, the parameter name and parameter value are delimited by the '=' (equals) character.

Example

allowNumericEntryFallback=1;fixedCashbackOptions=100000,80000,60000,50000,30000,8000

Indicates that the customer/operator has been prompted to select a cashback amount.

NOTE

This event requires the Cashback pipeline component to be configured in the request pipeline but for EMV transactions it may also be invoked by the device driver.

Also see PROMPT_IS_CASHBACK_REQUIRED.

PROMPT_CHECK_ACCOUNT_NUMBER

n/a

Indicates that the customer/operator has been prompted to enter the check account number.

NOTE

This event requires the ChequeAuth pipeline component to be configured in the request pipeline.

PROMPT_CHECK_INSTITUTION_CODE

n/a

Indicates that the customer/operator has been prompted to enter the check institution code.

NOTE

This event requires the ChequeAuth pipeline component to be configured in the request pipeline.

PROMPT_CHECK_LIMIT

n/a

Indicates that the customer/operator has been prompted to enter the check/cheque guarantee card limit.

NOTE

This event requires the ChequeAuth pipeline component to be configured in the request pipeline.

PROMPT_CHECK_NUMBER

n/a

Indicates that the customer/operator has been prompted to enter the check number.

NOTE

This event requires the ChequeAuth pipeline component to be configured in the request pipeline.

PROMPT_CHECKREAD

n/a

Indicates that the customer/operator has been prompted to insert the check into the check reader.

NOTE

This event requires the CheckRead pipeline component to be configured in the request pipeline.

PROMPT_CHECKREAD_FAILURE

n/a

Indicates to operator that a check read error occurred.

NOTE

This event requires the CheckRead pipeline component to be configured in the request pipeline.

PROMPT_CHECK_PRINTING

n/a

Indicates to the operator that the check printing is in progress.

NOTE

This event requires the ChequeAuth pipeline component to be configured in the request pipeline.

PROMPT_CONFIRM_CHECK_DATA

Check number, account number and transit number, comma separated.

Indicates that the customer/operator has been prompted to confirm the check data for this transaction.

NOTE

This event requires the ChequeAuth pipeline component to be configured in the request pipeline.

PROMPT_CONFIRM_EFFECTIVE_DATE

Effective date - YYMM

Indicates that the customer/operator has been prompted to confirm the card’s effective date.

NOTE

This event requires the EffectiveDate pipeline component to be configured in the request pipeline.

PROMPT_CONFIRM_EXPIRY_DATE

Expiry date - YYMM

Indicates that the customer/operator has been prompted to confirm the card’s expiry date.

NOTE

This event requires the ExpDate pipeline component to be configured in the request pipeline.

PROMPT_CONFIRM_GRATUITY_AMOUNT

Gratuity amount

Indicates that the customer/operator has been prompted to confirm the gratuity amount entered from the POS.

PROMPT_CONFIRM_MERCHANDISE_USER_ID

The merchandise type and merchandise ID in the format:

<merchandise_type>,<merchandise_id>

For example, "MSISDN,0122345677834"

Indicates that the merchandise item User ID must be confirmed, for example the MSISDN (cell phone number).

NOTE

This event requires the Prepay pipeline component to be configured in the request pipeline.

See the Prepay component in the eSocket.POS User Guide for further information.

PROMPT_CONFIRM_TRAN

Amount and account type, comma separated. for example, 000000010000,10

On a transaction with an accepted or declined dynamic currency conversion (DCC) offer, the alpha currency code of the transaction will also included. for example, 000000010000,10,USD

Indicates that the customer/operator has been prompted to confirm the transaction details (presented in the parameter data).

NOTE

This event requires the Confirm pipeline component to be configured in the request pipeline.

PROMPT_CONFIRM_TRAN_AID

Amount and application, comma separated. for example, 000000010000,Visa

On a transaction with an accepted or declined dynamic currency conversion (DCC) offer, the alpha currency code of the transaction will also included. for example, 000000010000,Visa,USD

Indicates that the customer/operator has been prompted to confirm the amount and application used for the transaction.

NOTE

This event requires the Confirm pipeline component to be configured in the request pipeline.

PROMPT_CORRECT_PRINTER_ERROR

The printer error type, which may be one of:

  • "0" - no error (n/a)

  • "1" - general error

  • "2" - out of paper

  • "3" - out of toner or ink

  • "4" - paper jam

Indicates that a printer error needs to be corrected.

NOTE

This event is not currently invoked by any standard eSocket.POS component, because the standard eSocket.POS product does not currently fully support driving the printer device, but may be invoked using a custom component.

PROMPT_CVV2

The CVV2 length in bytes.

Indicates that the customer/operator has been prompted to enter the card’s CVV2.

NOTE

This event requires the CVV2 pipeline component to be configured in the request pipeline.

PROMPT_EFFECTIVE_DATE

n/a

Indicates that the customer/operator has been prompted for the card’s effective date.

NOTE

This event requires the EffectiveDate pipeline component to be configured in the request pipeline.

PROMPT_DCC_OFFER

The currency conversion information in the format:

<name>=<val>|<name2>=<val2>|…​

The following properties are provided (in their corresponding order):

  • CommRate - foreign exchange commission rate as a fraction. Example: 0.07. Optional.

  • ExpTimestamp - offer expiration date and time in Coordinated Universal Time (UTC), formatted as an ISO 8601 date string: YYYYMMDDTHH:mm. Example: 20150730T15:35. Optional.

  • MargRate - foreign exchange markup rate of currency conversion provider as a fraction. Example: 0.03. Always present.

  • Provider - dynamic currency conversion (DCC) service provider. Optional.

  • Rate - exchange rate used during conversion (includes margin and commission). Example: 4.9881. Always present.

  • RateSrc - source of exchange rate. Optional.

  • SrcAmnt - transaction amount in minor denomination in the local currency before conversion. Example: 000000010000. Always present.

  • SrcCurr - alpha code of the local currency. Example: USD. Always present.

  • SrcAmntDec - transaction amount in major denomination in the local currency before conversion. Example: 100.00. Always present.

  • TgtAmnt - converted transaction amount in minor denomination in the foreign currency. Example: 000000009012. Always present.

  • TgtCurr - alpha code of the foreign currency. Example: EUR. Always present.

  • TgtAmntDec - converted transaction amount in major denomination in the foreign currency. Example: 90.12. Always present.

  • Timestamp - date and time conversion was performed in Coordinated Universal Time (UTC), formatted as an ISO 8601 date string: YYYYMMDDTHH:mm. Example: 20150730T15:35. Optional.

For example, CommRate=0.030456|ExpTimestamp=20170311T15:35|MargRate=0.102345|Provider=FEXCO|Rate=0.123456|RateSrc=US Fed Reserve|SrcAmnt=000000010000|SrcCurr=USD|SrcAmntDec=100.00|TgtAmnt=000000001234|TgtCurr=ZAR|TgtAmntDec=12.34|Timestamp=20160311T15:35

As indicated above, some of these properties are optional as some DCC providers may not provide all of the currency conversion information.

Indicates that the cardholder has been prompted to accept or decline a dynamic currency conversion (DCC) offer.

NOTE

This event requires the DCC pipeline component to be configured in the request pipeline.

PROMPT_EMBOSSED_DIGITS

The last 4 digits of the card number embossed on the card.

Indicates that the customer/operator has been prompted to enter the card embossed digits.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline.

PROMPT_EMV_APPLICATION_SELECTION

Comma separated list of the selection of EMV application names.

For example, Visa, MasterCard

Indicates that the customer/operator has been prompted to select an EMV application.

NOTE

This event is only raised if supported by the device driver, and also requires the EMV component to be configured in the request pipeline.

PROMPT_EXPIRY_DATE

n/a

Indicates that the customer/operator has been prompted for the card expiry date.

NOTE

This event requires the PAN and (for expiry date validation) the ExpDate pipeline component to be configured in the request pipeline.

PROMPT_EXTENDED_PAYMENT_PERIOD

Comma separated list of available extended payment periods.

For example, 06,09,12,18

Indicates that the customer/operator has been prompted to select an extended payment period from the list presented in the parameter.

NOTE

This event requires the ExtPayment pipeline component to be configured in the request pipeline.

PROMPT_GENERIC

The name of the prompt sent to the PED.

Indicates that a prompt has been presented to the customer/operator.

NOTE

This event requires the Prompt pipeline component to be configured in the request pipeline.

See the Prompt component in the eSocket.POS User Guide for further information.

PROMPT_GET_MERCHANDISE_CARD_SWIPE

The merchandise type.

Prompts for a merchandise card swipe.

NOTE

This event requires the Prepay pipeline component to be configured in the request pipeline.

See the Prepay component in the eSocket.POS User Guide for further information.

PROMPT_GET_MERCHANDISE_USER_ID

The merchandise type for which the User ID is required.

Indicates that the merchandise item User ID must be entered, for example the MSISDN (cell phone number).

NOTE

This event requires the Prepay pipeline component to be configured in the request pipeline.

See the Prepay component in the eSocket.POS User Guide for further information.

PROMPT_GRATUITY_AMOUNT

Transaction amount; Array of prompt options; Is custom gratuity amount allowed flag.

Indicates that the customer/operator has been prompted to select or enter a gratuity amount. The customer/operator can be provided with an option to enter the custom gratuity amount if the Boolean flag is set to true.

NOTE

This event requires the Gratuity pipeline component to be configured in the request pipeline.

PROMPT_INSERT_CARD

n/a

Indicates that the customer/operator has been prompted to insert a card into the card reader. This event is replaced by PROMPT_PRESENT_CARD when the Card Data Input Capability indicates that a contactless card reader is in use.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline. It will be used if the terminal can’t do contactless card reads or if the postilion.esocketpos.RaiseLegacyCardReadEvent property is set to true .

PROMPT_IS_CASHBACK_REQUIRED

n/a

Indicates that the customer/operator has been prompted to indicate whether cash back is desired.

NOTE

This event requires the Cashback pipeline component to be configured in the request pipeline but for EMV transactions it may also be invoked by the device driver.

Also see PROMPT_CASHBACK_AMOUNT.

PROMPT_IS_EXTENDED_PAYMENT_REQUIRED

n/a

Indicates that the customer/operator has been prompted to indicate whether extended payment is desired.

NOTE

This event requires the ExtPayment pipeline component to be configured in the request pipeline.

PROMPT_MERCHANDISE_CARD_SWIPE

Indicates that

NOTE

This event requires the PrepaidMerchandise pipeline component to be configured in the request pipeline.

PROMPT_PAN

n/a

Indicates that the customer/operator has been prompted to enter the PAN manually.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline.

PROMPT_PIN

n/a

Indicates that the customer/operator has been prompted to enter their PIN.

NOTE

This event requires the PIN pipeline component to be configured in the request pipeline.

PROMPT_POSTAL_CODE

n/a

Indicates that the customer/operator has been prompted to enter their postal code.

NOTE

This event requires the AVS pipeline component to be configured in the request pipeline.

PROMPT_PRESENT_CARD

n/a

Indicates that the customer/operator has been prompted to present their card. This event is used instead of PROMPT_INSERT_CARD when the Card Data Input Capability indicates that a contactless card reader is in use.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline. This event will not be raised if the postilion.esocketpos.RaiseLegacyCardReadEvent property is set to true .

PROMPT_READY_FOR_CARD_READ

n/a

Indicates that the eSocket.POS is ready to receive a transaction by means of a card read (EMV or swipe). In other words, the PreSwipe component is listening for a card read.

NOTE

This event requires the PreSwipe pipeline component to be configured in the request pipeline and the device driver to support EMV pre-swipe/pre-reads.

PROMPT_READY_FOR_SWIPE

n/a

Indicates that the eSocket.POS is ready to receive a transaction by means of a card swipe. I.e. the Prepay pipeline component is listening for a card swipe.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline.

PROMPT_REVERSAL_OUTCOME

The ISO response code received in the transaction response.

Indicates that the reversal outcome has been reported to the customer/operator.

NOTE

This event requires the RspCode pipeline component to be configured in the response pipeline.

PROMPT_SECURE_DATA_INPUT

n/a

Indicates that the customer/operator has been prompted to enter secure data.

NOTE

This event requires the PIN pipeline component to be configured in the request pipeline.

PROMPT_SIGNATURE_CAPTURE

n/a

Indicates that the customer/operator has been prompted to sign the signature capture device.

NOTE

This event requires the SignatureCapture pipeline component to be configured in the request pipeline.

PROMPT_SIGNATURE_REQUIRED

n/a

Indicates that the customer/operator has been prompted to sign the slip.

NOTE

This event requires the Signature pipeline component to be configured in the request pipeline.

PROMPT_SWIPE_CARD

n/a

Indicates that the customer/operator has been prompted to swipe their card.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline.

PROMPT_TRANSACTION_OUTCOME

The ISO response code received in the transaction response.

Indicates that the success or failure of the transaction has been reported to the customer/operator.

NOTE

This event requires the RspCode pipeline component to be configured in the request pipeline.

PROMPT_TRANSACTION_PROCESSING

n/a

Indicates that the customer/operator has been advised that the transaction is being processed.

NOTE

This event requires the WaitForAuth pipeline component to be configured in the request pipeline.

PROMPT_VERIFY_SIGNATURE

n/a

Indicates that signature verification is required.

NOTE

Currently, eSocket.POS supports flagging the signature verification requirement as a part of the eSocket.POS transaction, but not executing signature verification. Therefore, eSocket.POS does not invoke this event. However, you may create a custom pipeline component to invoke the event.

PROMPT_GET_OPC_SELECTION

The list of options, comma separated. Note that the first element is the original card name.for example, MasterCard,Opc1,Opc2

Indicates that the customer/operator has been prompted to select an OPC from the list (presented in the parameter data).

NOTE

This event requires the OPC pipeline component to be configured in the request pipeline.

PROMPT_GET_OPC_CONFIRMATION

The currency (ISO 8583 field 49), amount (ISO 8583 field 4) and OPC label, comma separated.for example, 826,000000200000,Opc2

Indicates that the customer/operator has been prompted to confirm the selected OPC (presented in the parameter data).

NOTE

This event requires the OPC pipeline component to be configured in the request pipeline.

PROMPT_DISPLAY_BARCODE

n/a

Indicates that an invalid barcode display request was sent to a device.

NOTE

This event requires the DisplayQRCode pipeline component to be configured in the request pipeline.

AUTHORIZE callback event data

The AUTHORIZE callback request and response data is supplied as a string of key-value pairs with the values inside single quotes, and the pairs separated by spaces, as illustrated in the following example:

_Key1='value1' Key2='value2' ... KeyN='valueN'_

Request data

The Callback Sink will provide some or all of the following keys in the authorization callback:

  • CardNumber

  • Track2

  • ExpiryDate

  • CardSequenceNumber

  • ServiceRestrictionCode

  • PanEntryMode

  • Track1

  • EmvAmount

  • EmvAmountOther

  • EmvApplicationIdentifier

  • EmvApplicationInterchangeProfile

  • EmvApplicationTransactionCounter

  • EmvApplicationUsageControl

  • EmvApplicationVersionNumber

  • EmvAuthorizationResponseCode

  • EmvCryptogram

  • EmvCryptogramInformationData

  • EmvCvmResults

  • EmvCvmList

  • EmvInterfaceDeviceSerialNumber

  • EmvIssuerActionCodeDefault

  • EmvIssuerActionCodeDenial

  • EmvIssuerActionCodeOnline

  • EmvIssuerApplicationData

  • EmvIssuerScriptResult

  • EmvTerminalApplicationVersionNumber

  • EmvTerminalCapabilities

  • EmvTerminalCountryCode

  • EmvTerminalType

  • EmvTerminalVerificationResult

  • EmvTransactionCurrencyCode

  • EmvTransactionDate

  • EmvTransactionStatusInformation

  • EmvTransactionType

  • EmvUnpredictableNumber

  • EmvTransactionCategoryCode

  • EmvTransactionSequenceCounter

Response Data

The POS may provide values for the following keys in the response:

  • ResponseCode (mandatory)

  • EmvIssuerAuthenticationData

  • EmvIssuerScriptTemplate1

  • EmvIssuerScriptTemplate2

  • AuthorizationNumber

  • PrivateData

DATA_REQUIRED event data

The POS Callback Device provides a set of logical devices which can be used to 'call back' to the POS in order to retrieve required data. These 'call backs' take the form of DATA_REQUIRED callbacks, where the event data specifies the data required.

DATA_REQUIRED callbacks may also occasionally be raised by custom entities in order to request data from the POS.

Note that, in order to receive the callback, the entity which raises the callback must be configured. For example, if the POS Callback Device keypad raises the event then

postilion.esocketpos.devicemanager.PosCallbackDevice must be configured as the 'Keypad' in the eSocket.POS deployment.

See the eSocket.POS User Guide for detailed information about the POS Callback Device.

The table below describes the expected response data. Alternatively, if the POS returns the string "CANCEL" in the response, this will have the effect of declining the transaction with a response code of 17 (Customer Cancellation).

Note that the Description describes the standard eSocket.POS component (if any) which will invoke the event with the specified event data. See the eSocket.POS User Guide for further information on each pipeline component.

Note that, where possible, the callback event data matches an eSocket.POS property name.

The events have been grouped alphabetically per Source.

Callback event data Source Format of expected response data Description

Account(<acc_type 1><acc_name 1>,…​,<acc_type n><acc_name n>)

Where:

  • <acc type i>

    is the ISO account type, format n2.

  • <acc_name i>

    is the descriptive name of the account,

    For example, Savings

For example, Account(10Savings,30Credit)

POSCallbackDevice (Keypad)

n2

The ISO account type of the selected account.

NOTE

This event requires the Account pipeline component to be configured in the request pipeline.

Address

POSCallbackDevice (Keypad)

ans..20

When used in conjunction with the Postal Code typically just the 1st line of the address is needed.

A typical use of this event is for an internet order transaction.

NOTE

This event requires the AVS pipeline component to be configured in the request pipeline.

Amount

POSCallbackDevice (Keypad)

n12

The transaction amount in the minor denomination.

CardNumber

POSCallbackDevice (Keypad)

n..19

NOTE:: This event requires the PAN pipeline component to be configured in the request pipeline.

CardSequenceNumber

POSCallbackDevice (Keypad)

n3 (Pad with leading zeros if required).

NOTE:: This event requires the CardSeqNr pipeline component to be configured in the request pipeline.

CashbackAmount(<max>)

Where

  • (<max>) is the maximum cashback amount allowed for the transaction.

POSCallbackDevice (Keypad)

n..12

The cashback amount in minor currency units. Zero or empty string if no cashback is required.

NOTE

This event requires the Cashback pipeline component to be configured in the request pipeline.

CashbackSelection(<parameters>)

Where

  • (<parameters>) consists of the following named parameters.

    Name : fixedCashbackOptions Description : Specifies the list of cashback amounts that were display on the PED at the fixed denomination cashback prompt. Value Format : Amount1,Amount2,AmountN

    Name : allowNumericEntryFallback Description : Indicates whether the customer was prompted to enter a cashback amount via a numeric entry screen. Value Format : 0 - Disallowed. 1 - Allowed.

    Format

    The above named parameters are specified in the format below. Parameters are delimited by the ';' (semi-colon) character, and within a parameter, the parameter name and parameter value are delimited by the '=' (equals) character.

    Example

    allowNumericEntryFallback=1;fixedCashbackOptions=100000,80000,60000,50000,30000,8000

POSCallbackDevice (Keypad)

n..12

The cashback amount in minor currency units, or zero if no cashback is required. If numeric fallback is allowed, and the user selected the 'other' option, an empty (zero-length) string should be provided by the POS in the callback response.

NOTE

This event requires the Cashback pipeline component to be configured in the request pipeline.

CheckNr

POSCallbackDevice (Keypad)

n..6

The check/cheque number in a check verification or check guarantee message.

NOTE

This event requires the ChequeAuth pipeline component in the request pipeline.

ChequeAccountNumber

POSCallbackDevice (Keypad)

ans16

The check/cheque account number in a check verification or check guarantee message.

NOTE

This event requires the ChequeAuth pipeline component to be configured in the request pipeline.

ChequeInstitutionCode

POSCallbackDevice (Keypad)

ans8

The check/cheque institution code in a check verification or check guarantee message.

NOTE

This event requires the ChequeAuth pipeline component to be configured in the request pipeline.

ChequeLimit

POSCallbackDevice (Keypad)

n..12

The check/cheque limit in minor currency units.

NOTE

This event requires the ChequeAuth pipeline component to be configured in the request pipeline.

Cvv2(<length>)

Where

  • (<length>) is optional and can be used to specify the length of the CVV2. Valid values for <length> are 4 for American Express cards and 3 for other cards. If (<length>) is omitted then a CVV2 length of 3 is assumed.

POSCallbackDevice (Keypad)

n3 or n4 if for American Express cards.

NOTE:: This event requires the CVV2 pipeline component to be configured in the request pipeline.

EmbossedDigits

POSCallbackDevice (Keypad)

n4

The last four digits of the PAN embossed on the card.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline.

ExpiryDate

POSCallbackDevice (Keypad)

n4, YYMM

NOTE:: This event requires the Expiry Date pipeline component to be configured in the request pipeline.

ExtendedPaymentPeriod(<periods>)

Where <periods> is a comma separated list of extended payment periods (in months) which can be selected for extended payment.

For example, ExtendedPaymentPeriod(6,12,24,36)

POSCallbackDevice (Keypad)

n2

The number of months that the cardholder prefers to pay for this item if permitted by the card issuer. Empty or '00' if extended payment is not required.

NOTE

This event requires the ExtPayment pipeline component to be configured in the request pipeline.

IsExtendedPaymentRequired

POSCallbackDevice (Keypad)

"TRUE" or "FALSE"

"TRUE" if extended payment is required; "FALSE" or an empty string if extended payment is not required.

NOTE

This event requires the ExtPayment pipeline component to be configured in the request pipeline.

IsPrinterErrorCorrected(<error_type)

Where the printer error type may be one of:

  • "0" - no error (n/a)

  • "1" - general error

  • "2" - out of paper

  • "3" - out of toner or ink

  • "4" - paper jam

POSCallbackDevice (Keypad)

"TRUE" or "FALSE"

"TRUE" if the printer error has been corrected; "FALSE" otherwise.

NOTE

Currently, eSocket.POS does not fully support driving the printer device. Therefore, eSocket.POS does not invoke the event. However, you can create a custom pipeline component to invoke the event.

PostalCode

POSCallbackDevice (Keypad)

an..9

Postal or ZIP code.

NOTE

This event requires the AVS pipeline component to be configured in the request pipeline.

SignatureVerification

POSCallbackDevice (Keypad)

n1

Signature Verification code which is one of the following:

  • "1" - the signature was successfully verified

  • "2" - the signature failed verification

  • "3" - a reprint of the merchant receipt is required

    NOTE

    eSocket.POS supports flagging the signature verification requirement as part of the eSocket.POS transaction, but not executing signature verification. Therefore eSocket.POS does not invoke the event. However, you can create a custom pipeline component to invoke the event.

StartDate

POSCallbackDevice (Keypad)

n4, YYMM

NOTE:: This event requires the EffectiveDate pipeline component to be configured in the request pipeline.

UserId

POSCallbackDevice (Keypad)

ans..12

NOTE:: This event requires the Prepay pipeline component to be configured in the request pipeline.

PinData(<pan>,<amount>,<acc_type>)

Where:

  • <pan> is the card number, format n..19.

  • <amount> is the transaction amount in the minor denomination, format n12.

  • <acc_type> is the ISO account type, format n2.

POSCallbackDevice (Pinpad)

an16

The 64-bit encrypted PIN data, expressed in 16 hexadecimal characters.

NOTE

This event requires the PIN pipeline component to be configured in the request pipeline.

PinKeySequenceNr

POSCallbackDevice (Pinpad)

an16

The 8-byte DUKPT key sequence number, expressed in 16 hexadecimal characters.

NOTE

This event requires the PIN pipeline component to be configured in the request pipeline.

MerchandiseCardSwipe(<merchandise_type>)

For example, MerchandiseCardSwipe(TELEPHONE PREPAY)

Where:

<merchandise_type >

is the merchandise type, for instance: 'TELEPHONE PREPAY'

POSCallbackDevice (Card Reader)

ans..30

NOTE:: This event requires the Prepay pipeline component to be configured in the request pipeline.

Track1

POSCallbackDevice (Card Reader)

ans..76

The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813, including field separators but excluding the begin sentinel, end sentinel, and longitudinal redundancy check characters.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline.

Track2

POSCallbackDevice (Card Reader)

z..37

The information encoded on Track 2 of the magnetic stripe as defined in ISO 7813, including field separators but excluding the begin sentinel, end sentinel, and longitudinal redundancy check characters. The field separator can be either a "=" or a "D" character.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline.

Track3

POSCallbackDevice (Card Reader)

n..104

The information encoded on Track 3 of the magnetic stripe, excluding the begin sentinel, end sentinel, and longitudinal redundancy check characters.

NOTE

This event requires the PAN pipeline component to be configured in the request pipeline.

PosCallbackDeviceV2

POS Callback Device callbacks

The POS Callback Device provides a set of logical devices which can be used to 'call back' to the POS in order to send a command to the device. Each supported device command is implemented by a callback event ID in the form <LogicalDevice><Command>_ , e.g. CardReader_GetCardSwipe - as indicated in the table below.

NOTE:
For the POS to receive a callback, the entity which raises the callback must be configured.
For example, if the POS Callback Device keypad raises an event, then postilion.esocketpos.devicemanager.PosCallbackDeviceV2 must be configured as the keypad in eSocket.POS.
Furthermore, the POS must register for each individual event ID it wants to receive callbacks for. See the eSocket.POS User Guide for detailed information about the POS callback device.

The following table lists the event IDs corresponding to the supported logical devices and commands. The event data and response data are in JSON format. Alternatively:

  • If the POS returns the string 'CANCEL' in the response, the transaction will be declined with a response code of 17 (Customer Cancellation).

  • If the POS returns the string 'ERROR' in the response, the transaction will be declined with a response code of 96 (Remote Device Failure).

Callback event ID Expected event data Expected response data Response data format Description

CardReader_GetCardSwipe

N/A

\{"track1":" <track1_data> ","track2":" <track2_data> ", "track3":" <track3_data> "}

Where:

  • <track1_data> is the information encoded on Track 1 of the magnetic stripe as defined in ISO 7813, including field separators but excluding the begin sentinel, end sentinel, and longitudinal redundancy check characters.

  • <track2_data> is the information encoded on Track 2 of the magnetic stripe as defined in ISO 7813, including field separators but excluding the begin sentinel, end sentinel, and longitudinal redundancy check characters. The field separator can be either an equals sign (=) or a "D" character.

  • <track3_data> is the information encoded on Track 3 of the magnetic stripe, excluding the begin sentinel, end sentinel, and longitudinal redundancy check characters.

track1 data is ans..76

track2 data is z..37

track3 data is n..104

Retrieves the track data from a card swipe.

CardReader_GetMerchandiseCardSwipe

\{"merchandiseType":" <merchandise_type> "}

For example,

\{"merchandiseType":"TELEPHONE_PREPAY"}

" <track_data> "

Where:

  • <track_data> is the merchandise card track data read from the card swipe.

ans..30

Retrieves the track data from the merchandise card swipe.

Display_DisplayPleaseWait

N/A

N/A

N/A

Sends the command to display "Please Wait" on the display.

Display_DisplayWelcome

N/A

N/A

N/A

Sends the command to display "Welcome" on the display.

Keypad_GetAccount

\{"accounts":[ \{"type":" <type 1> ", "name":" <name 1> "}, …​
\{"type":" <type n> ", "name":" <name n> "}]}

Where:

  • <type> is a 2-digit ISO account type.

  • <name> is the descriptive name of the account.

For example,

\{"accounts":[\{"type":"10","name":"Savings"}, \{"type":"30","name":"Credit"}]}

" <account_type> "

Where:

  • <account_type> is the ISO account type selected from the list of accounts sent in the event data.

n2

Retrieves the account type from a list of accounts sent to the POS in the event data.

Keypad_GetAddress

N/A

" <address> "

For example,

"2388 Lake Ave"

ans20

When used in conjunction with the postal code, typically just the first line of the address is needed.

A typical use case is for an internet order transaction.

Keypad_GetAmount

\{"maxAmount":" <max_amount> "}

Where:

  • <max_amount> is the maximum amount allowed in the minor denomination

" <amount> "

Where:

  • <amount> is the amount that is less than or equal to the set maximum amount, set in the minor denomination.

n12

Retrieves the transaction amount based on a set maximum amount.

Keypad_GetCardSequenceNumber

N/A

" <card_sequence_number> "

Where:

  • <card_sequence_number> is a 3-digit card sequence number.

n3

Retrieves the Card Sequence Number.

Keypad_GetCashbackAmount

\{"maxCashbackAmount":" <max_cashback_amount> "}

For example,

\{"maxCashbackAmount":"10000"}

" <cashback_amount> "

For example,

"5000"

n..12

Retrieves the cashback amount based on the maximum cashback amount allowed.

The amounts will be in minor denomination.

Keypad_GetCashbackAmount

NOTE: There are two instances of Keypad_GetCashbackAmount documented in this table, each with different parameters. You only need to register it once to be able to listen for both.

\{"promptOptions":[
\{"optionText":" <text 1> ", "optionResult":" <result 1> "},…​,
\{"optionText":" <text n> ", "optionResult":" <result n> "}], "allowNumericEntryFallback": <allow_numeric_entry_fallback> }

Where:

  • <text> is the cash back option display text.

  • <result> is the cash back option amount.

  • <allow_numeric_entry_fallback> is a Boolean (true or false) value indicating whether to allow numeric entry fallback.

For example,

\{"options":[\{"optionText":"$50.00", "optionResult":"5000"}, \{" optionText":"$100.00", "optionResult":"10000"}], "allowNumericEntryFallback":true}

" <cashback_amount> "

For example,

"5000"

n..12

Retrieves the cash back amount given a list of possible cash back options.

The amounts are in minor denomination.

Keypad_GetCheckNumber

N/A

" <check_number> "

For example,

"9201"

n..6

Retrieves the check number.

Keypad_GetCheckAccountNumber

N/A

" <check_account_number> "

For example,

"1234567890123456"

ans16

Retrieves the check account number.

Keypad_GetCheckInstitutionCode

N/A

" <check_institution_code> "

For example,

"12345678"

ans8

Retrieves the check institution code.

Keypad_GetCheckLimit

N/A

" <check_limit> "

For example,

"50000"

n..12

Retrieves the check limit in minor denomination.

Keypad_GetCvv2

N/A

" <cvv2> "

For example,

"123"

n3 or n4 if for American Express cards.

Retrieves the CVV2 of a card.

Keypad_GetEffectiveDate

N/A

" <effective_date> "

For example,

"2101"

n4, YYMM

Retrieves the effective or start date.

Keypad_GetEmbossedDigits

N/A

" <embossed_digits> "

For example,

"1111"

n4

Retrieves the last four digits of the PAN embossed on the card.

Keypad_GetExpiryDate

N/A

" <expiry_date> "

For example,

"2701"

n4, YYMM

Retrieves the card’s expiration date.

Keypad_GetExtendedPaymentPeriod

\{"periods":[" period 1 ",…​," period n "]}

Where:

  • <period> is the extended payment period in months.

For example,

\{"periods":["6", "12", "24", "36", "72"]}

" <extended_payment_period> "

For example,

"36"

n2

Retrieves selected extended payment periods from a list of available extended payment periods.

Keypad_GetGratuityAmount

\{"transactionAmount":" <transaction_amount> ", "promptOptions":[\{"optionText":" <text 1> ", "optionResult":" <result 1> "},…​\{"optionText":" <text n> ", "optionResult":" <result n> "}], "allowCustomGratuity": <allow_custom_gratuity> }

Where:

  • <transaction_amount> is the minor denomination transaction amount.

  • <text> is the gratuity option text.

  • <result> is the gratuity amount for the option.

  • <allow_custom_gratuity> is a Boolean (true or false) value indicating whether to allow custom gratuity amounts.

For example,

\{"transactionAmount":10000, "promptOptions":[\{"optionText":"$10.00", "optionResult":"1000"}, \{"optionText":"$20.00", "optionResult":"2000"}], "allowCustomGratuity":false}

" <gratuity_amount> "

For example,

"1000"

n12

Retrieves the gratuity amount selected from the list of gratuity prompt options.

Keypad_GetMerchandiseUserID

\{"merchandiseType":"<merchandise_type>"}

For example,

\{"merchandiseType":"TELEPHONE_PREPAY"}

" <user_id>"

For example,

"900001"

ans..12

Retrieves the user ID for the given merchandise type.

KeyPad_GetPan

N/A

" <pan> "

For example,

"1234567890123456789"

n..19

Retrieves the PAN.

Keypad_GetPostalCode

N/A

" <postal_code> "

For example,

"85142"

an..0

Retrieves the postal code.

Keypad_GetSignatureVerification

N/A

<signature_verification_code>

Where <signature_verification_code> is one of the following:

  • 1 - the signature was successfully verified.

  • 2 - the signature failed verification.

  • 3 - a reprint of the merchant receipt is required.

n1

Retrieves the signature verification code.

Keypad_IsExtendedPaymentRequired

N/A

<is_extended_payment_required>

For example,

true

true or false

Retrieves a Boolean value indicating whether extended payment is required.

Keypad_IsPrinterErrorCorrected

\{"errorType": <error_type> }

Where <error_type> is one of the following:

  • 0 - no error(N/A)

  • 1 - general error

  • 2 - out of paper

  • 3 - out of toner or ink

  • 4 - paper jam

<error_corrected>

For example,

true

true or false

Retrieves a Boolean value indicating whether the printer error has been corrected for the given error type.

Pinpad_CalculateMac

\{"encMacSessionKey":" <session_key> ", "macData":" <mac_data> "}

Where:

  • <session_key> is the MAC session key encrypted under the MAC master key.

  • <mac_data> is the data for which the MAC should be calculated.

" <mac> "

Where:

  • <mac> is the calculated MAC value.

an

Calculates the MAC value given the encrypted session key and the MAC data.

Pinpad_CalculateMacV2

\{"macData": "<mac_data>"}

Where:

<mac_data> is the data for which the MAC should be calculated.

" <mac> "

Where:

  • <mac> is the calculated MAC value.

an

Calculates the MAC value for the MAC data.

Pinpad_DoKeyChange

\{"keyData":" <key> "}

Where:

  • <key> is the new key data

" <response_code> "

Where:

  • <response_code> is the key load response code indicating success (00) or failure (05).

an

Changes the encryption key on the PIN pad and returns the response code (success or failure).

Pinpad_GetKeySequenceNumber

N/A

" <sequence_number> "

Where:

  • <sequence_number> is the Key Sequence Number from the PIN pad.

an16

Retrieves the Key Sequence Number from the PIN pad.

Pinpad_GetPinData

\{"pan":" <pan> ", "amount":" <amount> ", "accountType":" <account_type> "}

Where:

* <pan> is the card account number, format n..19. * <amount> is the transaction amount in the minor denomination, format n12. * <account_type> is the ISO account type, format n2.

" <pin_data> "

Where:

  • <pin_data> is the 64-bit encrypted PIN data, expressed in 16 hexadecimal characters.

an16

Creates the encrypted PIN data for the given PAN, amount, and account type.

Pinpad_LoadPinSessionKey

\{"pinSessionKey":" <session_key> "}

Where:

* <session_key> is the new PIN session key to load on the device.

N/A

N/A

Loads a new PIN session key on the device.

Pinpad_LoadMacSessionKey

\{"macSessionKey":" <session_key> "}

Where:

  • <session_key> is the new MAC session key to load on the device.

N/A

N/A

Loads a new MAC session key on the the device.

Pinpad_VerifyMac

\{"encMacSessionKey":" <session_key> ", "macData":" <mac_data> "}

Where:

  • <session_key> is the MAC session key encrypted under the MAC master key.

  • <mac_data> is the data for which the MAC should be verified

" <value> "

Where:

  • <value> is the verified MAC value.

an

Verifies the MAC for the given session key and MAC data and returns the value.

SmartCardReader_GetDeviceInfo

N/A

This method will return the device information in the Device Info JSON Structure section that follows.

See the Device Information Field Description section for the field descriptions.

Retrieves the device info for the smart card reader.

SmartCardReader_GetEmvKernelVersion

N/A

" <version> "

Where:

  • <version> is the EMV Kernel version.

ans

Retrieves the EMV Kernel Version.

Device information JSON structure

The device information returned from the POS must use the following JSON structure.

{
    "cap" : ["atm", "pos", "cardreader", "keypad", "printer", "display", "checkreader", "pinpad", "sigcap"],
    "hardware" : {
        "compliance" : [{
            "assigner" : "assigner",
            "effectiveDate" : "effectiveDate",
            "expirationDate" : "expirationDate",
            "issuer" : "issuer"},...
            "reference" : "reference",
            "type" : "type",
            "version" : "version"},...
        ],
        "date" : "date",
        "ipAddress" : "ipAddress",
        "macAddress" : "macAddress",
        "manufacturer" : "manufacturer",
        "manufacturingSerial" : "manufacturingSerial",
        "modelName" : "modelName",
        "modelNumber" : "modelNumber",
        "serial" : "serial",
        "series" : "series",
        "version" : "version",
        "hwId" : "hwId"
    },
    "id" : "id",
    "properties" : [{
        "name" : "name",
        "value" : "value"},...
    ],
    "software" : {
        "module" : [{
            "build" : "build",
            "compliance" : [{
                "assigner" : "assigner",
                "effectiveDate" : "effectiveDate",
                "expirationDate" : "expirationDate",
                "issuer" : "issuer"},...
                "reference" : "reference",
                "type" : "type",
                "version" : "version"},...
            ]
            "date" : "date",
            "hash" : "hash",
            "majorVersion" : "majorVersion",
            "minorVersion" : "minorVersion",
            "name" : "name",
            "provider" : "provider",
            "type" : "type",
            "version" : "version"},...
        ],
        "postilionModule" : [{
            "alpha" : "alpha",
            "beta" : "beta",
            "build" : "build",
            "compliance" : [{
                "assigner" : "assigner",
                "effectiveDate" : "effectiveDate",
                "expirationDate" : "expirationDate",
                "issuer" : "issuer"},...
                "reference" : "reference",
                "type" : "type",
                "version" : "version"},...
            ],
            "date" : "date",
            "dependency" : "dependency",
            "edition" : "edition",
            "hash" : "hash",
            "installType" : "installType",
            "majorVersion" : "majorVersion",
            "minorVersion" : "minorVersion",
            "name" : "name",
            "package" : "package",
            "patches" : "patches",
            "previousInstalledVersion" : "previousInstalledVersion",
            "sdkMajorVersion" : "sdkMajorVersion",
            "sdkMinorVersion" : "sdkMinorVersion",
            "sdkServicePackVersion" : "sdkServicePackVersion",
            "servicePackVersion" : "servicePackVersion",
            "version" : "version"},...
        ]
    }
}

Device information field descriptions

Field Description Format Required

cap

The supported capabilities of the connected device.

Each capability represented with one of the following values:

  • atm

  • pos

  • keypad

  • printer

  • display

  • checkreader

  • inpad

  • sigcap

Y

hardware

The hardware section contains the hardware information of the connected device.

See the Hardware section for the field descriptions.

N

id

The unique ID of the connected PED. An example of this could be as follows:

hardware_id + "" + _serial_number + "[" + device_name + "" + rank + "]"

ans

Y

properties

An array of additional properties for the connected device.

See the Properties section for the field descriptions.

N

software

The software section contains the software information of the connected device.

See the Software section for the field descriptions.

N

Hardware

Field Description Format Required

compliance

An array of compliance characteristics for the connected device.

See the Compliance section for the field descriptions.

N

date

The manufactured date of the connected device.

ns

N

ipAddress

The IP Address of the device. Set this if applicable.

ans39

Can be in either IPv4 or IPv6 format.

N

macAddress

The MAC address of the PED. Set this if applicable.

ans17

Can be formatted as follows:

  • xx:xx:xx:xx:xx:xx

  • xx-xx-xx-xx-xx-xx

N

manufacturer

The manufacturer of the PED

ans

N

manufacturingSerial

The terminal’s unique serial number, set by the manufacturer.

ans

N

modelName

The model name of the PED, for example, iPP350.

ans

N

modelNumber

The model number of the PED, for example, 350.

ans

N

serial

The terminal’s unique injected serial number.

ans

N

series

The hardware series of the PED, for example, iPP.

ans

N

version

The hardware version of the PED.

ans

N

hwId

The hardware identifier of the PED.

ans

N

Properties

Field Description Format Required

name

The name of the property

ans

Y

value

The value of the property

ans

Y

Software

Field Description Format Required

module

An array of software modules

See the Module section for the field descriptions.

N

postilionModule

An array of Postilion Modules

See the Postilion Module section for the field descriptions.

N

Module

Field

Description

Format

Required

build

The software module build number

ans

N

compliance

The software module compliance characteristics

See the Compliance section for the field descriptions.

N

date

The software module build date

ns

N

hash

The software module hash/CRC

ans

N

majorVersion

The major version of the software module

ans

N

minorVersion

The minor version of the software module

ans

N

name

The software module name

ans

Y

type

The software module type

Types of the software module include:

  • os

  • app

  • emv_kernel

  • cntctls_kernel

  • lib

  • file

Y

version

The software module version

ans

Y

Postilion Module

Field

Description

Format

Required

alpha

Indicates if the Postilion module is alpha

  • 1 - for true

  • 0 - for false

N

beta

Indicates if the Postilion module is beta

  • 1 - for true

  • 0 - for false

N

build

The software Postilion module build number

ans

N

compliance

The software Postilion module compliance characteristics

See the Compliance section for the field descriptions.

N