eSocket.POS

eSocket.POS Developer Guide

Postilion ®
ACI Worldwide, Inc
2024-02-09
Version: v3.0.00.835361-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 can 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

C

H

This property must be set to the following values, depending on the transaction type:

  • 1000 - Express credit application

  • 1010 - Credit application

  • 1011 - Credit application prescreen (preapproval) request

  • 1012 - Credit application prescreen (preapproval) acceptance

  • 2111 - Register device (if the MessageType is ADMIN_REQUEST)

  • 2112 - Advance encryption key (if the MessageType is ADMIN_REQUEST)

  • 7116 - Credit admin payment on account with cash transactions

  • 7117 - Credit admin payment on account with check transactions

Note
This property must not be set for gift card transactions where the Type property is set to CARD_ACTIVATE, CARD_DEACTIVATE, CARD_ACTIVATE_REFUND, LOAD, or UNLOAD. It must also not be set to 3100 (card activate) or 3101 (card deactivate) if the MessageType is set to ADMIN_REQUEST.

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 will not 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 will not 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 will not 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.

LongAuthorizationNumber

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 ExtendedAuthorizationNumber, and up to 50 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 will not be set in the response. If the Message Type is "CONFIRM" and eSocket.POS has been restarted, this field will not 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 will not 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 will not 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. will not 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

Can be set 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

Standalone 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

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 drycleaning items charged to the room.

LdAmountGiftShop

O

T

Lodging (e.g. hotel, motel) transactions: The total amount of gift shop and specialty 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.

OfflineAccumulatorBalance

-

C

Represents the amount of offline spending 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 compares 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.

RecurringPaymentIndicator

O

H

Specifies the recurring payment indicator.

StoredCredentialIndicator

O

H

Specifies the stored credential indicator.

RecurringPaymentDetail

O

H

Contains the details of the recurring payment.

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.

OfflineAccumulatorBalance

-

C

Represents the amount of offline spending 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

CustomerFirstName

O

H

CustomerLastName

O

H

CustomerMiddleInitial

O

H

CustomerInitials

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.3.5. BarcodeData

Format

Description

Barcode data encoded in Base64.

1.3.6. BarcodeStatusCode

Format

n1

Description

Status code indicating whether the barcode reads are successful.

Code Description

0

Success

1

Failure

2

Timeout

3

Cancelled

1.3.7. Symbology

Format

Description

The following table describes the mapping between codes and barcode symbologies.

Code Description

-1

Unknown

1

EAN13

2

EAN8

3

UPCA

4

UPCE

5

EAN13_2

6

EAN8_2

7

UPCA_2

8

UPCE_2

9

EAN13_5

10

EAN8_5

11

UPCA_5

12

UPCE_5

13

Code 39

14

RFU

15

Interleaved 2 of 5

16

Standard 2 of 5

17

Matrix 2 of 5

18

RFU

19

CodaBar

20

AmesCode

21

MSI

22

Pleassey

23

Code 128

24

Code 16k

25

Code 93

26

Code 11

27

Telepen

28

Code 49

29

Code 39_ItalianCPI

30

Codablock A

31

Codablock F

32

Codablock 256

33

PDF417

34

GSI_128

35

ISBT128

36

MicroPDF

37

GSI_DataBarOmni

38

GSI_DataBarLimited

39

GSI_DataBarExpanded

40

DataMatrix

41

QRCode

95

GSI DataBar Omni-Dir Composite (CC-A)

44

GSI DataBar

45

GS1 DataBar Expanded Composite (CC-A)

46

GS1 Composite/GS1-128 Composite (CC-A)

47

EAN-13 Composite (CC-A)

48

EAN-8 Composite (CC-A)

49

UPC-A Composite (CC-A)

50

UPC-E Composite (CC-A)

51

GS1 DataBar Omni-Dir Composite (CC-B)

52

GS1 DataBar Limited Composite (CC-B)

53

GS1 DataBar Expanded Composite (CC-B)

54

GS1 Composite/GS1-128 Composite (CC-B)

55

EAN-13 Composite (CC-B)

56

EAN-8 Composite (CC-B)

57

UPC-A Composite (CC-B)

58

UPC-E Composite (CC-B)

59

GS1 Composite/GS1-128 Composite (CC-C)

60

ISBN

61

Postnet

62

Planet

63

BPO

64

Canada Post

65

Australian Post

66

Japan Post

67

Dutch Post

68

China Post

69

Korean Post

70

TLC39

71

Trioptic

72

ISMN

73

ISSN

74

Aztec

75

Sweden Post

76

Infomail

77

Multicode

78

Incomplete Multicode

90

MaxiCode

91

NEC 2 of 5

92

Postal format

93

Pharma code

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

96

EBT cash benefit

98

EBT food stamp

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

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, and so on.

Account

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

Account can contain additional properties. These are listed in the table that follows:

=== Properties

Field Format Type (Element, Attribute) Description

TransactionBillingMethodIndicator

a..1

Attribute

Indicates how the transaction will be billed to the customer. R - Recurring transaction I - Installment billing transaction D - Deferred billing transaction

PaymentPurchaseIndicator

a..1

Attribute

Indicates the customer’s income frequency A - Annual M - Monthly W - Weekly

MinimumPaymentDue

n..12

Attribute

Minimum payment due

PromoCode

a..1

Attribute

A flag or value defining a promotion code. For Stored Value Systems (SVS), a value of 'Y' in this field enables promotional gift cards.

SerialNumber

n..16

Attribute

For SVS, this is returned in the response. Either a SerialNumber or a primary account number (PAN) can be returned.

AccountExpirationDateTime

an..14

Attribute

Account expiration date/time in UTC format(YYYYMMDDTHHMMZ)

PaymentPlanCode

n..5

Attribute

Payment plan code or credit plan.

ReferenceNo

ans..12

Attribute

Reference number sent back from the processor

ApplicationReferenceNo

n..16

Attribute

The application ID returned in the credit admin express application response

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.

PayeeContact

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

Payee contact can contain additional contact information for a payee as shown in the following table:

Properties
Field Format Type (Element, Attribute) Description

FirstName

ans..32

Attribute

Customer’s first name

LastName

ans..35

Attribute

Customer’s last name

CardHolderName

ans..45

Attribute

Customer’s actual name as embossed on the credit card

MiddleInitial

ans..1

Attribute

Customer’s middle initial

CustomerSuffix

ans..2

Attribute

Customer’s suffix, for example, Jr, Sr, or II

Gender

a..1

Attribute

Customer’s gender

CustomerDateOfBirth

n..8

Attribute

Customer’s date of birth (YYYYMMDD)

MotherMaidenName

ans..35

Attribute

Customer’s mother’s maiden name

LengthAtAddress

n..4

Attribute

Length of time living at the current address (YYMM)

CustomerCellPhoneNumber

n..10

Attribute

Customer’s cell phone number

CustomerBusinessPhone

n..10

Attribute

Customer’s business phone number

CustomerPreviousAddress

ans..40

Attribute

Customer’s previous residential address

CustomerPreviousCity

ans..40

Attribute

Customer’s previous residential city

CustomerPreviousState

ans..2

Attribute

Customer’s previous residential state

CustomerPreviousZip

ans..9

Attribute

Customer’s previous residential zip

CustomerPreviousLengthAtAddress

n..4

Attribute

Length of time living at the previous address

CustomerPreviousBusinessPhone

n..10

Attribute

Customer’s previous business phone number

HousingCode

a..1

Attribute

Housing code:

R - Rent
O - Own
T - Other

CustomerOccupationCode

an..2

Attribute

Customer’s occupation code

YearlyIncome

n..8

Attribute

Customer’s annual income

PrimaryIncomeFrequency

a..1

Attribute

Customer’s income frequency:

W - Weekly
A - Annually
M - Monthly

PanderFlag

n..1

Attribute

Pander flag:

1 - Mail can be sent
0 - Mail should not be sent

InsuranceIndicator

n..1

Attribute

Insurance indicator - used for authorizers that support online credit applications where the credit applicant can select if they would like to insure their card debt.

0 - not applicable
1 - yes, purchasing insurance
2 - no, not purchasing insurance

AdditionalID1

ans..40

Attribute

Additional ID 1

AdditionalID2

ans..40

Attribute

Additional ID 2

AdditionalID3

ans..40

Attribute

Additional ID 3

AdditionalID4

ans..40

Attribute

Additional ID 4

PatriotPlace

ans..2

Attribute

The state code or country code of the ID in the credit application request message. If a passport number is the ID in the message, then the patriot place is a 2-character country code. If a US driver’s license number is the ID in the message, then the patriot place is a 2-character state code.

PatriotIssueDate

n..8

Attribute

Patriot issue date - the issue date of the ID used in the credit application request message.

Format YYYYMMDD

PatriotExpirationDate

n..8

Attribute

Patriot expiration date - the expiration date of the ID used in the credit application request message.

Format YYYYMMDD

CustomerAuthorizedUser

ans..64

Attribute

Authorized user

JointAuthFlag

a..1

Attribute

Joint applicant values for ADS:

J - Joint application
A - Authorized buyer

RelativeCode

a..1

Attribute

Authorized buyer relationship:

O - Other
S - Spouse

SecondaryCustomerFirstName

ans..32

Attribute

Secondary customer’s first name

SecondaryCustomerMiddleInitial

ans..1

Attribute

Secondary customer’s middle initial

SecondaryCustomerLastName

ans..35

Attribute

Secondary customer’s last name

SecondaryCustomerDateOfBirth

n..8

Attribute

Secondary customer’s date of birth

SecondaryCustomerHomePhone

n..10

Attribute

Secondary customer’s home phone number

SecondaryCustomerBusinessPhone

n..10

Attribute

Secondary customer’s business phone number

SecondaryCustomerYearlyIncome

n..8

Attribute

Secondary customer’s annual income

SecondaryCustomerIncomeFrequency

a..1

Attribute

Secondary customer’s income frequency:

W - Weekly
A - Annually
M - Monthly

CardIssuanceLevel

n..1

Attribute

Card issuance level - indicates the number of times the card has been re-issued.

TextFlag

a..1

Attribute

Text flag - A flag indicating if the customer can be contacted via text messaging.

Y - the customer can be contacted via text message.
N - the customer cannot be contacted via text message.

AdditionalID

The format of AdditionalID is XXDDVV…​V, where

  • XX = The ID owner (either "01" Primary Card Holder or "02" Secondary Card Holder)

  • DD = The ID type. See the table that follows for a list of valid values.

  • VV…​V = The ID value.

Example: AdditionalID = 010212345678

Type of Identification Meaning

00

Unspecified

01

Credit

02

Driver’s license

03

Checking account

04

Debit card

05

Preferred shopper’s card

06

State ID

07

Social security number

08

Student ID

09

Employee ID

10

Passport number

11

Military ID

12

Senior citizens ID

50

Alternate value card

51

Alternate credit card

90

EBT card

91

Calling card

92

Value card

93

Prepaid cellular

94

eWIC card

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.

CtlsPinBypass

Format

n1

Description

A flag indicating whether the PIN was required but bypassed during a contactless transaction.

Possible values:

  • 0 : PIN was not bypassed for the contactless transaction. In this case, usually the flag will not be set.

  • 1 : PIN was bypassed for the contactless transaction.

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.

LongAuthorizationNumber

Format

Description

A code assigned by the authorizing institution indicating approval.

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

PromptForOdometer

String

ReceiptText

String

PrintPricePerGallon

String

MaximumAmount

String

MaximumOilAmount

String

MaximumPartsAmount

String

MaximumMiscellaneousAmount

String

FleetBatchData

Array of FleetBatchData objects

Prompt

Array of Prompt objects

DriverId

Format

Description

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

FleetBatchData

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

Properties

Name

Type

BatchDate

String

TransactionCount

String

Total

String

TotalUnit

String

BatchDate

Format

Description

The fleet batch date.

TransactionCount

Format

Description

The transaction count for a batch.

Total

Format

Description

The total fuel quantity.

TotalUnit

Format

n..

Description

The total units ('Gallons' or 'Liters').

MaximumAmount

Format

n12

Description

The maximum amount (in minor denomination) in the transaction’s currency.

MaximumMiscellaneousAmount

Format

n12

Description

The maximum miscellaneous amount (in minor denomination) in the transaction’s currency.

MaximumOilAmount

Format

n12

Description

The maximum oil amount in minor denomination in the currency of the transaction.

MaximumPartsAmount

Format

n12

Description

The maximum parts amount in minor denomination in the currency of the transaction.

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.

PrintPricePerGallon

Format

a1

Description

This field identifies if the price per gallon must be printed on the customer’s receipt. 'Y' indicates it must be printed. 'N' indicates it must not be printed.

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

CustomerData1

String

CustomerData2

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

SiteTransactionNumber

String

ContractNumber

Format

Description

The contract number.

CustomData

Format

Description

This field carries fleet authorizer specific data like "VoyagerData".

CustomerData

Format

Description

Any customer data.

CustomerData1

Format

Description

Any customer data.

CustomerData2

Format

Description

Any additional customer data.

Department

Format

Description

The department number.

DriverDateOfBirth

Format

Description

The driver date of birth.

DriverLicense

Format

Description

The driver license number.

DriverLicenseLocation

Format

Description

This is used to carry the state/province or other location data.

DriverLicenseName

Format

Description

The driver license name.

DriverLicenseState

Format

Description

The driver license state code.

EmployeeNumber

Format

n..

Description

The fleet employee number.

FleetId

Format

Description

The ID that is defined to the fleet authorizer.

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.

PumpNumber

Format

Description

The petrol pump number.

SiteTransactionNumber

Format

n12

Description

The site transaction number.

TractorNumber

Format

Description

The tractor number.

TrailerHours

Format

Description

The fleet trailer hours number.

TrailerId

Format

Description

The fleet trailer identification.

TrailerLicense

Format

Description

The trailer license number.

TrailerLicenseState

Format

Description

The trailer license state code.

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.

VehicleLicense

Format

Description

The vehicle license number.

VehicleLicenseState

Format

Description

The vehicle license state code.

VehicleTag

Format

Description

The fleet vehicle tag.

VehicleVINNumber

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

PromptForOdometer

Format

n1

Description

The field identifies if the prompt is required to complete the transaction. '1' indicates the prompt is required. '0' indicates the prompt is not required.

PurchaseType

Format

a1

Description

The type of products purchased.

Valid values:

  • F - Fuel

  • N - Non-fuel

  • B - Both

ReceiptText

Format

Description

The receipt text.

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

FleetDataRsp

Properties

Name

Type

PromptForOdometer

String

PrintPricePerGallon

String

MaximumPurchaseAmount

String

MaximumOilAmount

String

MaximumPartsAmount

String

MaximumAmountOther

String

HostBasedPurchaseRestriction

String

Restriction

Array of Restriction objects

HostBasedPurchaseRestriction

Format

ans

Description

The host-based purchase restriction data.

MaximumAmountOther

Format

Description

The maximum other amount in minor denomination in the currency of the transaction.

MaximumOilAmount

Format

Description

The maximum oil amount in minor denomination in the currency of the transaction.

MaximumPartsAmount

Format

Description

The maximum parts amount in minor denomination in the currency of the transaction.

MaximumPurchaseAmount

Format

Description

The maximum purchase amount in minor denomination in the currency of the transaction.

PrintPricePerGallon

Format

Description

This field identifies if price per gallon needs to be printed on customer receipt.

PromptForOdometer

Format

Description

The prompt is required to complete the transaction or not.

Restriction

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

Properties

Name Type

RestrictionCode

String

RestrictionCodeAmount

String

RestrictionCodeQualityt

String

RestrictionCodeUnitOfMeasure

String

CashLimit

String

InvoiceTotalLimit

String

MiscellaneousTotalLimit

String

AdditiveTotalLimit

String

RepairAmountLimit

String

CustomerName

String

CustomerCity

String

CustomerState

String

AdditiveTotalLimit

Format

Description

The additive total limit.

CashLimit

Format

Description

The cash limit.

CustomerCity

Format

ans

Description

The ciy of the customer.

CustomerName

Format

ans

Description

The name of the customer.

CustomerState

Format

ans

Description

The state in which the customer is located.

InvoiceTotalLimit

Format

ans

Description

The invoice total limit.

MiscellaneousTotalLimit

Format

ans

Description

The miscellaneous total limit.

RepairAmountLimit

Format

ans

Description

The repair amount limit.

RestrictionCode

Format

ans

Description

Contains the restriction code that applies to the fleet response restriction.

RestrictionCodeAmount

Format

ans

Description

The restriction code amount.

RestrictionCodeQuantity

Format

ans

Description

The restriction code quantity.

RestrictionCodeUnitOfMeasure

Format

ans

Description

The restriction code unit of measure.

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

Field 123 - POS Data Code
Details

Format

Description

A Realtime specific addition to the ISO 8583 standard used to identify terminal capability, terminal environment and presentation security data. It is used to indicate specific conditions that were present at the time a transaction took place at the Point-of-Service. This field consists of the following sub-fields:

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 first LineItem.

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).

ItemizedDiscount

Array of ItemizedDiscount objects

OrderDate

String

PurchaseDate

String

CustomerBillingCode

String

PurchaseOrderNumber

String

TaxExempt

Boolean

CommodityCode

String

Description

String

DiscountAmount

String

DiscountAmountSign

String

ParticipantDiscountAmount

String

ShippingAmount

String

ShippingAmountSign

String

DutyAmount

String

DutyAmountSign

String

TaxCollected

Boolean

TotalAmount

String

TotalNonFuelAmount

String

Comment

String

PrivateData

String

CardType

String

LineItem

Array of LineItem objects

Contact

Array of up to 4 Contact objects

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

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.

CardType

Format

Description

This field indicates the type of commercial card used.

InvoiceDiscountTreatment

Format

Description

It indicates how the merchant is managing discounts.

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

FirstName

String

LastName

String

CompanyName

String

Telephone

String

Address

String

Address2

String

City

String

State

String

Country

String

Email

String

ShippingWarehouse

String

ShippingMethod

String

Address

Format

Description

The company or authorized contact person’s street address.

Address2

Format

Description

Additional company or authorized contact person’s address data.

City

Format

Description

The city of the company or authorized person to contact.

CompanyName

Format

Description

The company name to contact.

Country

Format

an3

Description

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

Email

Format

Description

The company or authorized contact person’s email address.

FirstName

Format

Description

The first name of the authorized person to contact.

LastName

Format

Description

The last name of the authorized person to contact.

Name

Format

Description

The company name or full name of the authorized person to contact.

PostalCode

Format

Description

The ZIP or postal code for this contact.

ShippingMethod

Format

Description

The shipping method used.

ShippingWarehouse

Format

Description

The warehouse that fulfilled the shipment.

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.

ParticipantDiscountAmount

Format

n12

Description

The participant discount amount of the total purchase.

DiscountAmountSign

Format

Description

The discount amount interpretation.

DutyAmount

Format

Description

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

DutyAmountSign

Format

Description

The duty amount interpretation.

InvoiceNumber

Format

Description

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

ItemizedDiscount

A itemized discount is implemented by a ItemizedDiscount object in the API, or an Esp:ItemizedDiscount element in the XML interface.

Each entry contains information about a itemized discount applied to a transaction or line item.

Properties

Name

Type

Amount

String

Rate

String

DiscountCode

String

Amount

Format

Description

The discount amount (in the minor denomination).

Rate

Format

Description

The discount rate. Three decimal places are implied.

DiscountCode

Format

Description

The discount code supplied by the merchant.

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

TaxTreatment

String

ItemizedDiscount

Array of ItemizedDiscount objects

ProvincialSalesTaxRegistrationNr

String

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.

DiscountAmountSign

Format

Description

The discount amount interpretation.

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.

LineItemDetailIndicator

Format

Description

It indicates type of line item detail record.

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.

ProvincialSalesTaxRegistrationNr

Format

Description

The provincial sales tax registration number.

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.

ShippingAmountSign

Format

Description

The shippingAmount amount interpretation.

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).

TaxTreatment

Format

Description

It indicates how the merchant is handling taxes.

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.

UnitPriceExponent

Format

n1

Description

Indicates the number of places the decimal point shall be moved to the left, starting from the rightmost numeric digit of the UnitPrice value.

VatReferenceNr

Format

Description

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

OrderDate

Format

Description

The date of order.

OrderTime

Format

n6

Description

The time 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.

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.

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.

TotalNonFuelAmount

Format

n12

Description

The total amount (in the minor denomination) of this purchase transaction related to non-fuel items.

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.

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).

PosGeographicDataLatitude

Format

Description

This field contains the geographic data - Latitude information - of the current terminal. This field is optional.

PosGeographicDataLongitude

Format

Description

This field contains the geographic data - Longitude information - of the current terminal. This field is optional.

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.

    • When the ACI standard triple-DES DUKPT P2PE is used (i.e. the Scheme is set to "S1 3DES DUKPT"), the obfuscation scheme in the SensitiveDataBlock must be set to an ACI obfuscation scheme (e.g. N1, S1, S3, F1, F2, etc.) as defined in the ACI P2PE Interface Specification for PED Manufacturers. If the PED does not support an ACI whitelist format but a vendor-specific format, the PED must map the vendor-specific obfuscation schemes to the ACI obfuscation schemes when populating this field.

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.

RecurringPaymentIndicator

Format

a1

Description

Identifies the transaction as part of a recurring payment series and indicates how the transaction should be processed. This tag is mapped to 'RECURRING_PAYMENT' in Structured Data (field 127.22).

C

Cancelation of a recurring payment series

F

First transaction of a recurring payment series

M

Modification of a recurring payment series

S

Subsequent recurring transaction of a recurring payment series

RecurringPaymentDetail

Recurring Payment Detail is implemented using a RecurringPaymentDetail object in the API, or an Esp:RecurringPaymentDetail element in the XML interface.

Contains the detail of the recurring payment in its sub elements, described as follows.

Properties

Field Format Type (Element, Attribute) Description

RecurringAmount

n..12

Attribute

Specifies the recurring amount.

RecurringAmountPaymentType

an1

Attribute

Specifies the recurring amount payment type.

F - Fixed
M - Recurring payment with maximum amount
S - Variable

RecurringCycle

n..3

Attribute

Specifies the number of days, weeks, months, or years for each recurring payment cycle.

RecurringInterestRate

n..4

Attribute

Specifies the interest rate.

RecurringIteration

an..3

Attribute

Specifies the number of the current recurring payment iteration being paid. Valid values are 02 - 99, ND (Not Defined), and UC (Until Canceled).

RecurringMaximumPaymentAmount

n..12

Attribute

Specifies the maximum recurring payment amount.

RecurringMemberDefinedData

an..20

Attribute

Specifies the recurring member-defined data.

RecurringPaymentCurrency

n3

Attribute

Specifies the recurring payment currency.

RecurringResponsibleEntity

an1

Attribute

Specifies the recurring responsible entity.

0 - Issuer
1 - Merchant
2 - Acquirer
3 - Payment facilitator

RecurringTenure

n..3

Attribute

Specifies the total number of iterations that will be applicable for the recurring payment.

RecurringType

a1

Attribute

Specifies the recurring type.

A - Annually
B - Biweekly
D - Days
E - Every two Months
F - Fortnightly
H - Biannually
M - Months
N - Ten Days
Q - Quarterly
R - Trimester
T - Twice Weekly
U - Unscheduled
W - Weeks
Y - Years

RecurringUniqueId

an..14

Attribute

Specifies the recurring unique ID. This value is used to uniquely identify each of the recurring or installment payments.

RecurringValidationFlag

n1

Attribute

Specifies the recurring validation flag

1 - Validated
0 - Not Validated

RecurringValidationReference

ans..20

Attribute

Specifies the recurring validation reference.

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.

TerminalAddress

Format

Description

This field contains the terminal address information of the current terminal. This field is optional.

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"
StoredCredentialIndicator

Format

a1

Description

Specifies that the transaction is a cardholder-initiated stored credential transaction and indicates how the transaction should be processed. This tag is mapped to 'CARDHOLDER_INITIATED_PAYMENT' in Structured Data (field 127.22).

F

Store the cardholder credentials for the first time in anticipation of future use.

S

Subsequent transaction using credential on file.

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.

OfflineAccumulatorBalance

Format

n12

Description

Represents the amount of offline spending available on the Card.

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.

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.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

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 (consisting typically of first name, middle initial and last name), as found on the check.

CustomerFirstName

Format

Description

First name of the customer, as found on the check.

CustomerLastName

Format

Description

Last name of the customer, as found on the check.

CustomerMiddleInitial

Format

Description

Middle initial of the customer, as found on the check.

CustomerInitials

Format

Description

Initials 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, indicates the barcode reader has timed out, or a customer has pressed cancel on the connected PED.

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

    symbologies : <comma delimited list> - Specifies the specific symbologies that should be accepted by the barcode reader.

    For example, Enable ; scanMode : 1; symbologies : 1,2,3,4,5

    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.

  • symbologies : <comma delimited list>
    Returns a list of all symbologies that the reader was enabled for.

    NOTE

    Only returned when specified in the request.

  • 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

  • Enabled with symbologies specified response:
    scanMode:2;symbologies:1,2,3;readerEnabled:true;OK

  • Disable response:
    readerEnabled:false;OK

  • Error response:
    Error : Device failure occurred while processing Callback: BARCODE_READER with data : Enable

  • Invalid symbologies response:
    Error : Invalid symbology "100" received

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) Deprecated: This event has been deprecated. No supported device driver can detect this 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.

PROMPT_PIN_RETRY

n/a

Indicates that the customer/operator has been prompted to re-enter their PIN.

NOTE

Refer to the pipeline component PIN page in the eSocket.POS User Guide for additional information.

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

date

The software Postilion module build date

ns

N

dependency

The software Postilion module dependency

ans

N

edition

The software Postilion module edition

ans

N

hash

The software Postilion module hash/CRC

ans

N

installType

The software Postilion module Install Type

ans

N

majorVersion

The major version of the software Postilion module

ans

N

minorVersion

The minor version of the software Postilion module

ans

N

name

The software Postilion module name

ans

Y

package

The software Postilion module package

ans

N

patches

The software Postilion module patches

ans

N

previousInstalledVersion

The previously installed version of the software Postilion module

ans

N

sdkMajorVersion

The SDK major version of the software Postilion module

ans

N

sdkMinorVersion

The SDK minor version of the software Postilion module

ans

N

sdkServicePackVersion

The SDK service pack version of the software Postilion module

ans

N

servicePackVersion

The software Postilion module service pack version

ans

N

version

The software Postilion module version

ans

N

Compliance

Field Description Format Required

assigner

Assigner of the compliance

ans

N

effectiveDate

Effective date of the compliance

ns

N

expirationDate

Expiration date of the compliance

ns

N

issuer

Issuer of the compliance

ans

N

reference

Reference of the compliance

ans

N

type

Type of the compliance

ans

Y

version

Version of the compliance

ans

N

An example of the device information JSON structure response:

{
    "cap" : ["cardreader", "keypad", "display", "pinpad"],
    "id" : "IPP350_0070295588 [Ingenico EMV 0]",
    "hardware" : {
        "manufacturer" : "INGENICO",
        "modelName" : "IPP350",
        "modelNumber" : "IPP350",
        "serial" : "0070295588",
    },
        "properties" : [
            {"name" : "short_hw_id", "value" : "TI350"},
            {"name" : "full_hw_id", "value" : "IPP350"},
            {"name" : "sec_fw_id", "value" : "0101"},
            {"name" : "icc_reader_hw_v", "value" : "0001"},
            {"name" : "icc_reader_sw_v", "value" : "0104"},
            {"name" : "sec_v", "value" : "46560360"},
            {"name" : "sec_crc", "value" : "435B"},
            {"name" : "emv_l2_v", "value" : "30650465"},
            {"name" : "emv_l2_crc", "value" : "CD39"},
            {"name" : "retail_pinpad_rel",      "value" : "RAM0922"},
            {"name" : "retail_app_v", "value" : "RA10922"},
            {"name" : "verify_lib_v", "value" : "RA20102"},
            {"name" : "verify_lib_crc", "value" : "9EE6"},
            {"name" : "sec_file_v", "value" : "0001"},
            {"name" : "nr_ctls_mods", "value" : "03"},
            {"name" : "ctls_mod_name_0", "value" : "8133540025"},
            {"name" : "ctls_mod_crc_0", "value" : "70C6"},
            {"name" : "ctls_mod_name_1", "value" : "8133500204"},
            {"name" : "ctls_mod_crc_1", "value" : "16AD"},
            {"name" : "ctls_mod_name_2", "value" : "8133510211"},
            {"name" : "ctls_mod_crc_2", "value" : "A373"}
    ],
    "software" : {
        "module" : [
            {
                "name" : "Telium",
                "type" : "os"
            },
            {
                "name" : "RAM0922",
                "type" : "app",
                "version" : "RA10922"
            },
            {
                "hash" : "CD39",
                "name" : "EMV L2",
                "type" : "emv_kernel",
                "version" : "30650465"
            },
            {
                "hash" : "9EE6",
                "name" : "Verify library",
                "type" : "lib",
                "version" : "RA20102"
            },
            {
                "hash" : "435B",
                "name" : "Security component",
                "type" : "lib",
                "version" : "46560360"
            },
            {
                "name" : "Security file",
                "type" : "file",
                "version" : "0001"
            },
            {
                "hash" : "70C6",
                "name" : "8133540025",
                "type" : "cntctls_kernel",
                "version" : "version"
            },
            {
                "hash" : "16AD",
                "name" : "8133500204",
                "type" : "cntctls_kernel"
            },
            {
                "hash" : "A373",
                "name" : "8133510211",
                "type" : "cntctls_kernel"
            }
        ]
    }
}

SmartCardReader_GetDeviceInfo Flow

  1. The POS registers the callback SmartCardReader_GetDeviceInfo with ACI’s eSocket.POS during ESP INIT, similar to registering other callbacks:

    <?xml version="1.0" encoding="UTF-8"?>
        <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
            <Esp:Admin TerminalId="TestTerm" Action="INIT">
                <Esp:Register Type="CALLBACK" EventId="SmartCardReader_GetDeviceInfo"/>
            </Esp:Admin>
        </Esp:Interface>
  2. The POS sends the XML ADMIN request to eSocket.POS as follows:

    <?xml version="1.0" encoding="UTF-8"?>
        <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
            <Esp:Transaction TerminalId="TestTerm" TransactionId="170818" Type="ADMIN" MessageType="ADMIN_REQUEST" ExtendedTransactionType="2113" >
            </Esp:Transaction>
        </Esp:Interface>
  3. eSocket.POS PipelineComponentDeviceDataCapture sends the SmartCardReader_GetDeviceInfo callback to the POS to retrieve the device data.

    <?xml version="1.0" encoding="UTF-8"?>
        <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
            <Esp:Callback TerminalId="TestTerm" EventId="SmartCardReader_GetDeviceInfo">
            </Esp:Callback>
        </Esp:Interface>
  4. The POS will retrieve the device data from the terminal and supply it to eSocket.POS in the form of the callback response in the ResponseData field using the JSON structure described previously.

    <?xml version="1.0" encoding="UTF-8"?>
        <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
            <Esp:Callback TerminalId="TestTerm" EventId="SmartCardReader_GetDeviceInfo"
                ResponseData="{"cap" : ["cardreader", "keypad", "display", "pinpad"],
                        "id" : "IPP350_0070295588 [Ingenico EMV 0]",
                        "hardware" : { "manufacturer" : "INGENICO", "modelName" : "IPP350", "modelNumber" : "IPP350", "serial" : "0070295588",},
                        "properties" : [{"name" : "short_hw_id", "value : "TI350"},
                                {"name" : "full_hw_id", "value" : "IPP350"},
                                {"name" : "sec_fw_id", "value" : "0101"},
                                {"name" : "icc_reader_hw_v", "value" : "0001"},
                                {"name" : "icc_reader_sw_v", "value" : "0104"}],
                        "software" : {"module" : [{"name" : "Telium", "type" : "os"},
                                      {"name" : "RAM0922", "type" : "app", "version" : "RA10922"},
                                      {"hash" : "CD39","name" : "EMV L2", "type" : "emv_kernel", "version" : "30650465"}]}
                }">
            </Esp:Callback>
    NOTE

    The PED details from the terminal to the POS are formatted to the JSON structure format (described previously) by the POS to send it in the ResponseData field in the callback response.

  5. eSocket.POS PosCallbackDeviceV2 intercepts the callback response and converts it to Term.XSD format. eSP PipelineComponentDeviceDataCapture will send a 0620-request containing the device data in Term.XSD format in Structured Data to Postilion Realtime.

  6. eSocket.POS PipelineComponentDeviceDataCapture receives the 0630-response.

  7. eSocket.POS sends an XML ADMIN response back to the POS including the device data in Term.DTD format set in Structured Data:

    <?xml version="1.0" encoding="UTF-8"?>
        <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
            <Esp:Transaction
                ActionCode="APPROVE"
                BusinessDate="0806"
                DateTime="0829200820"
                ExtendedTransactionType="2113"
                LocalDate="0829"
                LocalTime="220820"
                MerchantId="111111111111111"
                MessageReasonCode="9790"
                MessageType="ADMIN_REQUEST"
                PanEntryMode="00"
                PosCondition="00"
                PosDataCode="010101054005101"
                ResponseCode="00"
                RetrievalRefNr="000000000120"
                TerminalId="TestTerm"
                TransactionId="170818"
                Type="ADMIN">
                <Esp:StructuredData
                    Name="Term"
                    Value="<?xml version="1.0" encoding="UTF-8"?>
                        <Term>
                            <Poi Id="IPP350_0070295588 [Ingenico EMV 0]">
                                <Cap>cardreader</Cap>
                                <Cap>keypad</Cap>
                                <Cap>display</Cap>
                                <Cap>pinpad</Cap>
                                <Hw ModNr="IPP350" Manuf="INGENICO" Serial="0070295588" ModName="IPP350"></Hw>
                                <Props>
                                    <Prop Name="short_hw_id" Val="TI350" />
                                    <Prop Name="full_hw_id" Val="IPP350" />
                                    <Prop Name="sec_fw_id" Val="0101" />
                                    <Prop Name="icc_reader_hw_v" Val="0001" />
                                    <Prop Name="icc_reader_sw_v" Val="0104" />
                                </Props>
                                <Sw>
                                    <Mod Type="os" Name="Telium" /Mod>
                                    <Mod Type="app" Name="RAM0922" Ver="RA10922" /Mod>
                                    <Mod Type="emv_kernel" Name="EMV L2" Ver="30650465" Hash="CD39" /Mod>
                                </Sw>
                            </Poi>
                        </Term>">
                </Esp:StructuredData>
            </Esp:Transaction>
        </Esp:Interface>
ResponseData

Format

Description

Response data sent in the response to a callback, dependent on the EventId . Consult the eSocket.POS User Guide for details of the data for specific callbacks.

Description

Format

Description

A description of a software exception that occurred during processing. More details will usually be found in the eSocket.POS event log.

EspRegister

Registering for events or callback is performed using the registerEvent and registerCallback methods in the API, or an Esp:Register element in the XML interface.

Name Type

Type

String

EventId

String

Type

Format

Description

Indicates whether this registration is for an event or callback.

Possible values:

EVENT CALLBACK

1.5. Interface Specification - Concepts

1.5.1. Events and callbacks

Description

eSocket.POS events and callbacks provide a means of direct communication between eSocket.POS entities and the POS.

  • An event is an unsolicited status message from one entity to another. Events use a fire-and-forget model and may be broadcast to more than one listener.

  • A callback is an unsolicited request for a value to be returned.

Both eSocket.POS and the POS application can raise events and callbacks and be notified of events and callbacks. However they will only be notified of events/callbacks for which they have registered.

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. Apart from the standard list of events and callbacks on the Event ID page, it is possible to have a custom list of events and callbacks depending on the device driver being used as well as any other custom pipeline components. See the device driver and custom component documentation for further information about the events they support.

The details of how to send, receive and register for events and callbacks vary between the API and XML interfaces. See the relevant interface definition for details.

Examples of events sent to the POS

Information about the status of the interaction between the customer and external devices:

  • Prompt for a card to be inserted

  • Report PIN entry status

  • Display a custom message (requires implementation in a custom component)

Examples of callback sent to the POS

eSocket.POS requests further information from the POS:

  • Get a value (e.g. when manual entry is not supported on the devices controlled by eSocket.POS)

Examples of events from the POS to eSocket.POS

The POS sends an event during processing of a transaction which alters how eSocket.POS processes the transaction:

  • POS forces PIN Entry to be bypassed

  • POS causes eSocket.POS to perform a custom action (requires implementation in a custom component)

Examples of callback from the POS to eSocket.POS

The POS requests a value from eSocket.POS during the life of the transaction

  • POS requests custom information from eSocket.POS (requires implementation in a custom component)

Note that the mechanism provided for events and callbacks is generic, and whether these events or callbacks are sent or handled will depend on the configuration and customization of eSocket.POS. The scenarios described above are examples of what may be implemented through this mechanism. These requirements should be defined as part of the integration phase between the POS application and eSocket.POS.

1.5.2. Gift card transactions

eSocket.POS supports the following gift card transactions:

  • Gift card activation

  • Gift card activation with deposit

  • Gift card load

  • Gift card deactivation

  • Gift card deactivation with cashback

  • Gift card unload

  • Gift card activation refund

Gift card transactions are processed as EspTransaction objects in the API (or Esp:Transaction elements in the XML interface). In order to send a gift card transaction, the POS must set the relevant properties for an EspTransaction object and set the Type property to one of CARD_ACTIVATE, LOAD, CARD_DEACTIVATE, UNLOAD or CARD_ACTIVATE_REFUND

Gift card transactions are usually sent as Transaction Request (0200) messages if they have a financial impact (e.g. card activation with deposit, load or card deactivation with cashback transactions). However, it is possible to use other ISO 8583 message types for gift card transactions with financial impact by setting the MessageType property. Gift card transactions that have no financial importance (e.g. pure card activation or card deactivation) are always sent as Administration Request (0600) messages.

If the TransactionAmount property is set to a non-zero value for a CARD_ACTIVATE transaction, the card will be activated and the specified amount deposited into the gift card account. If the TransactionAmount property is set to a non-zero value for a CARD_DEACTIVATE transaction, the card will be deactivated and the specified amount debited from the account and given to the customer.

Depending on the capabilities of the host system, responses to certain gift card transactions, such as card activation with deposit, load and card deactivation transactions, may contain the remaining balance on the card in the Additional Amounts field (field 54), which will then be available as a BalanceListItem in the response to the POS.

Note that gift card transaction processing requires PosConnect v2.0 with Patch 2 applied or later.

1.5.3. Healthcare benefit transactions

Healthcare benefit transactions are processed as EspTransaction objects in the API (or Esp:Transaction elements in the XML interface). These transactions are performed using a healthcare benefits card, which is typically a Flexible Savings Account (FSA), Health Reimbursement Arrangement (HRA) or Health Savings Account (HSA) card. In order to send a healthcare benefit transaction, the POS must set the relevant properties for an EspTransaction object. The extended transaction type property must be set to "7111 - Healthcare Benefit". If not, and the card is a healthcare benefit card, eSocket.POS sets it as such.

eSocket.POS checks if the card is a valid healthcare card and declines the transaction if it is not.

Healthcare benefit transactions are usually sent as transaction request (0200) messages with the following fields :

If the merchant supports partial approval, the property PosCondition is set to '41'. Any other value indicates that the merchant does not support partial approvals.

The response code in the response message indicates how the transaction amount was approved:

  • 00 - full amount was approved

  • 10 - partial amount was approved

1.5.4. Electronic benefits transfer

There are two types of EBT benefits:

  • EBT cash benefit (account type 96)

  • EBT food stamp (account type 98)

eSocket.POS supports the following EBT transactions. Unless stated explicitly, they apply to both cash benefit and food stamp benefits:

  • EBT balance inquiry

  • EBT purchase (including cash back under the cash benefit)

  • EBT food stamp electronic voucher

  • EBT reversal/void

  • EBT refund

  • EBT time out reversal

EBT balance inquiries are processed as EspInquiry objects in the API (or Esp:Inquiry elements in the XML interface). All other EBT transactions are processed as EspTransaction objects in the API (or Esp:Transaction elements in the XML interface). See "POS XML message flow examples" under the POS XML message flow examples > EBT transactions section for more details.

See the eSocket.POS User Guide for the required configuration to correctly process EBT transactions.

1.5.5. Character encodings

eSocket.POS supports the transfer of non-standard character encoded strings, e.g. UTF-8, downstream through the Pipeline Components, down to the POS. This is done by storing the encoded string in StructuredData , together with an eSP:Encoding entry in StructuredData .

eSP:Encoding is a reserved StructuredData entry, which should be a table, constructed with a HashtableMessage, of the character encodings associated with encoded string entries in StructuredData . The Name / Value pairing that should exist in eSP:Encoding is illustrated below.

eSP:Encoding

Name Value

The StructuredData field name, that contains the non-standard character encoding, e.g. EncodedData

The Java recognized Charset name of the character encoding used, e.g. UTF-8

An entry in eSP:Encoding is necessary only when the string is encoded with a character encoding other than ASCII . If no entry for a StructuredData field is present in eSP:Encoding , no additional processing will be performed on field, and it will be processed normally.

Example

As an example of a message with a non-standard character encoded string, assume that a message is received by eSocket.POS, with field 127.22 containing: *212eSP:Encoding221211EncodedData15UTF-8211EncodedData251(BINARY_DATA)* This entry consists of:

  • *211EncodedData251(BINARY_DATA)* : The field EncodedData together with the binary representation of the encoded string, in its encoded format.

  • *212eSP:Encoding221211EncodedData15UTF-8* : The field eSP:Encoding together the contents of this table. The contents include:

    • *211EncodedData15UTF-8* : This indicates that the field EncodedData is encoded using the character encoding UTF-8 .

Limitations

This feature is limited to the following:

  • Only downstream messages, passing through the Pipeline Components and sent to the POS, support the Character Encoding feature.

  • Only the following StructuredData fields may contain non-standard character encodings:

1.5.6. Mapping to ISO 8583

The eSocket.POS API allows the POS programmer to create transaction objects and set various properties. Internally, these properties are mapped onto the fields of an ISO 8583 message, and the fields in the ISO 8583 response are mapped back to transaction properties.

A developer using the eSocket.POS API will usually not have to be concerned with the details of the ISO 8583 protocol, or how properties are mapped to fields, and vice versa. However, an understanding of the mapping will sometimes be useful, for instance to set certain properties required upstream, or when working with the eSocket.POS trace file.

API Property ISO 8583 Field Description of Mapping

Account

Account From in Processing Code (field 3)

The account property is used to set the Account From subfield of Processing Code (field 3) and vice versa. If the transaction is a credit transaction (Transaction type in the range 20 - 29) the Account To subfield is used instead.

ActionCode

-

The Response Code (field 39) is mapped to a limited set of action codes

AddressVerificationResult

Address Verification Result (field 127.16)

One-to-one

AmountTransactionFee

Amount, Transaction Fee (field 28)

One-to-one

AuthorizationNumber

Authorization ID Response (field 38)

One-to-one

AuthorizationAgent

Authorizing Agent Institution (field 58)

One-to-one

Balance AccountType

- Account Type of an amount in Additional Amounts (field 54) for a Balance Inquiry

  • Tag FROM_ACC of Additional Data (field 48) for a Mini-statement Inquiry

One-to-one

Balance Amount

  • Amount of an amount in Additional Amounts (field 54) for a Balance Inquiry

  • Tag TRAN_AMOUNT of Additional Data (field 48) for a Mini-statement Inquiry

One-to-one

Balance AmountType

Amount Type of an amount in Additional Amounts (field 54)

One-to-one

Balance CurrencyCode

- Currency Code of an amount in Additional Amounts (field 54) for a Balance Inquiry

  • Tag CURR_CODE of Additional Data (field 48) for a Mini-statement Inquiry

One-to-one

Balance Sign

Sign of an amount in Additional Amounts (field 54)

One-to-one

Balance SequenceNumber

Tag SEQ_NR of Additional Data (field 48)

One-to-one

Balance DateTime

Tag DATE_TIME of Additional Data (field 48)

One-to-one

Balance TerminalId

Tag TERM_ID of Additional Data (field 48)

One-to-one

Balance TransactionType

Tag TRAN_TYPE of Additional Data (field 48)

One-to-one

Balance ToAccountType

Tag TO_ACC of Additional Data (field 48)

One-to-one

Balance AccountId1

Tag ACC_ID_1 of Additional Data (field 48)

One-to-one

Balance AccountId2

Tag ACC_ID_2 of Additional Data (field 48)

One-to-one

Balance AuthorizationId

Tag AUTH_ID of Additional Data (field 48)

One-to-one

Balance Surcharge

Tag SURCHARGE of Additional Data (field 48)

One-to-one

BalanceList

- Additional Amounts (field 54) for a Balance Inquiry

  • Additional Data (field 48) for a Mini-statement Inquiry

  • Up to six BalanceListItem objects are mapped onto amounts in Additional Amounts (field 54)

  • BalanceListItem objects have a one-to-one mapping to each line of a mini-statement in Additional Data (field 48)

BusinessDate

Date, Settlement (field 15)

One-to-one

CardholderAddress

Cardholder Address in Address Verification Data (field 127.15)

One-to-one

CardholderName

Element named 'CardholderName' in Structured Data (field 127.22)

One-to-one

CardholderInformation

Cardholder Information (field 127.17)

One-to-one

StoredCredentialIndicator

Element named 'CARDHOLDER_INITIATED_PAYMENT' in Structured Data (field 127.22)

One-to-one

CardNumber

Primary Account Number (PAN) (field 2)

One-to-one

CardProductName

Element named 'CardProductName' in Structured Data (field 127.22)

One-to-one

CardSequenceNumber

Card Sequence Number (field 23)

One-to-one

CardVerificationResult

Card Verification Result (field 127.27)

One-to-one

CashbackAmount

Amount in Additional Amounts (field 54)

If cashback amount is set, a cash amount is inserted into Additional Amounts (field 54)

Check fields (apart from those listed below)

Elements in CheckData element in StructuredData (field 127.22)

One-to-one

ChequeAccountNumber

Account Number in Check Data (field 127.7)

One-to-one

ChequeInstitutionCode

Institution Code in Check Data (field 127.7)

One-to-one

ChequeNumber

Check Number in Check Data (field 127.7)

One-to-one

ChainedTransactionId

Original Key (field 127.11)

One-to-one within the pipeline

CreditsAmount

Credits, Amount (field 86)

One-to-one

CreditsReversalAmount

Credits, Reversal Amount (field 87)

One-to-one

CurrencyCode

Currency Code, Transaction (field 49)

One-to-one

Cvv2

- CVV2 (field 127.10) if the CVV2 consists of 3 digits.

  • American Express Card Identifier (CID) (field 127.28) if the CVV2 consists of 4 digits.

One-to-one

DateTime

Transmission Date and Time (field 7)

One-to-one

DccStatusCode

Dynamic Currency Conversion Status Code (field 127.48)

One-to-one

DccProviderRoutingId

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.ProviderRoutingId' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccRate

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.Rate' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccSrcCurrCode

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.SrcCurr.Code' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccSrcCurrAlphaCode

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.SrcCurr.AlphaCode' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccSrcCurrMinorUnits

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.SrcCurr.MinorUnits' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccTgtCurrCode

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.TgtCurr.Code' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccTgtCurrAlphaCode

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.TgtCurr.AlphaCode' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccTgtCurrMinorUnits

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.TgtCurr.MinorUnits' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccProvider

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.Provider' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccRateSrc

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.RateSrc' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccTimestamp

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.Timestamp' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccMargRate

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.MargRate' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccCommRate

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.CommRate' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccSrcAmt

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.SrcAmt' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccTgtAmt

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.TgtAmt' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccExpTimestamp

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.ExpTimestamp' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccRcptTxt1

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.RcptTxt1' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccRcptTxt2

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.RcptTxt2' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccAcqId

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.DccAcqId' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccCardAccptrId

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.DccCardAccptrId' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DccTermId

Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.DccTermId' in currency conversion information XML in Structured Data (field 127.22)

One-to-one

DebitsAmount

Debits, Amount (field 88)

One-to-one

DebitsReversalAmount

Debits, Reversal Amount (field 89)

One-to-one

DoNotDisplay

Element named 'ResponseDisplay' in Structured Data (field 127.22)

One-to-one

EBT properties

Elements in ElectronicBenefitTransfer element in StructuredData (field 127.22)

One-to-one

EMV properties (apart from fields below)

Elements from IccData (field 127.25)

One-to-one

EmvApplicationLabel

Element of the same name in Structured Data (field 127.22)

One-to-one

EmvApplicationVersionNumber

Element of the same name in Structured Data (field 127.22)

One-to-one

EmvTransactionStatusInformation

Element of the same name in Structured Data (field 127.22)

One-to-one

EmvApplicationPreferredName

Element of the same name in Structured Data (field 127.22)

One-to-one

EmvIssuerCodeTableIndex

Element of the same name in Structured Data (field 127.22)

One-to-one

EspCardInfo

Element named 'EspCardInfo' in Structured Data (field 127.22)

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

ExpiryDate

Date, Expiration (field 14)

One-to-one

ExtendedPaymentPeriod

Extended Payment Code (field 67)

One-to-one

ExtendedTransactionType

Extended Transaction Type (field 127.33)

If ExtendedTransactionType is not set this is based on the Type and TransactionAmount properties, otherwise the mapping is one-to-one.

ExtendedAuthorizationNumber

Extended Authorization ID Response (field 127.51)

If AuthorizationNumber is not set and a response contain an extended authorization number with length between n7- n8.

LongAuthorizationNumber

Element named 'AuthorizationId' in Structured Data (field 127.22)

One-to-one

FinalAmount

Transaction Amount in Replacement Amounts (field 95)

One-to-one

FleetData

Element named 'FleetData' in Structured Data (field 127.22), in XML format

One-to-one

FleetDataRsp

Element named 'FleetDataRsp' in Structured Data (field 127.22), in XML format

One-to-one

GratuityAmount

Amount in Additional Amounts (field 54)

If gratuity amount is set, a tip (amount type 56) amount is inserted into Additional Amounts (field 54).

LocalDate

Date, Local Transaction (field 13)

One-to-one

LocalTime

Time, Local Transaction (field 12)

One-to-one

MerchantId

Card Acceptor ID Code (field 42)

One-to-one

MessageReasonCode

Message Reason Code (field 56)

One-to-one

PanEntryMode

PAN Entry Mode in POS Entry Mode (field 22)

One-to-one

PassThruPanReference

Elements named 'PassThruPanReference' and 'PassThruMaxReliableBinLength' in Structured Data (field 127.22)

Structured Data field 'PassThruPanReference' has the hash table message format. The XML fields will be mapped to the hash table message fields as follows:

Scheme, Data, SensitiveDataBlock, and WhitelistFileName will be mapped one-to-one.

Ksn will be mapped to KSN.

TlvMapping will be mapped to TLVMapping.

XML field MaxReliableBinLength will be mapped to Structured Data field 'PassThruMaxReliableBinLength'.

MaxReliableBinLength can exist in one or both XML elements PassThruPanReference and PassThruVolatileP2peData. If it exists in both, their values must match and either one of them will be mapped to Structured Data field PassThruMaxReliableBinLength.

PassThruVolatileP2peData

Elements named 'PassThruVolatileP2peData' and 'PassThruMaxReliableBinLength' in Structured Data (field 127.22)

Structured Data field 'PassThruVolatileP2peData' has the hash table message format. The XML fields will be mapped to the hash table message fields as follows:

Scheme, Data, SensitiveDataBlock, and WhitelistFileName will be mapped one-to-one.

Ksn will be mapped to KSN.

TlvMapping will be mapped to TLVMapping.

XML field MaxReliableBinLength will be mapped to Structured Data field 'PassThruMaxReliableBinLength'.

MaxReliableBinLength can exist in one or both XML elements PassThruPanReference and PassThruVolatileP2peData. If it exists in both, their values must match and either one of them will be mapped to Structured Data field PassThruMaxReliableBinLength.

PinData

PIN Data (field 52)

The 8 bytes of the ISO field are set using the 16-character hexadecimal value.

PinKeySequenceNr

Security Related Control Information (field 53)

The first 8 bytes of the ISO field are set using the 16-character hexadecimal value, and the rest are zero-filled.

PosCondition

POS Condition Code (field 25)

One-to-one

PosData

POS Data (field 127.4)

One-to-one

PosOperatorId

POS Operator ID in POS Data (field 127.4)

One-to-one

PostalCode

Postal/Zip Code in Address Verification Data (field 127.15)

One-to-one

PurchasingCardData

Element named 'PurchasingCardData' in Structured Data (field 127.22), in XML format.

If the first LineItem in the PurchasingCardData contains only the ProductCode, the ProductCode value is used to populate the XML element named 'PrepaidMerchandise' in Structured Data (field 127.22). If the 'PrepaidMerchandise' element is populated in this way, the source LineItem is cleared. If the only field populated in all of the PurchasingCardData was the ProductCode of the first LineItem, the entire PurchasingCardData element is cleared.

One-to-one

or

One-to-two (for gift card transactions)

PurchasingCardData with only the ProductCode of the first LineItem populated

Element named 'PrepaidMerchandise' in Structured Data (field 127.22), in XML format

One-to-one

PayeeNameAndAddress

Payee Name and Address (field 127.23)

Contains identification and billing information for a payee.

AdditionalPayeeInformation

Element named 'AdditionalPayeeInformation' in Structured Data (field 127.22)

Contains additional payee name and address details.

AccountData

Element named 'AccountData' in Structured Data (field 127.22)

Contains account details needed for credit application.

DisplayData

Element named 'DisplayData' in Structured Data (field 127.22)

The status response from ADS based on the processor specification.

PrintData

Element named 'PrintData' in Structured Data (field 127.22)

The status response that contains information about the account.

RecurringPaymentIndicator

Element named 'RECURRING_PAYMENT' in Structured Data (field 127.22)

One-to-one

RecurringPaymentDetail

Element named 'RecurringPaymentDetail' in Structured Data (field 127.22), in XML format.

One-to-one

MessageType - Check

ISO 8583 message type

If MessageType is not set, the ISO 8583 message type is set to 0100 - Authorization Request.

Otherwise, one-to-one: AUTHADV maps to 0120 - Authorization Advice, TRANREQ maps to 0200 - Transaction Request, and CONFIRM maps to 0220 - Transaction Advice.

MessageType - Transaction

ISO 8583 message type

If the MessageType is set then the ISO 8583 message type will be mapped as follows:

  • 0100 - Authorization Request if the MessageType is AUTH.

  • 0220 - Transaction Advice if the MessageType is CONFIRM.

  • 0220 - Referral Advice if the MessageType is REFERRAL. In this case a flag ReferralAdvice is also set in the Structured Data field, which can be used by components to do any special processing for referral advices.

  • 0200 if the MessageType is REFERRED. In this case a flag ReferralAuthorized is also set in the Structured Data field. Note that the REFERRED message type is deprecated, and the REFERRAL message type should be used instead.

  • 0600 if the MessageType is ADMIN_REQUEST.

If the MessageType is not set, the message type will be set according to the Type property. Note that the above mappings are overridden if the Reversal property is set to true .

In a response, the MessageType is set as follows:

  • AUTH for a 0110

  • CONFIRM for a 0230

  • ADMIN_REQUEST for a 0610 if the extended transaction type (field 127.33) is not set to 3100 - Card activation or 3101 - Card deactivation.

NetSettlementAmount - Sign

Amount, Net Settlement (Field 97)

The sign is stored in the first character of Amount, Net Settlement (Field 97).

NetSettlementAmount - Amount

Amount, Net Settlement (Field 97)

The amount is stored in the last sixteen digits of the Amount, Net Settlement (Field 97).

NetworkMngInfoCode

Network Management Information Code (field 70)

One-to-one

NumberOfAuthorizations

Authorizations, Number (field 81)

One-to-one

NumberOfCredits

Credits, Number (field 74)

One-to-one

NumberOfCreditsReversal

Credits, Reversal Number (field 75)

One-to-one

NumberOfDebits

Debits, Number (field 76)

One-to-one

NumberOfDebitsReversal

Debits, Reversal Number (field 77)

One-to-one

NumberOfInquiries

Inquiries, Number (field 80)

One-to-one

PosStructuredData

Element named 'PosStructuredData' in Structured Data (field 127.22)

Within the element in field 127.22, multiple name/value pairs are included, themselves also in Postilion Structured Data format (that is, nesting of one Structured Data string inside another).

PrivateData

Element named 'PosPrivateData' in Structured Data (field 127.22)

One-to-one

ReceivingInstIdCode

Receiving Institution ID Code (field 100)

One-to-one

ReferralTelephone

Additional Response Data (field 44)

One-to-one

ResponseCode

Response Code (field 39)

One-to-one

RetrievalRefNr

Retrieval Reference Number (field 37)

One-to-one

Reversal

ISO 8583 message type

If the Reversal property is set to true , the ISO 8583 message type is set to 0420 - Reversal Advice.

If the response has a message type of 0430 - Reversal Advice Response, the Reversal property is set to true

Reversal Type

ISO 8583 message type

If the Reversal Type property is set to REQUEST, the ISO 8583 message type is set to 0400.

If the Reversal Type property is set to ADVICE, the ISO 8583 message type is set to 0420.

SecurityInfo

Security Related Control Information (field 53)

The ISO field is set by converting to binary representation and right padding with binary zeros to 48 bytes.

ServiceRestrictionCode

Service Restriction Code (field 40)

One-to-one

SettlementCurrencyCode

Currency Code, Settlement (field 50)

One-to-one

SignatureAdditionalText

Element named 'SignatureAdditionalText' in Structured Data (field 127.22)

One-to-one

SignatureButtonValue

Element named 'SignatureButtonValue' in Structured Data (field 127.22)

One-to-one

SignatureCheckbox1State

Element named 'SignatureCheckbox1State' in Structured Data (field 127.22)

One-to-one

SignatureCheckbox1Text

Element named 'SignatureCheckbox1Text' in Structured Data (field 127.22)

One-to-one

SignatureCheckbox2State

Element named 'SignatureCheckbox2State' in Structured Data (field 127.22)

One-to-one

SignatureCheckbox2Text

Element named 'SignatureCheckbox2Text' in Structured Data (field 127.22)

One-to-one

SignatureCheckbox3State

Element named 'SignatureCheckbox3State' in Structured Data (field 127.22)

One-to-one

SignatureCheckbox3Text

Element named 'SignatureCheckbox3Text' in Structured Data (field 127.22)

One-to-one

SignatureImageFormat

Element named 'SignatureImageFormat' in Structured Data (field 127.22)

One-to-one

SignatureImagePassedInResponse

Element named 'SignatureImagePassedInResponse' in Structured Data (field 127.22)

One-to-one

SignaturePromptName

Element named 'SignaturePromptName' in Structured Data (field 127.22)

One-to-one

SignatureScrollableText

Element named 'SignatureScrollableText' in Structured Data (field 127.22)

One-to-one

SignatureStandAloneDynamicText

Element named 'SignatureStandAloneDynamicText' in Structured Data (field 127.22)

One-to-one

SignatureData

Element named 'SignatureData' in Structured Data (field 127.22)

One-to-one

SignatureFormat

Element named 'SignatureFormat' in Structured Data (field 127.22)

One-to-one

SignatureImageCategory

Element named 'SignatureImageCategory' in Structured Data (field 127.22)

One-to-one

SignatureImageEncrypted

Element named 'SignatureImageEncrypted' in Structured Data (field 127.22)

One-to-one

SignatureImageSequence

Element named 'SignatureImageSequence' in Structured Data (field 127.22)

One-to-one

SignatureOriginalFormat

Element named 'SignatureOriginalFormat' in Structured Data (field 127.22)

One-to-one

SignatureRequired

Element named 'SignatureRequired' in Structured Data (field 127.22)

One-to-one

StartDate

Element named 'StartDate' in Structured Data (field 127.22)

One-to-one

APM

Element named 'APM' in Structured Data (field 127.22).

One-to-one

PaymentBrand

Element named 'PaymentBrand' in Structured Data (field 127.22).

One-to-one

QRCodeType

Element named 'QRCodeType' in Structured Data (field 127.22).

One-to-one

QRCodeData

Element named 'QRCodeData' in Structured Data (field 127.22).

One-to-one

QRCodeImage

Element named 'QRCodeImage' in Structured Data (field 127.22).

One-to-one

QRCodeTranId

Element named 'QRCodeTranId' in Structured Data (field 127.22).

One-to-one

QRCodeHostRef

Element named 'QRCodeHostRef' in Structured Data (field 127.22).

One-to-one

BarcodeData

Element named 'BarcodeData' in Structured Data (field 127.22).

One-to-one

Quantity

Element named 'Quantity' in Structured Data (field 127.22).

One-to-one

TransactionName

Element named 'TransactionName' in Structured Data (field 127.22).

One-to-one

StoreId

Element named 'StoreId' in Structured Data (field 127.22).

One-to-one

Memo

Element named 'Memo' in Structured Data (field 127.22).

One-to-one

MerchantOpcSelection

Element named 'MerchantOpcSelection' in Structured Data (field 127.22). This field is specific to OPC transactions.

One-to-one

StructuredData

Structured Data (field 127.22)

One-to-one, excluding reserved name s from the mapping.

Track1

Track 1 Data (field 45)

One-to-one

Track2

Track 2 Data (field 35)

One-to-one

Track3

Track 3 Data (field 36)

One-to-one

TransactionId

Systems Trace Audit Number (field 11)

One-to-one

TransactionAmount

Transaction Amount (field 4)

One-to-one

Type - Check

Transaction Type in Processing Code (field 3) and Extended Transaction Type (field 127.33)

Extended Transaction Type:

  • ECCGUARANTEE, ECCVERIFY, ECC maps to '7112' - Electronic Check Authorization

Transaction Type:

  • GUARANTEE, ECCGUARANTEE maps to '03' - Check Guarantee

  • VERIFICATION, ECCVERIFY maps to '04' - Check Verification

  • ECC maps to '12' - General Debit

Type - Inquiry

Iso8583 message type and Transaction Type in Processing Code (field 3)

CARD_READ maps to an Iso8583 0600 - Administration Request message. All other transaction types map to the ISO 8583 message type 0100 - Authorization Request.

Mapping for types is one-to-one: AVAILABLE_FUNDS maps to a Transaction Type of 30 - Available Funds Inquiry BALANCE maps to 31 - Balance Inquiry CHEQUE_VERIFICATION maps to 04 - Cheque Verification CHEQUE_GUARANTEE maps to 03 - Cheque Guarantee CARD_READ maps to the internal value of 95 - Card Read GENERAL_INQ maps to 32 - General Inquiry CARD_VERIFICATION maps to 37 - Card Verification Inquiry

Type - Merchandise

Iso8583 message type and Transaction Type in Processing Code (field 3)

REQUEST maps to a 0100. PROCURE and REVERSE map to a 0200. CONFIRM maps to a 0220. The Transaction Type is set to '28' - Merchandise, except for REVERSE in which case it is set to '02' - Adjustment.

Type - Network

Iso8583 message type.

Iso8583 message type maps to a 0800.

Type - Reconciliation

Iso8583 message type.

Iso8583 message type maps to a 0500.

Type - Transaction

transaction type subfield of Processing Code (field 3), and ISO 8583 message type.

The mapping of this field will be described below.

The transaction type from Type - Transaction is mapped as follows:

  • PURCHASE maps to '00' - Goods and Services, or to '09' - Goods and Services with Cashback if the CashbackAmount is set.

  • DEPOSIT maps to '21' - Deposit.

  • DEPOSIT maps to '51' - Payment by Deposit if extended transaction type is set to '7116' - Credit Admin Payment on Account with Cash transaction, or '7117' - Credit Admin Payment on Account with Check transaction.

  • REFUND maps to '20' - Returns.

  • DEBIT_ADJUSTMENT maps to '02' - Adjustment.

  • CREDIT_ADJUSTMENT maps to '22' - Adjustment.

  • ADMIN maps to '91' - General Admin

  • CARD_ACTIVATE maps to '91' - General Admin if the TransactionAmount is not set or is set to a zero amount with the extended transaction type set to '3100' - Card Activate. Otherwise, it maps to '25' - General Credit, with the extended transaction type set to '6500' (CardActivation with Deposit verified by operator)'.

  • LOAD maps to '25' - General Credit.

  • CARD_DEACTIVATE maps to '91' - General Admin if the TransactionAmount is not set or is set to a zero amount with the extended transaction type set to '3101' - Card Deactivate. Otherwise, it maps to '12' - General Debit with the extended transaction type set to '6502' - Card Deactivate with cashback.

The ISO message type is set based on the MessageType property. If this property is not set, then the message type is mapped as follows:

  • 0100 - Authorization Request if the Type is AUTH __ (deprecated).

  • 0220 - Transaction Advice if the Type is REFERRAL of CONFIRM (both deprecated).

  • 0600 - Administration Request if the Type is CARD_ACTIVATE / CARD_DEACTIVATE and the TransactionAmount property is not set or is set to a zero amount.

  • 0620 - Administration Advice if the Type is ADMIN.

  • 0200 - Transaction Request otherwise.

The above mappings are overridden if the Reversal property has a value of true , in which case the message type is set to 0420 - Reversal Advice.

If the response has a message type of 0630, the transaction type is set to ADMIN. Otherwise, the Type is set according to the Transaction Type subfield of Processing Code (field 3) as follows:

  • 20 - Returns is mapped to REFUND.

  • 21 - Deposit is mapped to DEPOSIT.

  • 51 - Payment by Deposit with an Extended Transaction Type (field 127.33) of 7116 - Credit Admin Payment on Account with Cash or 7117 - Credit Admin Payment on Account with Check is mapped to DEPOSIT.

  • 02 - Adjustment is mapped to DEBIT_ADJUSTMENT.

  • 22 - Adjustment is mapped to CREDIT_ADJUSTMENT.

  • 91 - General Admin with an Extended Transaction Type (field 127.33) of 3100 - Card activation is mapped to CARD_ACTIVATE.

  • 91 - General Admin with an Extended Transaction Type (field 127.33) of 3101 - Card deactivation is mapped to CARD_DEACTIVATE.

  • 91 - General Admin with the Extended Transaction Type (field 127.33) not set to 3100 - Card activation or 3101 - Card deactivation is mapped to ADMIN.

  • 25 - General Credit with an Extended Transaction Type (field 127.33) of 6500 - Card activation with deposit verified by operator is mapped to CARD_ACTIVATE.

  • 25 - General Credit with an Extended Transaction Type (field 127.33) of 6501 - Deposit verified by operator is mapped to LOAD.

  • 12 - General Debit with an Extended Transaction Type (field 127.33) of 6502 - Card deactivation with cash back is mapped to CARD_DEACTIVATE.

  • Otherwise, this is set to PURCHASE.

The deprecated values of AUTH, CONFIRM and REFERRAL are never used in responses.

1.5.7. Data Element Format

The following notation conventions have been employed throughout the developers guide to describe the format of the eSocket.POS object properties (data elements).

This notation is based on the ISO 8583 (1987) specification.

a Alphabetic characters, A through Z and a through z

n

Numeric digits, 0 through 9

p

Pad character, space

s

Special characters, i.e. other printable characters

an

Alphabetic and numeric characters

as

Alphabetic and special characters

ns

Numeric and special characters

anp

Alphabetic, numeric and pad characters

ans

Alphabetic, numeric and special characters

object

The property (data element) is a reference to an object. Refer to the definitions of the object’s properties (data elements).

boolean

"TRUE" or "FALSE" when using the XML interface, otherwise true or false in Java API.

YY

Year, 00 through 99

YYYY

Year, 0001 through 9999

MM

Month, 01 through 12

dd

Day, 01 through 31

HH

Hour, 00 through 23

mm

Minute, 00 through 59

ss

Second, 00 through 59

3

Fixed length of 3 characters

..17

Variable length up to 17 characters.

x

C for credit, D for debit.

h

Hexadecimal representation of binary data

z

Track 2 as defined in ISO 7813

2. Java API

2.1. Overview

The Java application programming interface (API) for eSocket.POS was designed to be used by other applications to perform the following tasks:

  • Provide a Java interface between the application program and the eSocket.POS application. The eSocket.POS application provides a connection with Postilion.

  • Allow an EFT transaction with the necessary data elements to be created, in the form of a collection of objects and their properties.

  • Translate transaction objects into messages and pass the messages to eSocket.POS.

  • Receive response messages from eSocket.POS and presents them to the local application as a new transaction or merchandise object with the response code and other properties set.

  • Facilitate sending and receiving of events and callbacks between the POS and eSocket.POS.

The local application need not concern itself with the construction of messages to eSocket.POS or the Postilion system. All the local application needs to do is to create various objects and set their properties to the required values. The objects and their descriptions have been specifically designed to be intuitive to the developer of the local application, without requiring understanding of the underlying ISO 8583 message protocol. The construction of messages from the objects is handled transparently by eSocket.POS.

The transaction objects and their properties are defined in the Interface Specification section of this document.

2.1.1. Java

eSocket.POS is developed in Java (conforming to SUN Java v1.8). This means that local Java-based applications making use of eSocket.POS can run on any operating system, provided that there is an implementation of a Java virtual machine (JVM) available for the operating system. Through Java’s platform independence, eSocket.POS is supported on Windows, most distributions of Unix, Macintosh, and others.

Note: The eSocket.POS application contains various configurable components which allow it to be integrated with different operating systems, database environments and devices at the point-of-sale. Depending on your choice of operating system, database and devices, some of these components may be available, while others may need to be developed. This integration and configuration is beyond the scope of this developer guide. Please discuss this with your primary support provider.

2.1.2. Design principles

eSocket.POS implements an object-oriented design. Each transaction supported by eSocket.POS is represented as an object. The data elements associated with a transaction are the properties of the transaction object.

Each property must conform to a specific data element format. For example, the Card Number should consist of numeric values only, and be no greater than 19 characters in length. The Interface Specification section defines the data element format of each property.

2.2. Using EspInterface

The eSocket.POS API provides a single point of access to the POS developer. This is the EspInterface object.

EspInterface provides an interface for one or more terminals to connect to eSocket.POS. A single interface should be used for all POS terminals controlled by the application program. If the POS application is installed on a POS terminal, that interface will handle only that terminal. If the POS application runs on a store server and handles more than one POS terminal, a single EspInterface should be created to handle transactions from all connected POS terminals. The POS application should not create a separate interface for each physical terminal.

The POS program should create the instance of EspInterface as follows:

EspInterface esp_interface = new EspInterface();

The interface exposes methods which can be used for the following functions:

  • initializing eSocket.POS to receive transactions for a particular terminal

  • pre-initialize all terminals that run in a store server environment according to the level required by the configuration in the properties file

  • closing eSocket.POS for a particular terminal

  • sending a transaction from a terminal to eSocket.POS

  • inquiring the status of the transaction previously sent to eSocket.POS

  • sending an event or callback from a terminal to eSocket.POS

  • registering a terminal to receive events or callback from eSocket.POS

  • starting and closing Config Agent

These methods are dealt with on the subsequent pages of the developer guide.

2.3. Initialization

eSocket.POS can be run using two types of deployment: It can be implemented on each till or it can be implemented on a store server. The API provides means for either initializing per terminal or per store server .

2.4. Initializing a terminal

Once the EspInterface object has been created, each connecting terminal needs to be initialized via the interface. This is done using the initTerminal method with the Terminal ID and properties file name as parameters. It is also possible to supply the properties file to the initTerminal method as a Java Properties object instead of supplying the file name as a String. Refer to the eSocket.POS User Guide for the properties which must be supplied in this object.

The Terminal ID identifies which terminal parameters to apply, so data for that Terminal ID must be present in the eSocket.POS database before that terminal can be initialized. The Terminal ID must be unique across all the terminals connecting to the upstream Postilion system.

In the case of a POS application controlling a single terminal, the initTerminal method should be called once as follows

esp_interface.initTerminal("Term1234", "c:\\esocketpos\\properties.txt");

(Change the filename and path to reflect location of the properties file on the local system.)

If the POS application controls more than one POS terminal, each terminal should be initialized separately:

esp_interface.initTerminal("Term1234", "c:\\esocketpos\\properties.txt"); esp_interface.initTerminal("Term5678", "c:\\esocketpos\\properties.txt");

or by calling the overridden initTerminal method with the second parameter set to a Properties object.

This may be done at the discretion of the POS application: either all terminals can be initialized at startup, or terminals can be initialized as they come into action. Unused terminals may be closed using the close method (described later).

Note that the initTerminal command is memory and processor intensive, and should only be called once per POS terminal, typically when the application starts, or at the start of the day. Terminals should not be initialized per transaction.

Failure to initialize

If eSocket.POS can’t be started for the terminal ID specified, the initTerminal command will throw an XConfig exception. This might happen for any of a wide range of reasons, including:

  • problems with the properties file

  • the terminal ID not being found in the eSocket.POS database

  • inconsistent or incorrect configuration in the database

  • classes not being found

  • a connection problem to a device

  • many other possible causes

The cause of the problem is reported in the XConfig exception, and typically additional information about the error is logged in the eSocket.POS event log. The integrator or POS developer should refer to this event log to determine the reason that eSocket.POS failed to start, and fix the problem.

If the initTerminal method fails, no transactions can be sent using the send method for that terminal ID. The problem must be solved and initTerminal must be called successfully before transactions can be sent.

2.5. Initializing the store server

eSocket.POS instances can be initialized in the EspInterface by calling the initStoreServer method.

The store server can be initialized once as follows:

esp_interface.initStoreServer("c:\\esocketpos\\properties.txt");
*Note:* Change the filename and path to reflect location of the properties file on the local system.

This will allow eSocket.POS to deliver store-and-forward transactions by initializing the POS terminal when processing the first transaction. The level of POS terminal auto-initialization can be set in the eSocket.POS properties file by specifying one of the following values for the postilion.esocketpos.storeserver.AutoInitTerminals property:

  • None - No terminals will be pre-initialized.

  • Saf - Only pre-initialize the terminals that have transactions in the store-and-forward queue.

  • All - Pre-initialize all terminals.

  • AllSignOn - Pre-initialize and automatically sign-on all terminals. Note: Sign-on enables terminals to connect to and do initial setup for the PED devices.

Note: It is not necessary to call the initTerminal method for the terminals that will be auto-initialized.

2.6. Closing a terminal

When no more transactions are required, and a particular terminal is no longer needed, the POS application should close that terminal with eSocket.POS. This uses the close method:

esp_interface.close("Term1234"); esp_interface.close("Term5678");

Alternately, all terminal connections on that EspInterface can be closed with the closeAll method:

esp_interface.closeAll();

Terminals should not normally be closed and reopened between transactions as this process is memory and processor intensive. Typically a terminal should be closed before the POS application terminates, but the POS developer might also decide to close a terminal with eSocket.POS while it is inactive, for instance overnight. The decision about when to close a terminal is left to the POS application developer.

2.7. Starting and closing Config Agent

The EspInterface gives the ability to start and stop Config Agent.

Config Agent can be started by calling

esp_interface.startConfigAgent("c:\\esocketpos\\properties.txt");

(Change the filename and path to reflect location of the properties file on the local system.)

or by calling the startConfigAgent method with a Properties object as the parameter.

The closeConfigAgent method will close Config Agent if it is running.

2.8. Error handling

Overview

When an error occurs in EspInterface , an exception is raised. An error may occur for various reasons. Exceptions that are specific to EspInterface will also include a description of the exception. Errors that may occur include:

  • Errors during initialization

  • Attempting to set a transaction property to an invalid value

  • Attempting to send a message on behalf of a non-configured terminal

  • An invalid response received, either constructed by eSocket.POS or received from upstream

Java Exceptions

Exceptions raised by EspInterface may be caught by try/catch clauses. The following exceptions are specific to EspInterface :

  • XConfig - This exception is thrown during initialization in case the properties file is invalid or missing, or if eSocket.POS can’t start because of a configuration error or a problem with an external device.

  • XInvalidPropertyAssignment - This exception is thrown when invalid values are assigned to a property.

  • XPropertyNotSet - Certain properties are mandatory for transactions sent to eSocket.POS. This exception is thrown when mandatory properties have not been set.

  • XTransactionFailure - This exception is thrown when a serious problem is encountered while trying to send a message or receiving a response from eSocket.POS (e.g. when the message or response is null)

  • XUnknownTerminal - This exception is thrown when a Terminal ID is used that has not been successfully initialized.

  • XUnsupportedTransaction - This exception is thrown when an unknown transaction is received.

2.9. Transactions

2.9.1. Sending a transaction

The eSocket.POS API exposes objects and properties that can be used to send various types of transactions using eSocket.POS. These transactions are based on the following objects:

  • EspTransaction

  • EspInquiry

  • EspMerchandise

  • EspCheck

  • EspReconciliation

  • EspNetwork

Each time a transaction is required, a method is called to create the appropriate transaction object:

EspTransaction tran_purchase = esp_interface.newTransaction();

The necessary properties are set, for example:

tran_purchase.setTransactionId("123456");
tran_purchase.setType(EspTransaction.Type.PURCHASE);
tran_purchase.setTransactionAmount("1000");

The transaction is sent to eSocket.POS, and the response is returned. The Terminal ID used in the send method must be for a terminal which has already been initialized successfully:

EspTransaction tran_rsp = (EspTransaction) esp_interface.send("Term1234", tran_purchase);

Note that this method may take a considerable time to return, as eSocket.POS may need to interact with the customer via external devices, and wait for an online response.

Finally, the response properties are extracted, for instance to check for a successful response:

if (!"0".equals(tran_rsp.getActionCode())) //approved \
{
	System.out.println("The transaction was not successful.");
}

Other transaction properties might be printed on the receipt, saved to the POS database, etc.

2.9.2. Transaction flows

The EspTransaction object is used in a variety of contexts. Most importantly, it is used to effect a purchase transaction. This can be done in a single step, or through multiple steps, depending on the EFT model chosen by the merchant.

Purchase and possibly reverse:

With this model, most transactions will be completed with a single message flow (a 0200 message in ISO 8583 terms).

  1. Create an EspTransaction object, set the Type to PURCHASE, set the required properties, and send the object.

    • If the response is successful, the purchase has been completed.

    • If it is then decided to void the transaction, the following steps must be taken:

      1. Create another EspTransaction object, set the Reversal property to true , set the Type to PURCHASE, set the TransactionId to match the original transaction, set any other required properties, and send it.

        Note
        The ReversalType property can optionally be set to REQUEST for online reversal (a 0400 message in ISO 8583 terms). If the ReversalType is not set, or set to ADVICE, it will be an offline reversal (a 0420 message in ISO 8583 terms).
      2. If the ReversalType is ADVICE, the reversal will be approved, unless a format error or software error has occurred. In such cases, the transaction should be logged for possible exception processing.

Authorize and confirm or reverse:

With this model, transactions will require an authorization message and a fulfillment message (0100 followed by 0220 in ISO terms).

  1. Create an EspTransaction object, set the Type to PURCHASE, set the MessageType to AUTH, set the required properties, and send the object.

    • If the response is not successful, the authorization has been declined and another tender should be attempted. No reversal is required.

    • If the response is successful, funds might have been reserved against the cardholder’s account, but a fulfillment is required to confirm the transaction before the account is actually debited.

    • If the transaction is to be fulfilled, the following steps must be taken:

      1. Create another EspTransaction object, set the Type to PURCHASE, set the MessageType to CONFIRM, set the TransactionId to match the original transaction, set any other required properties, and send it.

      2. The reversal will be approved, unless a format error or software error occurs. In such cases, the transaction should be logged for possible exception processing.

    • If it is instead decided not to fulfill the transaction, the authorization must be reversed to remove the hold on the funds on the cardholder’s account. To do this, the following steps must be taken:

      1. Create another EspTransaction object, set the Reversal property to true, set the TransactionId to match the original transaction, set any other required properties, and send it.

        Note
        The ReversalType property can optionally be set to REQUEST for online reversal (a 0400 message in ISO 8583 terms). If the ReversalType is not set, or set to ADVICE, it will be an offline reversal (a 0420 message in ISO 8583 terms).
      2. If the ReversalType is ADVICE, the reversal will be approved, unless a format error or software error has occurred. In such cases, the transaction should be logged for possible exception processing.

    • Some merchants might elect to perform the fulfillment stage through an offline batch process and not through eSocket.POS. In this case, the POS application is responsible for generating the settlement files.

NOTE

AUTH and CONFIRM are deprecated Types and must no longer be used. These are equivalent to a PURCHASE Type and an AUTH or CONFIRM MessageType.

Refund:

A refund is a request for a refund (credit) against a cardholder’s account, usually when goods are returned. Although proof of purchase is usually required, the refund transaction is not usually linked to the original purchase transaction. A refund can be sent as a Transaction Advice (0220) or as a Transaction Request (0200). Device interaction is only possible if the refund is sent using a Transaction Request (0200).

  • Both methods require the creation of an EspTransaction object and that the Type is set to REFUND.

  • Thereafter, if you wish to send the refund as a Transaction Advice (0220), set the MessageType to CONFIRM. Otherwise, by default, the refund will be sent as a Transaction Request (0200).

  • Lastly, set the required properties, and send the object.

  • If the response is not successful, the refund has been declined.

Referral:

A referral transaction is used to give notice of a transaction that was approved by referral. This usually occurs when the original transaction is declined with a referral response code, and the transaction is then approved using an external authorization process, such as a telephone call. A referral can be a standalone transaction and does not necessarily occur on the same terminal as the original transaction. Since it is an advice message, and the customer may no longer be present, no device interaction is possible. This means that all required fields must be present in the transaction sent to eSocket.POS.

  1. Create an EspTransaction object, set the Type to PURCHASE and the MessageType to CONFIRM, set the required properties, and send the object.

  2. The referral will be approved, unless a format error or software error occurs. In such cases, the transaction should be logged for possible exception processing.

Note
REFERRAL is a deprecated Type and should no longer be used. This is equivalent to a PURCHASE Type and a CONFIRM MessageType.

2.9.3. Inquiry flows

The EspInquiry object is used for a number of inquiries, including balance, available funds, and card verification.

To perform an inquiry, the application programmer must perform the following steps:

  • create an EspInquiry object, set the required properties, and send the inquiry

  • if the inquiry was successful, unpack the requested information from the response object (e.g. a list of balances for a balance inquiry).

2.9.4. merchandise transaction flows

The EspMerchandise object is used to request a merchandise item, for example a telephone prepay purchase from a merchandise host.

To request merchandise, the application programmer may follow one of two approaches:

Request and Confirm or Reverse:

  • create an EspMerchandise object, set the Type to REQUEST, set the required properties, and send the object.

  • If the response is successful, a tender is required. This may be an EFT tender using eSocket.POS, or a cash or other tender which does not interact with eSocket.POS.

  • If the tender was successful, create a new EspMerchandise object, set the Type to CONFIRM, set the required properties, and send the object. At this stage, information in the original EspMerchandise response may be given to the customer, for instance a PIN for prepay services may be printed on a voucher.

  • If the tender was unsuccessful (the customer was unable to pay), create an EspMerchandise object, set the Type to REVERSE, set the required properties, and send the object.

  • If the REVERSE response is unsuccessful, the merchandise request could not be reversed. This may mean that the merchandise host regards the merchandise as dispensed and will expect payment for it. The steps to be taken in this situation are beyond the scope of eSocket.POS.

  • Procure and possibly Reverse:*

  • create an EspMerchandise object, set the Type to PROCURE, set the required properties, and send the object.

  • If the response is successful, a tender is required. This may be an EFT tender using eSocket.POS, or a cash or other tender which does not interact with eSocket.POS.

  • If the tender was successful, information in the original EspMerchandise response may be given to the customer, for instance a PIN for prepay services may be printed on a voucher. (No CONFIRM message is required.)

  • If the tender was unsuccessful (the customer was unable to pay), create an EspMerchandise object, set the Type to REVERSE, set the required properties, and send the object.

  • If the REVERSE response is unsuccessful, the merchandise request could not be reversed. This may mean that the merchandise host regards the merchandise as dispensed and will expect payment for it. The steps to be taken in this situation are beyond the scope of eSocket.POS.

2.10. Events and callback

2.10.1. Registering for events and callback

In order to receive events or callbacks from eSocket.POS, the POS application must register to receive particular events or callbacks for particular event IDs.

This is done by means of the registerEvent and registerCallback methods, and by providing an object which implements the IEspEventProcessor interface.

The IEspEventProcessor interface provides onEvent and callback methods. A sample implementation of this interface, supporting both events and callback, is given below. The POS application would need to provide the relevant method bodies.

public class EspProcessor
   implements IEspEventProcessor
{
   public void onEvent(String term_id, String event_id, String data)
   {
      System.out.println("EVENT " + event_id + ": '" + data + "'");
   }
   public String callback(String term_id, String event_id, String data)
   {
      System.out.print("CALLBACK " + event_id + ": '" + data + "'");
      System.out.println(", returning '123'");
      return "123";
   }
}

In order to register for events or callback, the POS application should create a processor and register it to receive events and/or callback as follows:

EspProcessor proc = new EspProcessor();
esp_interface.registerEvent("Term1234", proc , "EVENT_ID_1");
esp_interface.registerCallback("Term1234", proc , "CALL_ID_1");

This means that the POS application will receive any events with the ID EVENT_ID_1 or callbacks with the ID CALL_ID_1 which might be sent by eSocket.POS.

2.10.2. Receiving events and callback

The POS application may register an object implementing the IEspEventProcessor interface to receive events or callbacks with particular event IDs from eSocket.POS.

If it registers in this way, and eSocket.POS sends an event or callback with that particular event ID, the object’s onEvent or callback method will be called.

The POS application is free to handle events and callbacks in any way necessary. It is recommended that the onEvent method return as quickly as possible, so as not to delay the eSocket.POS application. The callback method may require longer, particularly if the return value requires customer or operator interaction.

If the POS does not want to process an event which it receives, it is free to ignore it. If the POS does not want to process a callback which it receives, it should return null .

2.10.3. Sending events and callback

The eSocket.POS API exposes methods which allow the POS application to send events or callbacks to eSocket.POS. These are the onEvent and callback methods on the EspInterface object.

Events use a fire-and-forget model, so the POS will not be aware of whether any internal entity in eSocket.POS has registered to receive the event, or what the results of receiving it were. Events are sent as follows:

esp_interface.onEvent("Term1234", "POS_EVENT", "pos event data");

Callbacks are handled within eSocket.POS by whatever entity has registered to receive the callback. If no entity has registered, null will be returned. Callbacks may take some time to return, for instance if customer interaction is required via an external device. Callbacks are sent as follows:

String rsp = esp_interface.callback("Term1234", "POS_CALLBACK", "pos callback data");

Whether these events or callbacks are handled by eSocket.POS depends on internal entities of eSocket.POS being registered for the particular event IDs used. This will be based on the configuration and customization of eSocket.POS, and should be determined during the integration phase between eSocket.POS and the POS application.

2.11. Reference guide

2.11.1. Reference Guide

The Java API Reference Guide can be found in the zip file dg_esocketpos_java_api.zip which is distributed alongside this document. It describes the specific features of the API more precisely and should be used as the core reference when implementing this API.

Package-postilion.esocketpos.api.html serves as an index of all the files in the Reference Guide.

3. XML Interface

3.1. Overview

The eSocket.POS XML interface provides remote access to eSocket.POS through a message interface based on an XML message format. This may be used when the POS application is not on the same machine as eSocket.POS, or when the POS application is unable to use Java method calls in the eSocket.POS API.

3.1.1. XML message format

The XML interface is based on an XML format which closely mirrors the eSocket.POS API. Message types are represented using XML elements, and the fields within the message are represented as attributes. XML elements representing repeated data sets may also be contained within the message element. For example, a successful inquiry response may contain up to six Esp:Balance elements, which in turn contain attributes with the balance information. In Esp:Transaction or Esp:Inquiry requests, a single purchasing card element may be used to include attributes related to purchasing cards, and this element may in turn include repeated line item, tax amount and contact elements.

Request and response messages use the same XML element, unless an error occurs (see below). Generally, the response message will contain attributes that are related to the response, for example, ActionCode would appear only in an Esp:Transaction response message, and not in the request message.

3.1.2. Initializing and closing

Before sending an EFT request message to the XML interface, an initialization message must be sent to register the terminal with eSocket.POS. When the terminal is finished operating, for instance at the end of the day, it can send a close message to eSocket.POS. These operations use an Esp:Admin request.

The Esp:Admin element takes the place of the init and close methods in the eSocket.POS API. There is no equivalent of the closeAll method.

3.1.3. Errors

If the XML interface is unable to process a message it receives, an Esp:Error response is returned. An example would be a message format error or a message received for an uninitialized terminal ID. If the XML interface is able to process the message, but an application error occurs within the eSocket.POS processing, a normal decline message will be returned of the same type as the request.

The Esp:Error element takes the place of the Java Exceptions that may be thrown when using the API.

3.1.4. MessageInterface DTD

The DTD MessageInterface.dtd is installed along with eSocket.POS and can be viewed with a text editor. Elements and attributes are defined in the Interface Specification section of this document.

Important
The subelements of Esp:Transaction, Esp:Inquiry, etc. must appear in the same order in the message as in the DTD. Subelement Esp:PurchasingCardData must appear before the Esp:Balances, and so on.

3.1.5. Communications protocol

Due to the fact that messages are sent from the POS to eSocket.POS to initiate transaction processing, the message protocol must provide integrity in cases where message transmissions fail. Such failure may occur as a result of network connection failure or corrupted message data.

It is important to realize that any message transmissions from eSocket.POS to the Postilion Realtime engine are not part of this discussion, as eSocket.POS takes care of the message integrity on this leg. For example, if eSocket.POS sends a transaction request to Postilion Realtime, and does not receive a response, eSocket.POS will time out, respond negatively to the POS, and generate a reversal to Postilion Realtime. However, in the case where the POS sends a message to eSocket.POS, and does not receive a response from eSocket.POS, the POS must time out, and generate a reversal message to eSocket.POS.

Transaction requests and responses are communicated with eSocket.POS in XML format, sent using TCP with each message preceded by a length indicator .

3.2. Using Esp:Interface

All messages sent and received via the eSocket.POS XML interface are contained within the Esp:Interface element. A typical message to or from the XML interface will have the following form:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> ... </Esp:Interface>

Within this element, various other elements can be contained to perform the following functions:

  • initializing eSocket.POS to receive transactions for a particular terminal ( Esp:Admin with Type set to 'INIT')

  • closing eSocket.POS for a particular terminal ( Esp:Admin with Type set to 'CLOSE')

  • sending a transaction from a terminal to eSocket.POS ( Esp:Transaction , Esp:Inquiry, Esp:Merchandise , Esp:Network or Esp:Check )

  • sending an event or callback from a terminal to eSocket.POS ( Esp:Event or Esp:Callback )

  • registering a terminal to receive events or callback from eSocket.POS ( Esp:Register element within Esp:Admin )

These elements are dealt with on the subsequent pages of the developer guide.

3.3. TCP messages

Communication between the POS and the XML interface uses a TCP message beginning with a header to indicate the length of the data segment of the message. This header must precede all messages sent to the XML interface, and will be sent at the beginning of all TCP responses from the XML interface.

If the message length is less than 2 16 -1 or 65,535 then a two-byte header will be used.

The first byte of the header contains the quotient of the length of the message (excluding this header) and 256. The second byte contains the remainder of this division. Both these values are represented in binary as unsigned integer values ranging from 0 to 255 (bytes 0x00 to 0xFF).

If the message length is greater than or equal to 2 16 -1 or 65,535 bytes then a six-byte header will be used.

In this case the bytes FF FF should be sent followed by a four-byte length indicator, i.e. six bytes in total.

3.4. Initializing a terminal

Before transactions can be sent from a terminal, the terminal must be initialized with eSocket.POS. This is done via the Esp:Admin element with the Type property set to 'INIT'.

The Terminal ID identifies which terminal parameters to apply, so data for that Terminal ID must be present in the eSocket.POS database before that terminal can be initialized. The Terminal ID must be unique across all the terminals connecting to the upstream Postilion system.

In the case of a POS application controlling a single terminal, the initTerminal method should be called once as follows

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Admin TerminalId="Term1234" Action="INIT" />
</Esp:Interface>

To indicate that the terminal has been successfully initialized, a response of the following form will be returned:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Admin Action="INIT" ActionCode="APPROVE" MessageReasonCode="9791" TerminalId="Term1234"></Esp:Admin>
</Esp:Interface>

See Terminal administration for a simple example of how to do this.

If the POS application controls more than one POS terminal, each terminal should be initialized in a separate message. This may be done at the discretion of the POS application: either all terminals can be initialized at startup, or terminals can be initialized as they come into action. Unused terminals may be closed using the Esp:Admin element with the Type property set to 'CLOSE' (as described later).

Note that the initialization process is memory and processor intensive and is typically called when the application starts, at the start of the day or after losing the TCP connection. Terminals should not be initialized per transaction.

3.5. Closing a terminal

When no more transactions are required, and a particular terminal is no longer needed, the POS application should close that terminal with eSocket.POS. This is done via the Esp:Admin element with the Type property set to 'CLOSE'.

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Admin TerminalId="Term1234" Action="CLOSE" />
</Esp:Interface>

To indicate that the terminal has been successfully closed, a response of the following form will be returned:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Admin Action="CLOSE" ActionCode="APPROVE" MessageReasonCode="9791" TerminalId="Term1234"></Esp:Admin>
</Esp:Interface>

See Terminal administration for a simple example of how to do this.

Terminals should not normally be closed and reopened between transactions as this process is memory and processor intensive. Typically a terminal should be closed before the POS application terminates, but the POS developer might also decide to close a terminal with eSocket.POS while it is inactive, for instance overnight. The decision about when to close a terminal is left to the POS application developer.

3.6. Handling timeouts

Once a transaction has been sent to eSocket.POS, the response may take a considerable time to be returned, as eSocket.POS may need to interact with the customer via external devices, and wait for an online response.

If no response is received within a reasonable time, the POS application needs to decide whether to ignore this, or to reverse the transaction, or send a repeat. Note that it is not necessary for the POS to handle a timeout if a valid response is received from eSocket.POS (even if the response code indicates a timeout), because in this case, eSocket.POS will take care of the repeat or reversal processing.

Message that timed out Result

Esp:Inquiry

Ignore. Inquiries do not have financial impact so no reversal is required.

Esp:Transaction with Type of PURCHASE, DEPOSIT or REFUND, and MessageType not set or set to AUTH

Send a reversal.

Esp:Transaction with Type of ADMIN, CONFIRM or REFERRAL, or MessageType of CONFIRM, or Reversal set.

Send a repeat of the message. Repeats may be sent indefinitely (until a response is received from eSocket.POS), or limited in number, after which the transaction should be logged by the POS application for exception processing, for instance through an offline process.

Esp:Check with MessageType not set or set to TRANREQ

Ignore. Check verifications do not have financial impact so no reversal is required.

Esp:Check with MessageType of AUTHADV or CONFIRM

Send a repeat of the message. Refer to notes above about sending repeats indefinitely.

Esp:Merchandise with Type of REQUEST or PROCURE

Send a reversal. If the reversal response code indicates that the reversal was unsuccessful, it means the merchandise request could not be reversed. This may mean that the merchandise host regards the merchandise as dispensed and will expect payment for it. The steps to be taken in this situation are beyond the scope of eSocket.POS.

Esp:Merchandise with Type of REVERSAL

Send a repeat of the reversal. Refer to notes above about sending repeats indefinitely, and dealing with declined merchandise reversals.

Esp:Merchandise with Type of CONFIRM

Send a repeat of the message.

Esp:Admin

Send a repeat of the message.

Esp:Callback

Continue as if no ResponseData was returned.

Esp:Event

Not applicable: events use a fire-and-forget model, and no response is received.

Note that it is not necessary for the POS to handle the timeout if a valid response is received from eSocket.POS (even if the response code indicates a timeout), because in this case, eSocket.POS will take care of the repeat or reversal processing.

3.7. Error handling

3.7.1. Overview

When an error occurs and the XML interface is unable to process a message, an exception is raised and logged in the Java application, and an error response is returned to the POS application. Errors that may occur include:

  • Attempting to set the property of an object to an invalid value

  • An unsupported transaction type

  • Attempting to send a message on behalf of a non-configured terminal

  • A configuration error

  • A timeout while waiting for a response to a request

  • Errors during initialization

3.7.2. Error messages

Error messages use an Esp:Error element inside the Esp:Interface element, and take the following form:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Error ActionCode="DECLINE" MessageReasonCode="9791" ResponseCode="30" TerminalId="Term1234" TransactionId="123456"></Esp:Error>
</Esp:Interface>

In some cases the error response may not include the TerminalId and TransactionId attributes, for instance when an incoming XML message from the POS could not be parsed and these elements could not be extracted.

The error response can also contain a Description attribute, which contains a description of a software exception that occurred during the processing of the message. Typically this occurs when a terminal fails to initialize because the configuration is incorrect or a device is not available. The description contains an indication of the cause, and more complete details will usually be found in the eSocket.POS event log.

3.8. Transactions

3.8.1. Sending a transaction

The eSocket.POS XML interface includes elements and attributes that that can be used to send various types of transactions to eSocket.POS. These transactions are based on the following elements:

  • Esp:Transaction

  • Esp:Inquiry

  • Esp:Merchandise

  • Esp:Check

  • Esp:Reconciliation

  • Esp:Network

A transaction message has the following form:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Transaction TerminalId="Term1234" TransactionAmount="10000" TransactionId="123456" Type="PURCHASE"/>
</Esp:Interface>

Other attributes may be set within the Esp:Transaction element depending on what is available on the POS.

The response from eSocket.POS will have the following form:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Transaction Account="10" ActionCode="APPROVE" CardNumber="1111222233334444" CurrencyCode="840" DateTime="0721084817" ExpiryDate="0912" MerchantId="123456 " MessageReasonCode="9790" PanEntryMode="00" PosCondition="00" ResponseCode="91" ServiceRestrictionCode="101" TerminalId="Term1234" Track2="1111222233334444=09121011234" TransactionAmount="10000" TransactionId="123456" Type="PURCHASE"></Esp:Transaction>
</Esp:Interface>

The POS application may then extract the attributes in the response, for instance using the ActionCode to determine whether the transaction was approved. Other attributed might be printed on the receipt, saved to the POS database, etc.

3.9. Events and callback

3.9.1. Registering for events and callback

In order to receive events or callbacks from eSocket.POS, the POS application must register to receive particular events or callbacks for particular event IDs.

This is done in the initialization message for that terminal, by including one or more Esp:Register elements inside the initialization Esp:Admin message. This will take the following form:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Admin TerminalId="Term1234" Action="INIT"><Esp:Register Type="CALLBACK" EventId="CALL_ID_1" />
		<Esp:Register Type="EVENT" EventId="EVENT_ID_1" />
	</Esp:Admin>
</Esp:Interface>

See Terminal administration for a simple example of how to do this.

This means that the POS application will receive any events with the ID EVENT_ID_1 or callbacks with the ID CALL_ID_1 which might be sent by eSocket.POS. These will take the form of additional messages from the XML interface. Depending on which entities within eSocket.POS initiate these events or callbacks, they might occur at any stage during or outside normal transaction processing for an initialized terminal.

3.9.2. Receiving events and callback

The POS application may register with the XML interface in order to receive events or callbacks with particular event IDs from eSocket.POS.

If it registers in this way, and eSocket.POS sends an event or callback with that event ID, the XML interface will send a message to the POS, using the Esp:Event or Esp:Callback element.

An event message will take the following form:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Event TerminalId="TestTerm" EventId="EVENT_ID_1" EventData="event data"/>
</Esp:Interface>

The POS may process the event in any way that it chooses, and no response should be sent.

A callback message will take the following form:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Callback TerminalId="TestTerm" EventId="CALL_ID_1" EventData="callback data"/>
</Esp:Interface>

The POS must return a response message to eSocket.POS, of the following form:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Callback TerminalId="TestTerm" EventId="CALL_ID_1" ResponseData="response data" />
</Esp:Interface>

The POS application may process the callback any way it chooses, but it must return a response containing the ResponseData attribute. If no response data is available, this should be indicated by an empty string inside quotes: ResponseData="". The response may require a certain amount of time, particularly if the return value requires customer or operator interaction. eSocket.POS allows a maximum of 60 seconds, after which an empty return value is assumed.

If the POS does not want to process an event which it receives, it is free to ignore it. If the POS does not want to process a callback which it receives, it must still return a response.

3.9.3. sending events and callback

The eSocket.POS XML interface provides a mechanism to allow the POS application to send events or callbacks to eSocket.POS. These take the form of additional messages using the Esp:Event or Esp:Callback elements inside the main Esp:Interface element.

Events use a fire-and-forget model, so the POS will not be aware of whether any internal entity in eSocket.POS has registered to receive the event, or what the results of receiving it were. Event messages sent to eSocket.POS take the following form:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Event TerminalId="Term1234" EventId="POS_EVENT" EventData="data"/>
</Esp:Interface>

Callbacks are handled within eSocket.POS by whatever entity has registered to receive the callback. Callbacks are sent as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Callback TerminalId="Term1234" EventId="POS_CALLBACK" EventData="pos callback data" />
</Esp:Interface>

Callbacks may take some time to return, for instance if customer interaction is required via an external device. A callback return message is sent as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Callback TerminalId="Term1234" EventId="POS_CALLBACK" ResponseData="response data"/>
</Esp:Interface>

If no entity has registered, or no response data is available, the empty string ResponseData="" will be returned.

Whether these events or callbacks are handled by eSocket.POS depends on internal entities of eSocket.POS being registered for the particular event IDs used. This will be based on the configuration and customization of eSocket.POS, and should be determined during the integration phase between eSocket.POS and the POS application.

3.10. POS XML message flow examples

3.10.1. Terminal administration

Introduction

A number of administrative interactions between the POS and eSocket.POS are required during the start-up of the environment, as well as during the shutdown. The message flow here is an example of a successful transaction. The following are possible administrative interactions:

  1. Terminal initialization

  2. Event and callback registration

  3. Terminal close

Message flow

Terminal administration

Follow the message flow and refer to the diagram.

  1. The POS sends an administration XML message to eSocket.POS containing a terminal initialization, a terminal initialization with event and callback registration, or a terminal close action.

  2. eSocket.POS performs the administrative task and responds to the POS to indicate the success or failure of the task.

Note: The registration of events and callbacks occurs in the same message as terminal initialization, and an initialization message may register multiple events and callbacks.

Events and callbacks between the POS device and eSocket.POS

No events and callbacks typically occur during terminal administration messages, as none are typically registered at this time.

For a complete list of all events and callbacks that may be registered with eSocket.POS, see EventId .

XML mappings in a terminal administration message

This section contains the XML properties and values that are typically associated with terminal administration messages. In the Value column, example values are in italics and mandatory values are in bold.

  1. Terminal initialization XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    Action

    M

    INIT

  2. Terminal initialization with events and callbacks registration XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    Action

    M

    INIT

    Register

    O

    Type

    M

    EVENT

    EventId

    M

    CARD_INFO

    Register

    O

    Type

    M

    EVENT

    EventId

    M

    PROMPT_SWIPE_CARD

    Register

    O

    Type

    M

    CALLBACK

    EventId

    M

    CARD_INFO

  3. Terminal close XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    Action

    M

    CLOSE

For a full list of possible properties in these messages, see Administration Properties .

For an explanation of the Condition column of these tables, see Object and Property Conditions .

Examples of terminal administration XML messages

Three examples are presented.

  1. Terminal initialization

  2. Terminal initialization with events and callbacks registration

  3. Terminal close

The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above for all the examples.

Example 1: Terminal initialization

The POS sends an Admin (request) terminal initialization XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Admin
            Action="INIT"
            TerminalId="TestTerm">
        </Esp:Admin>
    </Esp:Interface>

eSocket.POS initializes the terminal and responds with an Admin (response) XML message [2]:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Admin
            Action="INIT"
            ActionCode="APPROVE"
            MessageReasonCode="9791"
            TerminalId="TestTerm">
        </Esp:Admin>
    </Esp:Interface>

Example 2: Terminal initialization with events and callbacks registration

The POS sends an Admin (request) terminal initialization XML message containing events and callbacks to register [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Admin
            Action="INIT"
            TerminalId="TestTerm">
            <Esp:Register
                EventId="CARD_INFO"
                Type="EVENT">
            </Esp:Register>
            <Esp:Register
                EventId="PROMPT_SWIPE_CARD"
                Type="EVENT">
            </Esp:Register>
            <Esp:Register
                EventId="CARD_INFO"
                Type="CALLBACK">
            </Esp:Register>
        </Esp:Admin>
    </Esp:Interface>

eSocket.POS initializes the terminal, registers all specified events and callbacks, and responds with an Admin (response) XML message [2]:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Admin
            Action="INIT"
            ActionCode="APPROVE"
            MessageReasonCode="9791"
            TerminalId="TestTerm">
        </Esp:Admin>
    </Esp:Interface>

Example 3: Terminal close

The POS sends an Admin (request) terminal close XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Admin
            Action="CLOSE"
            TerminalId="TestTerm">
        </Esp:Admin>
    </Esp:Interface>

eSocket.POS closes the terminal and responds with an Admin (response) XML message [2]:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Admin
            Action="CLOSE"
            ActionCode="APPROVE"
            MessageReasonCode="9791"
            TerminalId="TestTerm">
        </Esp:Admin>
    </Esp:Interface>

3.10.2. Network

Introduction

When the POS needs to communicate with an upstream entity, a network transaction can be used. This example is of an echo message from the POS, to check the network connectivity. The POS sends a network message upstream and the first entity able to answer will do so. In this example, it is the Postilion system that sends the response back.

Message flow

Network

Follow the message flow and refer to the diagram.

  1. The POS sends a EspNetwork XML message to eSocket.POS.

  2. eSocket.POS sends a network request message (0800) to Postilion.

  3. Postilion sends a network response (0810) to eSocket.POS.

  4. eSocket.POS sends the appropriate response to the POS device.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a network transaction:

If registered, the following callbacks are called during a network transaction:

XML mappings in a network transaction

This section contains the XML properties and values that are typically associated with a network transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

198546

NetworkMngInfoCode

M

301

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Network Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Examples of network transaction XML messages

Two examples are presented.

  • Echo network transaction

  • EMV CAPK download transaction

Example 1: Echo network transaction This is an example of a network transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

This example is an echo network transaction. This transaction is defined in the value of the NetworkMngInfoCode field.

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Network
            NetworkMngInfoCode="301"
            TerminalId="TestTerm"
            TransactionId="198546">
        </Esp:Network>
    </Esp:Interface>

The resulting EspNetwork (response) XML message [4] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Network
            ActionCode="APPROVE"
            DateTime="1025205546"
            LocalDate="1025"
            LocalTime="225546"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            NetworkMngInfoCode="301"
            ResponseCode="00"
            TerminalId="TestTerm"
            TransactionId="198546"
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion"
            </Esp:StructuredData>
        </Esp:Network>
    </Esp:Interface>

Example 2: EMV CAPK download transaction This is an example of an EMV CAPK download transaction.

The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

This example is an EMV CAPK download transaction. This transaction is defined in the value of 130 in the NetworkMngInfoCode field.

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Network
            NetworkMngInfoCode="130"
            TerminalId="TestTerm"
            TransactionId="198546">
        </Esp:Network>
    </Esp:Interface>

The resulting EspNetwork (response) XML message [4] from eSocket.POS indicating that the requested CAPK records are available, and have been returned: NOTE: See EMV CA Public Key File , outlining the format of the EMV_CA_PKF field. And see EMV CA Public Key File Version , outlining the format of the EMV_FILE_VERSION field.

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Network
            ActionCode="APPROVE"
            DateTime="1025205546"
            LocalDate="1025"
            LocalTime="225546"
            MerchantId="111111111111111"
            MessageReasonCode="9791"
            NetworkMngInfoCode="301"
            ResponseCode="00"
            TerminalId="TestTerm"
            TransactionId="198546"
            <Esp:StructuredData
                Name="EMV_FILE_VERSION"
                Value="031720150000011523006"
                Name="EMV_CA_PKF"
                Value="031720150000011523006"
            </Esp:StructuredData>
        </Esp:Network>
    </Esp:Interface>

The resulting EspNetwork (response) XML message [4] from eSocket.POS indicating that the requested CAPK records are not available, and eSocket.POS has scheduled an online retrieval:

NOTE: After the scheduled retrieval has completed successfully, the CAPK_RETRIEVAL_COMPLETE event will be triggered.

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Network
            ActionCode="DECLINE"
            DateTime="1025205546"
            LocalDate="1025"
            LocalTime="225546"
            MerchantId="111111111111111"
            MessageReasonCode="9791"
            NetworkMngInfoCode="301"
            ResponseCode="06"
            TerminalId="TestTerm"
            TransactionId="198546"
        </Esp:Network>
    </Esp:Interface>

3.10.3. Device administrative message

Introduction

Device administrative messages are used to send data relating to a device to an upstream entity. Specifically, it sends device registration data and key encryption data.

Message flow

Device administration message - successful

Follow the message flow and refer to the diagram.

  1. The POS sends an ADMIN_REQUEST (request) XML message to eSocket.POS with a device administration extended transaction type.

  2. eSocket.POS sends an administration request (0600) to Postilion.

  3. Postilion sends the administration request (0600) upstream.

  4. Postilion receives an administration request response (0610) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the administration request response (0610) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Events and callbacks are not displayed in the above diagram.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following callbacks are called to collect data for a device administration message:

XML mappings in a device administration transaction

This section contains the XML properties and values that are typically associated with device administration transactions. In the Value column, example values are in italics and mandatory values are in bold.

Device administration request:

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

170818

Type

M

ADMIN

MessageType

M

ADMIN_REQUEST

ExtendedTransactionType

M

2111

Device administration response:

Property Condition Value

TRANSARMOR_TOKEN

O

String (Specified as part of EspStructuredData)

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in device administration transaction

This is an example of an administration request transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a Device Administration transaction with an ADMIN (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionId="170818"
            Type="ADMIN"
            MessageType="ADMIN_REQUEST"
            ExtendedTransactionType="2111">
        </Esp:Transaction>
    </Esp:Interface>

When the transaction completes successfully, eSocket.POS sends the ADMIN (response) XML message [6]:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            DateTime="0829200820"
            ExtendedTransactionType="2111"
            LocalDate="0829"
            LocalTime="220820"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            MessageType="ADMIN_REQUEST"
            PanEntryMode="00"
            PosCondition="00"
            PosDataCode="010101054005101"
            ResponseCode="00"
            RetrievalRefNr="000000000120"
            TerminalId="TestTerm"
            TransactionId="170818"
            Type="ADMIN">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.10.4. Device Data Capture

Introduction

This section discusses a Device Data capture flow, started at the POS and sent upstream via Postilion for Device data. The example is of a successful transaction.

Message flow

Device Data Capture Flow - successful

Follow the message flow and refer to the diagram.

  1. The POS sends an ADMIN (request) XML message to eSocket.POS.

  2. eSocket.POS sends a request for device to the connected device.

  3. The connected device responds with device information to eSocket.POS.

  4. eSocket.POS sends an administrative advice (0620) to Postilion.

  5. Postilion sends the administrative advice response (0630) to eSocket.POS.

  6. eSocket.POS sends an ADMIN (response) back to the POS. The response includes the retrieved device information.

Note: The eSocket.POS interface sends multiple requests to the PED and Postilion to get the information.

XML mappings in a single message pair Device data capture transaction

This section contains the XML properties and values that are typically associated with a single message pair purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property

Condition

Value

TerminalId

M

TestTerm

TransactionId

M

195322

Type

M

ADMIN

MessageType

M

ADMIN_REQUEST

ExtendedTransactionType

O

2113

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

Example: XML messages in a single message pair admin transaction

This is an example of a single message pair purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts an admin transaction with a ADMIN_REQUEST (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionId="195322"
            Type="ADMIN"
			MessageType="ADMIN_REQUEST"
			ExtendedTransactionType="2113"  >
        </Esp:Transaction>
    </Esp:Interface>

The resulting Device Data Capture (response) XML message [6] from eSocket.POS following the successful completion of the transaction follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ActionCode="APPROVE"
            BusinessDate="0806"
            DateTime="0829200820"
            ExtendedTransactionType="2113"
            LocalDate="0829"
            LocalTime="220820"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            MessageType="ADMIN_REQUEST"
            PanEntryMode="00"
            PosCondition="00"
            PosDataCode="010101054005101"
            ResponseCode="00"
            RetrievalRefNr="000000000120"
            TerminalId="TestTerm"
            TransactionId="195322"
            Type="ADMIN">
            <Esp:StructuredData
                Name="Term"
                Value="&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; &lt;Term&gt;
                    &lt;Poi&gt;
                    &lt;Hw ManufacturingSerial=&quot;13333750&quot; HwId=&quot;LAN30AA&quot; IPAddress=&quot;10.0.2.15&quot; Manuf=&quot;Ingenico&quot; Serial=&quot;3011087713333750&quot; ModName=&quot;L3000&quot;&gt;&lt;/Hw&gt;
                    &lt;Sw&gt;&lt;Mod Ver=&quot;0390&quot; Type=&quot;os&quot; Name=&quot;OS&quot;&gt;&lt;/Mod&gt;&lt;Mod Ver=&quot;6.80.10-0033&quot; Type=&quot;app&quot; Name=&quot;APPLICATION&quot;&gt;&lt;/Mod&gt;&lt;/Sw&gt;
                    &lt;/Poi&gt;&lt;/Term&gt;" >
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11. EFT transactions

3.11.1. Balance inquiry

To determine the balance of a cardholder’s account from the POS, a balance inquiry is sent upstream via Postilion. The response that comes back will contain the balance amount in that cardholder’s account at the time of the inquiry.

A balance inquiry is identical to a gift card balance inquiry. Refer to the gift card balance inquiry page for the complete message flow, events and callbacks, XML mappings, and examples.

3.11.2. Barcode reader

Introduction

The eSocket.POS barcode reader feature allows barcode data to be retrieved from a supported and configured barcode reader. The following diagram describes the message flow.

Message flow

Barcode read - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a BARCODE_READER (Enable) callback XML message to eSocket.POS.

  2. eSocket.POS enables the barcode reader.

  3. eSocket.POS sends the BARCODE_READ (Enable) callback response to the POS.

  4. PED sends the scanned barcode data to eSocket.POS.

  5. eSocket.POS raises the BARCODE_READ event.

  6. POS sends a BARCODE_READER (Disable) callback XML message to eSocket.POS.

  7. eSocket.POS disables the barcode reader.

  8. eSocket.POS sends the BARCODE_READ (Disable) callback response to the POS.

Note: When using multi-scan mode, multiple barcodes can be scanned until the barcode reader is disabled with the BARCODE_READER (Disable) callback.

After receiving a BARCODE_READ event with BarcodeStatusCode set to 2 - Timeout or 3 - Cancelled, even when in multi-scan mode, the barcode reader will be disabled.

Events and callbacks between the POS device and eSocket.POS

The events and callbacks listed here are typical to this scenario:

The BARCODE_READER callback is used to enable or disable the barcode reader.

The BARCODE_READ event is raised when a barcode is scanned.

XML mappings when reading barcodes

This section contains the XML properties and values that are typically associated with the barcode scanner. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

EventId

M

BARCODE_READER

EventData

M

Enable

Property Condition Value

TerminalId

M

SoftTerm

EventId

M

BARCODE_READER

EventData

M

Disable

See Event Properties for a full list of possible properties in these messages.

See Object and Property Conditions for an explanation of the Condition column in this table.

Example: XML messages to enable the barcode reader

The following are examples of enabling and disabling barcode scanning.

Enable barcode in multi-scan mode

This is an example of a successful request to enable the barcode reader. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the message flow diagram.

The POS sends a Callback XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="BARCODE_READER"
            EventData="Enable">
        </Esp:Callback>
    </Esp:Interface>

eSocket.POS responds with a Callback XML message [3] to the POS:

 <?xml version="1.0" encoding="UTF-8"?>
	<Esp:Interface
		Version="1.0"
		xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
		<Esp:Callback
			EventId="BARCODE_READER"
			ResponseData="scanMode:2;readerEnabled:true;OK"
			TerminalId="SoftTerm">
		</Esp:Callback>
	</Esp:Interface>

Disable barcode scan

The POS sends a Callback XML message [6] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="BARCODE_READER"
            EventData="Disable">
        </Esp:Callback>
    </Esp:Interface>

eSocket.POS responds with a Callback XML message [8] to the POS:

 <?xml version="1.0" encoding="UTF-8"?>
	<Esp:Interface
		Version="1.0"
		xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
		<Esp:Callback
			EventId="BARCODE_READER"
			ResponseData="readerEnabled:false;OK"
			TerminalId="SoftTerm">
		</Esp:Callback>
	</Esp:Interface>

3.11.3. Card Read Inquiry

Introduction

This retrieves the details of a card that is being read, as configured in eSocket.POS. The card can be read by a PED driven either by eSocket.POS or the POS. In the message flow outlined here, eSocket.POS drives the PED.

Message flow

EFT card read - successful

Refer to the diagram while stepping through the message flow that follows.

  1. The POS sends an INQUIRY (request) XML message to eSocket.POS.

  2. eSocket.POS sends a card read request to the PED.

  3. The PED sends a response, with data read from the card, to eSocket.POS.

  4. eSocket.POS sends the appropriate response, with card details, to the POS.

Note: No action is taken on the transaction (display transaction outcome, signature, and so on). eSocket.POS solely returns the card data back to the POS.
CardProductName is always retuned. Depending on the configuration, additional card details are also returned in an embedded EspCardInfo object within the response.

XML mappings in a transaction inquiry

This section contains the XML properties and values that are typically associated with a card read inquiry. In the Value column, example values are shown italics and mandatory values are shown in bold.

Property

Condition

Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

CARD_READ

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Inquiry Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a transaction inquiry

This is an example of a card read inquiry where eSocket.POS drives the PED. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the previous diagram.

The POS starts a card read inquiry with a CARD_READ (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            TerminalId="SoftTerm"
            TransactionId="195322"
            Type="CARD_READ">
        </Esp:Inquiry>
    </Esp:Interface>

If the card that is read by the PED is configured in eSocket.POS, then all the card-related data is populated in the CARD_READ (response) XML message [4] from eSocket.POS to the POS.

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            MessageReasonCode="9791"
            ResponseCode="00"
            TransactionId="195322"
            ActionCode="APPROVE">
            CardProductName="DefaultCard">
            TerminalId="term1">
            Track2="333333*********3339=2101">
            Type="CARD_READ">
            Type="TRAN_INQUIRY">
            <Esp:EspCardInfo CardProductName="DefaultCard">
                <Esp:EspAccount
                    DefaultPreauthAmountCtls="1000"
                    DefaultPreauthAmountEmv="1000"
                    DefaultPreauthAmountMsr="1000"
                    EmvFallbackAllowed="FALSE"
                    Name="Savings"
                    PinRequired="TRUE"
                    Type="10">
                </Esp:EspAccount>
                <Esp:EspAccount
                    DefaultPreauthAmountCtls="2000"
                    DefaultPreauthAmountEmv="2000"
                    DefaultPreauthAmountMsr="2000"
                    EmvFallbackAllowed="TRUE"
                    Name="Credit"
                    PinRequired="FALSE"
                    Type="30">
                </Esp:EspAccount>
                <Esp:Extracted
                    Name="MEMBERSHIPID"
                    Value="************">
                </Esp:Extracted>
            </Esp:EspCardInfo>
        </Esp:Inquiry>
    </Esp:Interface>

If the card that is read by the PED is not configured in eSocket.POS, then the resulting CARD_READ (response) XML message [4] from eSocket.POS to the POS will be a decline message and will not contain any card information.

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            MessageReasonCode="9751"
            ResponseCode="56"
            ActionCode="DECLINE">
            Track2="333333*********3339=2101">
            TransactionId="195322"
            TerminalId="term1">
            Type="CARD_READ">
        </Esp:Inquiry>
    </Esp:Interface>

3.11.4. Card verification inquiry

Introduction

To send the merchant’s intent to store the card details to a network (for example, VISA), a card verification inquiry is started at the POS and sent upstream using Postilion. This section discusses a successful card verification inquiry.

Message flow

Card Verification Inquiry

The message flow is as follows. View the flow together with the diagram.

  1. The POS sends a CARD_VERIFICATION (request) XML message to eSocket.POS.

  2. eSocket.POS sends an authorization request (0100) to Postilion.

  3. Postilion sends the authorization request (0100) upstream.

  4. Postilion receives an authorization request response (0110) from the entity upstream.

  5. Postilion sends the authorization request response (0110) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate authorization response (0110) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a card verification inquiry:

If registered, the following callbacks are called during a card verification inquiry:

XML mappings in a card verification inquiry

This section contains the XML properties and values that are typically associated with a card verification inquiry. In the Value column, italics is used to indicate example values. Bold is used to indicate mandatory values.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

CARD_VERIFICATION

RetrievalRefNr

O

000000000354

PosOperatorId

O

PosOp001

For information describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Inquiry Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a card verification inquiry

This is an example of a card verification inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram in the "Message flow" section of this page.

The POS starts a card verification inquiry with a CARD_VERIFICATION (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            CardNumber="333333*********3339"
            CardholderAddress="Cape Town"
            CurrencyCode="840"
            ExpiryDate="1912"
            PanEntryMode="90"
            PosCondition="08"
            PostalCode="7449"
            RetrievalRefNr="000000000072"
            TerminalId="SoftTerm"
            Track2="333333*********3339=1912"
            TransactionAmount="0"
            TransactionId="172128"
            Type="CARD_VERIFICATION">
        </Esp:Inquiry>
    </Esp:Interface>

The resulting CARD_VERIFICATION (response) XML message [6] from eSocket.POS following the successful completion of the card verification inquiry:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            Account="10"
            ActionCode="APPROVE"
            CardNumber="333333*********3339"
            CardProductName="DefaultCard"
            CurrencyCode="840"
            DateTime="0806061528"
            LocalDate="0806"
            LocalTime="081528"
            MerchantId="000000000000000"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="08"
            PosDataCode="51020125414C002"
            ResponseCode="00"
            TerminalId="SoftTerm"
            Track2="333333*********3339=1912"
            TransactionAmount="0"
            TransactionId="172128"
            Type="CARD_VERIFICATION"
            <Esp:StructuredData
                Name="RequestMerchantCategoryCode"
                Value="1234">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Inquiry>
    </Esp:Interface>

3.11.5. Check/Cheque verification

Introduction

When a check is presented as payment, a check verification message is used to verify the validity of the check or the account holder. After verifying and accepting the check, it must either be manually deposited at the bank to receive payment or processed as an Electronic Check Conversion (ECC) transaction, where the check is cancelled at the POS and the funds are processed through the ACH network. Below are examples of two kinds of check transactions started at the POS and sent upstream via Postilion for authorization.

  • A successful check verification transaction where the check is deposited manually.

  • A successful Electronic Check Conversion (ECC).

Message flow

Check Verification

Note: For the purposes of this example, a check guarantee (GAURANTEE) request is handled in the same way as a check verification (VERIFICATION) request. It is however handled differently upstream.

Check/Cheque verification transaction

Follow the message flow and refer to the diagram. . The POS sends a VERIFICATION (request) XML message to eSocket.POS with the final amount of the transaction. . eSocket.POS sends a purchase request (0200) to Postilion. . Postilion sends the purchase request (0200) upstream. . Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction. . Postilion sends the purchase response (0210) to eSocket.POS. . eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate purchase response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Electronic Check Conversion

Note: For the purposes of this example, an electronic check guarantee (ECCGAURANTEE) and electronic check autorization (ECC) request is handled in the same way as an electronic check verification (ECCVERIFY) request. It is however handled differently upstream.

Check/Cheque verification transaction

Follow the message flow and refer to the diagram. . The POS sends an ECCVERIFY (request) XML message to eSocket.POS with the final amount of the transaction. . eSocket.POS sends an authorization request (0100) to Postilion. . Postilion sends the authorization request (0100) upstream. . Postilion receives an authorization response (0110) back from the entity upstream responsible for authorizing the transaction. . Postilion sends the authorization response (0110) to eSocket.POS. . eSocket.POS sends the appropriate response to the POS device. . The POS sends an ECCVERIFY (request) XML message with a MessageType CONFIRM to eSocket.POS. . eSocket.POS sends the appropriate response to the POS device. . eSocket.POS sends a confirmation request (0220) to Postilion. . Postilion sends the confirmation response (0230) to eSocket.POS. . Postilion sends the confirmation request (0220) upstream. . Postilion receives a confirmation response (0230) back from the entity upstream responsible for confirm]ing the transaction.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a check verification transaction:

If registered, the following callbacks are called during a check verification transaction:

XML mappings in a check verification transaction

This section contains the XML properties and values that are typically associated with a check verification transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

146691

Type

M

VERIFICATION

MessageType

O

TRANREQ

RetrievalRefNr

O

000000000083

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Check Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages

Check Verification

This is an example of a check verification transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a transaction with a VERIFICATION (request) XML message [1] to eSocket.POS:

   <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Check
            MessageType="TRANREQ"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="146691"
            Type="VERIFICATION">
        </Esp:Check>
    </Esp:Interface>

The resulting VERIFICATION (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

   <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Check
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CurrencyCode="710"
            DateTime="0927115132"
            ExpiryDate="2012"
            LocalDate="0927"
            LocalTime="135132"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            ResponseCode="00"
            RetrievalRefNr="000000000082"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="146691"
            Type="VERIFICATION">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Check>
    </Esp:Interface>

Electronic Check Conversion

This is an example of a electronic check verification transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS sends an authorization transaction with a ECCVERIFY (request) XML message [1] to eSocket.POS:

   <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Check
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="146691"
            Type="ECCVERIFY">
        </Esp:Check>
    </Esp:Interface>

The resulting ECCVERIFY (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

   <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Check
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CurrencyCode="710"
            DateTime="0927115132"
            ExpiryDate="2012"
            ExtendedTransactionType="7112"
            LocalDate="0927"
            LocalTime="135132"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            ResponseCode="00"
            RetrievalRefNr="000000000082"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="146691"
            Type="ECCVERIFY">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Check>
    </Esp:Interface>

The POS sends an completion transaction with a ECCVERIFY (request) XML message with MessageType:CONFIRM [7] to eSocket.POS:

   <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Check
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="146691"
            Type="ECCVERIFY">
            MessageType="CONFIRM">
        </Esp:Check>
    </Esp:Interface>

The resulting ECCVERIFY (response) XML message [8] from eSocket.POS following the successful completion of the transaction:

   <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Check
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CurrencyCode="710"
            DateTime="0927115132"
            ExpiryDate="2012"
            ExtendedTransactionType="7112"
            LocalDate="0927"
            LocalTime="135132"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            ResponseCode="00"
            RetrievalRefNr="000000000082"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="146691"
            Type="ECCVERIFY">
            MessageType="CONFIRM">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Check>
    </Esp:Interface>

3.11.6. Credit adjustment

Introduction

When a credit adjustment is made from the POS, a credit adjustment transaction is sent upstream for authorization. The credit adjustment transaction credits the amount to the account.

Message flow

Credit adjustment

Follow the message flow and refer to the diagram.

  1. The POS sends a CREDIT_ADJUSTMENT (request) XML message to eSocket.POS with the amount.

  2. eSocket.POS sends a credit adjustment request (0200) to Postilion.

  3. Postilion sends the credit adjustment request (0200) upstream.

  4. Postilion receives a credit adjustment response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the credit adjustment response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate credit adjustment response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a credit adjustment transaction:

If registered, the following callbacks are called during a credit adjustment transaction:

XML mappings in a credit adjustment transaction

This section contains the XML properties and values that are typically associated with a credit adjustment transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

135265

Type

M

CREDIT_ADJUSTMENT

TransactionAmount

G

30000

CurrencyCode

O

710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Example: XML messages in a credit adjustment transaction

This is an example of a credit adjustment transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a credit adjustment with a CREDIT_ADJUSTMENT (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="135265"
            Type="CREDIT_ADJUSTMENT">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CREDIT_ADJUSTMENT (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="1025"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="1026070745"
            ExpiryDate="2012"
            LocalDate="1026"
            LocalTime="090745"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000009"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="135265"
            Type="CREDIT_ADJUSTMENT">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
								
								
	  
	  
	  
	  
	  
				   
																			  
						  
					 
					   
									
	  
					   
																																								  
	  
					   
									
	  
					   
																							  
	  
					   
																																							  
	  
				   
	
	
																			
	 
	
																		  
	 
	
																	 
	 
	
																							 
	 
	
																			
	 
	
																  
	 
	 
	  
					   
																																									   
	  
					   
																																																					 
	  
					   
																				   
	  
					   
																																							   
	  
					   
																						   
	  
				   
	
	
																				 
	 
	
																		   
	 
	 
	  
					   
																							  
	  
				   
	
	
										 
	 
	
																					
	 
	 
	  
					   
																	 
	  
					   
																																			
	  
													 
		  
						 
						 
						
						
						
		   
	   
	
																			
																			   
																			 
																		   
																			
	 
		
	   
	
																												 
																																						   
																			  
																				
																				
	 
	
																																		  
																																																					 
																			  
																				
																				
	 
	
																																	   
																																								 
																			  
																				
																				
	 
	
																																					 
																																		
																			  
																				
																				
	 
	
																													   
																																			  
																			  
																				
																				
	 
	
																														  
																																			   
																			  
																			   
																				
	 
	
																													  
																																			 
																			  
																			   
																				
	 
		
		
					   
																																		 
	  
					   
																															   
	  
					   
																																								
	  
					   
																			  
	  
					   
																																																			 
	  
					   
																													  
	  
					   
																																			 
	  
						  
					 
												  
																										
					   
										  
								 
								  
								  
									   
																  
																	  
																  
															   
								 
														 
														   
												 
											   
											
												  
									
										
									 
									   
													  
												  
													
										 
												   
								   
							   
										  
									
									
							
								
	  
	  
					   
																																														
	  
						  
					 
												  
																										
					   
								
										  
									
							 
								 
								  
							  
									  
									  
								   
							   
									  
														  
									
									
							
								
	  
	  
					   
																			   
	  
					   
																																				  
	  
													 
		  
						 
						 
						
						
						
		   
	   
	
																			
																			   
																			 
																		   
																			
	 
		
	   
	
																												 
																																				   
																			  
																				
																				
	 
	
																																		  
																																																			 
																			  
																				
																				
	 
	
																																					 
																																																																																																																																					 
																			  
																				
																				
	 
	
																											 
																																																	   
																			  
																				
																				
	 
	
																													   
																																			  
																			  
																				
																				
	 
	
																														  
																																			   
																			  
																			   
																				
	 
	
																													  
																																			 
																			  
																			   
																				
	 
		
		
					   
																																		 
	  
					   
																															   
	  
					   
																																								
	  
					   
																						
	  
					   
																																																				   
	  
					   
																													  
	  
					   
																																				   
	  
						  
					 
												  
																										
					   
										  
								 
								  
								  
								  
										
																																																																	   
									   
												  
									
													 
										 
												   
							
								
	  
	  
					   
																																																					  
	  
						  
					 
												  
																										
					   
								
										  
									
							 
								 
								  
							  
									  
									  
								   
							   
									  
														  
									
									
							
								
	  
	  
	  
	  
	  
				   
																						
						  
					 
					   
									
	  
					   
																																										   
	  
					   
									
	  
					   
																								  
	  
					   
																																								  
	  
				   
	
	
																	  
	 
	
																		   
	 
	
																	  
	 
	
																							  
	 
	
																			 
	 
	
																  
	 
	 
	  
					   
																																										
	  
					   
																																																					 
	  
					   
																				   
	  
					   
																																							   
	  
					   
																						   
	  
				   
	
	
																				 
	 
	
																		   
	 
	 
	  
					   
																							  
	  
				   
	
	
										 
	 
	
																					
	 
	 
	  
					   
																		  
	  
					   
																																				
	  
													 
		  
						 
						 
						
						
						
		   
	   
	
																			
																			   
																			 
																		   
																			
	 
		
	   
	
																													 
																																			 
																			  
																				
																				
	 
	
																													
																																		 
																			  
																				
																				
	 
	
																																		  
																																																			 
																			  
																				
																				
	 
	
																																	   
																																								
																			  
																				
																				
	 
	
																																					 
																																		
																			  
																				
																				
	 
	
																													   
																																			  
																			  
																				
																				
	 
	
																														  
																																			   
																			  
																			   
																				
	 
	
																													  
																																			 
																			  
																			   
																				
	 
		
		
					   
																																		 
	  
					   
																																	   
	  
					   
																																								
	  
					   
																				   
	  
					   
																																																				 
	  
					   
																													  
	  
					   
																																		   
	  
						  
					 
												  
																										
						   
										  
								 
								  
						
										   
									   
																  
																	  
																  
															   
								 
														 
														   
												 
											   
											
												  
									
										
									 
									   
													  
												  
													
										 
												   
								   
						   
									  
									
									
								
								
	  
	  
					   
																																													   
	  
						  
					 
												  
																										
						   
								
										  
									
							 
								 
								  
						
									   
									  
									  
								   
							   
									  
														  
									
									
								
								
	  
	  
					   
																			   
	  
					   
																																				  
	  
													 
		  
						 
						 
						
						
						
		   
	   
	
																			
																			   
																			 
																		   
																			
	 
		
	   
	
																													 
																																					 
																			  
																				
																				
	 
	
																													
																																				
																			  
																				
																				
	 
	
																																		  
																																																					 
																			  
																				
																				
	 
	
																																	   
																																																																																																					  
																			  
																				
																				
	 
	
																																					 
																																																																																																																																																																														
																			  
																				
																				
	 
	
																											 
																																																									  
																			  
																				
																				
	 
	
																										  
																																														 
																			  
																				
																				
	 
	
																													   
																																			  
																			  
																				
																				
	 
	
																														  
																																			   
																			  
																			   
																				
	 
	
																													  
																																			 
																			  
																			   
																				
	 
		
		
					   
																																		 
	  
					   
																																	   
	  
					   
																																								
	  
					   
																									
	  
					   
																																																				   
	  
					   
																													  
	  
					   
																																			 
	  
						  
					 
												  
																										
						   
										  
								 
								  
						
										   
								  
										
																																																																	   
									   
								  
									 
									   
									   
									   
																  
																	  
																  
															   
								 
														 
														   
												 
											   
											
												  
									
													   
													 
												 
											 
										 
												   
								   
							   
										  
									
									
        </Esp:Transaction>
    </Esp:Interface>

3.11.7. Debit adjustment

Introduction

For transactions that are not defined by eSocket.POS, and where a debit is required, a debit adjustment can be used to initiate an adjustment to a cardholders account. An example of this is the scenario where a cheque/check is used for a deposit to a cardholder’s account, but the check is returned unpaid. The deposited funds are reversed with a debit adjustment transaction.

Message flow

Debit adjustment

Follow the message flow and refer to the diagram.

  1. The POS sends a DEBIT_ADJUSTMENT (request) XML message to eSocket.POS with the card details.

  2. eSocket.POS sends a debit adjustment request (0200) to Postilion.

  3. Postilion sends the debit adjustment request (0200) upstream.

  4. Postilion receives a debit adjustment request response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the debit adjustment request response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate debit adjustment request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a debit adjustment transaction:

If registered, the following callbacks are called during a debit adjustment transaction:

XML mappings in a debit adjustment transaction

This section contains the XML properties and values that are typically associated with debit adjustment transactions. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

159937

Type

M

DEBIT_ADJUSTMENT

RetrievalRefNr

O

000000000085

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a debit adjustment transaction

This is an example of a debit adjustment request transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a debit adjustment transaction with a DEBIT_ADJUSTMENT (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="159937"
            Type="DEBIT_ADJUSTMENT">
        </Esp:Transaction>
    </Esp:Interface>

The resulting DEBIT_ADJUSTMENT (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="1024062600"
            ExpiryDate="2012"
            LocalDate="1024"
            LocalTime="082600"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000085"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="159937"
            Type="DEBIT_ADJUSTMENT">
            <Esp:Balance
                AccountType="00"
                Amount="30000"
                AmountType="53"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11.8. Deposit

Introduction

When a deposit is made into an account from the POS, a deposit transaction is sent upstream for authorization. The deposit transaction debits the amount to the account.

Message flow

Deposit

Follow the message flow and refer to the diagram.

  1. The POS sends a DEPOSIT (request) XML message to eSocket.POS with the amount.

  2. eSocket.POS sends a deposit request (0200) to Postilion.

  3. Postilion sends the deposit request (0200) upstream.

  4. Postilion receives a deposit request response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the deposit request response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate deposit request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a deposit transaction:

If registered, the following callbacks are called during a deposit transaction:

XML mappings in a deposit transaction

This section contains the XML properties and values that are typically associated with a deposit transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

170809

Type

M

DEPOSIT

TransactionAmount

G

30000

CurrencyCode

O

710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Example: XML messages in a deposit transaction

This is an example of a deposit transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a deposit with a DEPOSIT (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170808"
            Type="DEPOSIT">
        </Esp:Transaction>
    </Esp:Interface>

The resulting DEPOSIT (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0829200729"
            ExpiryDate="2012"
            LocalDate="0829"
            LocalTime="220729"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000101"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170808"
            Type="DEPOSIT">
        </Esp:Transaction>
    </Esp:Interface>

3.11.9. Line item display

Introduction

The line item display is used to display certain data on the PIN entry device (PED). The following two options are available:

  • The individual items purchased as they are scanned at the point of sale (POS).

  • The result of a transaction that was processed by the POS such as a Purchase Transaction.

Here are examples of the successful display of the 2 types of line item details on the PED.

Scanned item details

Message flow

Line Item Display - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a LINE_ITEM_DISPLAY (start) callback XML message to eSocket.POS.

  2. eSocket.POS puts the PED in line item display mode.

  3. eSocket.POS sends a PRE_SWIPE (enable) event to eSocket.POS if the scanAhead parameter is set to ON.

  4. eSocket.POS sends the display configuration back to the POS.

  5. The POS sends a LINE_ITEM_DISPLAY (first scanned item details) callback XML message to eSocket.POS.

  6. eSocket.POS displays the line item details on the PED.

  7. The POS sends a LINE_ITEM_DISPLAY (second scanned item details) callback XML message to eSocket.POS.

  8. eSocket.POS displays the line item details on the PED.

  9. The POS sends a LINE_ITEM_DISPLAY (end) callback XML message to eSocket.POS.

  10. eSocket.POS removes the PED from line item display mode.

  11. eSocket.POS sends a PRE_SWIPE (stop_listen) event to eSocket.POS.

Transaction results

Message flow

Line Item Display - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a LINE_ITEM_DISPLAY (start) callback XML message to eSocket.POS.

  2. eSocket.POS puts the PED in line item display mode.

  3. eSocket.POS sends the display configuration back to the POS.

  4. The POS sends a LINE_ITEM_DISPLAY (transaction results) callback XML message to eSocket.POS.

  5. eSocket.POS displays the transaction results on the PED.

  6. The POS sends a LINE_ITEM_DISPLAY (end) callback XML message to eSocket.POS.

  7. eSocket.POS removes the PED from line item display mode.

Events and callbacks between the POS device and eSocket.POS

The events and callbacks listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a line item display:

If registered, the following callbacks are called during a line item display:

XML mappings in a line item display

This section contains the XML properties and values that are typically associated with a line item display. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

EventId

M

LINE_ITEM_DISPLAY

EventData

M

1. lineItemDisplay:start
2. lineItemDisplay:itemDetail ; additionalInfoItem1 : <value> ; additionalInfoItem2 : <value> ; additionalInfoItem3 : <value> ; additionalInfoItem4 : <value> ; formattedItemDisplayLine : "<item details line 1> " " <item details line 2>" "<subtotal>"
3. lineItemDisplay:itemDetail ; itemNum : <value> ; quantity : <value> ; unitPrice : <value> ; lineTotal : <value> ; voided : <value> ; itemDescription : <value> ; subtotal : <value> ; additionalInfoItem1 : <value> ; additionalInfoItem2 : <value> ; additionalInfoItem3 : <value> ; additionalInfoItem4 : <value> ;
4. lineItemDisplay:tranResult ; formattedItemDisplayLine : "<transaction results> "
5. lineItemDisplay:end

Note: The additionalInfoItems are optional.

For a full list of possible properties in these messages, see Event Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a line item display

Here are examples of the two possible line item display. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

Scanned line items

The POS starts a line item display with a LINE_ITEM_DISPLAY (start) callback XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="LINE_ITEM_DISPLAY"
            EventData="lineItemDisplay : start; scanAhead : on; scanAheadMessage : Please Swipe Card;">
        </Esp:Callback>
    </Esp:Interface>

The POS sends a LINE_ITEM_DISPLAY (first scanned item details) callback XML message [5] to eSocket.POS: This message can have the EventData in two different formats:

Format 1:

   <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="LINE_ITEM_DISPLAY"
            EventData='lineItemDisplay : itemDetail; formattedItemDisplayLine :"itemNum : 1 ; quantity : 1 ; unitPrice : 10.21 ; lineTotal : 10.21 ; "  " voided : True ; itemDescription : Item 1 ;" "34.32" '>
        </Esp:Callback>
    </Esp:Interface>

Format 2:

   <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="LINE_ITEM_DISPLAY"
            EventData="lineItemDisplay : itemDetail; itemNum : 1 ; quantity : 1 ; unitPrice : 10.21 ; lineTotal : 10.21 ; voided : True ; itemDescription : Item 1 ; subtotal : 34.32 ;">
        </Esp:Callback>
    </Esp:Interface>

The POS completed a line item display with a LINE_ITEM_DISPLAY (end) callback XML message [9] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="LINE_ITEM_DISPLAY"
            EventData="lineItemDisplay : end;">
        </Esp:Callback>
    </Esp:Interface>

Transaction Results

The POS starts a line item display with a LINE_ITEM_DISPLAY (start) callback XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="LINE_ITEM_DISPLAY"
            EventData="lineItemDisplay : start; ">
        </Esp:Callback>
    </Esp:Interface>

The POS sends a LINE_ITEM_DISPLAY (transaction result) callback XML message [4] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="LINE_ITEM_DISPLAY"
            EventData='lineItemDisplay : tranResult; formattedItemDisplayLine :"The card authorization was successful" '>
        </Esp:Callback>
    </Esp:Interface>

The POS completed a line item display with a LINE_ITEM_DISPLAY (end) callback XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="LINE_ITEM_DISPLAY"
            EventData="lineItemDisplay : end;">
        </Esp:Callback>
    </Esp:Interface>

3.11.10. Pay At Table initialization

Introduction

The Pay At Table initialization is used to initialize a transaction from the PIN entry device (PED). The example below describes the message flow.

Message flow

Pay At Table init - successful

Follow the message flow and refer to the diagram.

  1. eSocket.POS displays the Pay At Table start screen.

  2. The start button is pressed on the PED.

  3. eSocket.POS sends a card swipe request for the employee ID.

  4. PED sends the employee card data to eSocket.POS.

  5. eSocket.POS sends a PAY_AT_TABLE_INIT callback XML message to the POS.

  6. The Pos sends a response for the PAY_AT_TABLE_INIT callback message to eSocket.POS

  7. eSocket.POS displays the Pay At Table result on the PED.

Events and callbacks between the POS device and eSocket.POS

The events and callbacks listed here are a sub-set of the total list possible and are typical to this scenario.

The PAY_AT_TABLE_INIT callback is used to send the employee ID to the POS for processing.

XML mappings in a Pay At Table initialization

This section contains the XML properties and values that are typically associated with a Pay At Table initialization. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

EventId

M

PAY_AT_TABLE_INIT

EventData

M

CashierID=12345678

For a full list of possible properties in these messages, see Event Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML message in a Pay At Table initialization

Pay At Table initialization

The eSocket.POS starts a Pay At Table initialization with a PAY_AT_TABLE_INIT callback XML message to the POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="PAY_AT_TABLE_INIT"
            EventData="cashierID=123456789">
        </Esp:Callback>
    </Esp:Interface>

The POS sends a PAY_AT_TABLE_INIT callback XML message response to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="SoftTerm"
            EventId="PAY_AT_TABLE_INIT"
            ResponseData='Success=0;ResponseText=Cashier ID valid'>
        </Esp:Callback>
    </Esp:Interface>

3.11.11. Pre-swipe

Introduction

The card pre-swipe is used to obtain card data while store items are still being processed, before the POS enters tender mode. This is an example of a successful pre-swipe.

Message flow

Pre-swipe - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a PRE_SWIPE (enable) event XML message to eSocket.POS.

  2. eSocket.POS sends a PROMPT_READY_FOR_SWIPE event XML message to the POS for magstripe pre-swipe environments. For enviroments that support EMV pre-swipe/pre-reads, eSocket.POS sends a PROMPT_READY_FOR_CARD_READ event.

  3. After successfully obtaining the card data, eSocket.POS sends a CARD_READ event XML message to the POS.

Events and callbacks between the POS device and eSocket.POS

The events and callbacks listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are raised during a pre-swipe:

If registered, the following callbacks are called during a pre-swipe:

XML mappings in a pre-swipe

This section contains the XML properties and values that are typically associated with a pre-swipe. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

EventId

M

PRE_SWIPE

EventData

O

Enable

For a full list of possible properties in these messages, see Event Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a pre-swipe

This is an example of a pre-swipe. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a pre-swipe with a PRE_SWIPE (Enable) event XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Event
            TerminalId="SoftTerm"
            EventId="PRE_SWIPE"
            EventData="Enable">
        </Esp:Event>
    </Esp:Interface>

The PROMPT_READY_FOR_SWIPE event XML message [2] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Event
            TerminalId="SoftTerm"
            EventId="PROMPT_READY_FOR_SWIPE"
            EventData="">
        </Esp:Event>
    </Esp:Interface>

The resulting CARD_READ event XML message [3] from eSocket.POS following a successful read of the card data:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Event
            TerminalId="SoftTerm"
            EventId="CARD_READ"
            EventData="PanEntryMode='90'">
        </Esp:Event>
    </Esp:Interface>

3.11.12. Prompt request

Introduction

This example describes the typical flow resulting from a set of prompts being sent by the point of sale (POS) to eSocket.POS. eSocket.POS processes these prompts and sends them, one prompt request at a time, to the PIN-entry device (PED). When it has received all the prompt responses from the PED, it populates the message with the retrieved data, and sends it upstream for further processing.

Message flow

Prompt Request- successful

Follow the message flow and refer to the diagram.

  1. The POS sends an ADMIN request to eSocket.POS which contains a Prompts XML string.

  2. eSocket.POS then generates an administrative request (0600 message) with an Extended Transaction Type field set to '4300' (Customer Prompt), populating its StructuredData field with the Prompts XML. eSocket.POS sends the first prompt request to the PED.

  3. The PED sends back the prompt response.

    The process of eSocket.POS sending a prompt request and receiving the response from the PED repeats for items 4-7. The Value attribute of each Prompt element is populated with the prompt response.

  4. eSocket.POS sends the 0600 message, which contains the prompts results in the Prompts XML, upstream. Depending on how the Prompts pipeline component is configured, the 0600 message is not sent upstream by default.

  5. eSocket.POS expects an administrative response (0610 message) to be sent by the upstream entity.

  6. eSocket.POS converts the 0610 message into an ADMIN response which it then sends to the POS.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following event is called during a Prompt request:

XML mappings in a single message prompt request

This section contains the XML properties and values that are typically associated with a Prompt request. In the Value column, example values are in italics and mandatory values are in bold.

  1. Prompt request

    Property Condition Value

    ExtendedTransactionType

    M

    2121

    StructuredData: Prompts

    M

    XML String

  2. Prompt response

    Property Condition Value

    ExtendedTransactionType

    M

    2121

    StructuredData: Prompts

    M

    XML String

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties and Callback Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a Prompt request

This is an example of a Prompt request. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts the Prompt transaction with an ADMIN (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
					 
					 
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction ExtendedTransactionType="2121" MessageType="ADMIN_REQUEST" Type="ADMIN">
										  
            <Esp:StructuredData
                Name="Prompts"
                Value="&lt;?xml version=&quot;1.0&quot;?&gt;&lt;Prompts&gt;&lt;Prompt Id=&quot;1&quot; Name=&quot;PromptDlNumber&quot;&gt;&lt;/Prompt&gt;&lt;Prompt Id=&quot;2&quot; Name=&quot;PromptDlState&quot;&gt;&lt;/Prompt&gt;&lt;Prompt Id=&quot;3&quot; Name=&quot;PromptSsn&quot;&gt;&lt;/Prompt&gt;&lt;/Prompts&gt;">
            </Esp:StructuredData>
							
										   
        </Esp:Transaction>
    </Esp:Interface>

The resulting ADMIN (response) XML message [10] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
					 
					 
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction ExtendedTransactionType="2121" MessageType="ADMIN_REQUEST" ResponseCode="00" Type="ADMIN">
										  
            <Esp:StructuredData
                Name="Prompts"
                Value="&lt;?xml version=&quot;1.0&quot;?&gt;&lt;Prompts&gt;&lt;Prompt Id=&quot;1&quot; Name=&quot;PromptDlNumber&quot; Value=&quot;1234567&quot;&gt;&lt;/Prompt&gt;&lt;Prompt Id=&quot;2&quot; Name=&quot;PromptDlState&quot; Value=&quot;CA&quot;&gt;&lt;/Prompt&gt;&lt;Prompt Id=&quot;3&quot; Name=&quot;PromptSsn&quot; Value=&quot;98765432&quot;&gt;&lt;/Prompt&gt;&lt;/Prompts&gt;">
											
												 
            </Esp:StructuredData>
							
										   
        </Esp:Transaction>
    </Esp:Interface>

3.11.13. Purchase with DCC using explicit rate requests

Introduction

In the case where a purchase transaction is eligible for dynamic currency conversion (DCC) , an administration request (i.e. the explicit rate request) is sent before the authorization to retrieve the DCC offer. The message flow here is an example of a DCC offer that is available and accepted by the cardholder on a successful transaction.

Message flow

Purchase with DCC using explicit rate requests

Follow the message flow (dual message pair) and refer to the diagram.

  1. The POS sends a PURCHASE AUTH (request) to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS converts the PURCHASE AUTH (request) into an authorization request (0100) and determines that DCC is allowed on transaction (see the DCC pipeline component in the eSocket.POS User Guide for more details). eSocket.POS sends an explicit rate request (0600) to Postilion.

  3. Postilion sends a DCC rate request to the DCC provider.

  4. Postilion receives a DCC rate response containing a DCC offer from the DCC provider.

  5. Postilion sends an explicit rate response (0610) containing a DCC offer to eSocket.POS.

  6. eSocket.POS displays the DCC offer to the cardholder on the PED.

  7. The cardholder accepts the offer.

  8. eSocket.POS updates the following DCC-related fields in the authorization request (0100) before sending it to Postilion:

    • The DCC Status Code (ISO 8583 field 127.48) is updated to reflect the cardholder decision, the host decision and the terminal configuration.

    • The Transaction Amount (field 4) and Transaction Currency Code (field 49) are updated to reflect the cardholder/foreign amount and currency.

    • The DCC Reference Number (field 127.22.CurrencyConvInfo.DccReferenceNumber) is set to the corresponding value received in the explicit rate response (0110) [5].

  9. Postilion sends the authorization request (0100) upstream.

  10. Postilion receives an authorization response (0110) from the entity upstream responsible for authorizing the transaction.

  11. Postilion sends the authorization response (0110) to eSocket.POS.

  12. eSocket.POS converts this authorization response (0110) into a PURCHASE AUTH (response) and sends it to the POS. The PURCHASE AUTH (response) contains the DCC information, most of which will be included on the printed receipt.

  13. The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.

  14. eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.

  15. eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.

  16. Postilion receives the transaction advice request (0220) and sends a transaction advice response (0230) to eSocket.POS.

  17. Postilion sends the transaction advice request (0220) upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.

  18. Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.

Notes :

  • If the single message pair flow is used for DCC, the message types in steps 1 and 12 are PURCHASE (request) and PURCHASE (response). The message types in steps 8 to 12 are 0200 and 0210, and steps 13 to 18 are absent.

  • If Postilion is the card issuer, the appropriate authorization response (0110) and transaction advice response (0230) is sent from Postilion, and steps 9, 10, 17, and 18 are eliminated. If the PURCHASE AUTH (response) in step 12 is not an approval, the transaction will cease after step 12.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a DCC purchase transaction:

If registered, the following callbacks are called during a DCC purchase transaction:

XML mappings in a DCC purchase transaction

This section contains the XML properties and values that are typically associated with a DCC purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase authorization request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    AUTH

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Purchase confirmation request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    CONFIRM

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    2500

    CurrencyCode

    O

    840

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in these tables, see Object and Property Conditions .

Example: XML messages in a DCC purchase transaction

This is an example of a DCC purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a DCC purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            MessageType="AUTH"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE AUTH (response) XML message [11] from eSocket.POS following the successful completion of the authorization:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="840"
            DateTime="0906065846"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            MessageType="AUTH"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000084"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="2200"
            TransactionId="114726"
            Type="PURCHASE"
            DccStatusCode="YYY"
            DccProviderRoutingId="12345"
            DccAcqId="00000000001"
            DccCardAccptrId="000000000000002"
            DccTermId="00000003"
            DccRate="0.766666"
            DccSrcCurrCode="710"
            DccSrcCurrAlphaCode="ZAR"
            DccSrcCurrMinorUnits="2"
            DccTgtCurrCode="840"
            DccTgtCurrAlphaCode="USD"
            DccTgtCurrMinorUnits="2"
            DccProvider="FEXCO"
            DccRateSrc="REUTERS INTERBANK RATE"
            DccTimestamp="20170426T15:35"
            DccMargRate="0.03"
            DccDiffOverECB="0.001"
            DccIsEEA="Y"
            DccCommRate="0.01"
            DccSrcAmt="30000"
            DccTgtAmt="2200"
            DccExpTimestamp="20170429T15:35"
            DccRcptTxt1="I recognise I was given the choice of payment currencies. I accept the exchange rate. My decision to pay in my currency is final.">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS sends a PURCHASE CONFIRM (request) XML message [12] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            CurrencyCode="840"
            MessageType="CONFIRM"
            TerminalId="TestTerm"
            TransactionAmount="2200"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE CONFIRM (response) XML message [13] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="840"
            DateTime="0906065853"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            MessageType="CONFIRM"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="2200"
            TransactionId="114726"
            Type="PURCHASE"
            DccStatusCode="YYY"
            DccProviderRoutingId="12345"
            DccAcqId="00000000001"
            DccCardAccptrId="000000000000002"
            DccTermId="00000003"
            DccRate="0.766666"
            DccSrcCurrCode="710"
            DccSrcCurrAlphaCode="ZAR"
            DccSrcCurrMinorUnits="2"
            DccTgtCurrCode="840"
            DccTgtCurrAlphaCode="USD"
            DccTgtCurrMinorUnits="2"
            DccProvider="FEXCO"
            DccRateSrc="REUTERS INTERBANK RATE"
            DccTimestamp="20170426T15:35"
            DccMargRate="0.03"
            DccDiffOverECB="0.001"
            DccIsEEA="Y"
            DccCommRate="0.01"
            DccSrcAmt="30000"
            DccTgtAmt="2200"
            DccExpTimestamp="20170429T15:35"
            DccRcptTxt1="I recognise I was given the choice of payment currencies. I accept the exchange rate. My decision to pay in my currency is final.">
        </Esp:Transaction>
    </Esp:Interface>

3.11.14. Purchase with DCC using implicit rate requests

Introduction

In the case where a purchase transaction is eligible for implicit dynamic currency conversion (DCC), the authorization request will serve as an implicit DCC rate request. The message flow here is an example of an implicit DCC offer that is available and accepted by the cardholder.

Message flow

Purchase with DCC using implicit rate requests

Follow the message flow (dual message pair) and refer to the diagram.

  1. The POS sends a PURCHASE AUTH (request) to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS converts the PURCHASE AUTH (request) into an authorization request (0100) and determines that implicit DCC is allowed on transaction (see the DCC pipeline component in the eSocket.POS User Guide for more details). eSocket.POS sends an implicit rate request (0100) to Postilion.

  3. Postilion sends a DCC rate request to the DCC provider.

  4. Postilion receives a DCC rate response containing a DCC offer from the DCC provider.

  5. Postilion sends an implicit rate response (0110) containing a DCC offer to eSocket.POS.

  6. eSocket.POS displays the DCC offer to the cardholder on the PED.

  7. The cardholder accepts the offer.

  8. eSocket.POS updates the following DCC-related fields in the authorization request (0100) before sending it to Postilion:

    • The DCC Status Code (ISO 8583 field 127.48) is updated to reflect the cardholder decision, the host decision and the terminal configuration.

    • The Transaction Amount (field 4) and Transaction Currency Code (field 49) are updated to reflect the cardholder/foreign amount and currency.

    • The DCC Reference Number (field 127.22.CurrencyConvInfo.DccReferenceNumber) is set to the corresponding value received in the implicit rate response (0610) [5].

  9. Postilion sends the authorization request (0100) upstream.

  10. Postilion receives an authorization response (0110) from the entity upstream responsible for authorizing the transaction.

  11. Postilion sends the authorization response (0110) to eSocket.POS.

  12. eSocket.POS converts this authorization response (0110) into a PURCHASE AUTH (response) and sends it to the POS. The PURCHASE AUTH (response) contains the DCC information, most of which will be included on the printed receipt.

  13. The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.

  14. eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.

  15. eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.

  16. Postilion receives the transaction advice request (0220) and sends a transaction advice response (0230) to eSocket.POS.

  17. Postilion sends the transaction advice request (0220) upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.

  18. Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.

Notes :

  • If the single message pair flow is used for DCC, the message types in steps 1 and 12 are PURCHASE (request) and PURCHASE (response). The message types in steps 8 to 12 are 0200 and 0210, and steps 13 to 18 are absent.

  • If Postilion is the card issuer, the appropriate authorization response (0110) and transaction advice response (0230) is sent from Postilion, and steps 9, 10, 17, and 18 are eliminated. If the PURCHASE AUTH (response) in step 12 is not an approval, the transaction will cease after step 12.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a DCC purchase transaction:

If registered, the following callbacks are called during a DCC purchase transaction:

XML mappings in a DCC purchase transaction

This section contains the XML properties and values that are typically associated with a DCC purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase authorization request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    AUTH

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Purchase confirmation request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    CONFIRM

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    2500

    CurrencyCode

    O

    840

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in these tables, see Object and Property Conditions .

Example: XML messages in a DCC purchase transaction

This is an example of a DCC purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a DCC purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            MessageType="AUTH"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE AUTH (response) XML message [11] from eSocket.POS following the successful completion of the authorization:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="840"
            DateTime="0906065846"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            MessageType="AUTH"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000084"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="2200"
            TransactionId="114726"
            Type="PURCHASE"
            DccStatusCode="YYY"
            DccProviderRoutingId="12345"
            DccAcqId="00000000001"
            DccCardAccptrId="000000000000002"
            DccTermId="00000003"
            DccRate="0.766666"
            DccSrcCurrCode="710"
            DccSrcCurrAlphaCode="ZAR"
            DccSrcCurrMinorUnits="2"
            DccTgtCurrCode="840"
            DccTgtCurrAlphaCode="USD"
            DccTgtCurrMinorUnits="2"
            DccProvider="FEXCO"
            DccRateSrc="REUTERS INTERBANK RATE"
            DccTimestamp="20170426T15:35"
            DccMargRate="0.03"
            DccDiffOverECB="0.001"
            DccIsEEA="Y"
            DccCommRate="0.01"
            DccSrcAmt="30000"
            DccTgtAmt="2200"
            DccExpTimestamp="20170429T15:35"
            DccRcptTxt1="I recognise I was given the choice of payment currencies. I accept the exchange rate. My decision to pay in my currency is final.">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS sends a PURCHASE CONFIRM (request) XML message [12] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            CurrencyCode="840"
            MessageType="CONFIRM"
            TerminalId="TestTerm"
            TransactionAmount="2200"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE CONFIRM (response) XML message [13] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="840"
            DateTime="0906065853"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            MessageType="CONFIRM"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="2200"
            TransactionId="114726"
            Type="PURCHASE"
            DccStatusCode="YYY"
            DccProviderRoutingId="12345"
            DccAcqId="00000000001"
            DccCardAccptrId="000000000000002"
            DccTermId="00000003"
            DccRate="0.766666"
            DccSrcCurrCode="710"
            DccSrcCurrAlphaCode="ZAR"
            DccSrcCurrMinorUnits="2"
            DccTgtCurrCode="840"
            DccTgtCurrAlphaCode="USD"
            DccTgtCurrMinorUnits="2"
            DccProvider="FEXCO"
            DccRateSrc="REUTERS INTERBANK RATE"
            DccTimestamp="20170426T15:35"
            DccMargRate="0.03"
            DccDiffOverECB="0.001"
            DccIsEEA="Y"
            DccCommRate="0.01"
            DccSrcAmt="30000"
            DccTgtAmt="2200"
            DccExpTimestamp="20170429T15:35"
            DccRcptTxt1="I recognise I was given the choice of payment currencies. I accept the exchange rate. My decision to pay in my currency is final.">
        </Esp:Transaction>
    </Esp:Interface>

3.11.15. Purchase (dual message pair)

Introduction

In the case when a purchase transaction requires authorization before it can be sent, a dual message pair purchase transaction flow can be used. An online authorization request is sent from the POS to determine, amongst other things, if the cardholder’s account contains sufficient funds for the purchase transaction. Once this authorization is received, the purchase transaction can proceed. The message flow here is an example of a successful transaction.

Message flow

Purchase (dual message pair)

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE AUTH (request) to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS converts this PURCHASE AUTH (request) into an authorization request (0100) and sends it to Postilion.

  3. Postilion sends the authorization request (0100) upstream.

  4. Postilion receives an authorization response (0110) from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the authorization response (0110) to eSocket.POS.

  6. eSocket.POS converts this authorization response (0110) into a PURCHASE AUTH (response) and sends it to the POS.

  7. The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.

  8. eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.

  9. eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.

  10. Postilion receives the transaction advice request and sends a transaction advice response (0230) to eSocket.POS.

  11. Postilion sends the transaction advice request (0220) and sends it upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.

  12. Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.

Note: If Postilion is the card issuer, the appropriate authorization response (0110) and transaction advice response (0230) is sent from Postilion, and steps 3, 4, 11, and 12 are eliminated. If the PURCHASE AUTH (response) in step 6 is not an approval, the transaction will cease after step 6.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a dual message pair purchase transaction:

If registered, the following callbacks are called during a dual message pair purchase transaction:

XML mappings in a dual message pair purchase transaction

This section contains the XML properties and values that are typically associated with a dual message pair purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase authorization request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    AUTH

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Purchase confirmation request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    CONFIRM

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in these tables, see Object and Property Conditions .

Example: XML messages in a dual message pair purchase transaction

This is an example of a dual message pair purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a dual message pair purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            MessageType="AUTH"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE AUTH (response) XML message [6] from eSocket.POS following the successful completion of the authorization:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0906065846"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            MessageType="AUTH"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000084"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
            <Esp:Balance
                AccountType="00"
                Amount="30000"
                AmountType="53"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS sends a PURCHASE CONFIRM (request) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            MessageType="CONFIRM"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE CONFIRM (response) XML message [8] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0906065853"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            MessageType="CONFIRM"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

3.11.16. Purchase with consumer-presented QR code

Introduction

This section discusses a QR code transaction, started at the POS and sent upstream via Postilion for authorization. The example is of a successful transaction.

Message flow

QR code - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction, QRCodeType field set to a valid QRCodeType, and QRCodeData or BarcodeData.

  2. eSocket.POS sends a purchase request (0200) to Postilion Realtime.

  3. Postilion Realtime sends the purchase request (0200) upstream.

  4. Postilion Realtime receives a purchase response (0210) back from the upstream entity responsible for authorizing the transaction.

  5. Postilion Realtime sends the purchase response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a QR code transaction:

If registered, the following callbacks are called during a QR code transaction:

XML mappings in a QR code transaction

This section contains the XML properties and values that are typically associated with a QR code transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property

Condition

Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

PURCHASE

QRCodeType

M

PAYPAL_CPQRC

QRCodeData

M

793456782312

RetrievalRefNr

O

000000000083

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a QR code transaction

This is an example of a QR code transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a QR code transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE"
            QRCodeType="PAYPAL_CPQRC"
            QRCodeData="793456782312"
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0831"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0831064214"
            ExpiryDate="2012"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000083"
            ServiceRestrictionCode="***"
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE"
            QRCodeType="PAYPAL_CPQRC"
            QRCodeTranId="123456789"
            QRCodeHostRef="1234567ACDS">
            <Esp:Balance
                AccountType="00"
                Amount="30000"
                AmountType="53"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11.17. Purchase with merchant-presented QR code

Introduction

This section discusses a merchant-presented QR code transaction, started at the POS and sent upstream via Postilion for processing. The example is of a successful transaction.

Message flow

QR code - successful

Follow the message flow and refer to the diagram.

  1. The POS initiates a merchant-presented QR code transaction by sending a QR_CODE_INITIATE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends an admin request (0600) to Postilion Realtime.

  3. Postilion Realtime sends the admin response (0610) to eSocket.POS. The response will contain sufficient data for the merchant to display a QR code for the customer.

  4. eSocket.POS sends the appropriate response to the POS device.

  5. The POS uses the response data to display the QR code.

  6. The POS sends a message to check whether the payment was completed using the QR code by sending a QR_CODE_STATUS_REQUEST containing either the TransactionId from the original payment request, or the QRCodeTranId that was received in the original response.

  7. eSocket.POS sends an admin request (0600) to Postilion Realtime.

  8. Postilion Realtime sends the admin response (0610) to eSocket.POS.

  9. If the admin response has a response code of 09 (request in progress) eSocket.POS will repeat sending up the status request until the maximum number of retries have been attempted as per the eSocket.POS configuration.

  10. After an admin response with a response code other than 09 (request in progress) is received, eSocket.POS sends the response to the POS.

  11. The response code indicates the state of the payment.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following callbacks are called during a merchant-presented QR code transaction:

XML mappings in a merchant-presented QR code transaction

This section contains the XML properties and values that are typically associated with a merchant-presented QR code transaction. In the Value column, example values are in italics and mandatory values are in bold.

XML mappings in a merchant-presented QR code Initiate request

Property

Condition

Value

TerminalId

M

SoftTerm

TransactionAmount

G

30000

TransactionId

M

195322

QRCodeType

M

ACI_URL_MPQRC

Type

M

QR_CODE_INITIATE

XML mappings in a merchant-presented QR code Status request

Property

Condition

Value

TerminalId

M

SoftTerm

TransactionId

C

195322

Type

M

QR_CODE_STATUS_REQUEST

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a merchant-presented QR code transaction

This is an example of a merchant-presented QR code transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

Example: QR code initiate (request)

The POS starts a merchant-presented QR code transaction with a QR code initiate (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="QR_CODE_INITIATE"
            QRCodeType="ACI_URL_MPQRC"
        </Esp:Transaction>
    </Esp:Interface>

The resulting QR code initiate (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Type="QR_CODE_INITIATE"
            ExtendedTransactionType="2400"
            CurrencyCode="710"
            TransactionId="195322"
            TerminalId="SoftTerm"
            QRCodeTranId="1234"
            QRCodeData="https://mycheckout.merchant.com/qrc/somepage?session=1234"
            QRCodeImage="NzkxMDIzMTk3ODYw"
            QRCodeType="ACI_URL_MPQRC"
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

Example: QR code status request

The POS sends a message to check whether the payment was completed QR code status request XML message [8] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionId="195322"
            Type="QR_CODE_STATUS_REQUEST"
        </Esp:Transaction>
    </Esp:Interface>

The resulting QR code status request (response) XML message [14] from eSocket.POS following the successful response from upstream:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            Type="QR_CODE_STATUS_REQUEST"
            ResponseCodequot;00"
            TerminalId="SoftTerm"
            ActionCode="APPROVE"
            PosCondition="00"
            LocalDate="0829"
            LocalTime="220820"
            MerchantId="111111111111111"
            CardNumber="0000000000000000000"
            DateTime="0829200820"
            TransactionId="195322"
            PanEntryMode="00"
            LocalTime="220820"
            MessageReasonCode="9790"
            AuthorizationProfile="11"
            ExtendedTransactionType="2401"
            QRCodeTranId="1234"
            QRCodeType="ACI_URL_MPQRC"
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11.18. Purchase with merchant-presented QR code and reversal/void

Introduction

This section discusses a reversal/void for a merchant-presented QR code transaction, started at the POS and sent upstream via Postilion for processing. The example is of a successful transaction.

Message flow

QR code - reversal/void

Follow the message flow and refer to the diagram.

  1. The POS initiates a merchant-presented QR code transaction by sending a QR_CODE_INITIATE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends an admin request (0600) to Postilion Realtime.

  3. Postilion Realtime sends the admin response (0610) to eSocket.POS. The response will contain sufficient data for the merchant to display a QR code for the customer.

  4. eSocket.POS sends the appropriate response to the POS device.

  5. The POS uses the response data to display the QR code.

  6. The POS sends a message to check whether the payment was completed using the QR code by sending a QR_CODE_STATUS_REQUEST containing either the TransactionId from the original payment request or the QRCodeTranId that was received in the original response.

  7. eSocket.POS sends an admin request (0600) to Postilion Realtime.

  8. Postilion Realtime sends the admin response (0610) to eSocket.POS.

  9. If the admin response has a response code of 09 (request in progress), eSocket.POS will repeat sending up the status request until the maximum number of retries have been attempted as per the eSocket.POS configuration.

  10. Once an admin response with a response code other than 09 (request in progress) is received, eSocket.POS sends the response to the POS.

  11. The response code indicates the state of the payment.

  12. The POS sends a QR code cancelation XML message to eSocket.POS to reverse/cancel the original QR transaction request.

  13. eSocket.POS sends a QR code cancelation advice (0620) to Postilion Realtime.

  14. Postilion Realtime sends the QR code cancelation advice response (0630) to eSocket.POS.

  15. eSocket.POS sends a QR code cancelation response to the POS device.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

The reversal message does not call any events. If registered, the following callbacks are called during a merchant-presented QR code transaction:

XML mappings in a merchant-presented QR code transaction

This section contains the XML properties and values that are typically associated with a merchant-presented QR code transaction. In the Value column, example values are in italics and mandatory values are in bold.

  1. Merchant-presented QR code Initiate request

    Property

    Condition

    Value

    TerminalId

    M

    SoftTerm

    TransactionAmount

    G

    30000

    TransactionId

    M

    195322

    QRCodeType

    M

    ACI_URL_MPQRC

    Type

    M

    QR_CODE_INITIATE

  2. Merchant-presented QR code Status request

    Property

    Condition

    Value

    TerminalId

    M

    SoftTerm

    TransactionId

    C

    195322

    Type

    M

    QR_CODE_STATUS_REQUEST

  3. Reversal transaction

    Property

    Condition

    Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    195322

    Type

    M

    PURCHASE

    Reversal

    C

    TRUE

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a merchant-presented QR code transaction

Some examples of merchant-presented QR code transactions are outlined here. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

Example: QR code initiate (request)

The POS starts a merchant-presented QR code transaction with a QR code initiate (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="QR_CODE_INITIATE"
            QRCodeType="ACI_URL_MPQRC"
        </Esp:Transaction>
    </Esp:Interface>

The resulting QR code initiate (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Type="QR_CODE_INITIATE"
            ExtendedTransactionType="2400"
            CurrencyCode="710"
            TransactionId="195322"
            TerminalId="SoftTerm"
            QRCodeTranId="1234"
            QRCodeData="https://mycheckout.merchant.com/qrc/somepage?session=1234"
            QRCodeImage="NzkxMDIzMTk3ODYw"
            QRCodeType="ACI_URL_MPQRC"
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

Example: QR code status request

The POS sends a message to check whether the payment was completed with a QR code status request XML message [8] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionId="195322"
            Type="QR_CODE_STATUS_REQUEST"
        </Esp:Transaction>
    </Esp:Interface>

The resulting QR code status request (response) XML message [14] from eSocket.POS following the successful response from upstream:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            Type="QR_CODE_STATUS_REQUEST"
            ResponseCodequot;00"
            TerminalId="SoftTerm"
            ActionCode="APPROVE"
            PosCondition="00"
            LocalDate="0829"
            LocalTime="220820"
            MerchantId="111111111111111"
            CardNumber="0000000000000000000"
            DateTime="0829200820"
            TransactionId="195322"
            PanEntryMode="00"
            LocalTime="220820"
            MessageReasonCode="9790"
            AuthorizationProfile="11"
            ExtendedTransactionType="2401"
            QRCodeTranId="1234"
            QRCodeType="ACI_URL_MPQRC"
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

Example: QR code reversal (request)

The POS starts a reversal transaction with a PURCHASE (reversal) XML message [12] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="SoftTerm"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (reversal response) XML message [15] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="0000000000000000000"
            LocalDate="0829"
            LocalTime="220820"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="00"
            PosCondition="00"
            PosDataCode="A1010105434C101"
            QRCodeTranId="D4C64D28692E758596C3D493AA6DDED8"
            QRCodeType="ACI_URL_MPQRC"
            ResponseCode="00"
            Reversal="TRUE"
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

3.11.19. Purchase with referral

Introduction

This example represents a POS transaction that is declined upstream and returned with a referral response code. The transaction is then approved using an external authorization process, such as a telephone call. To complete the transaction, a referral advice which includes all relevant data must be sent upstream.

Message flow

Purchase transaction referral - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends a purchase request (0200) to Postilion.

  3. Postilion sends the purchase request (0200) upstream.

  4. Postilion receives a purchase response (0210) - with a referral response code - back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the purchase response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

  7. The POS sends a PURCHASE REFERRAL (request) XML message to eSocket.POS with the relevant data and transaction amount.

  8. eSocket.POS sends the appropriate response to the POS device.

  9. eSocket.POS generates a referral advice request (0220) and sends it to Postilion. eSocket.POS will resend the referral advice request (0220) to Postilion until it receives a response.

  10. Postilion receives the referral advice request and sends a referral advice response (0230) to eSocket.POS.

  11. Postilion sends the referral advice request (0220) upstream. Postilion will resend the referral advice request (0220) to the network until it receives a response.

  12. Postilion receives a referral advice response (0230) from the entity upstream responsible for authorizing the transaction.

Note: If Postilion is the card issuer, the appropriate purchase response (0210) and referral advice response (0230) is sent from Postilion, and steps 3, 4, 11, and 12 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a purchase transaction:

If registered, the following callbacks are called during a purchase transaction:

XML mappings in a purchase transaction with referral

This section contains the XML properties and values that are typically associated with a purchase transaction and referral advice. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase transaction

    Property Condition Value

    TerminalId

    M

    SoftTerm

    TransactionId

    M

    195322

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000083

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Referral advice

    Property Condition Value

    TerminalId

    M

    SoftTerm

    TransactionId

    M

    195322

    Type

    M

    PURCHASE

    MessageType

    M

    REFERRAL

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

    RetrievalRefNr

    O

    000000000083

    PosOperatorId

    O

    PosOp001

    AuthorizationNumber

    C

    123456

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in these tables, see Object and Property Conditions .

Example: XML messages in a purchase transaction with referral

This is an example of a purchase transaction with referral. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            PosOperatorId="PosOp001"
            RetrievalRefNr="000000000083"
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (response) XML message [6] from eSocket.POS with a referral response code:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="AUTH"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0831"
            CardProductName="VisaDebit"
            CurrencyCode="710"
            DateTime="0831064214"
            ExpiryDate="2012"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="311111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="01"
            RetrievalRefNr="000000000083"
            TerminalId="SoftTerm"
            TransactionAmount="0"
            TransactionId="195322"
            Type="PURCHASE">
            <Esp:Balance
                AccountType="00"
                Amount="0"
                AmountType="53"
                CurrencyCode="710"
                Sign="C">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS sends a PURCHASE REFERRAL (request) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            AuthorizationNumber="123456"
            MessageType="REFERRAL"
            PosOperatorId="PosOp001"
            ResponseCode="00"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE REFERRAL (response) XML message [8] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AuthorizationNumber="123456"
            CardNumber="111122******4444"
            CardProductName="VisaDebit"
            CurrencyCode="710"
            DateTime="0906065853"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="311111111111111"
            MessageReasonCode="9792"
            MessageType="REFERRAL"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000084"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

3.11.20. XML - Purchase with timeout and online reversal/void

Introduction

When a purchase transaction at the POS does not receive the required response within a certain time period, the transaction is reversed. This example is of a transaction that is approved upstream via Postilion. The response is received by eSocket.POS, but not by the POS. At the POS, the transaction times out and an online reversal is initiated to reverse the transaction.

Message flow

Purchase with Online reversal

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends a purchase request (0200) to Postilion.

  3. Postilion sends the purchase request (0200) upstream.

  4. Postilion receives a purchase response (0210) back from the upstream entity responsible for authorizing the transaction.

  5. Postilion sends the purchase response (0210) to eSocket.POS.

  6. eSocket.POS receives the purchase response (0210) and converts this into an appropriate PURCHASE (response) to forward to the POS. The POS times out while waiting for the PURCHASE (response) from eSocket.POS.

  7. The POS sends a PURCHASE (Online reversal) to eSocket.POS

  8. eSocket.POS generates a Reversal Request (0400) and sends it to Postilion.

  9. Postilion receives a Reversal Request(0400) and generates an Online Reversal Response(410).

  10. Postilion sends an Online Reversal Response(410) back to eSocket.POS.

  11. eSocket.POS receives an Online Reversal Response(410) and sends it to the POS.

  12. The POS receives an Online Reversal Response(410).

For more information on handling timeouts, see XML - handling timeouts.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the full list and are typical to this scenario.

If registered, the following events are called during a purchase transaction:

If registered, the following callbacks are called during a purchase transaction:

XML mappings in a purchase transaction timeout and reversal

The first table contains the XML properties and values that are typically associated with a purchase transaction. The second table contains the XML properties and values that are typically associated with a reversal request. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase transaction

    Property

    Condition

    Value

    TerminalId

    M

    SoftTerm

    TransactionId

    M

    195322

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000083

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Reversal request

    Property

    Condition

    Value

    TerminalId

    M

    SoftTerm

    TransactionId

    M

    195322

    Type

    M

    PURCHASE

    Reversal

    O

    TRUE

    ReversalType

    O

    REQUEST

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in the above tables, see Object and Property Conditions .

Example: XML messages in a purchase transaction timeout and reversal

This is an example of a purchase transaction timeout and reversal. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The POS starts a reversal request with a PURCHASE (reversal) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="SoftTerm"
            TransactionId="195322"
            Type="PURCHASE"
            ReversalType="REQUEST">
        </Esp:Transaction>
    </Esp:Interface>

An example of the resulting PURCHASE (reversal response) XML message [8] from eSocket.POS follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0831064214"
            ExpiryDate="2012"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            Reversal="TRUE"
            ServiceRestrictionCode="***"
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE"
            ReversalType="REQUEST">
        </Esp:Transaction>
    </Esp:Interface>

3.11.21. Purchase with Signature capture

Introduction

This section discusses a purchase transaction with signature capture. eSocket.POS determines if a signature is required, while processing an approved response (0110/0210/0230). If a signature is required, eSocket.POS sends a SIGNATURE_PROMPT event indicating that it will attempt to capture the cardholder’s signature. The captured signature data is sent upstream before completing the transaction.

This example makes use of events and callbacks. It also includes cashback and extended payment scenarios. A cashback is when a cardholder withdraws cash at a POS. An extended payment refers to the option given to cardholders to pay the transaction amount into their account over a number of months (e.g. 6 or 12 months).

Message flow

Signature Capture - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends a DATA_REQUIRED (request) callback XML message to the POS to verify the cashback amount.

  3. The POS sends a DATA_REQUIRED (response) callback XML message to eSocket.POS with the final cashback amount.

  4. eSocket.POS sends a DATA_REQUIRED (request) callback XML message to the POS to determine whether to use extended payment.

  5. The POS sends a DATA_REQUIRED (response) callback XML message to eSocket.POS with a valid response.

  6. eSocket.POS sends a purchase request (0200) to Postilion.

  7. Postilion sends the purchase request (0200) upstream.

  8. Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.

  9. Postilion sends the purchase response (0210) to eSocket.POS.

  10. eSocket.POS sends a SIGNATURE_PROMPT event XML message to the POS.

  11. eSocket.POS sends the appropriate response to the POS device.

  12. eSocket.POS generates an admin advice (0620) which contains the signature data and sends it to Postilion. eSocket.POS will resend the admin advice to Postilion until it receives a response.

  13. Postilion sends an admin advice response (0630) back to eSocket.POS.

  14. Postilion forwards the admin advice (0620) to the relevant network. Postilion will resend the admin advice until it receives a response.

  15. Postilion receives an admin advice response (0630) from the network.

Note: If Postilion is the card issuer, the appropriate purchase response (0210) and admin advice response (0630) is sent from Postilion, and steps 7, 8, 14 and 15 are eliminated.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a purchase transaction with signature capture:

If registered, the following callbacks are called during a purchase transaction with signature capture:

XML mappings in a single message pair purchase transaction

This section contains the XML properties and values that are typically associated with a purchase transaction with signature capture. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase transaction

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    161499

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000122

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. DATA_REQUIRED callback response for cashback amount

    Property Condition Value

    TerminalId

    M

    TestTerm

    EventId

    M

    DATA_REQUIRED

    ResponseData

    -

    1000

  3. DATA_REQUIRED callback response for extended payment

    Property Condition Value

    TerminalId

    M

    TestTerm

    EventId

    M

    DATA_REQUIRED

    ResponseData

    -

    FALSE

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties and Callback Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a purchase transaction with signature capture

This is an example of a purchase transaction with signature capture. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts the purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="161499"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

eSocket.POS sends a DATA_REQUIRED (request) callback XML message [2] to the POS to verify the cashback amount:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="TestTerm"
            EventId="DATA_REQUIRED"
            EventData="CashbackAmount(3000)"/>
    </Esp:Interface>

The POS sends a DATA_REQUIRED (response) callback XML message [3] to eSocket.POS with the final cashback amount:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="TestTerm"
            EventId="DATA_REQUIRED"
            ResponseData="1000">
        </Esp:Callback>
    </Esp:Interface>

eSocket.POS sends a DATA_REQUIRED (request) callback XML message [4] to the POS to determine whether to use extended payment:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="TestTerm"
            EventId="DATA_REQUIRED"
            EventData="IsExtendedPaymentRequired"/>
    </Esp:Interface>

The POS sends a DATA_REQUIRED (response) callback XML message [5] to eSocket.POS with response data:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Callback
            TerminalId="TestTerm"
            EventId="DATA_REQUIRED"
            ResponseData="FALSE">
        </Esp:Callback>
    </Esp:Interface>

The SIGNATURE_PROMPT event XML message [10] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Event
            TerminalId="TestTerm"
            EventId="SIGNATURE_PROMPT"
            EventData=""/>
    </Esp:Interface>

The resulting PURCHASE (response) XML message [11] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="30"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="1031"
            CardProductName="MCCredit"
            CashbackAmount="1000"
            CurrencyCode="710"
            DateTime="1101091819"
            ExpiryDate="1912"
            LocalDate="1101"
            LocalTime="111819"
            MerchantId="211111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000122"
            ServiceRestrictionCode="***"
            SignatureData="Signature Data"
            SignatureFormat="FMT"
            TerminalId="TestTerm"
            TransactionAmount="31000"
            TransactionId="161499"
            Type="PURCHASE">
            <Esp:Balance
                AccountType="30"
                Amount="31000"
                AmountType="53"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:Balance
                AccountType="30"
                Amount="1000"
                AmountType="40"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11.22. Purchase (single message pair)

Introduction

This section discusses a single message pair purchase transaction, started at the POS and sent upstream via Postilion for authorization. The example is of a successful transaction.

Message flow

Purchase (single message pair) - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends a purchase request (0200) to Postilion.

  3. Postilion sends the purchase request (0200) upstream.

  4. Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the purchase response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate purchase response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a single message pair purchase transaction:

If registered, the following callbacks are called during a single message pair purchase transaction:

XML mappings in a single message pair purchase transaction

This section contains the XML properties and values that are typically associated with a single message pair purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

PURCHASE

RetrievalRefNr

O

000000000083

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a single message pair purchase transaction

This is an example of a single message pair purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a single message pair purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0831"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0831064214"
            ExpiryDate="2012"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000083"
            ServiceRestrictionCode="***"
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
            <Esp:Balance
                AccountType="00"
                Amount="30000"
                AmountType="53"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11.23. Purchase and reversal/void

Introduction

When a purchase transaction is approved and for some reason we need the transaction to be reversed, a reversal is required. The following example describes a purchase transaction, finalized successfully, and then followed by a reversal advice. The example is of a successful transaction.

Message flow

Purchase and reversal/void

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends a purchase request (0200) to Postilion.

  3. Postilion sends the purchase request (0200) upstream.

  4. Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the purchase response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device. At this stage, the purchase transaction is completed.

  7. The POS sends a PURCHASE (reversal) XML message to eSocket.POS to reverse the original request transaction.

  8. eSocket.POS sends a PURCHASE (reversal response) to the POS device.

  9. eSocket.POS sends a reversal advice (0420) to Postilion.

  10. Postilion sends the reversal advice response (0430) to eSocket.POS.

  11. Postilion sends the reversal advice (0420) upstream.

  12. Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.

Note: If Postilion is the card issuer, the appropriate purchase response (0210) is sent from Postilion, and steps 3 and 4 are eliminated. In this scenario steps 11 and 12 are also eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

The reversal message does not call any events. If registered, the following events are called during a purchase transaction:

The reversal message does not get any callbacks. If registered, the following callbacks are called during a purchase transaction:

XML mappings in a purchase transaction reversal

This section contains the XML properties and values that are typically associated with a purchase transaction. The second table contains the XML properties typically associated with a purchase transaction reversal. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase transaction

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    141790

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    00000000008

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Reversal transaction

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    141790

    Type

    M

    PURCHASE

    Reversal

    C

    TRUE

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Example: XML messages in a purchase transaction reversal

This is an example of a purchase transaction, followed by a transaction to reverse the purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="141790"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="086082950"
            ExpiryDate="2012"
            LocalDate="0806"
            LocalTime="102950"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="00000000008"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="141790"
            Type="PURCHASE">
            <Esp:Balance
                AccountType="00"
                Amount="30000"
                AmountType="53"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS starts a reversal transaction with a PURCHASE (reversal) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="TestTerm"
            TransactionId="141790"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0806082951"
            ExpiryDate="2012"
            LocalDate="0806"
            LocalTime="102950"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            Reversal="TRUE"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="141790"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

3.11.24. Purchase with timeout and reversal/void

Introduction

When a purchase transaction at the POS does not receive the required response within a certain time period, the transaction is reversed. This example is of a transaction that is approved upstream via Postilion. The response is received by eSocket.POS, but not by the POS. At the POS, the transaction times out and a reversal is initiated to reverse the transaction.

Message flow

Purchase with timeout and reversal/void

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends a purchase request (0200) to Postilion.

  3. Postilion sends the purchase request (0200) upstream.

  4. Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the purchase response (0210) to eSocket.POS.

  6. eSocket.POS receives the purchase response (0210) and converts this into an appropriate PURCHASE (response) to forward to the POS. The POS times out while waiting for the PURCHASE (response) from eSocket.POS.

  7. The POS sends a PURCHASE (reversal) to eSocket.POS to cancel any impact the original purchase request may have had on the cardholder’s account.

  8. eSocket.POS generates a PURCHASE (reversal response) and sends it to the POS.

  9. eSocket.POS generates a reversal advice (0420) and sends it to Postilion. eSocket.POS will resend the Reversal Advice to Postilion until it receives a response.

  10. Postilion sends a reversal advice response (0430) back to eSocket.POS.

  11. Postilion forwards the reversal advice (0420) to the relevant network. Postilion will resend the reversal advice until it receives a response.

  12. Postilion receives a reversal advice response (0430) from the network.

Note: If Postilion is the card issuer, the appropriate purchase response (0210) and reversal advice response (0430) is sent from Postilion, and steps 3, 4, 11 and 12 are eliminated.

For more information on handling timeouts, refer to XML - handling timeouts .

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a purchase transaction:

If registered, the following callbacks are called during a purchase transaction:

XML mappings in a purchase transaction timeout and reversal

The first table contains the XML properties and values that are typically associated with a purchase transaction. The second table contains the XML properties and values that are typically associated with a reversal advice. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase transaction

    Property Condition Value

    TerminalId

    M

    SoftTerm

    TransactionId

    M

    195322

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000083

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Reversal advice

    Property Condition Value

    TerminalId

    M

    SoftTerm

    TransactionId

    M

    195322

    Type

    M

    PURCHASE

    Reversal

    O

    TRUE

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in the above tables, see Object and Property Conditions .

Example: XML messages in a purchase transaction timeout and reversal

This is an example of a purchase transaction timeout and reversal. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The POS starts a reversal advice with a PURCHASE (reversal) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="SoftTerm"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (reversal response) XML message [8] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0831064214"
            ExpiryDate="2012"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            Reversal="TRUE"
            ServiceRestrictionCode="***"
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

3.11.25. Purchase with Token generation request for online standin with advice

Introduction

In the case where a purchase transaction is eligible for online stand-in, an administration request (create card token) is sent before the authorization to create a card token. The message flow here is an example of online stand-in transaction with a successful token generation.

Message flow

Purchase with Token generation request for online standin with advice

Follow the message flow (dual message pair) and refer to the diagram.

  1. The POS sends a PURCHASE AUTH (request) to eSocket.POS with the amount of the transaction lesser than floor limits.

  2. eSocket.POS converts the PURCHASE AUTH (request) into an authorization request (0100). Once it determines that the transaction is eligible of online stand-in, it converts the message to authorization advice request(0120) and sends a create card token request (0600) to Postilion.

  3. Postilion sends the create card token request to the Token Engine.

  4. Postilion receives a create card token response containing a card token from the Token Engine.

  5. Postilion sends an create card token response (0610) containing a card token to eSocket.POS.

  6. eSocket.POS updates the authorization advice request (0120) with the card token and sends the authorization advice response(0130).It then converts the authorization advice response(0130) to authorization response (0110) and then to PURCHASE AUTH (response) and sends it to the POS. The PURCHASE AUTH (response) contains the card token which will be used in furture transactions.

  7. eSocket.POS sends the authorization advice request (0120) to Postilion. eSocket.POS will resend the authorization advice request (0120) to Postilion until it receives a response.

  8. Postilion receives the authorization advice request (0120) and sends a authorization advice response (0130) to eSocket.POS.

  9. Postilion sends the authorization advice request (0120) upstream. Postilion will resend the authorization advice request (0120) to the network until it receives a response.

  10. Postilion receives a authorization advice response (0130) from the entity upstream responsible for authorizing the transaction.

  11. The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.

  12. eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.

  13. eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.

  14. Postilion receives the transaction advice request (0220) and sends a transaction advice response (0230) to eSocket.POS.

  15. Postilion sends the transaction advice request (0220) upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.

  16. Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.

Notes :

  • If the single message pair flow is used, the message types in steps 1 and 6 are PURCHASE (request) and PURCHASE (response). The message types in steps 2 and 6 to 10 are 0200,0220,0230 and 0210, and steps 11 to 16 are absent.

  • If Postilion is the card issuer, the appropriate authorization response (0130) and transaction advice response (0230) is sent from Postilion, and steps 9, 10, 15, and 16 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a purchase transaction:

If registered, the following callbacks are called during a purchase transaction:

XML mappings in a purchase transaction

This section contains the XML properties and values that are typically associated with a purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase authorization request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    AUTH

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Purchase confirmation request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    CONFIRM

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    2500

    CurrencyCode

    O

    710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in these tables, see Object and Property Conditions .

Example: XML messages is purchase transaction that generates a card token.

This is an example of a purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            MessageType="AUTH"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE AUTH (response) XML message [12] from eSocket.POS following the successful completion of the authorization:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0906065846"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            MessageType="AUTH"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000084"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
            <Esp:Balance
                AccountType="00"
                Amount="30000"
                AmountType="53"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="CardToken"
                Value="7114062501124444">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS sends a PURCHASE CONFIRM (request) XML message [13] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            MessageType="CONFIRM"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE CONFIRM (response) XML message [14] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0906065853"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            MessageType="CONFIRM"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
            <Esp:StructuredData
                Name="CardToken"
                Value="7114062501124444">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11.26. Purchase with Token generation request for online standin without advice

Introduction

In the case where a purchase transaction is eligible for online stand-in, an administration request (create card token) is sent before the authorization to create a card token. The message flow here is an example of online stand-in transaction with a successful token generation.

Message flow

Purchase with Token generation request for online standin with advice

Follow the message flow (dual message pair) and refer to the diagram.

  1. The POS sends a PURCHASE AUTH (request) to eSocket.POS with the amount of the transaction lesser than floor limits.

  2. eSocket.POS converts the PURCHASE AUTH (request) into an authorization request (0100). Once it determines that the transaction is eligible of online stand-in, it approves the transaction and sends a create card token request (0600) to Postilion.

  3. Postilion sends the create card token request to the Token Engine.

  4. Postilion receives a create card token response containing a card token from the Token Engine.

  5. Postilion sends the create card token response (0610) containing a card token to eSocket.POS.

  6. eSocket.POS updates the authorization response(0110) with the card token and then coverts it to PURCHASE AUTH (response) and sends it to the POS. The PURCHASE AUTH (response) contains the card token which will be used in furture transactions.

  7. The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.

  8. eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.

  9. eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.

  10. Postilion receives the transaction advice request (0220) and sends a transaction advice response (0230) to eSocket.POS.

  11. Postilion sends the transaction advice request (0220) upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.

  12. Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.

Notes :

  • If the single message pair flow is used, the message types in steps 1 and 6 are PURCHASE (request) and PURCHASE (response). The message types in steps 2 and 6 are 0200 and 0210, and steps 7 to 12 are absent.

  • If Postilion is the card issuer, the appropriate transaction advice response (0230) is sent from Postilion, and steps 10 and 11 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a purchase transaction:

If registered, the following callbacks are called during a purchase transaction:

XML mappings in a purchase transaction

This section contains the XML properties and values that are typically associated with a purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.

  1. Purchase authorization request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    AUTH

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Purchase confirmation request XML message.

    Property Condition Value

    TerminalId

    M

    TestTerm

    MessageType

    M

    CONFIRM

    TransactionId

    M

    114726

    Type

    M

    PURCHASE

    RetrievalRefNr

    O

    000000000084

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    2500

    CurrencyCode

    O

    710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in these tables, see Object and Property Conditions .

Example: XML messages is purchase transaction that generates a card token.

This is an example of a purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            MessageType="AUTH"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE AUTH (response) XML message [6] from eSocket.POS following the successful completion of the authorization:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0906065846"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            MessageType="AUTH"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000084"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
            <Esp:Balance
                AccountType="00"
                Amount="30000"
                AmountType="53"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="CardToken"
                Value="7114062501124444">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS sends a PURCHASE CONFIRM (request) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            MessageType="CONFIRM"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE CONFIRM (response) XML message [8] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0906065853"
            ExpiryDate="2012"
            LocalDate="0906"
            LocalTime="085846"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            MessageType="CONFIRM"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="114726"
            Type="PURCHASE">
            <Esp:StructuredData
                Name="CardToken"
                Value="7114062501124444">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11.27. Reconciliation

Introduction

This section discusses a reconciliation transaction, started at the POS and sent upstream to Postilion for authorization. The purpose of the reconciliation transaction is to perform a batch cutover and to determine if the totals maintained by the POS match those maintained by Postilion. The example is of a successful reconciliation.

Note: The reconciliation message is not supported when using eSocket.POS with a dual sink configuration.

Message flow

Reconciliation - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a Reconciliation (request) XML message to eSocket.POS.

  2. eSocket.POS sends an reconciliation request (0500) to Postilion.

  3. Postilion sends the reconciliation response (0510) to eSocket.POS.

  4. eSocket.POS sends the appropriate response to the POS device.

Note: If there are transactions in the eSocket.POS store and forward queue, eSocket.POS will queue a 0520 in the store and forward queue instead of sending a 0500 to Postilion. In this scenario, transaction totals will not be sent to the POS. See the reconciliation pipeline component in the eSocket.POS User Guide.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. There are no events and callbacks typically associated to this message.

XML mappings in a reconciliation transaction

This section contains the XML properties and values that are typically associated with a reconciliation transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Reconciliation Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a reconciliation transaction

This is an example of a reconciliation transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a reconciliation transaction with a RECONCILIATION (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Reconciliation
            TerminalId="SoftTerm"
            TransactionId="195322"
        </Esp:Reconciliation>
    </Esp:Interface>

The resulting RECONCILIATION (response) XML message [4] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Reconciliation
            ActionCode="APPROVE"
            CreditsAmount="0"
            CreditsReversalAmount="0"
            DateTime="1026105736"
            DebitsAmount="60000"
            DebitsReversalAmount="0"
            LocalDate="1026"
            LocalTime="125736"
            MessageReasonCode="9790"
            NumberOfAuthorizations="0"
            NumberOfCredits="0"
            NumberOfCreditsReversal="0"
            NumberOfDebits="2"
            NumberOfDebitsReversal="0"
            NumberOfInquiries="0"
            ResponseCode="00"
            SettlementCurrencyCode="840"
            TerminalId="SoftTerm"
            TransactionId="195322">
            <Esp:NetSettlementAmount
                Amount="60000"
                Sign="D">
            </Esp:NetSettlementAmount>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Reconciliation>
    </Esp:Interface>

3.11.28. Refund

Introduction

This section discusses a refund transaction, started at the POS and sent upstream via Postilion for authorization. The example is of a successful refund.

Message flow

Refund - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a REFUND (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends a refund request (0200) to Postilion.

  3. Postilion sends the refund request (0200) upstream.

  4. Postilion receives a refund response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the refund response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate refund response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a refund transaction:

If registered, the following callbacks are called during a refund transaction:

XML mappings in a refund transaction

This section contains the XML properties and values that are typically associated with a refund transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

REFUND

RetrievalRefNr

O

000000000083

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

710

TRANSARMOR_TOKEN

O

String (Specified as part of EspStructuredData)

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a refund transaction

This is an example of a refund transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a refund transaction with a REFUND (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="REFUND">
        </Esp:Transaction>
    </Esp:Interface>

The resulting REFUND (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0831"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0831064214"
            ExpiryDate="2012"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000083"
            ServiceRestrictionCode="***"
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="REFUND">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11.29. Signature capture request

Introduction

When the POS requires signature data, it sends a request to the PED via eSocket.POS. The PED prompts for the signature, captures the image, and sends it back to the POS, via eSocket.POS.

Message flow

Signature Capture Request- successful

Follow the message flow and refer to the diagram.

1. The POS sends an ADMIN (request) to eSocket.POS. The message contains a request for signature capture. 2. eSocket.POS generates an admin request (0600) and sends a request to the PED to prompt for a signature. 3. The PED prompts for a signature, captures the data, and sends it back to eSocket.POS. eSocket.POS translates the data to an admin request response (0610). 4. eSocket.POS sends an ADMIN (response) back to the POS. The response includes the signature image data. Note : Transactions that qualify for rapid payment service (RPS) and have an account that is configured for RPS must not request a signature capture.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a signature capture request:

XML mappings in a single message pair signature capture request

This section contains the XML properties and values that are typically associated with a signature capture request. In the Value column, example values are in italics and mandatory values are in bold.

  1. Signature capture request

    Property Condition Value

    ExtendedTransactionType

    M

    3030

    SignatureStandAloneDynamicText

    M

    String

    SignatureImagePassedInResponse

    M

    TRUE or FALSE

    SignatureImageFormat

    M

    TIFF,JPEG,ASCII, or PNG

    SignatureScrollableText

    M

    String

    SignatureCheckbox1Text

    M

    String

    SignatureCheckbox2Text

    M

    String

    SignatureCheckbox3Text

    M

    String

    SignatureAdditionalText

    O

    YES or NO

    SignaturePromptName

    O

    String

    SignatureLineItemTextCount

    O

    String (Specified as part of EspStructuredData)

    SignatureLineItemText

    O

    String (Specified as part of EspStructuredData)

  2. Signature capture response

    Property Condition Value

    ExtendedTransactionType

    C

    3030

    SignatureCheckbox1State

    C

    TRUE or FALSE

    SignatureCheckbox2State

    C

    TRUE or FALSE

    SignatureCheckbox3State

    C

    TRUE or FALSE

    SignatureButtonValue

    C

    ACCEPT, CANCEL or CLEAR

    SignatureData

    C

    String of Base64 data

    SignatureFormat

    C

    String

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties and Callback Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a signature capture request

This is an example of a signature capture request. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts the signature capture transaction with an ADMIN (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="3030"
            SignatureStandAloneDynamicText="Hello"
            SignatureImagePassedInResponse="TRUE"
            SignatureImageFormat="ASCII"
            SignatureScrollableText="Hello"
            SignatureCheckbox1Text="Click me"
            SignatureCheckbox2Text="Select me too"
            SignatureCheckbox2Text="Select me as well"
            Type="ADMIN">
            MessageType="ADMIN_REQUEST">
            <Esp:StructuredData
                Name="SignatureLineItemText1"
                Value="line1">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="SignatureLineItemText2"
                Value="line2">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="SignatureLineItemText3"
                Value="line3">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="SignatureLineItemTextCount"
                Value="3">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

If the transaction completes successfully, then the following is the ADMIN (response) XML message [4] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="3030"
            SignatureCheckbox1State="TRUE"
            SignatureCheckbox2State="TRUE"
            SignatureCheckbox3State="TRUE"
            SignatureButtonValue="ACCEPT"
            SignatureData="ZjAuXiBfO14gPF9fUyBfPSBfPCBfLCBfLCBfKSBfIS"
            SignatureFormat="ASCII"
            Type="ADMIN">
            MessageType="ADMIN_REQUEST">
        </Esp:Transaction>
    </Esp:Interface>

Multiple request signature capture using SignatureAdditionalText

When the SignatureAdditionalText field is set to YES, you can initiate a signature capture over multiple request messages. Each message provides different signature details to eSocket.POS.

If SignatureAdditionalText is set to YES, you can set the following fields in the message:

  1. Signature capture request

    Property Condition Value

    ExtendedTransactionType

    M

    3030

    SignatureStandAloneDynamicText

    M

    String

    SignatureScrollableText

    M

    String

    SignatureCheckbox1Text

    M

    String

    SignatureCheckbox2Text

    M

    String

    SignatureCheckbox3Text

    M

    String

    SignatureAdditionalText

    O

    YES or NO

    SignaturePromptName

    O

    String

    SignatureLineItemTextCount

    O

    String (Specified as part of EspStructuredData)

    SignatureLineItemText

    O

    String (Specified as part of EspStructuredData)

  2. Signature capture response

    Property Condition Value

    ExtendedTransactionType

    C

    3030

    SignatureCheckbox1State

    C

    TRUE or FALSE

    SignatureCheckbox2State

    C

    TRUE or FALSE

    SignatureCheckbox3State

    C

    TRUE or FALSE

    SignatureButtonValue

    C

    NEXT, CANCEL or CLEAR

Example: XML messages in a signature capture request with additional text

This is an example of a signature capture request using SignatureAdditionalText. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts the signature capture transaction with additional text by sending an ADMIN (request) XML message to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="3030"
            SignatureAdditionalText="YES"
            SignatureStandAloneDynamicText="Hello"
            SignatureScrollableText="This is page 1 of 2"
            SignatureCheckbox1Text="Click me"
            SignatureCheckbox2Text="Select me too"
            SignatureCheckbox3Text="Select me as well"
            Type="ADMIN">
            MessageType="ADMIN_REQUEST">
        </Esp:Transaction>
    </Esp:Interface>

The resulting ADMIN (response) XML message from eSocket.POS indicates the user interaction with the signature capture form, but no signature data is returned in this response:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="3030"
            SignatureCheckbox1State="TRUE"
            SignatureCheckbox2State="TRUE"
            SignatureCheckbox3State="TRUE"
            SignatureButtonValue="NEXT"
            Type="ADMIN">
            MessageType="ADMIN_REQUEST">
        </Esp:Transaction>
    </Esp:Interface>

The POS must initiate the signature capture transaction with the next and final screen of additional text by sending an ADMIN (request) XML message to eSocket.POS. The SignatureAdditionalText is omitted or set to NO:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="3030"
            SignatureAdditionalText="NO"
            SignatureStandAloneDynamicText="Hello"
            SignatureImagePassedInResponse="TRUE"
            SignatureImageFormat="ASCII"
            SignatureScrollableText="This is page 2 of 2"
            SignatureCheckbox1Text="Click me"
            SignatureCheckbox2Text="Select me too"
            SignatureCheckbox3Text="Select me as well"
            Type="ADMIN">
            MessageType="ADMIN_REQUEST">
            <Esp:StructuredData
                Name="SignatureLineItemText1"
                Value="line1">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="SignatureLineItemText2"
                Value="line2">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="SignatureLineItemText3"
                Value="line3">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="SignatureLineItemTextCount"
                Value="3">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

If the transaction completes successfully, then the ADMIN (response) XML message from eSocket.POS contains the signature data:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="3030"
            SignatureCheckbox1State="TRUE"
            SignatureCheckbox2State="TRUE"
            SignatureCheckbox3State="TRUE"
            SignatureButtonValue="ACCEPT"
            SignatureData="ZjAuXiBfO14gPF9fUyBfPSBfPCBfLCBfLCBfKSBfIS"
            SignatureFormat="ASCII"
            Type="ADMIN">
            MessageType="ADMIN_REQUEST">
        </Esp:Transaction>
    </Esp:Interface>

3.11.30. Signature lookup request

Introduction

Previously captured signature data may be retrieved from the eSocket.POS database at the request of the POS.

Message flow

Signature Lookup Request- successful

Follow the message flow and refer to the diagram.

1. The POS sends an ADMIN (request) to eSocket.POS that contains a request for signature lookup. The message is linked, via the transaction ID, to a previous transaction that required signature capture. 2. eSocket.POS sends an ADMIN (response) back to the POS. The response includes the retrieved signature image data.

Events and callbacks between the POS device and eSocket.POS

There are no events and callbacks associated with this message.

XML mappings in a single message pair signature lookup request

This section contains the XML properties and values that are typically associated with a signature lookup request. In the Value column, example values are in italics and mandatory values are in bold.

  1. Signature lookup request

    Property Condition Value

    ExtendedTransactionType

    M

    3031

    TransactionId

    M

    195322

    SignatureImageFormat

    O

    JPEG

    If the SignatureImageFormat property is not set, a default value of TIFF will be used. Signature images stored in the eSocket.POS database are encoded in this format.

  2. Signature lookup response

    Property Condition Value

    ExtendedTransactionType

    A

    3031

    TransactionId

    A

    195322

    SignatureImageFormat

    A

    JPEG

    SignatureData

    A

    A string of Base64 data

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a signature lookup request

This is an example of a signature lookup request. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts the signature lookup transaction with an ADMIN (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="3031"
            TransactionId="195322"
            SignatureImageFormat="TIFF"
            Type="ADMIN">
            MessageType="ADMIN_REQUEST">
        </Esp:Transaction>
    </Esp:Interface>

The resulting ADMIN (response) XML message [2] from eSocket.POS following the successful retrieval of the signature image data:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="3031"
            TransactionId="195322"
            SignatureImageFormat="TIFF"
            SignatureData="ZjAuXiBfO14gPF9fUyBfPSBfPCBfLCBfLCBfKSBfIS"
            Type="ADMIN">
            MessageType="ADMIN_REQUEST">
        </Esp:Transaction>
    </Esp:Interface>

3.11.31. Token Lookup (TransArmor)

Introduction

This section discusses a token lookup admin transaction, started at the POS and sent upstream via Postilion for authorization. An example of a successful transaction is provided.

Limitations

The token lookup request from the POS is only supported only for TransArmor tokens and not for tokens generated by the Postilion tokenization solution.

Message flow

Token Lookup - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a TOKEN_LOOKUP (request) XML message to eSocket.POS.

  2. eSocket.POS sends an admin request (0600) to Postilion.

  3. Postilion sends the admin request (0600) upstream.

  4. Postilion receives an admin response (0610) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the admin response (0610) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the token issuer, the appropriate admin response (0610) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Events and callbacks are typically not associated with this message.

XML mappings in a token lookup transaction

This section contains the XML properties and values that are typically associated with a token lookup transaction. In the Value column, example values are shown in italics and mandatory values are shown in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

TOKEN_LOOKUP

RetrievalRefNr

O

000000000083

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a token lookup transaction

This is an example of a token lookup transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a token lookup transaction with a TOKEN_LOOKUP (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
	<Esp:Interface
		Version="1.0"
		xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
		<Esp:Transaction
			TerminalId="SoftTerm"
			TransactionId="195322"
			Type="TOKEN_LOOKUP">
		</Esp:Transaction>
	</Esp:Interface>

The resulting TOKEN_LOOKUP (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
	<Esp:Interface
		Version="1.0"
		xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
		<Esp:Transaction
			Account="00"
			ActionCode="APPROVE"
			BusinessDate="0831"
			DateTime="0831064214"
			ExpiryDate="2012"
			LocalDate="0831"
			LocalTime="084214"
			MerchantId="111111111111111"
			MessageReasonCode="9790"
			PanEntryMode="90"
			PosCondition="00"
			ResponseCode="00"
			RetrievalRefNr="000000000083"
			TerminalId="SoftTerm"
			TransactionId="195322"
			Type="TOKEN_LOOKUP">
			<Esp:StructuredData
				Name="ResponseFromPostilion"
				Value="ResponseFromPostilion">
			</Esp:StructuredData>
			<Esp:StructuredData
				Name="TRANSARMOR_TOKEN"
				Value="1234567890123">
			</Esp:StructuredData>
		</Esp:Transaction>
	</Esp:Interface>

3.11.32. XML - FSA/HSA Purchase

Introduction

This section discusses a FSA/HSA purchase transaction, started at the POS and sent upstream via Postilion for authorization. The example is of a successful transaction.

Message flow

Purchase (single message pair) - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS containing healthcare totals.

  2. eSocket.POS sends a purchase request (0200) to Postilion.

  3. Postilion sends the purchase request (0200) upstream.

  4. Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the purchase response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Events and callbacks are not displayed in the above diagram.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a single message pair purchase transaction:

If registered, the following callbacks are called during a single message pair purchase transaction:

XML mappings for HSA/FSA

This section contains the XML properties and values that are typically associated with a single message pair purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

285078

Type

M

PURCHASE

RetrievalRefNr

O

000000000083

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

710

rts_Total_Healthcare

C

30000

rts_Clinic_Amount

O

15000

rts_Prescription_Amount

O

4000

rts_Dental_Amount

O

5000

rts_Optical_Amount

C

15000

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a FSA/HSA transaction

This is an example of a single message pair purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a single message pair purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
		RtsClinicAmount="15000"
		RtsDentalAmount="5000"
		RtsOpticalAmount="6000"
		RtsPrescriptionAmount="4000"
		RtsTotalHealthcareAmount="30000"
		TerminalId="SoftTerm"
		TransactionAmount="40000"
		TransactionId="285078"
        Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
		Account="10"
		ActionCode="APPROVE"
		AmountTransactionFee="C0"
		AuthorizationProfile="11"
		AuthorizationNumber="935030"
		BusinessDate="0831"
		CardProductName="FSA"
		CurrencyCode="840"
		DateTime="0831064214"
		ExtendedTransactionType="7111"
		LocalDate="0831"
		LocalTime="084214"
		MerchantId="111111111111111"
		ExpiryDate="2012"
		MessageReasonCode="9790"
		PanEntryMode="90"
		PosCondition="00"
		ResponseCode="00"
		TerminalId="SoftTerm"
		TransactionAmount="40000"
		TransactionId="285078"
		Type="PURCHASE">
         <Esp:Balance
		 AccountType="00"
		 Amount="40000"
		AmountType="53"
		CurrencyCode="840"
		Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.11.33. EFT Transaction Inquiry

Introduction

To inquire the status of a transaction previously sent to eSocket.POS after a timeout or any communication failure between eSocket.POS and the POS.

Message flow

EFT transaction inquiry - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a INQUIRY (request) XML message to eSocket.POS.

  2. eSocket.POS sends the appropriate response to the POS device.

Note: No action is taken on the transaction (display transaction outcome, signature etc..), eSocket.POS solely returns the transaction data back to the POS in an embedded EspTransaction object within the response.

XML mappings in a transaction inquiry

This section contains the XML properties and values that are typically associated with a transaction inquiry. The values sent here should match the ones for the original transaction being looked up. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

TRAN_INQUIRY

DateTime

O

1231235959

OriginalMessageType

O

AUTH

OriginalTransactionType

O

PURCHASE

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Inquiry Properties .

If the MessageType is set, only transactions for the given message type will be considered.

If the DateTime is set, only the transaction received at that specific time will be considered.

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a transaction inquiry

This is an example of a transaction inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a transaction inquiry with a TRAN_INQUIRY (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            TerminalId="SoftTerm"
            TransactionId="195322"
            DateTime="1231235959"
            OriginalTransactionType="PURCHASE"
            Type="TRAN_INQUIRY">
        </Esp:Inquiry>
    </Esp:Interface>

If, the transaction is found, the resulting TRAN_INQUIRY (response) XML message [2] from eSocket.POS will include an instance of Esp:Transaction with the transaction data:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            MessageReasonCode="9790"
            ResponseCode="00"
            TransactionId="195322"
            Type="TRAN_INQUIRY">
            OriginalTransactionType="PURCHASE"
            <Esp:Transaction
                CardNumber="333333******3339"
                CurrencyCode="840"
                ExpiryDate="1912"
                ResponseCode="00"
                MessageReasonCode="9790"
                PanEntryMode="05"
                RetrievalRefNr="000000000072"
                FinalAmount="000000000395">
            </Esp:Transaction>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Inquiry>
    </Esp:Interface>

If, the transaction is not found, the resulting TRAN_INQUIRY (response) XML message [2] from eSocket.POS will be a decline message and will not include an Esp:Transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            MessageReasonCode="9720"
            ResponseCode="25"
            TransactionId="195322"
            Type="TRAN_INQUIRY">
        </Esp:Inquiry>
    </Esp:Interface>

If eSocket.POS is busy processing a transaction while the transaction inquiry is received, an error is immediately sent back with response code P3 (Device busy) and message reason code 9647 (Device Currently Busy).

Transaction Inquiry used for token retrieval for offline-approved transactions

If a situation arises where eSocket.POS approves a transaction offline for a particular transaction and neither the TransArmor token nor the card token is returned in Structured Data, in the transaction response to the POS (due to the transaction not reaching Postilion Realtime), then the transaction inquiry mechanism is the recommended approach to retrieve the token after receiving the stand-in advice response from the SINK.

To support this feature, the Transaction Inquiry component must be setup to prioritize advice messages. This is achieved by setting the ADVICE_PRIORITY parameter for the component to give precedence to advice messages over regular requests.

A typical transaction flow for such a scenario would look as follows:

EFT transaction inquiry stand-in token retrieval

  1. eSocket.POS loses connection to Postilion

  2. The POS sends a purchase (request) XML message to eSocket.POS

  3. eSocket.POS sends the approval response to the POS system. It is important to note that this response will not contain the token since it is not available yet.

  4. At this point, the POS system can commence a "polling" procedure where it sends transaction inquiries to eSocket.POS to retrieve a token.

  5. If a token is not accessible eSocket.POS will send a response without a token

  6. The connection is restored between eSocket.POS and Postilion

  7. eSocket.POS retrieves the token from Postilion by sending up a Transaction Advice

  8. Transaction Advice Response (processed by Token Server) contains the token

  9. The POS system can repeat the "polling" procedure to retrieve a token

  10. eSocket.POS can now send a response that contains the token retrieved from Postilion

By following the aforementioned steps, the POS system can retrieve the TransArmor or card token even when initial communication with Postilion Realtime is disrupted or delayed.

NOTE: The TransactionToken Structured Data field can’t be returned to the POS using transaction Inquiries.

Example: TRAN_INQUIRY (response) with a TransArmor token.

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            Account="99"
            ActionCode="APPROVE"
            CardProductName="DefaultCard"
            ExtendedTransactionType="2116"
            MessageReasonCode="9799"
            ResponseCode="00"
            TerminalId="term1   "
            TransactionId="126378"
            Type="TRAN_INQUIRY">
            <Esp:Transaction
                MessageReasonCode="9790"
                PanEntryMode="00"
                PosDataCode="51020105414C002"
                ResponseCode="00">
                <Esp:StructuredData
                    Name="TRANSARMOR_TOKEN"
                    Value="1234567890">
                </Esp:StructuredData>
            </Esp:Transaction>
        </Esp:Inquiry>
    </Esp:Interface>

Example: TRAN_INQUIRY (response) with a card token.

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            Account="99"
            ActionCode="APPROVE"
            CardProductName="DefaultCard"
            ExtendedTransactionType="2116"
            MessageReasonCode="9799"
            ResponseCode="00"
            TerminalId="term1   "
            TransactionId="176394"
            Type="TRAN_INQUIRY">
            <Esp:Transaction
                AuthorizationNumber="1234  "
                CardNumber="333333*********3339"
                CurrencyCode="840"
                ExpiryDate="2312"
                FinalAmount="000000002000"
                MessageReasonCode="9790"
                PanEntryMode="05"
                PosDataCode="51020150014C002"
                ResponseCode="00"
                RetrievalRefNr="000000000072">
                <Esp:StructuredData
                    Name="CardToken"
                    Value="1234567890123">
                </Esp:StructuredData>
            </Esp:Transaction>
        </Esp:Inquiry>
    </Esp:Interface>

3.11.34. Terminal Status

Introduction

To inquire the status of a eSocket.POS that serves a terminal.

Message flow

Terminal Status - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a INQUIRY (request) XML message to eSocket.POS.

  2. eSocket.POS sends the appropriate response to the POS device.

XML mappings in a terminal status inquiry

This section contains the XML properties and values that are typically associated with a terminal status inquiry. The values sent here should match the ones for the original terminal status being looked up. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

TERMINAL_STATUS

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Inquiry Properties.

For an explanation of the Condition column in this table, see Object and Property Conditions.

Example: XML messages in a transaction inquiry

This is an example of a transaction inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a transaction inquiry with a TERMINAL_STATUS (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            TerminalId="SoftTerm"
            TransactionId="195322"
            Type="TERMINAL_STATUS">
        </Esp:Inquiry>
    </Esp:Interface>

TERMINAL_STATUS (response) XML message [2] from eSocket.POS will return monitoring information regrading the all the entities monitored by eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            MessageReasonCode="9791"
            ResponseCode="00"
            TransactionId="195322"
            Type="TERMINAL_STATUS"
            TerminalId="SoftTerm"
            TerminalStatus="000001000000020300#010101010101#Magnetic Stripe Card Reads~1~2|~1 successful~2 reads|#2|1|243|#1">
        </Esp:Inquiry>
    </Esp:Interface>

3.12. Gift card transactions

3.12.1. Gift card activation

Introduction

A gift card must be activated before it is used as a form of payment. This example is of a successful card activation, started at the POS and sent upstream for authorization via Postilion.

Message flow

Gift card activation - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a CARD_ACTIVATE (request) XML message to eSocket.POS with the card details.

  2. eSocket.POS sends an administration request (0600) to Postilion.

  3. Postilion sends the administration request (0600) upstream.

  4. Postilion receives an administration request response (0610) back from the entity upstream responsible for authorizing the activation.

  5. Postilion sends the administration request response (0610) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate administration request response (0610) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a gift card activation:

If registered, the following callbacks are called during a gift card activation:

XML mappings in a gift card activation

This section contains the XML properties and values that are typically associated with gift card activations. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

170818

Type

M

CARD_ACTIVATE

Note : If the transaction amount is present, it has to be zero (which is equivalent to the amount being absent).

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a gift card activation

This is an example of an administration request. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card activation with a CARD_ACTIVATE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionId="170818"
            Type="CARD_ACTIVATE">
        </Esp:Transaction>
    </Esp:Interface>

Note : The POS can also populate the transaction amount, but then it has to be zero (which is equivalent to the amount being absent):

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionId="170818"
            Type="CARD_ACTIVATE"
            TransactionAmount="0">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_ACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            DateTime="0829200820"
            ExpiryDate="2012"
            LocalDate="0829"
            LocalTime="220820"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000120"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionId="170818"
            Type="CARD_ACTIVATE">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.12.2. Gift card activation with load

Introduction

This transaction is performed when the purchase of a gift card occurs and funds are loaded to a gift card. The gift card is activated and loaded with the funds.This example is of a successful gift card activation with load amount, started at the POS and sent upstream for authorization via Postilion.

Message flow

Gift card activation and refund- successful

Follow the message flow and refer to the diagram.

  1. The POS sends a CARD_ACTIVATE (request) XML message to eSocket.POS with the card details.

  2. eSocket.POS sends the Refund request (0200) to Postilion.

  3. Postilion sends the Refund request (0200) to upstream.

  4. Postilion receives the Refund response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends Refund response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate Refund response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a gift card activation transaction:

If registered, the following callbacks are called during a gift card activation transaction:

XML mappings in a gift card activation with load transaction

This section contains the XML properties and values that are typically associated with gift card activation with load transactions. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

170818

Type

M

CARD_ACTIVATE

TransactionAmount

M

30000

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a gift card activation transaction

This is an example of an administration request transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card activation transaction with a CARD_ACTIVATE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionId="170818"
            Type="CARD_ACTIVATE">
            TransactionAmount="30000">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_ACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            DateTime="0829200820"
            ExpiryDate="2012"
            LocalDate="0829"
            LocalTime="220820"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000120"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionId="170818"
            PreviousBalance="450"
            Type="CARD_ACTIVATE">
            TransactionAmount="30000">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.12.3. Gift card activation with load - reversal/void

Introduction

When a gift card is activated and simultaneously loaded with funds and for some reason the activation should not have happened, a reversal is required. The following example describes a gift card which is successfully activated and loaded with funds, and then followed by a reversal advice.

Message flow

Gift card activation - void/reversal

Follow the message flow and refer to the diagram.

  1. The POS sends a CARD_ACTIVATE (request) XML message to eSocket.POS with the card details.

  2. eSocket.POS sends a general credit request (0200) to Postilion.

  3. Postilion sends a general credit request (0200) upstream.

  4. Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the general credit request response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

  7. The POS sends a CARD_ACTIVATE (reversal) XML message to eSocket.POS to reverse the original request transaction.

  8. eSocket.POS sends a CARD_ACTIVATE (reversal response) to the POS device.

  9. eSocket.POS sends a reversal advice (0420) to Postilion.

  10. Postilion sends the reversal advice response (0430) to eSocket.POS.

  11. Postilion sends the reversal advice (0420) upstream.

  12. Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.

Note: If Postilion is the card issuer, the appropriate card activate response (0210) is sent from Postilion, and steps 3 and 4 are eliminated. In this scenario steps 11 and 12 are also eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

The reversal message does not call any events. If registered, the following events are called during a card activate transaction:

The reversal message does not get any callbacks. If registered, the following callbacks are called during a card activate transaction:

XML mappings in a card activate transaction reversal

This section contains the XML properties and values that are typically associated with a card activate transaction. The second table contains the XML properties typically associated with a card activate transaction reversal. In the Value column, example values are in italics and mandatory values are in bold.

  1. Card activate transaction

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    141790

    Type

    M

    CARD_ACTIVATE

    RetrievalRefNr

    O

    00000000008

    PosOperatorId

    O

    PosOp001

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Reversal transaction

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    141790

    TransactionAmount

    M

    30000

    Type

    M

    CARD_ACTIVATE

    Reversal

    C

    TRUE

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Example: XML messages in a card activate transaction reversal

This is an example of a card activate transaction, followed by a transaction to reverse the card activate transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a card activate transaction with a CARD_ACTIVATE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="141790"
            Type="CARD_ACTIVATE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_ACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="086082950"
            ExpiryDate="2012"
            LocalDate="0806"
            LocalTime="102950"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="00000000008"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="141790"
            Type="CARD_ACTIVATE">
            <Esp:Balance
                AccountType="00"
                Amount="30000"
                AmountType="53"
                CurrencyCode="710"
                Sign="D">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS starts a reversal transaction with a CARD_ACTIVATE (reversal) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="TestTerm"
            TransactionId="141790"
            TransactionAmount="30000"
            Type="CARD_ACTIVATE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_ACTIVATE (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0806082951"
            ExpiryDate="2012"
            LocalDate="0806"
            LocalTime="102950"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            Reversal="TRUE"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="141790"
            Type="CARD_ACTIVATE">
        </Esp:Transaction>
    </Esp:Interface>

3.12.4. Gift card activation with load timeout

Introduction

A gift card activation with load transaction is used to activate a gift card while simultaneously loading funds onto the gift card. If a gift card activation with load times out before the POS receives a response, the transaction must be reversed. Reversing a gift card activation with load, will reverse both the activation of the gift card and the loading of funds onto the card. This example describes the activation with load timeout and subsequent reversal.

Message flow

Gift card activation timeout

Follow the message flow and refer to the diagram.

  1. The POS sends a CARD_ACTIVATE (request) XML message to eSocket.POS with the card details and the final amount to be loaded.

  2. eSocket.POS sends a general credit request (0200) to Postilion.

  3. Postilion sends the general credit request (0200) upstream.

  4. Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the general credit request response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device. However, the response doesn’t reach the POS and a timeout occurs.

  7. The POS sends a CARD_ACTIVATE (reversal) XML message to eSocket.POS to reverse the original request transaction.

  8. eSocket.POS sends a CARD_ACTIVATE (reversal response) to the POS device.

  9. eSocket.POS sends a reversal advice (0420) to Postilion. eSocket.POS will resend the reversal advice (0420) to Postilion until it receives a response.

  10. Postilion sends the reversal advice response (0430) to eSocket.POS.

  11. Postilion sends the reversal advice (0420) upstream. Postilion will resend the reversal advice (0420) to the network until it receives a response.

  12. Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.

Note: If Postilion is the card issuer, the appropriate general credit request response (0210) and reversal advice response (0430) is sent from Postilion, and steps 3, 4, 11, and 12 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a general credit transaction:

If registered, the following callbacks are called during a general credit transaction:

XML mappings in a gift card activation with load timeout

This section contains the XML properties and values that are typically associated with a gift card activation with load timeout. In the Value column, example values are in italics and mandatory values are in bold.

  1. Gift card activation with load

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    125872

    Type

    M

    CARD_ACTIVATE

    TransactionAmount

    O

    30000

    RetrievalRefNr

    O

    000000000086

    PosOperatorId

    O

    PosOp001

  2. Gift card activation with load reversal

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    125872

    Type

    M

    CARD_ACTIVATE

    Reversal

    C

    TRUE

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of these tables, see Object and Property Conditions .

Example: XML messages in a gift card activation with load timeout

This is an example of a gift card activation with load transaction, followed by a transaction to reverse the activation with load when a timeout occurs between eSocket.POS and the POS. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts an general credit request transaction with a CARD_ACTIVATE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionId="125872"
            Type="CARD_ACTIVATE">
            TransactionAmount="30000">
        </Esp:Transaction>
    </Esp:Interface>

The POS starts a reversal transaction with a CARD_ACTIVATE (reversal) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="TestTerm"
            TransactionId="125872"
            Type="CARD_ACTIVATE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_ACTIVATE (reversal response) XML message [8] from eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0913084441"
            ExpiryDate="2012"
            ExtendedTransactionType="3100"
            LocalDate="0913"
            LocalTime="104440"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            Reversal="TRUE"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="125872"
            Type="CARD_ACTIVATE">
        </Esp:Transaction>
    </Esp:Interface>

3.12.5. Gift card load funds

Introduction

This is an example is of a successful funds load to a gift card, performed at the POS and sent upstream for authorization.

Message flow

Gift card load funds

Follow the message flow and refer to the diagram.

  1. The POS sends a LOAD (request) XML message to eSocket.POS with the amount.

  2. eSocket.POS sends a general credit request (0200) to Postilion.

  3. Postilion sends the general credit request (0200) upstream.

  4. Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the general credit request response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate general credit request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a gift card funds load:

If registered, the following callbacks are called during a gift card funds load:

XML mappings in a gift card funds load

This section contains the XML properties and values that are typically associated with a gift card funds load transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

170822

Type

M

LOAD

TransactionAmount

G

30000

CurrencyCode

O

710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Example: XML messages in a gift card funds load

This is an example of a gift card funds load. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card with a LOAD (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170822"
            Type="LOAD">
        </Esp:Transaction>
    </Esp:Interface>

The resulting LOAD (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0829200907"
            ExpiryDate="2012"
            ExtendedTransactionType="6501"
            LocalDate="0829"
            LocalTime="220907"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000126"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170822"
            Type="LOAD">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.12.6. Gift card reversal/void

Introduction

Where a gift card is loaded with money and for some reason the load should not have happened, a reversal is required. The following example describes a gift card, loaded successfully, and then followed by a reversal advice.

Message flow

Gift card reversal/void

Follow the message flow and refer to the diagram.

  1. The POS sends a LOAD (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS sends a general credit request (deposit verified by operator) (0200) to Postilion.

  3. Postilion sends the general credit request (0200) upstream.

  4. Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the general credit request response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device. At this stage, the general credit request transaction is completed.

  7. The POS sends a LOAD (reversal) XML message to eSocket.POS to reverse the original request transaction.

  8. eSocket.POS sends a LOAD (reversal response) to the POS device.

  9. eSocket.POS sends a reversal advice (0420) to Postilion.

  10. Postilion sends the reversal advice response (0430) to eSocket.POS.

  11. Postilion sends the reversal advice (0420) upstream.

  12. Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.

Note: If Postilion is the card issuer, the appropriate general credit request response (0210) and the reversal advice (0420) is sent from Postilion, and steps 3, 4, 11 and 12 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

The reversal message does not call any events. If registered, the following events are called during a gift card load:

The reversal message does not get any callbacks. If registered, the following callbacks are called during a gift card:

XML mappings in a gift card load reversal

This section contains the XML properties and values that are typically associated with a gift card load transaction. The second table contains the XML properties typically associated with a gift card load reversal. In the Value column, example values are in italics and mandatory values are in bold.

  1. Gift card load

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    170823

    Type

    M

    LOAD

    TransactionAmount

    G

    30000

    CurrencyCode

    O

    710

  2. Reversal transaction

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    170823

    Type

    M

    LOAD

    Reversal

    C

    TRUE

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Example: XML messages in a gift card load reversal

This is an example of a gift card load, followed by a transaction to reverse the load transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card with a LOAD (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170823"
            Type="LOAD">
        </Esp:Transaction>
    </Esp:Interface>

The resulting LOAD (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0829200910"
            ExpiryDate="2012"
            ExtendedTransactionType="6501"
            LocalDate="0829"
            LocalTime="220910"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000127"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170823"
            Type="LOAD">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS starts a reversal transaction with a LOAD (reversal) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="TestTerm"
            TransactionId="170823"
            Type="LOAD">
        </Esp:Transaction>
    </Esp:Interface>

The resulting LOAD (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0829200912"
            ExpiryDate="2012"
            ExtendedTransactionType="6501"
            LocalDate="0829"
            LocalTime="220910"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            Reversal="TRUE"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170823"
            Type="LOAD">
        </Esp:Transaction>
    </Esp:Interface>

3.12.7. Gift card unload funds

Introduction

This transaction is performed when funds have to be removed from the gift card account but the account will remain active. This is an example of a successful transaction that removes funds from a gift card account(status remains active), performed at the POS and sent upstream for authorization.

Message flow

Gift card unload funds

Follow the message flow and refer to the diagram.

  1. The POS sends a UNLOAD (request) XML message to eSocket.POS with the amount.

  2. eSocket.POS sends a general credit request (0200) to Postilion.

  3. Postilion sends the general credit request (0200) upstream.

  4. Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the general credit request response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate general credit request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a gift card funds unload:

If registered, the following callbacks are called during a gift card funds unload:

XML mappings in a gift card funds unload

This section contains the XML properties and values that are typically associated with a gift card funds unload transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

170822

Type

M

UNLOAD

TransactionAmount

O

30000

CurrencyCode

O

710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Example: XML messages in a gift card funds unload

This is an example of a gift card funds unload. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card with a UNLOAD (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170822"
            Type="UNLOAD">
        </Esp:Transaction>
    </Esp:Interface>

The resulting UNLOAD (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0829200907"
            ExpiryDate="2012"
            ExtendedTransactionType="6501"
            LocalDate="0829"
            LocalTime="220907"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000126"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170822"
            Type="UNLOAD">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.12.8. Gift card unload - reversal/void

Introduction

This transaction is performed when funds were removed from a gift card account(status remains active) and for some reason that should not have happened and hence a reversal is required. This example is of a successful gift card unload, started at the POS and sent upstream for authorization via Postilion and then followed by a reversal advice.

Message flow

Gift card unload funds void

Follow the message flow and refer to the diagram.

  1. The POS sends a UNLOAD (request) XML message to eSocket.POS with the amount.

  2. eSocket.POS sends a general credit request (0200) to Postilion.

  3. Postilion sends the general credit request (0200) upstream.

  4. Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the general credit request response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

  7. The POS sends a UNLOAD (reversal) XML message to eSocket.POS to reverse the original request transaction.

  8. eSocket.POS sends a UNLOAD (reversal response) to the POS device.

  9. eSocket.POS sends a reversal advice (0420) to Postilion.

  10. Postilion sends the reversal advice response (0430) to eSocket.POS.

  11. Postilion sends the reversal advice (0420) upstream.

  12. Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.

Note: If Postilion is the card issuer, the appropriate general credit request response (0210) and the reversal advice (0420) is sent from Postilion, and steps 3, 4, 11 and 12 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a gift card funds unload:

If registered, the following callbacks are called during a gift card funds unload:

XML mappings in a gift card funds unload

This section contains the XML properties and values that are typically associated with a gift card funds unload transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

170822

Type

M

UNLOAD

TransactionAmount

O

30000

CurrencyCode

O

710

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Example: XML messages in a gift card funds unload reversal

This is an example of a gift card funds unload, followed by a transaction to reverse the unload transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card with a UNLOAD (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170822"
            Type="UNLOAD">
        </Esp:Transaction>
    </Esp:Interface>

The resulting UNLOAD (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0829200907"
            ExpiryDate="2012"
            ExtendedTransactionType="6501"
            LocalDate="0829"
            LocalTime="220907"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000126"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170822"
            Type="UNLOAD">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS starts a reversal transaction with a UNLOAD (reversal) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="TestTerm"
            TransactionId="170823"
            Type="UNLOAD">
        </Esp:Transaction>
    </Esp:Interface>

The resulting UNLOAD (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0829200912"
            ExpiryDate="2012"
            ExtendedTransactionType="6501"
            LocalDate="0829"
            LocalTime="220910"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            Reversal="TRUE"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170823"
            Type="UNLOAD">
        </Esp:Transaction>
    </Esp:Interface>

3.12.9. Gift card activation and refund

Introduction

This transaction is performed when the purchase of a gift card occurs for merchandise returns or unfulfilled orders. The gift card is activated and loaded with the funds. This transaction differs from regular activations in that the customer does not tender funds to provide the value. This example is of a successful gift card refund activation, started at the POS and sent upstream for authorization via Postilion.

Message flow

Gift card activation and refund- successful

Follow the message flow and refer to the diagram.

  1. The POS sends a CARD_ACTIVATE_REFUND (request) XML message to eSocket.POS with the card details.

  2. eSocket.POS sends the Refund request (0200) to Postilion.

  3. Postilion sends the Refund request (0200) to upstream.

  4. Postilion receives the Refund response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends Refund response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate Refund response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a gift card activation transaction:

If registered, the following callbacks are called during a gift card activation transaction:

XML mappings in a gift card activation transaction

This section contains the XML properties and values that are typically associated with gift card activation transactions. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

170818

Type

M

CARD_ACTIVATE_REFUND

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a gift card activation transaction

This is an example of an administration request transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card activation transaction with a CARD_ACTIVATE_REFUND (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionId="170818"
            Type="CARD_ACTIVATE_REFUND">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_ACTIVATE_REFUND (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            DateTime="0829200820"
            ExpiryDate="2012"
            LocalDate="0829"
            LocalTime="220820"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000120"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionId="170818"
            PreviousBalance="450"
            Type="CARD_ACTIVATE_REFUND">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.12.10. Gift card activation and refund - reversal/void

Introduction

This transaction is performed when the purchase of a gift card occurs for a merchandise returns or unfulfilled orders and for some reason it needs to be reversed. This example is of a successful gift card refund activation, started at the POS and sent upstream for authorization via Postilion and then followed by a reversal advice.

Message flow

Gift card activate refund reversal/void

Follow the message flow and refer to the diagram.

  1. The POS sends a CARD_ACTIVATE_REFUND (request) XML message to eSocket.POS with the card details.

  2. eSocket.POS sends the Refund request (0200) to Postilion.

  3. Postilion sends the Refund request (0200) to upstream.

  4. Postilion receives the Refund response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends Refund response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

  7. The POS sends a CARD_ACTIVATE_REFUND (reversal) XML message to eSocket.POS to reverse the original request transaction.

  8. eSocket.POS sends a CARD_ACTIVATE_REFUND (reversal response) to the POS device.

  9. eSocket.POS sends a reversal advice (0420) to Postilion.

  10. Postilion sends the reversal advice response (0430) to eSocket.POS.

  11. Postilion sends the reversal advice (0420) upstream.

  12. Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.

Note: If Postilion is the card issuer, the appropriate general credit request response (0210) and the reversal advice (0420) is sent from Postilion, and steps 3, 4, 11 and 12 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

The reversal message does not call any events. If registered, the following events are called during a gift card load:

The reversal message does not get any callbacks. If registered, the following callbacks are called during a gift card:

XML mappings in a gift card activate refund reversal

This section contains the XML properties and values that are typically associated with a gift card activate refund transaction. The second table contains the XML properties typically associated with a gift card activate refund reversal. In the Value column, example values are in italics and mandatory values are in bold.

  1. Gift card activate refund reversal

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    170823

    Type

    M

    CARD_ACTIVATE_REFUND

  2. Reversal transaction

    Property Condition Value

    TerminalId

    M

    TestTerm

    TransactionId

    M

    170823

    Type

    M

    CARD_ACTIVATE_REFUND

    Reversal

    C

    TRUE

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column of this table, see Object and Property Conditions .

Example: XML messages in a gift card activate refund reversal

This is an example of a gift card activate refund , followed by a transaction to reverse of card activate refund transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card with a CARD_ACTIVATE_REFUND (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170823"
            Type="CARD_ACTIVATE_REFUND">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_ACTIVATE_REFUND (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0829200910"
            ExpiryDate="2012"
            ExtendedTransactionType="6501"
            LocalDate="0829"
            LocalTime="220910"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000127"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170823"
            Type="CARD_ACTIVATE_REFUND">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS starts a reversal transaction with a CARD_ACTIVATE_REFUND (reversal) XML message [7] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="TestTerm"
            TransactionId="170823"
            Type="CARD_ACTIVATE_REFUND">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_ACTIVATE_REFUND (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0829200912"
            ExpiryDate="2012"
            ExtendedTransactionType="6501"
            LocalDate="0829"
            LocalTime="220910"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            Reversal="TRUE"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="30000"
            TransactionId="170823"
            Type="CARD_ACTIVATE_REFUND">
        </Esp:Transaction>
    </Esp:Interface>

3.12.11. Gift card de-activation

3.12.12. Gift card de-activation

Introduction

This section discusses gift card de-activation, started at the POS and sent upstream via Postilion for authorization. The example is of a successful de-activation.

Message flow

Gift card de-activation - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a CARD_DEACTIVATE (request) XML message to eSocket.POS.

  2. eSocket.POS sends an administration request (0600) to Postilion.

  3. Postilion sends the administration request (0600) upstream.

  4. Postilion receives an administration response (0610) back from the entity upstream.

  5. Postilion sends the administration response (0610) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate administration response (0610) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a gift card de-activation:

If registered, the following callbacks are called during a gift card de-activation:

XML mappings in a gift card de-activation

This section contains the XML properties and values that are typically associated with a gift card de-activation. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

375329

Type

M

CARD_DEACTIVATE

RetrievalRefNr

O

000000000354

PosOperatorId

O

PosOp001

Note : If the transaction amount is present, it has to be zero (which is equivalent to the amount being absent).

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a gift card de-activation.

This is an example of a gift card de-activation. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card de-activation with a CARD_DEACTIVATE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionId="375329"
            Type="CARD_DEACTIVATE">
        </Esp:Transaction>
    </Esp:Interface>

Note : The POS can also populate the transaction amount, but then it has to be zero (which is equivalent to the amount being absent):

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="SoftTerm"
            TransactionId="375329"
            Type="CARD_DEACTIVATE"
            TransactionAmount="0">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_DEACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the de-activation:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0831"
            CardProductName="AllOtherCard"
            DateTime="0831064214"
            ExpiryDate="2012"
            ExtendedTransactionType="3101"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000354"
            ServiceRestrictionCode="***"
            TerminalId="SoftTerm"
            TransactionId="375329"
            Type="CARD_DEACTIVATE">
            <Esp:Balance
                AccountType="00"
                Amount="50000"
                AmountType="02"
                CurrencyCode="710"
                Sign="C">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.12.13. Gift card deactivation with unload

Introduction

This transaction is performed when the gift card is de-activated following the removal of remaining funds on the card (i.e. cashback). This is an example of a successful transaction that removes remaining funds from a gift card account and then de-activates the card, performed at the POS and sent upstream for authorization.

Message flow

Gift card activation and refund- successful

Follow the message flow and refer to the diagram.

  1. The POS sends a CARD_DEACTIVATE (request) XML message to eSocket.POS with the card details and amount.

  2. eSocket.POS sends a general debit request (0200) to Postilion.

  3. Postilion sends the general debit request (0200) to upstream.

  4. Postilion receives a general debit request response (0210) back from the entity upstream responsible for authorizing the transaction.

  5. Postilion sends the general debit request response (0210) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate general debit request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a gift card de-activation with unload transaction:

If registered, the following callbacks are called during a gift card de-activation with unload transaction:

XML mappings in a gift card de-activation with unload transaction

This section contains the XML properties and values that are typically associated with gift card de-activation with unload transactions. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

170818

Type

M

CARD_DEACTIVATE

TransactionAmount

M

30000

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Transaction Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a gift card de-activation with unload transaction

This is an example of a gift card de-activation with unload transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card de-activation with unload transaction with a CARD_DEACTIVATE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionId="170818"
            Type="CARD_DEACTIVATE">
            TransactionAmount="30000">
        </Esp:Transaction>
    </Esp:Interface>

The resulting CARD_DEACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="AllOtherCard"
            DateTime="0829200820"
            ExpiryDate="2012"
            ExtendedTransactionType="6502"
            LocalDate="0829"
            LocalTime="220820"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000120"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionId="170818"
            Type="CARD_DEACTIVATE"
            TransactionAmount="30000">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.12.14. Gift card balance inquiry

Introduction

To confirm the funds available on a gift card, a balance inquiry is started at the POS and sent upstream via Postilion. This section discusses a successful balance inquiry.

Message flow

Gift card balance inquiry - successful

Follow the message flow and refer to the diagram.

  1. The POS sends a BALANCE (request) XML message to eSocket.POS.

  2. eSocket.POS sends an authorization request (0100) to Postilion.

  3. Postilion sends the authorization request (0100) upstream.

  4. Postilion receives an authorization request response (0110) back from the entity upstream.

  5. Postilion sends the authorization request response (0110) to eSocket.POS.

  6. eSocket.POS sends the appropriate response to the POS device.

Note: If Postilion is the card issuer, the appropriate authorization response (0110) is sent from Postilion, and steps 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during a gift card balance inquiry:

If registered, the following callbacks are called during a gift card balance inquiry:

XML mappings in a gift card balance inquiry

This section contains the XML properties and values that are typically associated with a gift card balance inquiry. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

BALANCE

RetrievalRefNr

O

000000000354

PosOperatorId

O

PosOp001

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Inquiry Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a gift card balance inquiry

This is an example of a gift card balance inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a gift card balance inquiry with a BALANCE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            TerminalId="SoftTerm"
            TransactionId="195322"
            Type="BALANCE">
        </Esp:Inquiry>
    </Esp:Interface>

The resulting BALANCE (response) XML message [6] from eSocket.POS following the successful completion of the balance inquiry:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            Account="00"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            BusinessDate="0831"
            CardProductName="AllOtherCard"
            CurrencyCode="710"
            DateTime="0831064214"
            ExpiryDate="2012"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000354"
            ServiceRestrictionCode="***"
            TerminalId="SoftTerm"
            TransactionAmount="0"
            TransactionId="195322"
            Type="BALANCE">
            <Esp:Balance
                AccountType="70"
                Amount="500000"
                AmountType="01"
                CurrencyCode="710"
                Sign="C">
            </Esp:Balance>
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Inquiry>
    </Esp:Interface>

3.12.15. Gift card Purchase - reversal/void

Introduction

When a purchase transaction using gift card is approved and for some reason the transaction needs to be reversed, a reversal is required.

A gift card purchase reversal/void is identical to a normal purchase reversal/void. Refer to the Purchase and reversal/void page for the complete message flow, events and callbacks, XML mappings, and examples.

3.13. EBT transactions

3.13.1. XML - EBT balance inquiry

Introduction

To confirm the cash benefit or food stamp account balances available on an EBT card, a balance inquiry is started at the POS and sent upstream via Postilion. In the message flow outlined in this topic, eSocket.POS drives the PED and prompts for the account.

Message flow

EBT balance inquiry

Follow the message flow and refer to the diagram.

  1. The POS sends a BALANCE (request) XML message to eSocket.POS.

  2. eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS.

  3. The cardholder selects the account type.

  4. eSocket.POS sends an authorization request (0100) to Postilion.

  5. Postilion sends the authorization request (0100) upstream.

  6. Postilion receives an authorization request response (0110) back from the entity upstream.

  7. Postilion sends the authorization request response (0110) to eSocket.POS.

  8. eSocket.POS sends the appropriate response to the POS device.

Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during an EBT balance inquiry:

If registered, the following callbacks are called during an EBT balance inquiry:

XML mappings in an EBT balance inquiry

The following table contains the XML properties and values that are typically associated with an EBT balance inquiry request. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

BALANCE

RetrievalRefNr

O

000000000354

PosOperatorId

O

PosOp001

The following table contains the XML properties and values specific to an EBT balance inquiry response. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

EbtResponseText

C

EBT Response Text

EbtAvailableFoodStampAccountBalance

C

D00000003000

EbtAvailableCashBenefitsAccountBalance

C

D00000002500

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Inquiry Properties.

For an explanation of the Condition column in this table, see Object and Property Conditions.

Example: XML messages in an EBT balance inquiry

This is an example of a successful EBT balance inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts an EBT balance inquiry with a BALANCE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            TerminalId="SoftTerm"
            TransactionId="195322"
            Type="BALANCE">
        </Esp:Inquiry>
    </Esp:Interface>

The resulting BALANCE (response) XML message [8] from eSocket.POS following the successful completion of the balance inquiry follows, assuming the benefit type selected by the cardholder was the cash benefit (account type 96):

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            Account="96"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            BusinessDate="0831"
            CardProductName="EbtCard"
            CurrencyCode="840"
            DateTime="0831064214"
            ExpiryDate="2030"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000354"
            ServiceRestrictionCode="***"
            TerminalId="SoftTerm"
            TransactionAmount="0"
            TransactionId="195322"
            EbtResponseText="EBT Response Text"
            EbtAvailableCashBenefitsAccountBalance="D00000002500"
            Type="BALANCE">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Inquiry>
    </Esp:Interface>

3.13.2. XML - EBT food stamp purchase with electronic voucher

Introduction

This example represents an EBT food stamp purchase transaction that is declined upstream with response code 91 (host unavailable). The transaction is then approved using an external authorization process, such as a telephone call. To complete the transaction, an EBT food stamp electronic voucher advice, which includes all relevant data, is sent upstream. In the message flow outlined here:

  • eSocket.POS drives the PED and prompts for the account.

  • The timeout occurs between Postilion and the upstream host.

    Note
    The timeout can also occur between eSocket.POS and Postilion, or between the POS and eSocket.POS. In the latter case, the POS needs to send a timeout reversal before the purchase referral. See Purchase with timeout and reversal/void for details.
Message flow

EBT food stamp purchase with electronic voucher

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS. The cardholder selects 98 (food stamp).

  3. The cardholder selects the account type.

  4. eSocket.POS sends a purchase request (0200) to Postilion.

  5. Postilion sends the purchase request (0200) upstream.

  6. Postilion times out while waiting for a purchase response (0210) from the entity upstream responsible for authorizing the transaction.

    Note
    Although not indicated on the diagram, Postilion sends a reversal advice (0420) upstream at this point to cancel any impact the original purchase request may have had on the cardholder’s account.
  7. Postilion sends a purchase response (0210) to eSocket.POS.

  8. eSocket.POS sends the appropriate response to the POS device.

  9. After receiving approval through the external voice authorization process, the POS sends a PURCHASE REFERRAL (request) XML message to eSocket.POS with the relevant data and transaction amount.

  10. eSocket.POS sends the appropriate response to the POS device.

  11. eSocket.POS generates a referral advice request (0220) and sends it to Postilion. eSocket.POS will resend the referral advice request (0220) to Postilion until it receives a response.

  12. Postilion receives the referral advice request and sends a referral advice response (0230) to eSocket.POS.

  13. Postilion sends the referral advice request (0220) upstream. Postilion will resend the referral advice request (0220) to the network until it receives a response.

  14. Postilion receives a referral advice response (0230) from the entity upstream responsible for authorizing the transaction.

Note
The message flow assumes the voice authorization occurs while the cardholder is in the lane and the original purchase transaction (with the card details) can be looked up in eSocket.POS. If the cardholder needs to leave the lane for the voice authorization (for example, to go to a customer service desk), and the EBT food stamp electronic voucher is initiated on a different POS which only supports manual PAN entry, eSocket.POS will prompt for manual PAN entry when receiving the PURCHASE REFERRAL (request) XML message [9].

Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during an EBT purchase transaction:

If registered, the following callbacks are called during an EBT purchase transaction:

XML mappings in an EBT food stamp purchase transaction with electronic voucher

The following table contains the XML properties and values that are typically associated with an EBT food stamp purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

PURCHASE

RetrievalRefNr

O

00000000083

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

710

The following table contains the XML properties and values that are typically associated with an EBT food stamp electronic voucher advice. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

SoftTerm

TransactionId

M

195322

Type

M

PURCHASE

MessageType

M

REFERRAL

TransactionAmount

G

30000

CurrencyCode

O

710

RetrievalRefNr

O

000000000083

PosOperatorId

O

PosOp001

AuthorizationNumber

C

*123456*

EbtVoucherNumber

C

*123456*

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Transaction Properties.

For an explanation of the Condition column in these tables, see Object and Property Conditions.

Example: XML messages in a purchase transaction with referral

This is an example of a purchase transaction with referral. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            PosOperatorId="PosOp001"
            RetrievalRefNr="000000000083"
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (response) XML message [8] from eSocket.POS with a host unavailable response code follows, assuming the benefit type selected by the cardholder was food stamp (account type 98):

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="98"
            ActionCode="AUTH"
            AmountTransactionFee="C0"
            AuthorizationProfile="30"
            BusinessDate="0831"
            CardProductName="EbtCard"
            CurrencyCode="710"
            DateTime="0831084214"
            ExpiryDate="2012"
            LocalDate="0831"
            LocalTime="084214"
            MerchantId="311111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="91"
            RetrievalRefNr="000000000083"
            TerminalId="SoftTerm"
            TransactionAmount="0"
            TransactionId="195322"
            Type="PURCHASE">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS sends a PURCHASE REFERRAL (request) XML message [9] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            MessageType="REFERRAL"
            PosOperatorId="PosOp001"
            ResponseCode="00"
            TerminalId="SoftTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            AuthorizationNumber="123456"
            EbtVoucherNumber="123456"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE REFERRAL (response) XML message [10] from eSocket.POS follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="98"
            ActionCode="APPROVE"
            AuthorizationNumber="123456"
            CardNumber="111122******4444"
            CardProductName="EbtCard"
            CurrencyCode="710"
            DateTime="0831084215"
            ExpiryDate="2012"
            LocalDate="0831"
            LocalTime="084215"
            MerchantId="311111111111111"
            MessageReasonCode="9792"
            MessageType="REFERRAL"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="000000000084"
            TerminalId="SofttTerm"
            TransactionAmount="30000"
            TransactionId="195322"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

3.13.3. XML - EBT purchase (including with cash back)

Introduction

This section discusses an EBT purchase transaction, started at the POS and sent upstream via Postilion for authorization and approval. In the message flow outlined here, eSocket.POS drives the PED and prompts for the account.

Message flow

EBT purchase

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS.

  3. The cardholder selects the account type.

  4. If account type 96 (cash benefit) was selected, eSocket.POS displays a prompt on the PED to the cardholder for the cash back amount.

  5. If account type 96 (cash benefit) was selected, the cardholder is given the option to enter a cash back amount. If an amount was entered, eSocket.POS changes the ISO 8583 transaction type to 09 (goods and services with cash back).

    Note
    If the transaction amount from the POS is zero while the cashback amount is non-zero, it indicates a cashback only (withdrawal) transaction.
  6. eSocket.POS sends a purchase request (0200) to Postilion.

  7. Postilion sends the purchase request (0200) upstream.

  8. Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.

  9. Postilion sends the purchase response (0210) to eSocket.POS.

  10. eSocket.POS sends the appropriate response to the POS device.

Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during an EBT purchase transaction:

If registered, the following callbacks are called during an EBT purchase transaction:

XML mappings in an EBT purchase transaction

The following table contains the XML properties and values that are typically associated with an EBT purchase transaction request. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

141790

Type

M

PURCHASE

RetrievalRefNr

O

00000000008

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

810

The following table contains the XML properties and values specific to an EBT purchase transaction response. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

EbtVoucherNumber

C

123456

EbtCaseNumber

C

1234567890

EbtResponseText

C

EBT Response Text

EbtBeginningFoodStampAccountBalance

C

D00000003000

EbtEndingFoodStampAccountBalance

C

D00000002000

EbtAvailableFoodStampAccountBalance

C

D00000002000

EbtBeginningCashBenefitsAccountBalance

C

D00000002500

EbtEndingCashBenefitsAccountBalance

C

D00000001500

EbtAvailableCashBenefitsAccountBalance

C

D00000001500

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Transaction Properties.

For an explanation of the Condition column in this table, see Object and Property Conditions.

Example: XML messages in an EBT purchase transaction

This is an example of a successful EBT purchase transaction The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts an EBT purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="1000"
            TransactionId="141790"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (response) XML message [10] from eSocket.POS following the successful completion of the transaction follows, assuming the benefit type selected by the cardholder was the cash benefit (account type 96):

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="96"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="EbtCard"
            CurrencyCode="840"
            DateTime="0806082950"
            ExpiryDate="2030"
            LocalDate="0806"
            LocalTime="082950"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="00000000008"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="1000"
            TransactionId="141790"
            EbtVoucherNumber="123456"
            EbtCaseNumber="1234567890"
            EbtResponseText="EBT Response Text"
            EbtEndingCashBenefitsAccountBalance="D00000002000"
            Type="PURCHASE">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.13.4. XML - EBT purchase and reversal/void

Introduction

This section discusses an EBT purchase transaction, started at the POS and sent upstream via Postilion for authorization and approval. After the transaction is approved, it needs to be reversed/voided for some reason. The purchase transaction is therefore followed by a reversal advice. In the message flow outlined here, eSocket.POS drives the PED and prompts for the account.

Message flow

EBT purchase and reversal/void

Follow the message flow and refer to the diagram.

  1. The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.

  2. eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS.

  3. The cardholder selects the account type.

  4. If account type 96 (cash benefit) was selected, eSocket.POS displays a prompt on the PED to the cardholder for the cash back amount.

  5. If account type 96 (cash benefit) was selected, the cardholder is given the option to enter a cash back amount. If an amount was entered, eSocket.POS changes the ISO 8583 transaction type to 09 (goods and services with cash back).

    Note
    If the transaction amount from the POS is zero while the cashback amount is non-zero, it indicates a cashback only (withdrawal) transaction.
  6. eSocket.POS sends a purchase request (0200) to Postilion.

  7. Postilion sends the purchase request (0200) upstream.

  8. Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.

  9. Postilion sends the purchase response (0210) to eSocket.POS.

  10. eSocket.POS sends the appropriate response to the POS device. At this stage, the purchase transaction is completed.

  11. The POS sends a PURCHASE (reversal) XML message to eSocket.POS to reverse the original request transaction.

  12. eSocket.POS sends a PURCHASE (reversal response) to the POS device.

  13. eSocket.POS sends a reversal advice (0420) to Postilion.

  14. Postilion sends the reversal advice response (0430) to eSocket.POS.

  15. Postilion sends the reversal advice (0420) upstream.

  16. Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.

Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

The reversal message does not call any events. If registered, the following events are called during an EBT purchase transaction:

The reversal message does not get any callbacks. If registered, the following callbacks are called during an EBT purchase transaction:

XML mappings in an EBT purchase transaction reversal

The following table contains the XML properties and values that are typically associated with an EBT purchase transaction request. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

141790

Type

M

PURCHASE

RetrievalRefNr

O

00000000008

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

810

The following table contains the XML properties and values that are specific to an EBT purchase transaction response. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

EbtVoucherNumber

C

123456

EbtCaseNumber

C

1234567890

EbtResponseText

C

EBT Response Text

EbtBeginningFoodStampAccountBalance

C

D00000003000

EbtEndingFoodStampAccountBalance

C

D00000002000

EbtAvailableFoodStampAccountBalance

C

D00000002000

EbtBeginningCashBenefitsAccountBalance

C

D00000002500

EbtEndingCashBenefitsAccountBalance

C

D00000001500

EbtAvailableCashBenefitsAccountBalance

C

D00000001500

The following table contains the XML properties and values that are typically associated with an EBT purchase reversal. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

141790

Type

M

PURCHASE

Reversal

C

TRUE

MessageReasonCode

O

4000

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Transaction Properties.

For an explanation of the Condition column of this table, see Object and Property Conditions.

Example: XML messages in an EBT purchase transaction reversal

This is an example of a successful EBT purchase transaction, followed by an EBT purchase reversal to reverse the purchase transaction due to a customer cancellation (for example, the MessageReasonCode is set to 4000). The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts an EBT purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="1000"
            TransactionId="141790"
            MessageReasonCode="4000"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (response) XML message [10] from eSocket.POS following the successful completion of the transaction follows, assuming the benefit type selected by the cardholder was food stamp (account type 98):

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="98"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="EbtCard"
            CurrencyCode="840"
            DateTime="0806082950"
            ExpiryDate="2030"
            LocalDate="0806"
            LocalTime="082950"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="00000000008"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="1000"
            TransactionId="141790"
            EbtVoucherNumber="123456"
            EbtCaseNumber="1234567890"
            EbtResponseText="EBT Response Text"
            EbtEndingFoodStampAccountBalance="D00000002000"
            Type="PURCHASE">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

The POS starts an EBT purchase reversal with a PURCHASE (reversal) XML message [11] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Reversal="TRUE"
            TerminalId="TestTerm"
            TransactionId="141790"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

The resulting PURCHASE (reversal response) XML message [12] from eSocket.POS following the successful completion of the transaction follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="98"
            ActionCode="APPROVE"
            CardNumber="111122******4444"
            CardProductName="EbtCard"
            CurrencyCode="840"
            DateTime="0806083350"
            ExpiryDate="2030"
            LocalDate="0806"
            LocalTime="083350"
            MerchantId="111111111111111"
            MessageReasonCode="9792"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            Reversal="TRUE"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="1000"
            TransactionId="141790"
            EbtVoucherNumber="123456"
            Type="PURCHASE">
        </Esp:Transaction>
    </Esp:Interface>

3.13.5. XML - EBT refund

Introduction

This section discusses an EBT refund transaction, started at the POS and sent upstream via Postilion for authorization and approval. In the message flow outlined here, eSocket.POS drives the PED and prompts for the account.

Message flow

EBT refund

Follow the message flow and refer to the diagram.

  1. The POS sends a REFUND (request) XML message to eSocket.POS.

  2. eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS.

  3. The cardholder selects the account type.

  4. eSocket.POS sends a refund request (0200) to Postilion.

  5. Postilion sends the refund request (0200) upstream.

  6. Postilion receives a refund response (0210) back from the entity upstream responsible for authorizing the transaction.

  7. Postilion sends the refund response (0210) to eSocket.POS.

  8. eSocket.POS sends the appropriate response to the POS device. At this stage, the refund transaction is completed.

Note
If the refund needs to be reversed for some reason, the POS sends a REFUND (reversal) XML message to eSocket.POS. See the Purchase and reversal/void page for the complete message flow, events and callbacks, XML mappings, and examples. In the case of a refund, the Type field in the XML messages must be set to REFUND.

Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.

If registered, the following events are called during an EBT refund transaction:

If registered, the following callbacks are called during an EBT refund transaction:

XML mappings in an EBT refund transaction

The following table contains the XML properties and values that are typically associated with an EBT refund transaction request. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

TerminalId

M

TestTerm

TransactionId

M

141790

Type

M

REFUND

RetrievalRefNr

O

00000000008

PosOperatorId

O

PosOp001

TransactionAmount

G

30000

CurrencyCode

O

810

EbtVoucherNumber

O

*123456*

The following table contains the XML properties and values that are specific to an EBT refund transaction response. In the Value column, example values are in italics and mandatory values are in bold.

Property Condition Value

EbtVoucherNumber

H

123456

EbtCaseNumber

H

1234567890

EbtResponseText

H

EBT Response Text

EbtBeginningFoodStampAccountBalance

C

D00000003000

EbtEndingFoodStampAccountBalance

C

D00000002000

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Transaction Properties.

For an explanation of the Condition column of this table, see Object and Property Conditions.

Example: XML messages in a refund transaction void

This is an example of a successful EBT refund transaction, followed by an EBT refund void to reverse the refund transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

The POS starts an EBT refund transaction with a REFUND (request) XML message [1] to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            TerminalId="TestTerm"
            TransactionAmount="1000"
            TransactionId="141790"
            EbtVoucherNumber="123456"
            Type="REFUND">
        </Esp:Transaction>
    </Esp:Interface>

The resulting REFUND (response) XML message [8] from eSocket.POS following the successful completion of the transaction follows, assuming the benefit type selected by the cardholder was food stamp (account type 98):

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface
        Version="1.0"
        xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            Account="98"
            ActionCode="APPROVE"
            AmountTransactionFee="C0"
            AuthorizationProfile="11"
            BusinessDate="0806"
            CardProductName="EbtCard"
            CurrencyCode="840"
            DateTime="0806082950"
            ExpiryDate="2030"
            LocalDate="0806"
            LocalTime="082950"
            MerchantId="111111111111111"
            MessageReasonCode="9790"
            PanEntryMode="90"
            PosCondition="00"
            ResponseCode="00"
            RetrievalRefNr="00000000008"
            ServiceRestrictionCode="***"
            TerminalId="TestTerm"
            TransactionAmount="1000"
            TransactionId="141790"
            EbtVoucherNumber="123456"
            EbtCaseNumber="1234567890"
            EbtResponseText="EBT Response Text"
            EbtEndingFoodStampAccountBalance="D00000002000"
            Type="REFUND">
            <Esp:StructuredData
                Name="ResponseFromPostilion"
                Value="ResponseFromPostilion">
            </Esp:StructuredData>
        </Esp:Transaction>
    </Esp:Interface>

3.13.6. XML - EBT timeout reversal

See Handling timeouts for when to send timeout reversals for EBT purchases and refunds. The message flow is very similar to EBT purchase and reversal/void, for example, except for the following:

  • The purchase response (0210) [7] sent by Postilion is not received by eSocket.POS (similar to what happens with a purchase with timeout and reversal/void).

  • In the PURCHASE (reversal) XML message [9] to eSocket.POS, the MessageReasonCode is either not set, or it is set to 4021 (timeout waiting for response).

3.14. Credit application transactions

3.14.1. Credit admin account lookup

Introduction

This section discusses a Credit Admin Account Lookup inquiry transaction.

Message flow

The Credit Admin Account Lookup inquiry transaction message flow description follows. Use the numbering in the diagram together with the numbered flow descriptions:

Credit Admin Account Lookup Inquiry - successful

  1. The POS sends a GENERAL_INQ (request) XML message to eSocket.POS (1).

  2. eSocket.POS sends an authorization request (0100) to Postilion (2).

  3. Postilion sends the authorization request (0100) upstream (3).

  4. Postilion receives an authorization response (0110) back from the entity upstream (4).

  5. Postilion sends the authorization response (0110) to eSocket.POS (5).

  6. eSocket.POS sends the valid response to the POS device (6).

Note
If Postilion is the card issuer, the valid authorization response (0110) is sent from Postilion, and message legs 3 and 4 are eliminated.

Events and callbacks are not displayed in the preceding diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.

If registered, the following events are called during a Credit Admin Account Lookup inquiry transaction:

If registered, the following callbacks are called during a Credit Admin Account Lookup inquiry transaction:

XML mappings in a Credit Admin Account Lookup

This section contains the XML properties and values that are typically associated with a Credit Admin Account Lookup inquiry transaction.

Property Description Condition Request Response

Type

The type of the transaction. For this type of transaction, Type = GENERAL_INQ.

M

Yes

Yes

ExtendedTransactionType

A code used to further distinguish between transactions with the same type. For this type of transaction, ExtendedTransactionType = 7001

M

Yes

Yes

PayeeNameAndAddress

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

O

Yes

Yes

AdditionalPayeeInformation

Contains additional payee name and address details, if any.

O

Yes

Yes

AccountData

Contains account details needed for a credit application, if any.

O

Yes

Yes

DisplayData

The status response from ADS based on the processor specification.

O

No

Yes

PrintData

The status response that contains information about the account.

O

No

Yes

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Inquiry Properties.

For an explanation of the Condition column in this table, see Object and Property Conditions.

Example: XML messages in a Credit Admin Account Lookup

This is an example of a Credit Admin Account Lookup inquiry transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the preceding diagram.

Note
The XML element order must be followed exactly as shown in the examples that follow.

The POS starts a Credit Admin Account Lookup inquiry transaction with a GENERAL_INQ (request) XML message to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            ExtendedTransactionType="7001"
            TerminalId="term1"
            TransactionId="242459"
            Type="GENERAL_INQ">
            <Esp:PayeeNameAndAddress
                AddressLine1="Mill St"
                AddressLine2="Montello"
                AddressLine3=""
                City="Marquette"
                CountryCode="USA"
                Name="Lawrence"
                Phone="1234567890"
                PostalCode="411014"
                Region="Wisconsin">
            </Esp:PayeeNameAndAddress>
            <Esp:AdditionalPayeeInformation>
                <Esp:PayeeContact
                    FirstName="Lawrence"
                    MiddleInitial="S"
                    LastName="Williams"
                    CardHolderName="Lawrence Williams"
                    CustomerDateOfBirth="01031986"
                    AdditionalID1="010212345678">
                </Esp:PayeeContact>
            </Esp:AdditionalPayeeInformation>
            <Esp:AccountData>
                <Esp:Account
                    ReferenceNo="1234">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Inquiry>
    </Esp:Interface>

The resulting GENERAL_INQ (response) XML message from eSocket.POS after the successful completion of the Credit Admin Account Lookup inquiry transaction follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            ActionCode="APPROVE"
            ExtendedTransactionType="7001"
            MessageReasonCode="9790"
            ResponseCode="00"
            TerminalId="term1"
            TransactionId="242459"
            Type="GENERAL_INQ"
            PrintData="0008A1Approved"
            DisplayData="Approved">
            <Esp:AccountData>
                <Esp:Account
                    ReferenceNo="1234"
                    ApplicationReferenceNo="987654321">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Inquiry>
    </Esp:Interface>

XML mappings in a Driver’s License Account Lookup

This section contains the XML properties and values that are typically associated with a Driver’s License Account Lookup transaction.

Property Description Condition Request Response

Type

The type of the transaction. For this transaction, Type = GENERAL_INQ.

M

Yes

Yes

ExtendedTransactionType

A code used to further distinguish between transactions with the same type. For this transaction, ExtendedTransactionType = 7001

M

Yes

Yes

AdditionalPayeeInformation

Contains additional payee name and address details, if any. For this type of transaction, it contains the SSN in the AccountID1 subfield.

NOTE

If the POS/PED prompts the cardholder to only enter the last four digits of their SSN, then the format for populating the existing SSN field in the eSocket.POS XML message would be to pad the field with leading zeros, followed by the last four digits entered by the cardholder, for example, 000006789.

M

Yes

Yes

StructuredData DriverLicenseData

Contains the scanned driver’s license information encoded in Base64 format. See the example that follows this table.

M

Yes

Yes

AccountData

Contains account details needed for a credit application, if any.

O

Yes

Yes

DisplayData

The status response from ADS based on the processor specification.

O

No

Yes

PrintData

The status response that contains information about the account.

O

No

Yes

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Inquiry Properties.

For an explanation of the Condition column in this table, see Object and Property Conditions.

Example: XML messages in a Driver’s License Account Lookup

This is an example of a Driver’s License Account Lookup transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the previous diagram.

Note
The XML element order must be followed exactly as shown in the examples that follow.

The POS starts a Driver’s License Account Lookup transaction with a GENERAL_INQ (request) XML message to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            ExtendedTransactionType="7001"
            TerminalId="term1"
            TransactionId="242459"
            Type="GENERAL_INQ">
            <Esp:StructuredData
                Name="DriverLicenseData"
                Value="MjUwMTAxNTQwMCRJMTUwVDBXNDA3NEowMUNBODBCXUxACh4NSURDSEs5ODk4OTUwMTAxREwwMDI5MDE3OERMMVpBQVBQUk9WRSxBTFdBWVMsLAoxWkIzMTAwIEVBU1RPTiBTUVVBUkUgUExBQ0UKMVpVCjFaQ0NPTFVNQlVTCkRBSk9ICjFaRTQzMjE5CjFaRjQ1NTY0OTgyNgoxWkc1CjFaSAoxWkkKMVpKMjAxNTA">
            </Esp:StructuredData>
            <Esp:AdditionalPayeeInformation>
                <Esp:PayeeContact
                    AdditionalID1="0107000006789">
                </Esp:PayeeContact>
            </Esp:AdditionalPayeeInformation>
        </Esp:Inquiry>
    </Esp:Interface>

The example that follows shows the resulting GENERAL_INQ (response) XML message from eSocket.POS after the successful completion of the Driver’s License Account Lookup transaction:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            ActionCode="APPROVE"
            ExtendedTransactionType="7001"
            MessageReasonCode="9790"
            ResponseCode="00"
            TerminalId="term1"
            TransactionId="242459"
            Type="GENERAL_INQ"
            PrintData="0008A1Approved"
            DisplayData="Approved">
            <Esp:AccountData>
                <Esp:Account
                    ReferenceNo="1234"
                    ApplicationReferenceNo="987654321">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Inquiry>
    </Esp:Interface>

3.14.2. Credit admin status application

Introduction

The POS sends a Credit Admin Status Application request upstream via Postilion. This section discusses a successful Status Application General Inquiry transaction.

Message flow

A successful Status Application General Inquiry transaction message flow is described below

Credit Admin Status Application Inquiry - successful

  • The POS sends a GENERAL_INQ (request) XML message to eSocket.POS (1).

  • eSocket.POS sends an authorization request (0100) to Postilion (2).

  • Postilion sends the authorization request (0100) upstream (3).

  • Postilion receives an authorization response (0110) back from the entity upstream (4).

  • Postilion sends the authorization response (0110) to eSocket.POS (5).

  • eSocket.POS sends the valid response to the POS device (6).

Note: If Postilion is the card issuer, the valid authorization response (0110) is sent from Postilion, and message legs 3 and 4 are eliminated.

Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, see signature capture transaction example.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.

If registered, the following events are called during a General Inquiry transaction:

If registered, the following callbacks are called during a General Inquiry transaction:

XML mappings in a Credit Admin Status Application

This section contains the XML properties and values that are typically associated with a Status Application General Inquiry transaction.

Property Description Condition Request Response

Type

The type of the transaction. For this transaction, Type = GENERAL_INQ.

M

Yes

Yes

ExtendedTransactionType

A code used to further distinguish between transactions with the same type. For this transaction, ExtendedTransactionType = 7007

M

Yes

Yes

PayeeNameAndAddress

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

O

Yes

Yes

AdditionalPayeeInformation

Contains additional payee name and address details, if any.

O

Yes

Yes

AccountData

Contains account details needed for a credit application, if any.

O

Yes

Yes

DisplayData

The status response from ADS based on the processor specification.

O

No

Yes

PrintData

The status response that contains information about the account.

O

No

Yes

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .

For a full list of possible properties in these messages, see Inquiry Properties .

For an explanation of the Condition column in this table, see Object and Property Conditions .

Example: XML messages in a Credit Admin Status Application

This is an example of a Status Application General Inquiry transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.

Note: The order of xml elements must be followed exactly as shown in the examples that follow.

The POS starts a Status Application General Inquiry transaction with a GENERAL_INQ (request) XML message to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            ExtendedTransactionType="7007"
            TerminalId="term1   "
            TransactionId="242459"
            Type="GENERAL_INQ">
            <Esp:PayeeNameAndAddress
                AddressLine1="Mill St                            "
                AddressLine2="Montello                               "
                AddressLine3="                                   "
                City="Marquette                               "
                CountryCode="USA"
                Name="Lawrence                          "
                Phone="1234567890                         "
                PostalCode="411014              "
                Region="Wisconsin         ">
            </Esp:PayeeNameAndAddress>
            <Esp:AdditionalPayeeInformation>
                <Esp:PayeeContact
                    FirstName="Lawrence"
                    MiddleInitial="S"
                    LastName="Williams"
                    CardHolderName="Lawrence Williams"
                    CustomerDateOfBirth="01031986"
                    AdditionalID1="010212345678">
                </Esp:PayeeContact>
            </Esp:AdditionalPayeeInformation>
            <Esp:AccountData>
                <Esp:Account
                    ReferenceNo="1234">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Inquiry>
    </Esp:Interface>

The resulting GENERAL_INQ (response) XML message from eSocket.POS following the successful completion of the Status Application General Inquiry transaction follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Inquiry
            ActionCode="APPROVE"
            ExtendedTransactionType="7007"
            MessageReasonCode="9790"
            ResponseCode="00"
            TerminalId="term1   "
            TransactionId="242459"
            Type="GENERAL_INQ"
            PrintData="0008A1Approved"
            DisplayData="Approved">
            <Esp:AccountData>
                <Esp:Account
                    ReferenceNo="1234"
                    ApplicationReferenceNo="987654321">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Inquiry>
    </Esp:Interface>

3.14.3. Credit application prescreen acceptance

Introduction

This section discusses a Credit Application Prescreen (Preapproval) Acceptance transaction that is used when the customer accepts a preapproved offer of credit.

Message flow

The Credit Application Prescreen Acceptance transaction message flow description follows. Use the numbering in the diagram together with the numbered flow descriptions:

Credit Admin Express Application Inquiry - successful

  1. The POS sends a Prescreen Acceptance ADMIN (request) XML message to eSocket.POS (1) containing the customer’s address and demographic information, as well as the Prescreen ID.

  2. eSocket.POS sends an administrative request (0600) to Postilion (2).

  3. Postilion sends the administrative request (0600) upstream (3).

  4. Postilion receives an administrative response (0610) back from the entity upstream (4).

  5. Postilion sends the administrative response (0610) to eSocket.POS (5).

  6. eSocket.POS sends the response to the POS device (6).

Events and callbacks are not displayed in the preceding diagram. For an example of events and callbacks, see the signature capture transaction page.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.

If registered, the following events are called during an administrative transaction:

XML mappings in a Credit Application Prescreen Acceptance transaction

This section contains the XML properties and values that are typically associated with a Credit Application Prescreen Acceptance transaction.

Property Description Condition Request Response

Type

Set to ADMIN.

M

Yes

Yes

MessageType

Set to ADMIN_REQUEST.

M

Yes

Yes

ExtendedTransactionType

Set to 1012 (Preapproval Credit Offer Acceptance).

M

Yes

Yes

PurchasingCardData.Contact

Contains the customer contact information. The PurchasingCardData.Contact.Type field must be set to BILL_TO.

M

Yes

Yes

AdditionalPayeeInformation

Contains additional customer information, such as the SSN, yearly annual income, and so on, that are required in the Prescreen Acceptance transaction.

C

Yes

Yes

AccountData

The AccountData.Account.ApplicationReferenceNo field must contain the Prescreen ID - a unique number assigned to a preapproved offer. This ID is obtained either in the online Prescreen Request response, or sent to the customer via email or direct mail if a batch prescreen process was used.

M

Yes

Yes

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Transaction Properties.

For an explanation of the Condition column in this table, see Object and Property Conditions.

Example: Credit Application Prescreen Acceptance transaction

The POS starts a Credit Application Prescreen Acceptance transaction with an ADMIN (request) XML message to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="1012"
            TerminalId="term1   "
            TransactionId="242459"
            Type="ADMIN"
            MessageType="ADMIN_REQUEST">
            <Esp:PurchasingCardData>
              <Esp:Contact
                  Type="BILL_TO"
                  Telephone="5551238888"
                  Email="lsmith@mailserve.com"
                  Address="1 Street Road"
                  Address2="Greenville"
                  City="My City"
                  PostalCode="19103">
              </Esp:Contact>
            </Esp:PurchasingCardData>
            <Esp:AdditionalPayeeInformation>
                <Esp:PayeeContact
                    FirstName="Lawrence"
                    LastName="Smith"
                    CustomerDateOfBirth="19900102"
                    AdditionalID1="010712345678"
                    HousingCode="0"
                    LengthAtAddress="0102"
                    YearlyIncome="200000"
                    PrimaryIncomeFrequency="M">
                </Esp:PayeeContact>
            </Esp:AdditionalPayeeInformation>
            <Esp:AccountData>
                <Esp:Account
                    ApplicationReferenceNo="123450987654321">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Transaction>
    </Esp:Interface>

The resulting ADMIN (response) XML message from eSocket.POS after the successful completion of the transaction follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ActionCode="APPROVE"
            ExtendedTransactionType="1012"
            MessageReasonCode="9790"
            ResponseCode="00"
            TerminalId="term1   "
            TransactionId="242459"
            Type="ADMIN"
            MessageType="ADMIN_REQUEST"
            DisplayData="OP">
            <Esp:AccountData>
                <Esp:Account
                    ApplicationReferenceNo="123450987654321">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Transaction>
    </Esp:Interface>

3.14.4. Credit application prescreen request

Introduction

This section discusses a Credit Application Prescreen (Preapproval) transaction. This type of transaction is also referred to as an Online Prescreen. The customer is prescreened in real time by the host system using the customer’s address and demographic information to extend preapproved offers of credit. If preapproved, the offer can be accepted by the customer using a Prescreen Acceptance transaction.

Message flow

The Credit Application Prescreen transaction message flow description follows. Use the diagram together with the numbered flow descriptions:

Credit Admin Express Application Inquiry - successful

  1. The POS sends a Prescreen ADMIN (request) XML message to eSocket.POS (1) containing the customer’s address and demographic information.

  2. eSocket.POS sends an administrative request (0600) to Postilion (2).

  3. Postilion sends the administrative request (0600) upstream (3).

  4. Postilion receives an administrative response (0610) back from the entity upstream (4).

  5. Postilion sends the administrative response (0610) to eSocket.POS (5).

  6. eSocket.POS sends the response to the POS device (6).

Events and callbacks are not displayed in the preceding diagram. For an example of events and callbacks, see the signature capture transaction page.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.

If registered, the following events are called during an administrative transaction:

XML mappings in a Credit Application Prescreen transaction

This section contains the XML properties and values that are typically associated with a Credit Application Prescreen transaction.

Property Description Condition Request Response

Type

Set to ADMIN.

M

Yes

Yes

MessageType

Set to ADMIN_REQUEST.

M

Yes

Yes

ExtendedTransactionType

Set to 1011 (Credit Application Preapproval).

M

Yes

Yes

PurchasingCardData.Contact

Contains the customer contact information. The PurchasingCardData.Contact.Type field must be set to BILL_TO.

M

Yes

Yes

AdditionalPayeeInformation

Contains additional customer information, such as the SSN, yearly annual income, and so on, that are required to prescreen the customer.

C

Yes

Yes

AccountData

In responses, the AccountData.Account.ApplicationReferenceNo field contains the Prescreen ID - a unique number assigned to a preapproved offer. This must be provided in the Prescreen Acceptance transaction when the customer accepts the preapproved offer.

C

No

Yes

DisplayData

The status response from the host system.

O

No

Yes

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Transaction Properties.

For an explanation of the Condition column in this table, see Object and Property Conditions.

Example: Credit Application Prescreen transaction

The POS starts a Credit Application Prescreen transaction with an ADMIN (request) XML message to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="1011"
            TerminalId="term1   "
            TransactionId="242459"
            Type="ADMIN"
            MessageType="ADMIN_REQUEST">
            <Esp:PurchasingCardData>
              <Esp:Contact
                  Type="BILL_TO"
                  Telephone="5551238888"
                  Email="lsmith@mailserve.com"
                  Address="1 Street Road"
                  Address2="Greenville"
                  City="My City"
                  PostalCode="19103">
              </Esp:Contact>
            </Esp:PurchasingCardData>
            <Esp:AdditionalPayeeInformation>
                <Esp:PayeeContact
                    FirstName="Lawrence"
                    LastName="Smith"
                    CustomerDateOfBirth="19900102"
                    AdditionalID1="010712345678"
                    HousingCode="0"
                    LengthAtAddress="0102"
                    YearlyIncome="200000"
                    PrimaryIncomeFrequency="M">
                </Esp:PayeeContact>
            </Esp:AdditionalPayeeInformation>
        </Esp:Transaction>
    </Esp:Interface>

The resulting ADMIN (response) XML message from eSocket.POS after the successful completion of the transaction follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ActionCode="APPROVE"
            ExtendedTransactionType="1011"
            MessageReasonCode="9790"
            ResponseCode="00"
            TerminalId="term1   "
            TransactionId="242459"
            Type="ADMIN"
            MessageType="ADMIN_REQUEST"
            DisplayData="OP">
            <Esp:AccountData>
                <Esp:Account
                    ApplicationReferenceNo="123450987654321">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Transaction>
    </Esp:Interface>

3.14.5. Express/instant credit application

Introduction

This section discusses an Express/Instant Credit Application transaction.

Message flow

The Express/Instant Credit Application transaction message flow description follows. Use the numbering in the diagram together with the numbered flow descriptions:

Credit Admin Express Application Inquiry - successful

  1. The POS sends an Express/Instant Credit Application ADMIN (request) XML message to eSocket.POS (1) containing the customer’s information.

  2. eSocket.POS sends an administrative request (0600) to Postilion (2).

  3. Postilion sends the administrative request (0600) upstream (3).

  4. Postilion receives an administrative response (0610) back from the entity upstream (4).

  5. Postilion sends the administrative response (0610) to eSocket.POS (5).

  6. eSocket.POS sends the response to the POS device (6).

Events and callbacks are not displayed in the preceding diagram. For an example of events and callbacks, see the signature capture transaction page.

Events and callbacks between the POS device and eSocket.POS

Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.

If registered, the following events are called during an administrative transaction:

XML mappings in an Express/Instant Credit Application transaction

This section contains the XML properties and values that are typically associated with an Express/Instant Credit Application transaction.

Property Description Condition Request Response

Type

Set to ADMIN.

M

Yes

Yes

MessageType

Set to ADMIN_REQUEST.

M

Yes

Yes

ExtendedTransactionType

Identifies the administrative message as a credit application transaction. The following values may be specified, depending on the host system to which the transaction is sent:

  • 1000 - Membership sign-up

  • 1010 - Credit application

M

Yes

Yes

PayeeNameAndAddress

Contains the customer’s contact information such as the AddressLine1, AddressLine2, AddressLine3, City, Region, PostCode, and CountryCode.

NOTE

The PurchasingCardData.Contact field can also be used for the customer’s contact information instead of this field, depending on the host system to which the transaction is sent.

C

Yes

Yes

PurchasingCardData.Contact

Contains the customer contact information. The PurchasingCardData.Contact.Type field must be set to BILL_TO.

NOTE

The PayeeNameAndAddress field can also be used for the customer’s contact information instead of this field, depending on the host system to which the transaction is sent.

C

Yes

Yes

AdditionalPayeeInformation

Contains additional customer information, if any. It may contain the alternate phone number, mobile phone number, SSN, and annual income amount in the CustomerBusinessPhone, CustomerCellPhoneNumber, AdditionalID1, and YearlyIncome subfields, respectively, if required.

O

Yes

Yes

StructuredData.DriverLicenseData

Contains the scanned driver’s license information encoded in Base64 format. This is required for Instant Credit Applications with Driver’s License transactions.

C

Yes

No

StructuredData.CUSTOMER_EMAIL

Contains the customer email address.

NOTE

The PurchasingCardData.Contact.Email field can also be used for the email address instead of this field, depending on the host system to which the transaction is sent.

O

Yes

No

AccountData

Contains account details, if any.

In the response, the AccountData.Account.ApplicationReferenceNo field contains the Credit Application ID.

O

Yes

Yes

DisplayData

The status response from the host system.

O

No

Yes

PrintData

The status response that contains information about the account.

O

No

Yes

For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.

For a full list of possible properties in these messages, see Transaction Properties.

For an explanation of the Condition column in this table, see Object and Property Conditions.

Example 1: Express/Instant Credit Application transaction

The POS starts an Express Credit Application transaction with an ADMIN (request) XML message to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="1000"
            TerminalId="term1"
            TransactionId="242459"
            Type="ADMIN"
            MessageType="ADMIN_REQUEST">
            <Esp:PayeeNameAndAddress
                AddressLine1="Mill St"
                AddressLine2="Montello"
                AddressLine3=""
                City="Marquette"
                CountryCode="USA"
                Name="Lawrence"
                Phone="1234567890"
                PostalCode="411014"
                Region="Wisconsin">
            </Esp:PayeeNameAndAddress>
            <Esp:AdditionalPayeeInformation>
                <Esp:PayeeContact
                    FirstName="Lawrence"
                    MiddleInitial="S"
                    LastName="Williams"
                    CardHolderName="Lawrence Williams"
                    CustomerDateOfBirth="01031986"
                    AdditionalID1="010212345678">
                </Esp:PayeeContact>
            </Esp:AdditionalPayeeInformation>
            <Esp:AccountData>
                <Esp:Account
                    ReferenceNo="1234">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Transaction>
    </Esp:Interface>

The resulting ADMIN (response) XML message from eSocket.POS after the successful completion of the transaction follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ActionCode="APPROVE"
            ExtendedTransactionType="1000"
            MessageReasonCode="9790"
            ResponseCode="00"
            TerminalId="term1"
            TransactionId="242459"
            Type="ADMIN"
            MessageType="ADMIN_REQUEST"
            PrintData="0008A1Approved"
            DisplayData="IC">
            <Esp:AccountData>
                <Esp:Account
                    ReferenceNo="1234"
                    ApplicationReferenceNo="123450987654321">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Transaction>
    </Esp:Interface>

Example 2: Instant Credit Application with Driver’s License transaction

The POS starts an Instant Credit with Driver’s License transaction with an ADMIN (request) XML message to eSocket.POS:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ExtendedTransactionType="1000"
            TerminalId="term1"
            TransactionId="242459"
            Type="ADMIN"
            MessageType="ADMIN_REQUEST">
            <Esp:StructuredData
                Name="DriverLicenseData"
                Value="MjUwMTAxNTQwMCRJMTUwVDBXNDA3NEowMUNBODBCXUxACh4NSURDSEs5ODk4OTUwMTAxREwwMDI5MDE3OERMMVpBQVBQUk9WRSxBTFdBWVMsLAoxWkIzMTAwIEVBU1RPTiBTUVVBUkUgUExBQ0UKMVpVCjFaQ0NPTFVNQlVTCkRBSk9ICjFaRTQzMjE5CjFaRjQ1NTY0OTgyNgoxWkc1CjFaSAoxWkkKMVpKMjAxNTA">
            </Esp:StructuredData>
            <Esp:StructuredData
                Name="CUSTOMER_EMAIL"
                Value="abc@xyz.com">
            </Esp:StructuredData>
            <Esp:PayeeNameAndAddress
                AddressLine1="Mill St"
                AddressLine2="Montello"
                AddressLine3=""
                City="Marquette"
                CountryCode="USA"
                Name="Lawrence"
                Phone="1234567890"
                PostalCode="411014"
                Region="Wisconsin">
            </Esp:PayeeNameAndAddress>
            <Esp:AdditionalPayeeInformation>
                <Esp:PayeeContact
                    CustomerCellPhoneNumber="987654321"
                    CustomerBusinessPhone="123456789"
                    AdditionalID1="0107000006789"
                    YearlyIncome="100000">
                </Esp:PayeeContact>
            </Esp:AdditionalPayeeInformation>
            <Esp:AccountData>
                <Esp:Account
                    ReferenceNo="1234">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Transaction>
    </Esp:Interface>

The resulting ADMIN (response) XML message from eSocket.POS after the successful completion of the transaction follows:

 <?xml version="1.0" encoding="UTF-8"?>
    <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
        <Esp:Transaction
            ActionCode="APPROVE"
            ExtendedTransactionType="1000"
            MessageReasonCode="9790"
            ResponseCode="00"
            TerminalId="term1"
            TransactionId="242459"
            Type="ADMIN"
            MessageType="ADMIN_REQUEST"
            PrintData="0008A1Approved"
            DisplayData="IC">
            <Esp:AccountData>
                <Esp:Account
                    ReferenceNo="1234"
                    ApplicationReferenceNo="987654321">
                </Esp:Account>
            </Esp:AccountData>
        </Esp:Transaction>
    </Esp:Interface>

3.15. Prompts

Format

Description

XML String containing a list of Prompt elements, each of which map to a Generic Prompt to be presented to the user.

The DTD that defines how the XML elements are represented in the message is available here:

  • Prompts.dtd

Key value = "Prompts" , Top level element = "Prompts"

Field

Type

Condition

Format

Description

Prompts

The top-level element of the Prompts XML document, which can contain one or more Prompt elements.

   Prompt

Element

Zero or more

A list of prompts that are displayed to the user. The prompts are displayed in the order in which they are received in the XML.

      Id

Attribute

Optional

ans..

A unique number assigned to this prompt. This value need only be unique per Prompt element.

      Name

Attribute

Mandatory

ans..

The name of the prompt. This must always be present in all Prompt requests and Prompt responses.

      DataType

Attribute

Optional

a1

The type of data that will be entered for the prompt.

Valid values are:

  • A (Alphanumeric)

  • N (Numeric)

  • B (Boolean)

  • C (Continue)

  • M (Money)

  • K (Acknowledge)

  • O (Option)

  • S (Signature)

  • R (Radio)

      MinLength

Attribute

Optional

n..

The minimum length of the prompt value to be entered.

      MaxLength

Attribute

Optional

n..

The maximum length of the prompt value to be entered.

      InputType

Attribute

Optional

a1

The visibility of the data entered. This field provides backwards compatibility for legacy applications.

Valid values are:

  • C (Clear) - The data entered is displayed as unmasked on the POS.

  • M (Masked) - The data is entered unencrypted, but is displayed as masked on the POS.

  • D (Do Not Print) - The data is displayed in the clear on the POS, but not printed on the receipt.

  • H (Hidden) - The prompt is not displayed on the POS or printed on the receipt. Used for prompts with auto-populated answers.

      Timeout

Attribute

Optional

n..

The length of time (in milliseconds) that the device should wait for the user to enter an answer, before aborting the prompt.

      AcceptText

Attribute

Optional

ans..

The actual text displayed on the Accept Button on the device.

Note
Limited device driver support.

      DeclineText

Attribute

Optional

ans..

The actual text displayed on the Decline Button on the device.

Note
Limited device driver support.

      Source

Attribute

Optional

a1

The source of the prompt, that is, where the prompt is displayed. This field provides backwards compatibility for legacy applications.

Valid values are:

  • T (Terminal) - The prompt is displayed as an edit box on the POS.

  • K (Keypad) - The prompt is displayed as a numerical keypad on the POS.

  • L (List) - The prompt is displayed as a list of options (in other words, a selection panel) on the POS.

      DisplayText

Attribute

Optional

ans..

This field provides backwards compatibility for legacy applications.

      Image

Attribute

Optional

ans..

This field provides backwards compatibility for legacy applications.

      Value

Attribute

Optional

ans..

The answer to the prompt. This field is required in the prompt response.

      SignatureFormat

Attribute

Optional

ans..

The format of the signature. This field is required in the signature prompt response.

      AdditionalButton

Element

Zero or more

ans..

Represents a single additional button.

Note: Limited device driver support.

         Text

Attribute

Optional

ans..

The actual text displayed on an Additional Button on the device.

         Result

Attribute

Optional

ans..

The value that will be returned if the additional button on the device is pressed.

      DisplayTextLine

Element

Zero or more

A line of text associated with the prompt.

         Text

Attribute

Optional

ans..

The actual text displayed on the device, associated with a single DisplayTextLine.

      Option

Element

Zero or more

This element provides backwards compatibility for legacy applications.

         Value

Attribute

Optional

ans..

This field provides backwards compatibility for legacy applications.

         Text

Attribute

Optional

ans..

This field provides backwards compatibility for legacy applications.

      CustomProperty

Element

Zero or more

A custom property associated with the prompt.

         Key

Attribute

Optional

ans..

The key for the custom property.

         Value

Attribute

Optional

ans..

The value for the custom property.

      OptionTextLine

Element

Zero or more

Represents a single option, when sending an option type generic prompt.

         Text

Attribute

Optional

ans..

The text that will be displayed on the device representing the option.

         Result

Attribute

Optional

ans..

The value that will be returned on successful selection of the option.

3.16. Display

Format

Description

An XML string containing a list of display elements. Each element maps to a display message that is presented to the user.

See Display.dtd to see how the XML elements are represented in the message.

The following table describes the structure of the XML string.

Field Type Condition Format Description

Display

Top level element of the Display XML message which can contain one DisplayData element and zero or more DisplayResult elements.

   DisplayData

Element

One

List of Display messages and parameters associated with a Display message. These must be sent to the device in the order received.

      ResponseRequired

Attribute

Optional

a

Indicates whether eSocket.POS requires a response to the display message.

      DisplayTime

Attribute

Optional

n..

Time period (in seconds) that the message must be displayed for.

      Device

Attribute

Mandatory

an

Device on which the message must be displayed:

  • POS

  • PED

      DisplayType

Attribute

Optional

a

Type of information to be displayed.

      BacklightEnabled

Attribute

Optional

a

Indicates whether the backlight on the device should be switch on or not.

      FormID

Attribute

Optional

a

Specifies the form used for display.

      DisplayContent

Element

Optional

Content to be displayed.

         Format

Attribute

Optional

a

Format of the output:

  • MessageReference

  • Text

  • Barcode

  • XHTML

         OutputText

Element

Zero or more

Text object to display - must be present if the Format field is equal to "Text".

            Text

Attribute

Optional

ans

Actual text to display.

            Font

Attribute

Optional

an

Font of the text to display.

            StartRow

Attribute

Optional

n

Row from which to start the text display - vertical alignment.

            StartColumn

Attribute

Optional

n

Column from which to start the text display - horizontal alignment.

            Color

Attribute

Optional

a

Color of the text to display:

  • White

  • Black

  • Red

  • Green

  • Blue

  • Yellow

  • Magenta

  • Cyan

            CharStyle

Attribute

Optional

a

Style of the characters to display:

  • Normal

  • Bold

  • Italic

  • Underline

            NewLineFlag

Attribute

Optional

a

Indicates whether a carriage return must be displayed.

            Alignment

Attribute

Optional

a

Positional alignment of the characters to display:

  • Left

  • Right

  • Centred

  • Justified

         OutputXHTML

Attribute

Optional

ans

Base64 representation of XHTML data to display - must be present if the Format field is equal to "XHTML".

      CustomDisplayData

Element

Zero or more

Custom parameters associated with a DisplayData object - the order of this list must match the list of DisplayData objects.

         DisplayContent

Element

Optional

Custom content object.

            PredefinedContent

Element

Zero or One

a

Predefined display content - must be present if the Format field is equal to "MessageReference".

               ReferenceID

Attribute

Optional

an

Referenced to the predefined content.

               Language

Attribute

Optional

a

Language of the predefined content.

            OutputText

Element

Zero or more

Custom Output text object - must match the order of the DisplayContent.OutputText structure.

               CharSet

Attribute

Optional

an

IANA character encoding of the text to display.

               CharWidth

Attribute

Optional

a

Width of the characters to display:

  • SingleWidth

  • DoubleWidth

               CharHeight

Attribute

Optional

a

Height of the characters to display:

  • SingleHeight

  • DoubleHeight

  • HalfHeight

            OutputBarcode

Element

Optional

Must be present if the Format field is equal to "Barcode".

               Type

Attribute

Optional

an

Type of barcode encoding:

  • EAN13

  • EAN8

  • UPCA

  • Code25

  • Code128

  • PDF417

               Value

Attribute

Optional

an

Barcode value to display.

            OutputSignature

Attribute

Optional

ans

Signature associated with the text - in base64 format.

   DisplayResult

Element

Zero or more

Lists the display results, matching them to the DisplayData items, and in the same order.

      Result

Attribute

Optional

a

Indicates the result of the transaction:

  • Success

  • Failure

      ErrorCondition

Attribute

Optional

an

Error condition, if the Result field is equal to "Failure".

      AdditionalResponse

Attribute

Optional

an

Additional information associated with the response.

3.17. Receipt printing

Description: eSocket.POS is responsible for formatting, validating, and printing receipts. Receipts are defined using the eSocket.POS Structured Receipt Scripting Language (SRSL), the HTML template file, or a template defined on the PIN Entry Device (PED). The terminal can be configured to print the receipt for the purchase and/or reversal transaction and the customer and/or merchant. See the eSocket.POS User Guide for information on how to configure the PipelineComponentReceiptPrinter that handles receipt printing.

The following is a flow describing how receipt reprint works.

Receipt reprint administration request

admin receipt reprinting

Details of the receipt reprint administration request flow:

  1. A receipt reprint administration request is sent from the POS interface with the extended transaction type set to 2130 and a reprint transaction linking number (this is the original transaction reference number).

  2. eSocket.POS maps the reprint administration request to a 0600 message, retrieves the original transaction from the database, then sends a request to the device printer, which displays the "please wait" message.

  3. The device printer sends a response to the request indicating that the request was received.

  4. eSocket.POS sends the receipt data to the device printer, and the device printer prints the receipt.

  5. The device printer sends a response to the request indicating the receipt was printed.

  6. The transaction is approved offline, and a receipt reprint administration response is sent back to the POS.

Below is an example of how XML messages work during a Prompt request. The POS starts the Prompt transaction with an ADMIN (request) XML message [1] to eSocket.POS, as indicated in the above diagram:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface
	Version="1.0"
	xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Transaction
		ExtendedTransactionType="2121"
		<Esp:StructuredData
			Name="RetrievalRefNr"
			Value="OriginalTransactionRefNr">
			Name="ExtendedTransactionType"
			Value="2130">
		</Esp:StructuredData>
		Type="ADMIN">
		MessageType="ADMIN_REQUEST">
	</Esp:Transaction>
</Esp:Interface>

The resulting ADMIN (response) XML message [6] from eSocket.POS following the successful completion of the transaction:

<?xml version="1.0" encoding="UTF-8"?>
<Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/">
	<Esp:Transaction
		ExtendedTransactionType="2121"
		<Esp:StructuredData
			Name="ResponseFromPostilion"
			Value="ResponseFromPostilion">
		</Esp:StructuredData>
		Type="ADMIN">
		MessageType="ADMIN_REQUEST">
	</Esp:Transaction>
</Esp:Interface>

Note: The OriginalTransactionRefNr on the request message is the original transaction reference number of the original message that you want to print the receipt for. This can be the STAN (Field 11) or Retrieval Reference Number (Field 37) depending on the eSocket.POS configuration.

4. Implement/Extending eSocket.POS components

4.1. Overview - Implementing/Extending eSocket.POS components

eSocket.POS provides multiple interfaces which may be implemented to extend or enhance functionality provided by eSocket.POS.

The following topics are covered in this document:

  • Transaction Processing Result (TPR)

  • Using Caches in eSocket.POS

  • SensitiveTimedHashtable

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

4.2. Implement Transaction Processing Results (TPR)

Transaction Processing Results (TPR) tracks decisions made while processing a message. The decisions, stored in a bitmap, are placed into the message under a provided TPR key. The purpose of the tracking is to record which decisions were made when processing a message.

In ISO 8583 messages, the TPR is placed in structured data (field 127.22) under the provided key.

The bitmap is defined by extending ATransactionDecision . Due to the limitations of Java 1.4, a static list must be created and the itemList() method must return that static list. After this, public static final objects of the extending class will automatically be assigned positions in the bitmap, starting at byte 1 bit 8 and continuing until byte 1 bit 1 after which it rolls over to byte 2 bit 8 and this pattern continues.

An example of ATransactionDecision implementation follows:

public static class MyDecision extends ATransactionDecision
{
   public static List items = new LinkedList();
   public MyDecision()
   {
      super(name);
   }
   protected List itemList()
   {
      return items;
   }
   public static final MyDecision _1_8_DECISION_ONE = new MyDecision("FirstDecision");
   public static final MyDecision _1_7_DECISION_TWO = new MyDecision("SecondDecision");
   public static final MyDecision _1_6_DECISION_THREE = new MyDecision("ThirdDecision");
   ...
}

By default the key will be the name of the class. Optionally the getGroupName() method may be overridden to specify which structured data tag, the decision will reside under.

Note: Recording always prepends "TPR:" to the key. In the following example, the output will be recorded into structured data, under the key "TPR:MyStructuredDataTag".

protected String getGroupName()
{
	return "MyStructuredDataTag";
}

4.3. Recording decisions

eSocket.POS includes convenience methods for recording decisions in both device drivers and pipeline components.

4.3.1. Recording decisions in a device driver

Decisions usually made in the device driver are provided by GenericDeviceDriverTransactionDecision . All device drivers that extend APhysicalDevice have a convenience method setDecision which should be used to set the devices decisions. These decisions will automatically be recorded by the PAN and EMV pipeline components. For example:

setDecision(GenericDeviceDriverTransactionDecision._1_5_PAN_ENTERED_MANUALLY);

4.3.2. Recording decisions in a pipeline component

Each pipeline component must define its own set of decisions. All pipelines that extend APipelineComponent provide the convenience method setDecision . Any decisions set in the pipeline component will automatically be recorded in the message after processing the request, and again after processing the response.

For example, the following could be used to set a decision:

setDecision(PanDecision._1_7_GET_PAN_FROM_CARD_READ);

4.3.3. General recording of decisions

When recording decisions outside the device driver or pipeline component, a TransactionProcessingResults object should be created to contain the decision bits. The TprRecorder provides convenience methods to set the decisions, directly or by recording the contents of the TransactionProcessingResults object, into the ISO 8583 message.

The following examples only record the second decision in the message.

Example 1:

TransactionProcessingResults tpr = new TransactionProcessingResults(MyDecision._1_8_DECISION_ONE);
tpr.setDecision(MyDecisions._1_7_DECISION_TWO);
TprRecorder.record(tpr, msg);

Example 2:

TprRecorder.record(MyDecisions._1_7_DECISION_TWO, msg);

4.3.4. Recording multiple different Transaction Processing Results

Multiple separate TransactionProcessingResults objects may be recorded using a TprRegistry object. The TprRegistry is a container that may contain multiple TransactionProcessingResults . Each of these TPRs will be recorded individually.

For example:

TprRecorder.record(tprRegistry, msg);

4.4. Retrieving decisions

TprRecorder should be used to obtain the correct structured data key for a given ATransactionDecision when reading a TPR from a message. The contents of the key can be decoded using TransactionProcessingResults.decode(String) method. Next, the isDecisionSet method can be used to check whether a specific bit is set.

For example:

String structDataValue = structuredData.get(TprRecorder.getGroupName(MyDecision._1_8_DECISION_ONE);
TransactionProcessingResults tpr = new TransactionProcessingResults(MyDecision._1_8_DECISION_ONE);
tpr.decode(structDataValue);
boolean isSet = tpr.isDecisionSet(MyDecision._1_7_DECISION_TWO);

4.5. Using Caches in eSocket.POS

eSocket.POS provides a framework to handle the creation and access to in-memory caches. These caches can be used to store any Java object for the lifetime of the cache.

4.5.1. General concepts

A cache is logically divided into the objects placed into the cache ( AObjectCache ), the cache manager ( ACacheManager ) that keeps track of multiple named caches, the cache accessor ( ACacheAccessor ) which is used to access a cache, and finally the cache factory ( CacheAcessorFactory ) which is used to create the accessors

Local vs cross terminal caches

There are two types of cache managers, those that maintain local caches (a cache that can only accessed from the current eSocket.POS terminal), and those that maintain cross terminal caches. Both of these manager types have their own limitations, for example, the local cache cannot share its information with other terminals in a store server. A cross terminal cache cannot be resetForNextTran nor can it be closed and for this reason, a cross terminal cache cannot have a TranLifeObjectCache registered in it.

Cache lifetime

All caches described here are in-memory caches and are not persisted between eSocket.POS shutdowns, restarts or resyncs. When a cache is registered, the contents are given a time period for which they will exist. For example, a TranLifeObjectCache has its cache contents cleared when the eSocket.POS resets for the next transaction i.e. the cache only lasts for the duration of the current transaction in eSocket.POS. The TranLinkedObjectCache , on the other hand, is backed by a timed hash table and clears its contents based on the expiry time provided.

Registering and accessing the cache

The caches are registered and accessed through an accessor which, in turn, is provided by the accessor factory. The accessor factory can be obtained from the information server.

An example of registering a transaction life cache is as follows:

infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().registerTranLifeCache("my_cache_name", String.class);

An example of registering a timed cache is as follows:

infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().registerTimedCache("my_cache_name", String.class, 5 * 60 * 1000);

A value can be placed into the same cache as follows:

infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().set("my_cache_name", isoMsg,"Content String");

The value may be retrieved from the cache as follows:

String value = (String) infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().get("my_cache_name", isoMsg);

The value may be removed from the cache as follows:

String value = (String) infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().remove("my_cache_name", isoMsg);

To access the same cache, it is important to use the same accessor object and also specify the same cache name. The different accessors specify what makes their cache elements distinct i.e. what value is used to key to different values in the cache.

The same cache can be registered with the same name, however, if the cache contains different configuration values to an existing cache with the same name, an exception will be thrown.

4.5.2. Cache Accessors Overview

This section gives a brief overview of the different available accessors.

BooleanTranLinkedCacheAccessor

This accessor provides convenience methods to store boolean values in the cache, otherwise this functions as a TranlinkedCacheAccessor .

MessageCacheAccessor

This accessor is used exclusively by the MessageCache in InformationServer to cache ISO8583 messages based on the transaction linking number in the messages and the terminal ID. This cache is used throughout eSocket.POS and should be handled with care. Since it caches the whole ISO8583 message and might contain sensitive data, the message is kept encrypted.

infoServer.getMessageCache().addRequestMessageToCache(isoMsg);
Iso8583Post cachedMsg = infoServer.getMessageCache().getCachedRequestMessage(isoMsg);
Iso8583Post cachedMsg = infoServer.getMessageCache().removeRequestMessageFromCache(isoMsg);
TranLinkedCacheAccessor

The content of this cache is keyed off the transaction linking number in the provided message and the current terminal ID. When registering a cache, a class type must be provided which is used to validate that only the allowed type is placed into the cache.

TranLinkMsgTypeCacheAccessor

The content of this cache is keyed off the transaction linking number and message type in the provided message and the current terminal ID. When registering a cache, a class type must be provided which is used to validate that only the allowed type is placed into the cache.

5. Object properties and conditions

The transaction table indicates which objects and properties should be set in a particular transaction.

The condition ( Cond ) of each property is indicated as:

  • M (mandatory) - the property should always be set;

  • C (conditional) - the property should only be set if certain conditions apply;

  • G (configuration) - the property should be set depending on eSocket.POS configuration; for instance if a particular Pipeline Component is configured, or a device is configured which is capable of retrieving and inserting the property, it may not be necessary for this property to be set;

  • O (optional) - the property may be set if applicable data is available.

Once the transaction has been performed, a response will be received. The response to a transaction will be returned in another Transaction object. In the response object - depending on the issuer’s response - some properties will be unmodified, others might be modified, and yet others not set in the original transaction might be set in the response.

The response condition ( Rsp ) of each property is indicated as:

  • A (always present) - the property will always be present;

  • T (original transaction) - the property will be present if it was present in the original transaction object;

  • G (configuration) - the property may be set depending on eSocket.POS configuration;

  • C (conditional) - the property may be set if certain conditions apply;

  • H (host) - the property will be set if sent by the upstream host system.

6. Diagnostic tools

6.1. Event log

A number of informational and error events are logged by eSocket.POS. Events are logged either to a text file or to the Windows event log, depending on configuration.

Configuring the Event log is described in the eSocket.POS User Guide .

6.1.1. Events

Event 10000

Severity:

Informational

Symbolic Name:

ESOCKETPOS_STARTED

Message:

Text:

The application %1 was started with parameters %2.

Parameter %1:

the application

Parameter %2:

startup parameters

Description:

The application has started successfully

Action:

None.

Event 10001

Severity:

Error

Symbolic Name:

COMMAND_PORT_NOT_LOADED

Message:

Text:

eSocket.POS could not retrieve the command port from the Information Server for terminal %1.

Parameter %1:

the terminal ID

Description:

This event is logged when eSocket.POS fails to load the port number (on which it should receive commands) from the Information Server

Action:

Check the eSocket.POS configuration.

Event 10002

Severity:

Error

Symbolic Name:

COMPONENT_FAILURE

Message:

Text:

The %1 component could not process a transaction it received from Terminal %3. The reason reported is: %2.

Parameter %1:

Component name

Parameter %2:

Description of the failure

Parameter %3:

Terminal ID

Description:

This event is logged when eSocket.POS component fails to function properly. The error may be caused by incorrect configuration, invalid data supplied to the component, or an error in the component. The event includes the name of the component that failed, and the description of the cause of the failure

Action:

Contact your primary support provider.

Event 10003

Severity:

Error

Symbolic Name:

CONFIG_AGENT_DATASET_ACTIVATE_FAILED

Message:

Text:

An error occurred while attempting to set the dataset "%1" active. When the command was issued dataset "%2" was active. The next message logged contains related technical information

Parameter %1:

the timestamp of the dataset that was requested to be made active

Parameter %2:

the timestamp of the dataset that was active when the command was issued.

Description:

An error occurred while attempting to mark the requested data set active.

Action:

Contact your primary support provider.

Event 10004

Severity:

Error

Symbolic Name:

CONFIG_AGENT_FILE_FORMAT_INVALID

Message:

Text:

The Configuration Agent was unable to validate the file "%1". The following fault was reported: %2

Parameter %1:

the name of the file that could not be validated

Parameter %2:

the error that was reported

Description:

The named file could not be validated by the Configuration Agent

Action:

Determine the cause of the validation error and modify the file accordingly.

Event 10005

Severity:

Error

Symbolic Name:

CONFIG_AGENT_INCR_LOAD_PREP_FAILED

Message:

Text:

The Configuration Agent was unable to prepare the database for an incremental upload. The next event logged contains related technical information

Description:

An error occurred while preparing the database for the application of and incremental load

Action:

Contact your primary support provider.

Event 10006

Severity:

Error

Symbolic Name:

CONFIG_AGENT_INVALID_PROPERTY

Message:

Text:

The value "%2" is not a valid option for the key "%1". Please consult the User Guide for the appropriate values for this key. The Configuration Agent has not been started.

Parameter %1:

the key for which an incorrect value has been supplied

Parameter %2:

the incorrect value

Description:

An invalid value has been specified for an entry in the Configuration Agent’s properties file.

Action:

Consult the User Guide for the list of values are valid for this key and correct the entry in the properties file.

Event 10007

Severity:

Error

Symbolic Name:

CONFIG_AGENT_LOAD_FAILED

Message:

Text:

The Configuration Agent was unable to complete processing of the upload file "%1". This entire upload has been aborted and rolled back. The next message logged contains related technical information.

Parameter %1:

the name of the upload file that was being processed when the error

Parameter %2:

occurred

Description:

An error occurred while writing the contents of an upload file to the database

Action:

Contact your primary support provider.

Event 10008

Severity:

Warning

Symbolic Name:

CONFIG_AGENT_FILE_DELETE_FAILED

Message:

Text:

The Configuration Agent was unable to complete deleting of the file "%1".

Parameter %1:

the name of the file that was being processed when the error

Parameter %2:

occurred

Description:

An error occurred while Configuration Agent was attempting to delete old configuration files.

Action:

Contact your primary support provider.

Event 10009

Severity:

Error

Symbolic Name:

CONFIG_AGENT_LOAD_STATUS_MARK_FAILED

Message:

Text:

The Configuration Agent was unable to mark the upload set as "%1". This upload has been aborted and rolled back. The next message logged contains related technical information.

Parameter %1:

the status mark that the Configuration Agent attempted to write

Parameter %2:

to the database

Description:

The status of the upload could not be written to the eSocket.POS database

Action:

If it was an attempt to mark an upload as 'loading' that failed, then ensure that a data set with the same timestamp as the aborted load does not yet exist in the database. If one does not exist then contact your primary support vendor.

Event 10010

Severity:

Error

Symbolic Name:

CONFIG_AGENT_CLEANER_FAILED

Message:

Text:

An SQL error occurred while the Configuration Agent was cleaning old configuration. The error occurred while the Configuration Agent was busy processing the %1 table. The previous event will contain more information on the nature of the SQL error.

Parameter %1:

the table that was being processed when the error occurred.

Description:

A SQL error occurred while cleaning old configuration data from the eSocket.POS database.

Action:

Contact your primary support provider.

Event 10011

Severity:

Error

Symbolic Name:

CONFIG_AGENT_NO_EXTANT_DATA_FOR_INCREMENTAL_LOAD

Message:

Text:

An incremental upload could not be applied because the eSocket.POS database contained no data. The upload has been aborted.

Description:

The Configuration Agent found and attempted to load an incremental upload file. However, the eSocket.POS database did not contain any data to which the incremental upload could be applied.

Action:

Apply a full upload file before attempting the incremental upload.

Event 10012

Severity:

Error

Symbolic Name:

CONFIG_AGENT_PROPERTIES_FILE_NOT_FOUND

Message:

Text:

The configuration file "%1" could not be loaded. The Configuration Agent has not been started

Parameter %1:

the name of the properties file from which the Configuration Agent

Parameter %2:

attempted to read its configuration options

Description:

The eSocket.POS Configuration Agent cannot load the properties file containing its configuration parameters

Action:

Ensure that a correctly named properties file is present in the directory from which the config agent was started

Event 10013

Severity:

Error

Symbolic Name:

CONFIG_AGENT_PROPERTY_NOT_FOUND

Message:

Text:

The required key "%1" has not been specified in the Configuration Agent’s properties file. The Configuration Agent has not been started.

Parameter %1:

the required key

Description:

A required property has not been specified in the Configuration Agent’s properties file.

Action:

Consult the User Guide for the correct name of the key and the values that are associated with it.

Event 10014

Severity:

Error

Symbolic Name:

CONFIG_AGENT_PROPERTY_INVALID_VALUE

Message:

Text:

The "%1" property has an invalid value "%2". Please refer to the user guide for information on the values allowed for this property. Until such time as this property is correctly specified the Config Agent will continue processing as if this property is not present.

Parameter %1:

the key of the property with invalid value.

Parameter %2:

the invalid value specified for the property.

Description:

A property has been populated with an invalid value in the Configuration Agent’s properties file.

Action:

Consult the User Guide for information on the allowed values for this property.

Event 10015

Severity:

Error

Symbolic Name:

CONFIG_AGENT_UPLOAD_DIRECTORY_NOT_FOUND

Message:

Text:

The specified upload directory "%1" could not be found

Parameter %1:

the name of the directory specified in the Configuration Agent’s

Parameter %2:

properties file as the one into which upload files are to be placed.

Description:

The upload directory specified in the properties file does not exist

Action:

Create the directory, or correct the name of the directory in the properties file and restart the Configuration Agent.

Event 10016

Severity:

Error

Symbolic Name:

DEVICE_CONNECT_FAILED

Message:

Text:

A device connection failed for terminal ID %1 (IP address %2, port %3).

Parameter %1:

The terminal ID

Parameter %2:

The IP address

Parameter %3:

The port

Description:

A device connection failed.

Action:

Contact your primary support provider.

Event 10017

Severity:

Error

Symbolic Name:

DEVICE_DISCONNECTED

Message:

Text:

eSocket.POS attempted to access a device which was not available.

Description:

eSocket.POS attempted to access a device which was not available.

Action:

Check that the device is connected and properly configured.

Event 10018

Severity:

Error

Symbolic Name:

DEVICE_INIT_FAILED

Message:

Text:

The %1 device could not be initialized.

Parameter %1:

The device name

Description:

A device could not be initialized.

Action:

Contact your primary support provider.

Event 10019

Severity:

Error

Symbolic Name:

ENTITY_CLASS_NOT_FOUND

Message:

Text:

The %1 configured class %2 could not be found. Terminal %3 affected.

Parameter %1:

Name of the entity for which the class is missing

Parameter %2:

Name of the missing class

Parameter %3:

Terminal ID

Description:

This event is logged when one of the classes specified in the configuration is not found.

Action:

Check the eSocket.POS configuration.

Event 10020

Severity:

Error

Symbolic Name:

ESP_PROPERTIES_FILE_NOT_FOUND

Message:

Text:

eSocket.POS could not be started by terminal %1 because the properties file "%2" could not be found

Parameter %1:

The Terminal ID

Parameter %2:

The name of the properties file

Description:

This event is logged when the eSocket.POS properties file could not be found

Action:

Check the eSocket.POS configuration.

Event 10021

Severity:

Error

Symbolic Name:

ESP_PROPERTY_NOT_FOUND

Message:

Text:

eSocket.POS could not be started because the property "%1" could not be found in the properties file

Parameter %1:

The Property that could not be found in the file

Description:

This event is logged when a required property could not be found in the eSocket.POS properties file

Action:

Check the eSocket.POS configuration.

Event 10022

Severity:

Error

Symbolic Name:

FAILED_TO_START

Message:

Text:

eSocket.POS could not be started for terminal %1. The error reported is as follows: %2

Parameter %1:

The Terminal ID

Parameter %2:

Error reported, or name of the entity which could not be instantiated

Description:

This event is logged when eSocket.POS fails to start properly.

Action:

Check the eSocket.POS configuration.

Event 10023

Severity:

Error

Symbolic Name:

FAILED_TO_START_DESCRIPTION

Message:

Text:

eSocket.POS could not be started for terminal %1. The error reported is as follows: %2. Details of the error are as follows: %3

Parameter %1:

The Terminal ID

Parameter %2:

Error reported, or name of the entity which could not be instantiated

Parameter %3:

The exception that resulted in the entity not starting

Description:

This event is logged when an eSocket.POS fails to start properly.

Action:

Check the eSocket.POS configuration.

Event 10024

Severity:

Error

Symbolic Name:

HOTCARD_LOAD_ERROR

Message:

Text:

A record in a hotcard file could not be loaded and was ignored, or the hotcard file could not be loaded. The following error was reported: %1.

Parameter %1:

Text describing the error or the invalid record from the file

Description:

An error occurred while loading the hotcard file.

Action:

Determine the cause of the error and modify the file accordingly. If the error still occurs contact your primary support provider.

Event 10025

Severity:

Error

Symbolic Name:

DEPRECATED_EVENT_1

Message:

Text:

An unconfigured account type of %2 was entered for PAN %1.

Parameter %1:

The Primary Account Number

Parameter %2:

The account type entered

Description:

An account type was entered which was not configured for this card. This event previously called INVALID_ACCOUNT_TYPE is not used and should not be used in future since it contains the PAN in the clear.

Action:

Consult your primary support provider.

Event 10026

Severity:

Error

Symbolic Name:

DEPRECATED_EVENT_2

Message:

Text:

A card with PAN %1 was used but no BIN is configured for this PAN.

Parameter %1:

The Primary Account Number

Description:

A card was used with a BIN which was not configured. This event previously called INVALID_BIN is not used and should not be used in future since it contains the PAN in the clear.

Action:

Consult your primary support provider.

Event 10027

Severity:

Error

Symbolic Name:

INVALID_DEVICE_MSG

Message:

Text:

A message could not be sent to the %1 device because it was invalid.

Parameter %1:

The device name

Description:

An attempt was made to send an invalid message to a device.

Action:

Contact your primary support provider.

Event 10028

Severity:

Error

Symbolic Name:

INVALID_DEVICE_RSP

Message:

Text:

An invalid response was received from the %1 device.

Parameter %1:

The device name

Description:

An invalid response was received from a device.

Action:

Contact your primary support provider.

Event 10029

Severity:

Error

Symbolic Name:

KEYCHANGE_FAILED

Message:

Text:

A PIN key change failed for terminal %1 with code %2. No PIN-based transactions can be processed.

Parameter %1:

The terminal ID

Parameter %2:

The key change response code

Description:

The key change failed. This is usually a cryptographic configuration problem between the PIN Pad and the upstream entity. The key change will be retried at regular intervals until successful.

Action:

Identify the reason that the key change failed.

Event 10030

Severity:

Error

Symbolic Name:

MISSING_DATA

Message:

Text:

Data required for mandatory field %1 could not be retrieved.

Parameter %1:

Field number

Description:

This event is logged when an eSocket.POS component fails to retrieve information which is required for a mandatory Iso8583 field.

Action:

Contact your primary support provider.

Event 10031

Severity:

Error

Symbolic Name:

NO_ORIGINAL_TRAN

Message:

Text:

An original transaction was required but could not be found.

Description:

An original transaction was required but was not found by the information server.

Action:

Contact your primary support provider.

Event 10032

Severity:

Error

Symbolic Name:

REMOTE_SINK_RECVD_MSG_CONTAINS_NO_SWITCH_KEY

Message:

Text:

The Sink Driver returned a message to the RemoteSink that does not contain a switch key ( 127.002 ). The message has been ignored

Description:

The Postilion Interface ( RemoteSink ) received a message with no switch key

Action:

Contact your primary support provider.

Event 10033

Severity:

Error

Symbolic Name:

SINK_ENTITY_UNSUPPORTED_MSG_FROM_TRAN_ENGINE

Message:

Text:

An unsupported message (%1) was received from the Transaction Engine at Terminal %2.

Parameter %1:

The message type

Parameter %2:

The terminal ID

Description:

The eSocket.POS Sink Entity received an unsupported message from the eSocket.POS Transaction Engine.

Action:

Contact your primary support provider.

Event 10034

Severity:

Error

Symbolic Name:

SOURCE_ENTITY_UNSUPPORTED_MSG_FROM_EPOS

Message:

Text:

An unsupported message (%1) was received from the EPOS system. Terminal ID %2.

Parameter %1:

The message type

Parameter %2:

The terminal ID

Description:

The eSocket.POS Source Entity received an unsupported message from the EPOS system.

Action:

Contact your primary support provider.

Event 10035

Severity:

Error

Symbolic Name:

TLV_EXTRACT_ERROR

Message:

Text:

An EMV formatted message could not be unpacked. This usually refers to incorrectly formatted TLV data or PDOL data received from an EMV smartcard. The data was as follows: %1.

Parameter %1:

Contents of the message

Description:

An error occurred while unpacking an EMV formatted message.

Action:

Contact your primary support provider.

Event 10036

Severity:

Error

Symbolic Name:

UNABLE_TO_CONSTRUCT_REJECT_RSP

Message:

Text:

eSocket.POS attempted to reject a message from the EPOS system but was unable to construct the reject response.

Description:

eSocket.POS attempted to reject a message from the EPOS system but was unable to construct the reject response.

Action:

Contact your primary support provider.

Event 10037

Severity:

Error

Symbolic Name:

UNABLE_TO_SAVE_MSG

Message:

Text:

eSocket.POS (Terminal %1) was unable to save a message using the information server.

Parameter %1:

Terminal ID

Description:

eSocket.POS was unable to save a message.

Action:

Check that the message was properly formatted and the information server was properly configured.

Event 10038

Severity:

Error

Symbolic Name:

UNSUPPORTED_MSG_TYPE

Message:

Text:

eSocket.POS received a message with an unsupported message type %1.

Parameter %1:

The unsupported message type received

Description:

eSocket.POS received a message with an unsupported message type.

Action:

Contact your primary support provider.

Event 10039

Severity:

Warning

Symbolic Name:

CLASS_NOT_FOUND

Message:

Text:

The information server for terminal %1 could not find the class %2.

Parameter %1:

The terminal ID

Parameter %2:

The requested data which is not contained in the store

Description:

The information server could not find the requested class.

Action:

Check that the class name is correctly configured and that the class is present in the correct location.

Event 10040

Severity:

Warning

Symbolic Name:

COMPONENT_DECLINED_TRAN

Message:

Text:

The %1 component on Terminal %3 has declined a transaction it received. The reason returned was: %2.

Parameter %1:

Component name

Parameter %2:

Description of why the transaction was declined

Parameter %3:

Terminal ID

Description:

This event is logged when an eSocket.POS component declines a transaction. The event includes the name of the component that declined the transaction and a description of why the transaction was declined

Action:

Contact your primary support provider.

Event 10041

Severity:

Warning

Symbolic Name:

CONFIG_AGENT_ROLLBACK_FAILED

Message:

Text:

The Configuration Agent was unable to completely rollback an aborted upload. The next event logged contains related technical information.

Description:

The Configuration Agent failed to rollback an aborted upload. This is not a critical failure as the data that could not be rolled back will not have marked active and will not be used by eSocket.POS

Action:

Contact your primary support provider.

Event 10042

Severity:

Warning

Symbolic Name:

COMPONENT_WRN_EXCEPTION

Message:

Text:

The %1 component on Terminal %3 has logged the following warning: %2.

Parameter %1:

Component name

Parameter %2:

Description of the exception condition

Parameter %3:

Terminal ID

Description:

This event is logged when a component wished to report an exception condition that, while not serious enough to stop processing, may require technical attention.

Action:

Contact your primary support provider.

Event 10043

Severity:

Warning

Symbolic Name:

FAILED_TO_RETRIEVE_DATA

Message:

Text:

The information server for terminal %1 failed to retrieve %2.

Parameter %1:

The terminal ID

Parameter %2:

The data which could not be retrieved

Description:

The information server failed to retrieve the requested data.

Action:

Contact your primary support provider.

Event 10044

Severity:

Warning

Symbolic Name:

FAILED_TO_DELETE_DATA

Message:

Text:

The information server for terminal %1 failed to delete data: %2.

Parameter %1:

The terminal ID

Parameter %2:

The data which could not be deleted

Description:

The information server failed to delete the requested data.

Action:

Contact your primary support provider.

Event 10045

Severity:

Warning

Symbolic Name:

FAILED_TO_STORE_REQUEST

Message:

Text:

The information server for terminal %1 failed to save a transaction request.

Parameter %1:

The terminal ID

Description:

The information server failed to save a transaction request.

Action:

Contact your primary support provider.

Event 10046

Severity:

Warning

Symbolic Name:

FAILED_TO_STORE_RESPONSE

Message:

Text:

The information server for terminal %1 failed to save a transaction response.

Parameter %1:

The terminal ID

Description:

The information server failed to save a transaction response.

Action:

Contact your primary support provider.

Event 10047

Severity:

Warning

Symbolic Name:

FAILED_TO_UPDATE_DATA

Message:

Text:

The information server for terminal %1 failed to update %2.

Parameter %1:

The terminal ID

Parameter %2:

The data which could not be updated

Description:

The information server failed to update the requested data.

Action:

Contact your primary support provider.

Event 10048

Severity:

Warning

Symbolic Name:

FAILED_TO_RETRIEVE_FROM_STORE

Message:

Text:

The information server for terminal %1 failed to retrieve information from the store.

Parameter %1:

The terminal ID

Description:

The information server failed to retrieve information from the store.

Action:

Contact your primary support provider.

Event 10049

Severity:

Warning

Symbolic Name:

FAILED_TO_RETRIEVE_MERCHANDISE_FROM_STORE

Message:

Text:

The information server for terminal %1 failed to retrieve merchandise information with transaction number %2 from the store.

Parameter %1:

The terminal ID

Parameter %2:

The transaction ID (Systems Trace Audit Number)

Description:

The information server failed to retrieve merchandise information from the store.

Action:

Contact your primary support provider.

Event 10050

Severity:

Warning

Symbolic Name:

FAILED_TO_RETRIEVE_TRAN_FROM_STORE

Message:

Text:

The information server for terminal %1 failed to retrieve a transaction list for the System Trace Audit Number %2 from the store.

Parameter %1:

The terminal ID

Parameter %2:

The transaction ID (Systems Trace Audit Number)

Description:

The information server failed to retrieve a transaction from the store.

Action:

Contact your primary support provider.

Event 10051

Severity:

Warning

Symbolic Name:

FAILED_TO_UPDATE_MERCHANDISE_IN_STORE

Message:

Text:

The information server for terminal %1 failed to update merchandise information with transaction number %2 in the store.

Parameter %1:

The terminal ID

Parameter %2:

The transaction ID (Systems Trace Audit Number)

Description:

The information server failed to update merchandise information in the store.

Action:

Contact your primary support provider.

Event 10052

Severity:

Warning

Symbolic Name:

KEYCHANGE_DISCONNECTED

Message:

Text:

A PIN key change could not be performed because eSocket.POS is disconnected for terminal %1.

Parameter %1:

The terminal ID

Description:

The key change could not be performed because eSocket.POS is disconnected. The key change will be retried at regular intervals until eSocket.POS is connected.

Action:

Identify why eSocket.POS is disconnected.

Event 10053

Severity:

Warning

Symbolic Name:

NOT_FOUND_IN_INFO_STORE

Message:

Text:

The information server for terminal %1 does not contain the requested data: %2.

Parameter %1:

The terminal ID

Parameter %2:

The requested data which is not contained in the store

Description:

The information server does not contain the requested data.

Action:

Identify why the requested data is missing.

Event 10054

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_CONFIG_LOAD_COMPLETED_SUCCESSFULLY

Message:

Text:

The Configuration Agent has successfully applied a new %1 configuration

Parameter %1:

The configuration type

Description:

The Config Agent successfully applied a new set of configuration files to the eSocket.POS database.

Action:

None.

Event 10055

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_CONFIG_LOAD_COMPLETED_UNSUCCESSFULLY

Message:

Text:

The Configuration Agent has not successfully applied a new %1 configuration

Parameter %1:

The configuration type

Description:

An error occurred while applying a set of configuration files.

Action:

Contact your primary support provider.

Event 10056

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_HOTCARD_LOAD_COMPLETE

Message:

Text:

The Configuration Agent has successfully loaded new hotcard information

Description:

The Config Agent successfully applied a new set of hotcard data to the eSocket.POS database.

Action:

None.

Event 10057

Severity:

Warning

Symbolic Name:

CONFIG_AGENT_HTTP_DOWNLOAD_FAILED

Message:

Text:

The Configuration Agent failed to download new configuration files via HTTP. Reason: %1

Parameter %1:

The reason given for the failure

Description:

An error occurred while attempting to download new configuration files via http. Configuration file download failures and Hotcard configuration file download failures are logged separately.

Action:

Contact your primary support provider.

Event 10058

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_HTTP_DOWNLOAD_COMPLETE

Message:

Text:

The Configuration Agent has successfully downloaded new configuration files via HTTP

Description:

New configuration files were successfully downloaded via HTTP.

Action:

None.

Event 10059

Severity:

Warning

Symbolic Name:

CONFIG_AGENT_CANT_CREATE_DOWNLOAD_DIR

Message:

Text:

The Configuration Agent was unable to create a directory in which to store downloaded configuration files

Description:

The configuration agent was unable to create a directory in which to store downloaded configuration files

Action:

Contact your primary support provider.

Event 10060

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_STARTED

Message:

Text:

The Configuration Agent has been successfully started

Description:

The Config Agent has started successfully.

Action:

None.

Event 10061

Severity:

Informational

Symbolic Name:

KEYCHANGE_SUCCESS

Message:

Text:

The PIN key was successfully exchanged for terminal %1.

Parameter %1:

The terminal ID

Description:

The key change succeeded.

Action:

None.

Event 10062

Severity:

Informational

Symbolic Name:

DEVICE_STATUS_EVENT

Message:

Text:

A status event was returned from device. Device Reason Code = %1.

Parameter %1:

Device reason/status code.

Description:

Declined status event returned from device.

Action:

Contact your primary support provider.

Event 10063

Severity:

Error

Symbolic Name:

XML_VALUE_VALIDATION_ERROR

Message:

Text:

The value specified in a xml element or attribute does not conform to the required format. Element/Attribute name: %1. Specified value: %2. Description: %3.

Parameter %1:

Field name

Parameter %2:

Value specified

Parameter %3:

Description

Description:

This event is logged if the value specified in a xml element or attribute does not conform to the required format.

Action:

Contact your primary support provider.

Event 10064

Severity:

Error

Symbolic Name:

DEVICE_CONFIG_LOAD_FAILED

Message:

Text:

The device configuration load for terminal %1 failed due to the following reason: %2

Parameter %1:

Terminal name

Parameter %2:

Description

Description:

This event is logged if device configuration loading failed.

Action:

Contact your primary support provider.

Event 10065

Severity:

Error

Symbolic Name:

ESP_PROPERTY_VALUE_ERROR

Message:

Text:

A property value for terminal %1 was incorrectly specified. Description: %2

Parameter %1:

The Terminal ID

Parameter %2:

A description of the error

Description:

This event is logged when a property found in the eSocket.POS properties file is incorrectly specified / formatted

Action:

Check the eSocket.POS configuration.

Event 10066

Severity:

Error

Symbolic Name:

DEVICE_COMMS_ERROR

Message:

Text:

A communication error occurred: %1

Parameter %1:

A description of the error

Description:

This event is logged if a problem occurs during serial or TCP/IP communication with a device

Action:

Check the communication configuration for the device.

Event 10067

Severity:

Informational

Symbolic Name:

CHECK_READ_MICR_UNPACK_FAIL

Message:

Text:

The checkreader at Terminal %3 was unable to unpack data %1 because %2.

Parameter %1:

The micr data line

Parameter %2:

Unpack fail reason

Parameter %3:

Terminal ID

Description:

This event is logged if the Check Read Component is unable to unpack the micr line

Action:

Contact your primary support provider.

Event 10068

Severity:

Error

Symbolic Name:

SMARTCARD_READER_ERROR

Message:

Text:

The smartcard reader encountered the following error: %1

Parameter %1:

The error encountered

Description:

This event is logged if the card reader encountered an error.

Action:

Contact your primary support provider.

Event 10069

Severity:

Error

Symbolic Name:

ATTEMPT_TO_SET_NULL_TLV_VALUE

Message:

Text:

A tlv field could not be set as the value provided for that field was null. The field tag was: %1

Parameter %1:

The tlv tag that was being set with a null value

Description:

This event is logged if a tlv field was set with a null value

Action:

Contact your primary support provider.

Event 10070

Severity:

Error

Symbolic Name:

DEVICE_TIMED_OUT

Message:

Text:

Timed out while waiting for a response from a %1 device.

Parameter %1:

Name of the entity which timed out

Description:

This event is logged if a time out was encountered while waiting for a response from a device.

Action:

Contact your primary support provider.

Event 10071

Severity:

Error

Symbolic Name:

MONITORING_MSG_NOT_SENT

Message:

Text:

A monitoring message could not be sent. At the time of this attempt the state of the eSocket.POS system was %1.

Parameter %1:

The system state when this error was logged.

Description:

This event is logged if the Monitoring component cannot send an 0800 Monitoring message because eSocket.POS is not connected.

Action:

Contact your primary support provider if necessary.

Event 10072

Severity:

Error

Symbolic Name:

DEVICE_UPDATE_FAILED

Message:

Text:

Update failed for the %1 device. The error reported was: %2.

Parameter %1:

The device name

Parameter %2:

The error message

Description:

This event is logged if a device firmware update fails.

Action:

Contact your primary support provider.

Event 10073

Severity:

Informational

Symbolic Name:

DEVICE_UPDATE_SUCCESS

Message:

Text:

Firmware update completed successfully for the %1 device.

Parameter %1:

The device name

Description:

This event is logged if a device firmware update completes successfully.

Action:

None.

Event 10074

Severity:

Error

Symbolic Name:

CLASS_VERSION_MISMATCH

Message:

Text:

The current class version does not match the required one. A possible VM restart may be required to load a patched class. If problems are encountered after the restart, please contact your primary support provider to obtain the updated device integration code.

Description:

This event is logged after a device firmware update completes successfully but the class version validation fails.

Action:

Restart the VM. Contact your primary support provider if the problem persists.

Event 10075

Severity:

Informational

Symbolic Name:

SOFTWARE_UPDATE_COMPLETED

Message:

Text:

The Configuration agent has successfully applied a new software update

Description:

This event is logged after a software update completes successfully

Action:

None.

Event 10076

Severity:

Error

Symbolic Name:

SOFTWARE_UPDATE_FAILED

Message:

Text:

The Configuration agent failed to apply the new software update

Description:

This event is logged if a software update failed to complete

Action:

Contact your primary support provider.

Event 10077

Severity:

Informational

Symbolic Name:

SOFTWARE_UPDATE_ROLLBACK_COMPLETED

Message:

Text:

The Configuration agent has successfully rolled back the failed software update

Description:

This event is logged after a software update has been rolled back

Action:

None.

Event 10078

Severity:

Informational

Symbolic Name:

SOFTWARE_UPDATE_CONFIGURATION_NOT_APPLIED

Message:

Text:

The Configuration agent has not applied the set of configuration files due to a failed software update

Description:

This event is logged after a software update has failed, therefore the associated configuration was not applied

Action:

Contact your primary support provider.

Event 10079

Severity:

Error

Symbolic Name:

FATAL_PRINTER_ERROR

Message:

Text:

A fatal printer error has occurred. The receipt printing has been aborted.

Description:

This event is logged when a fatal printer error occurs and a receipt could not be printed.

Action:

Contact your primary support provider.

Event 10080

Severity:

Error

Symbolic Name:

RECEIPT_PARSE_FAILURE

Message:

Text:

A receipt of type %1 could not be constructed. The receipt printing has been aborted. The following error has been reported: %2

Parameter %1:

The receipt type that could not be parsed.

Parameter %2:

A description of the exact problem that has occurred.

Description:

This event is logged if a raw receipt definition could not be parsed.

Action:

Contact your primary support provider.

Event 10081

Severity:

Error

Symbolic Name:

REMOTE_SINK_DISCARDED_ADVICE

Message:

Text:

The RemoteSink discarded an advice message after %1 attempts to send it.

Parameter %1:

The number of attempts to send the message after which it was discarded.

Description:

The Postilion Interface (RemoteSink) discarded an advice message after exceeding the maximum number of retry attempts.

Action:

Investigate why eSocket.POS did not receive a response to this advice. This transaction may be resubmitted.

Event 10082

Severity:

Informational

Symbolic Name:

SQL_DATA_UPDATE_COMPLETED

Message:

Text:

The Configuration agent has successfully applied a new SQL data update

Description:

This event is logged after a SQL data update completes successfully

Action:

None.

Event 10083

Severity:

Error

Symbolic Name:

SQL_DATA_UPDATE_FAILED

Message:

Text:

The Configuration agent failed to apply the new SQL data update

Description:

This event is logged if a SQL data update failed to complete

Action:

Contact your primary support provider.

Event 10084

Severity:

Informational

Symbolic Name:

SQL_DATA_UPDATE_ROLLBACK_COMPLETED

Message:

Text:

The Configuration agent has successfully rolled back the failed SQL data update

Description:

This event is logged after a SQL data update has been rolled back

Action:

None.

Event 10085

Severity:

Informational

Symbolic Name:

SOFTWARE_UPGRADE_PENDING

Message:

Text:

Upgrade(s) pending: %1. Configuration changes will not be applied until all upgrades are complete.

Parameter %1:

The names of the pending software upgrades.

Description:

This event is logged when Configuration changes are not loaded yet because there are upgrades pending.

Action:

None.

Event 10086

Severity:

Warning

Symbolic Name:

CONFIG_AGENT_HTTP_UPLOAD_FAILED

Message:

Text:

The Configuration Agent failed to upload files via http. Reason: %1

Parameter %1:

The reason given for the failure

Description:

An error occurred while attempting to upload files via http

Action:

Contact your primary support provider.

Event 10087

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_HTTP_UPLOAD_COMPLETE

Message:

Text:

The Configuration Agent has successfully uploaded files via HTTP

Description:

New files were successfully uploaded via HTTP.

Action:

None.

Event 10088

Severity:

Error

Symbolic Name:

LOG_DRIVER_FAILURE

Message:

Text:

The Log Driver %1 threw the following exception: %2

Parameter %1:

The name of the log driver

Parameter %2:

The exception that was thrown

Description:

A log driver threw an exception while attempting to log an event.

Action:

Contact your primary support provider.

Event 10089

Severity:

Error

Symbolic Name:

CHAINED_TRAN_RESOLVE_FAILURE

Message:

Text:

PosConnectSinkDriver could not resolve the system trace number %1 to a previous transaction.

Parameter %1:

The invalid System Trace Audit Number

Description:

This event is logged when PosConnectSinkDriver fails to resolve a chained transaction id to a previous transaction.

Action:

Contact your primary support provider.

Event 10090

Severity:

Error

Symbolic Name:

FAIL_TO_RENAME_FILE

Message:

Text:

Config Agent could not rename the file %1.

Parameter %1:

The name of the file

Description:

This event is logged when Config Agent fails to rename an upload file.

Action:

Contact your primary support provider.

Event 10091

Severity:

Error

Symbolic Name:

RANK_NOT_INTEGER

Message:

Text:

The rank for the %1 pipeline component must be an integer. %2 is not a valid rank value.

Parameter %1:

The pipeline component tag

Parameter %2:

The pipeline component rank

Description:

This event is logged if the value configured for the rank of a pipeline component is not an integer.

Action:

Contact your primary support provider.

Event 10092

Severity:

Error

Symbolic Name:

ESP_GLOBAL_PROPERTY_VALUE_ERROR

Message:

Text:

The value for property, %1, is invalid. Description: %2

Parameter %1:

The name of the property

Parameter %2:

A description of the error

Description:

This event is logged when a property found in the eSocket.POS properties file is incorrectly specified / formatted

Action:

Check the eSocket.POS properties file configuration.

Event 10093

Severity:

Error

Symbolic Name:

PAN_ENCRYPTION_KEY_MISSING

Message:

Text:

The RSA Public Key required for PAN encryption is not available.

Description:

This event is logged when a PAN cannot be encrypted because there is no RSA Public Key available to use for encryption.

Action:

Contact your primary support provider.

Event 10094

Severity:

Informational

Symbolic Name:

CERTIFICATE_CHANGE_SUCCESS

Message:

Text:

The RSA Certificate with alias, %1, was successfully retrieved and stored.

Parameter %1:

The alias of the certificate.

Description:

The RSA certificate change succeeded.

Action:

None.

Event 10095

Severity:

Error

Symbolic Name:

CERTIFICATE_CHANGE_INVALID_RESPONSE

Message:

Text:

The RSA Certificate change cannot be processed: %1.

Parameter %1:

The reason for the failure.

Description:

The RSA certificate change 0810 response message is invalid or the request was declined.

Action:

Identify the reason that the certificate change failed.

Event 10096

Severity:

Error

Symbolic Name:

CERTIFICATE_CHANGE_EXCEPTION

Message:

Text:

The RSA Certificate change cannot be processed by terminal, %1, because of an unexpected exception.

Parameter %1:

The terminal ID that attempted to process the request

Description:

The RSA Certificate change cannot be processed because of an unexpected exception.

Action:

Identify the reason that the certificate change failed.

Event 10097

Severity:

Warning

Symbolic Name:

CERTIFICATE_CHANGE_DISCONNECTED

Message:

Text:

An RSA Certificate change could not be performed because eSocket.POS is disconnected for terminal %1.

Parameter %1:

The terminal ID

Description:

The certificate change could not be performed because eSocket.POS is disconnected. The certificate change will be retried at regular intervals until eSocket.POS is connected.

Action:

Identify why eSocket.POS is disconnected.

Event 10098

Severity:

Informational

Symbolic Name:

RSA_CERTIFICATE_UPDATE_COMPLETED

Message:

Text:

The Configuration agent has successfully updated an RSA certificate.

Description:

This event is logged after an RSA certificate update completes successfully

Action:

None.

Event 10099

Severity:

Error

Symbolic Name:

RSA_CERTIFICATE_UPDATE_FAILED

Message:

Text:

The Configuration agent failed to update an RSA certificate.

Description:

This event is logged if an RSA certificate update failed to complete

Action:

Contact your primary support provider.

Event 10100

Severity:

Error

Symbolic Name:

SSL_SERVER_AUTHENTICATION_FAILURE

Message:

Text:

The SSL certificate provided by the server is not trusted. Server details: %1. Serial number: %2.

Parameter %1:

The server certificate details.

Parameter %2:

The server certificate serial number.

Description:

This event is logged if the server certificate provided by the server during the SSL handshake is not trusted.

Action:

Check the SSL configuration.

Event 10101

Severity:

Informational

Symbolic Name:

SSL_KEYSTORE_INITIALIZATION

Message:

Text:

An SSL connection has been established for the first time. The following server certificate will be trusted in the future: %1. Serial number: %2.

Parameter %1:

The server certificate details.

Parameter %2:

The server certificate serial number.

Description:

This event is logged when eSocket.POS or Config Agent connect to the server for the first time and receive a certificate that they will trust in the future.

Action:

Check the SSL configuration.

Event 10102

Severity:

Error

Symbolic Name:

CONFIG_AGENT_HTTP_DISCONNECT_FAILED

Message:

Text:

The Configuration Agent failed to disconnect from the HTTP server.

Description:

An error occurred while attempting to disconnect from the HTTP server

Action:

Contact your primary support provider.

Event 10103

Severity:

Informational

Symbolic Name:

ESOCKETPOS_STOPPED

Message:

Text:

eSocket.POS has been closed for terminal %1.

Parameter %1:

The terminal ID of the terminal that was closed.

Description:

This event is logged when eSocket.POS is shut down for a terminal

Action:

Event 10104

Severity:

Warning

Symbolic Name:

CONFIG_AGENT_UNABLE_TO_GET_INSTALLED_APPS

Message:

Text:

The Configuration Agent failed to determine the installed applications.

Description:

The list of installed applications could not be determined.

Action:

Contact your primary support provider.

Event 10105

Severity:

Error

Symbolic Name:

REMOTE_SINK_DISCARDED_ADVICE_AFTER_MAX_TIME_LIMIT

Message:

Text:

The RemoteSink discarded an advice message (transaction number %1) after approximately %2 minutes, due to a software or database error.

Parameter %1:

The approximate maximum time limit in minutes to retry sending the message.

Description:

The Postilion Interface (RemoteSink) discarded an advice message after approximately the maximum retry time limit, due to a software or database error.

Action:

Investigate why eSocket.POS could not send this message.

Event 10106

Severity:

Warning

Symbolic Name:

SINK_DRIVER_RESPONSE_PROCESSING_ERROR

Message:

Text:

The Sink Driver encountered an error when attempting to process a response received from the upstream entity. See the previous event for more information.

Description:

The Sink Driver encountered an error when attempting to process a response received from the upstream entity.

Action:

Investigate why the sink driver encountered an error.

Event 10107

Severity:

Error

Symbolic Name:

FAILED_TO_RESTART

Message:

Text:

eSocket.POS could not be restarted. The error reported is as follows: %1 Details of the error are as follows: %2

Parameter %1:

Error reported.

Parameter %2:

The exception that caused the error.

Description:

This event is logged when eSocket.POS fails to restart properly.

Action:

Check the eSocket.POS configuration.

Event 10108

Severity:

Error

Symbolic Name:

FAILED_TO_RESYNC

Message:

Text:

Could not resync eSocket.POS for terminal %1. The error reported is as follows: %2.

Parameter %1:

Terminal identifier.

Parameter %2:

Error reported.

Description:

This event is logged when eSocket.POS fails to resync a terminal.

Action:

Check the eSocket.POS configuration.

Event 10109

Severity:

Informational

Symbolic Name:

GLOBAL_RESTART

Message:

Text:

Global restart initiated.

Description:

This event is logged before eSocket.POS attempts to restart.

Action:

None.

Event 10110

Severity:

Error

Symbolic Name:

TRANSACTION_FAIL_RESYNC_IN_PROGRESS

Message:

Text:

Could not process transaction for terminal %1 because a resync is in progress.

Parameter %1:

Terminal identifier.

Description:

This event is logged when eSocket.POS fails to process a transaction because a resync is in progress.

Action:

Resend transaction after resync completed.

Event 10111

Severity:

Error

Symbolic Name:

TASK_HANDLER_TASK_FAIL

Message:

Text:

A task failed due to the following error: %1 %2

Parameter %1:

The exception that caused the error.

Parameter %2:

Stack trace

Description:

This event is logged when one of the task handler tasks fails due to a runtime exception.

Action:

Check the eSocket.POS configuration.

Event 10112

Severity:

Warning

Symbolic Name:

PROCESSING_TERMINATED_TERMINAL_INSTANCE_CLOSED

Message:

Text:

The transaction cannot be processed: the eSocket.POS terminal instance has been closed.

Description:

This event is logged when an eSocket.POS instance is closed while a transaction is in flight.

Action:

No action is required.

Event 10113

Severity:

Informational

Symbolic Name:

CUSTOMER_CANCELLED

Message:

Text:

Transaction cancelled by customer.

Description:

This event is logged when the customer cancelled the transaction.

Action:

No action is required.

Event 10114

Severity:

Warning

Symbolic Name:

CUSTOMER_TIMEOUT

Message:

Text:

Timeout while waiting for customer response.

Description:

This event is logged when a timeout occurs while awaiting customer information.

Action:

No action is required.

Event 10115

Severity:

Error

Symbolic Name:

CARD_READ_RETRIES_EXCEEDED

Message:

Text:

The number of card read retries is exceeded. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when the number of card read retries is exceeded.

Action:

No action is required.

Event 10116

Severity:

Error

Symbolic Name:

NO_SUPPORTED_APPLICATIONS

Message:

Text:

No supported applications were found. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when there are no supported applications.

Action:

No action is required.

Event 10117

Severity:

Error

Symbolic Name:

CARDHOLDER_VERIFICATION_FAILURE

Message:

Text:

Cardholder verification has failed. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when cardholder verification fails.

Action:

No action is required.

Event 10118

Severity:

Warning

Symbolic Name:

ICC_BLOCKED

Message:

Text:

ICC data is blocked.

Description:

This event is logged when ICC data is blocked.

Action:

No action is required.

Event 10119

Severity:

Error

Symbolic Name:

ICC_TRANSACTION_FAILED

Message:

Text:

An ICC transaction has failed. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when an ICC transaction fails.

Action:

No action is required.

Event 10120

Severity:

Error

Symbolic Name:

DEVICE_FAILURE

Message:

Text:

A device failure occurred. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when the device fails.

Action:

No action is required.

Event 10121

Severity:

Error

Symbolic Name:

FAILURE_TO_COMPLETE_ONLINE_TRANSACTION

Message:

Text:

Failure to complete online transaction. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when an online transaction was not completed.

Action:

No action is required.

Event 10122

Severity:

Warning

Symbolic Name:

CARD_STILL_IN_SLOT

Message:

Text:

The card is still in the slot.

Description:

This event is logged when the card is still in the slot.

Action:

No action is required.

Event 10123

Severity:

Error

Symbolic Name:

CARD_INSERT_RETRIES_EXCEEDED

Message:

Text:

The card insert retries have been exceeded. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when the card insert retries have been exceeded.

Action:

No action is required.

Event 10124

Severity:

Informational

Symbolic Name:

OPERATOR_CANCELLED

Message:

Text:

The operator has cancelled an operation.

Description:

This event is logged when the operator cancels a transaction.

Action:

No action is required.

Event 10125

Severity:

Error

Symbolic Name:

FAILED_TO_START_ENTITY

Message:

Text:

eSocket.POS could not be started for terminal %1, entity %2 The error reported is as follows: %3

Parameter %1:

The Terminal ID

Parameter %2:

The entity name

Parameter %3:

Error reported, or name of the entity which could not be instantiated

Description:

This event is logged when eSocket.POS fails to start properly.

Action:

Check the eSocket.POS configuration.

Event 10126

Severity:

Error

Symbolic Name:

FAILED_TO_START_MESSAGE

Message:

Text:

eSocket.POS could not be started. The error reported is as follows: %1.

Parameter %1:

Error reported, due to nature of the error, no further information is available.

Description:

This event is logged when eSocket.POS fails to start properly.

Action:

Check the eSocket.POS configuration.

Event 10127

Severity:

Error

Symbolic Name:

ESOCKETPOS_MISCONFIGURED

Message:

Text:

eSocket.POS is not configured correctly. The error reported is as follows: %1

Parameter %1:

Error reported.

Description:

This event is logged when eSocket.POS is not configured correctly.

Action:

Check the eSocket.POS configuration.

Event 10128

Severity:

Error

Symbolic Name:

DEVICE_CONNECT_FAILURE

Message:

Text:

A device connection failed for terminal ID %1 (SAP address %2, SetupData %3).

Parameter %1:

The terminal ID

Parameter %2:

The SAP address

Parameter %3:

The setup data

Description:

A device connection failed.

Action:

Contact your primary support provider.

Event 10129

Severity:

Error

Symbolic Name:

FAILED_TO_MASK_SENSITIVE_DATA

Message:

Text:

eSocket.POS failed to mask %1 because %2.

Parameter %1:

The name of the sensitive data field

Parameter %2:

The error reported

Description:

Failed to mask sensitive data.

Action:

Contact your primary support provider.

Event 10130

Severity:

Warning

Symbolic Name:

NOT_PCI_COMPLIANT

Message:

Text:

%1 may have been started in a non-PCI compliant manner. The configuration causing concern is: %2

Parameter %1:

The eSocket.POS specific application, ie. eSocket.POS or Config Agent.

Parameter %2:

The configuration that may cause eSocket.POS to not be PCI compliant

Description:

eSocket.POS may have been started in a non-PCI compliant manner.

Action:

Consult the eSocket.POS documentation and check the configuration.

Event 10131

Severity:

Error

Symbolic Name:

ESP_SAP_INVALID_CONFIG

Message:

Text:

The SAP configuration is not valid. The error reported is as follows: %1

Parameter %1:

Error reported.

Description:

This event is logged when a SAP is incorrectly configured.

Action:

Verify that the SAP configuration is correct.

Event 10132

Severity:

Warning

Symbolic Name:

SSL_LOCAL_CERT_OLD

Message:

Text:

The current date and time is close to the expiry date given in a certificate that was used to authenticate eSocket.POS to a remote entity. The certificate with alias %1 is valid until %2. Certificate Details: %3. Serial number: %4.

Parameter %1:

The alias used to retrieve the certificate from the SSL keystore.

Parameter %2:

The not after date of the validity period taken from the certificate.

Parameter %3:

The subject distinguished name from the certificate.

Parameter %4:

The serial number from the certificate.

Description:

This is event is logged if the current date and time is close to the expiry date given in a certificate that was used to authenticate eSocket.POS to a remote entity.

Action:

Update the local certificate before it expires.

Event 10133

Severity:

Warning

Symbolic Name:

SSL_LOCAL_CERT_NOT_VALID

Message:

Text:

The current date and time is not within the validity period given in a certificate that was selected for authenticating eSocket.POS to the remote entity. The certificate with alias %1 is valid from %2 until %3. Certificate Details: %4. Serial Number: %5.

Parameter %1:

The alias used to retrieve the certificate from the SSL keystore.

Parameter %2:

The not before date of the validity period taken from the certificate.

Parameter %3:

The not after date of the validity period taken from the certificate.

Parameter %4:

The subject distinguished name from the certificate.

Parameter %5:

The serial number from the certificate.

Description:

This event is logged when the current date and time is not within the validity period given in a certificate that was selected for authenticating eSocket.POS to a remote entity. eSocket.POS will not drop the SSL connection, but it is likely that the remote entity will.

Action:

If the connection fails then the local certificate should be updated, or the configuration should be updated to use a different local certificate.

Event 10134

Severity:

Error

Symbolic Name:

SSL_CLIENT_AUTHENTICATION_FAILURE

Message:

Text:

The SSL certificate provided by the client is not trusted. Client details: %1. Serial number: %2.

Parameter %1:

The client certificate details.

Parameter %2:

The client certificate serial number.

Description:

This event is logged if the certificate provided by the remote client during the SSL handshake is not trusted.

Action:

Check the SSL configuration.

Event 10135

Severity:

Error

Symbolic Name:

SSL_NO_SERVER_CERTIFICATE

Message:

Text:

The remote server did not provide a SSL certificate, the connection will be dropped.

Description:

This event is logged if the server does not provide a certificate and eSocket.POS is required to authenticate the server.

Action:

Check the SSL configuration on eSocket.POS and on the remote server.

Event 10136

Severity:

Error

Symbolic Name:

MESSAGE_ENCRYPTION_KEY_MISSING

Message:

Text:

The RSA Public Key required for MESSAGE encryption is not available.

Description:

This event is logged when a message cannot be encrypted because there is no RSA Public Key available to use for encryption.

Action:

Contact your primary support provider.

Event 10137

Severity:

Error

Symbolic Name:

MSG_DECRYPTION_ERROR

Message:

Text:

The endpointfilter could not decrypt a message and the message will be ignored.

Description:

This event is logged when a general error occurred while decrypting a message in the EndpointFilterEncrypt class.

Action:

Contact your primary support provider.

Event 10138

Severity:

Error

Symbolic Name:

MSG_ENCRYPTION_ERROR

Message:

Text:

The endpoint filter could not encrypt a message and the message will be ignored.

Description:

This event is logged when a general error occurred while encrypting a message in the EndpointFilterEncrypt class.

Action:

Contact your primary support provider.

Event 10139

Severity:

Error

Symbolic Name:

CIPHER_KEY_GENERATION_ERROR

Message:

Text:

A new cipher key could not be generated.

Description:

This event is logged when an error occurred when a new cipher key was generated for message encryption.

Action:

Contact your primary support provider.

Event 10140

Severity:

Warning

Symbolic Name:

SECURE_DIRECTORY_CREATED

Message:

Text:

Config Agent created the secure config directory at: %1. Ensure that the security permissions to this directory is configured such that only the Config Agent and Upgrade Manager processes has write privileges to it.

Parameter %1:

The name of the secure incoming directory.

Description:

This event is logged when Config Agent creates the secure config directory. This directory is used internally by the application and it should be configured such that only the Config Agent and Upgrade Manager processes has write privileges to it.

Action:

Configure the security permissions such that only the Config Agent and Upgrade Manager processes has write access to this directory.

Event 10141

Severity:

Warning

Symbolic Name:

SIGNING_CERTIFICATE_INITIALIZATION

Message:

Text:

A signing certificate is being loaded for the first time and it will be trusted in future. Please inspect the following certificate and ensure that it is trusted: %1

Parameter %1:

The certificate details.

Description:

This event is logged the first time that Config Agent receives a signer certificate as part of a PKI Data Update. The certificate will be trusted in the future.

Action:

Inspect the installed certificate and ensure that it belongs to a trusted source.

Event 10142

Severity:

Error

Symbolic Name:

JAR_AUTHENTICATION_FAILURE

Message:

Text:

The Configuration Agent was unable to authenticate the file "%1". The following reason was reported: %2 %3

Parameter %1:

The name of the file that failed authentication

Parameter %2:

The reason that authentication failed

Parameter %3:

Additional Data associated with the error

Description:

This event is logged when authentication of a JAR file fails.

Action:

Ensure that the Configuration Server is correctly configured to distribute signed files and that the correct certificates are loaded into the eSocket.POS Trusted Certificate Store.

Event 10143

Severity:

Informational

Symbolic Name:

PKI_DATA_UPDATE_COMPLETED

Message:

Text:

The Configuration agent has successfully applied a PKI Data Update.

Description:

This event is logged after successfully applying a PKI data update.

Action:

None.

Event 10144

Severity:

Error

Symbolic Name:

PKI_DATA_UPDATE_FAILED

Message:

Text:

The Configuration agent failed to apply a PKI Data Update.

Description:

This event is logged if a PKI data update failed.

Action:

Contact your primary support provider.

Event 10145

Severity:

Error

Symbolic Name:

JVM_VERSION_NOT_SUPPORTED

Message:

Text:

An attempt was made to use functionality that is not supported on the version of the Java Virtual Machine that is currently running. The description of the functionality is as follows: %1

Parameter %1:

A description of the functionality that is not supported on this JVM.

Description:

Some functionality is only supported on specific versions of the Java Virtual Machine. This error is logged when an attempt is made to use functionality that is not supported on the current Java Virtual Machine.

Action:

Install a later version of the Java Virtual Machine or disable the feature that is not supported on the current version.

Event 10146

Severity:

Error

Symbolic Name:

CONFIG_AGENT_FILE_PARSE_FAILED

Message:

Text:

The Configuration Agent was unable to parse an upload file successfully: "%1". The exception reported is as follows: %2

Parameter %1:

an error message providing additional information about the error.

Parameter %2:

the report of the last exception recorded during the parsing of the load file.

Description:

An error occurred while parsing and loading the contents of an upload file

Action:

Contact your primary support provider.

Event 10147

Severity:

Warning

Symbolic Name:

SECURITY_PROVIDER_LOAD_FAILED

Message:

Text:

The security provider class that is required for PCI SSF compliancy could not be loaded: %1

Parameter %1:

The fully qualified name of the security provider class that could not be loaded.

Description:

This warning is logged when eSocket.POS fails to load the security provider class. This is not an error condition but it indicates that eSocket.POS cannot be configured for PCI SSF compliancy and an attempt to make use of the PCI SSF features may result in an error.

Action:

No action required. See the eSocket.POS user guide for more information on PCI Software Security Framework.

Event 10148

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_HTTP_RETRYING_FAILED_DOWNLOAD

Message:

Text:

The Configuration Agent failed to download new configuration files via HTTP. Reason: %1. The download will be retried in %2 seconds. If the download fails again, it will be retried %3 more time(s).

Parameter %1:

The reason given for the failure

Parameter %2:

The number of seconds before the download is going to be retried

Parameter %3:

The number of times the download will be retried if it fails again

Description:

An error occurred while attempting to download new configuration files via HTTP and the download is going to be retried.

Action:

None.

Event 10149

Severity:

Informational

Symbolic Name:

ESOCKETPOS_PRE_INITIALISED

Message:

Text:

The application %1 was pre-initialized with parameters %2.

Parameter %1:

the application

Parameter %2:

startup parameters

Description:

The application has started pre-initialised

Action:

None.

Event 10150

Severity:

Error

Symbolic Name:

CONFIG_AGENT_INCOMPLETE_DOWNLOAD

Message:

Text:

The Configuration Agent downloaded an incomplete set of configuration files. These files have not been applied as this could lead to an inconsistent configuration.

Description:

Configuration Agent did not download all the configuration file types.

Action:

Check the status of the Configuration Server to determine why not all file types were retrieved.

Event 10151

Severity:

Informational

Symbolic Name:

ESOCKETPOS_SECURITY_REGISTER_PRIVILEGED

Message:

Text:

The privileged software module with class name %1 has registered itself with the eSocket.POS access controller. This privileged module will be allowed to access sensitive data.

Parameter %1:

the name of the privileged module class

Description:

A privileged software module has registered itself with the eSocket.POS access controller. This privileged module will be allowed to access sensitive data.

Action:

None.

Event 10152

Severity:

Informational

Symbolic Name:

ESOCKETPOS_SECURITY_REGISTER_PRIVILEGED_LIST

Message:

Text:

The following privileged software modules have registered themselves with the eSocket.POS access controller: %1. These privileged modules will be allowed to access sensitive data.

Parameter %1:

the names of the privileged module classes

Description:

This event records a list of all privileged software modules that have registered themselves with the eSocket.POS access controller. These privileged modules will be allowed to access sensitive data.

Action:

None.

Event 10153

Severity:

Informational

Symbolic Name:

STORE_CLEANER_COMPLETED

Message:

Text:

The Store Cleaner has completed.

Description:

This event is logged when the Store Cleaner has completed.

Action:

None.

Event 10154

Severity:

Warning

Symbolic Name:

DEVICE_SERIAL_NR_VALIDATION_FAILED

Message:

Text:

Serial Number Validation has failed and the %1 device has moved to a DENIED state. Access to the device is now denied for processing financial data. The %3 application has denied the %2 serial number because %4. %5

Parameter %1:

the device for which the serial number validation failed.

Parameter %2:

the serial number of the connected device, if known.

Parameter %3:

the authorizing entity: the POS or eSocket.POS

Parameter %4:

a description of why serial number validation failed.

Parameter %5:

additional information e.g. is serial nr configured in database?

Description:

This event is logged when the device moves from an UNKNOWN or ALLOWED state into a DECLINED state following Serial Number Validation failure.

Action:

Investigate why validation has failed for the connected device.

Event 10155

Severity:

Informational

Symbolic Name:

DEVICE_SERIAL_NR_VALIDATED

Message:

Text:

Serial Number Validation has succeeded and the %1 device has moved to an ALLOWED state. The device can now therefore be accessed for processing financial data. The %3 application has validated the %2 serial number because %4. %5

Parameter %1:

the device for which the serial number validation succeeded.

Parameter %2:

the serial number of the connected device, if known.

Parameter %3:

the authorizing entity: POS or eSocket.POS.

Parameter %4:

a description of why serial number validation succeeded.

Parameter %5:

additional information e.g. is serial nr configured in database?

Description:

This event is logged when the device moves from an UNKNOWN or DENIED state into an ALLOWED state following Serial Number Validation success.

Action:

None.

Event 10156

Severity:

Informational

Symbolic Name:

DEVICE_SERIAL_NR_CHANGED

Message:

Text:

The serial number of the %1 device has changed. The last serial number to be retrieved was %2. The current serial number is %3. %4

Parameter %1:

the device for which the serial number has changed.

Parameter %2:

the serial number of the last connected device (if applicable).

Parameter %3:

the serial number of the connected device (if applicable).

Parameter %4:

additional info: e.g. is serial nr configured in database? is device disconnected?

Description:

This event is logged when a change is detected in the device serial number during Serial Number Validation. The change may relate to a new device, a replaced device or a disconnected device.

Action:

Action to be determined by merchant.

Event 10157

Severity:

Error

Symbolic Name:

EVENT_DATA_INVALID

Message:

Text:

The %1 event or callback received by %2 has the following invalid event data: %3 The specific error(s) are: %4. As a result %5. %6

Parameter %1:

the event or callback with invalid data.

Parameter %2:

a description of the event listener.

Parameter %3:

the invalid event data.

Parameter %4:

specific error(s).

Parameter %5:

the resulting behavior.

Parameter %6:

additional information.

Description:

This event is logged when an event or callback has invalid data.

Action:

Investigate the root cause.

Event 10158

Severity:

Warning

Symbolic Name:

EVENT_DISCARDED

Message:

Text:

The %1 event or callback received by %2 has been discarded. The event data is: %3 The reason(s) are: %4. %5

Parameter %1:

the discarded event or callback.

Parameter %2:

a description of the event listener.

Parameter %3:

the event data.

Parameter %4:

specific reason(s).

Parameter %5:

additional information.

Description:

This event is logged when an event or callback is discarded.

Action:

Investigate the root cause.

Event 10159

Severity:

Error

Symbolic Name:

CALLBACK_TIMED_OUT

Message:

Text:

The %1 callback has timed out. The entity listening for the event is: %2. As a result %3.

Parameter %1:

the callback name.

Parameter %2:

a description for the event listener.

Parameter %3:

the resulting behavior.

Description:

This event is logged when a callback response is expected but is not recieved.

Action:

Investigate the root cause.

Event 10160

Severity:

Informational

Symbolic Name:

PERIPHERAL_DEVICE_CONNECTED

Message:

Text:

The %1 device has been connected or come online. %2

Parameter %1:

the device name.

Parameter %2:

additional information e.g. context or resulting behavior.

Description:

A peripheral device has been connected.

Action:

None or merchant specific.

Event 10161

Severity:

Informational

Symbolic Name:

PERIPHERAL_DEVICE_DISCONNECTED

Message:

Text:

The %1 device has been disconnected or is unresponsive due to a device error. %2

Parameter %1:

the device name.

Parameter %2:

additional information e.g. context or resulting behavior.

Description:

A peripheral device has been disconnected.

Action:

Check the device connectivity and validity.

Event 10162

Severity:

Error

Symbolic Name:

INCONSISTENT_INCREMENTAL_HOTCARD_LOAD

Message:

Text:

The configuration agent attempted to apply an invalid incremental hotcard update. A hashing algorithm different from the one currently active was specified in the file. The update has been aborted.

Description:

This event is logged when the algorithm indicator in an incremental hotcard update file differs from the one recorded in the database.

Action:

Ensure that the hashing algorithm used by Config Server is consistent with that used by the latest hotcards in the eSocket.POS database.

Event 10163

Severity:

Error

Symbolic Name:

INVALID_SALT_FORMAT

Message:

Text:

The configuration agent attempted to load an invalidly formatted hotcard salt. The salt was not a 24-byte hexadecimal string. A message will be sent to inform Config Server.

Description:

This event is logged when the hotcard salt retrieved by the configuration agent is not a 24-byte hexadecimal string.

Action:

Ensure that the salt supplied by Config Server is a 24-byte hexadecimal string.

Event 10164

Severity:

Informational

Symbolic Name:

HOTCARD_SALT_LOADED_SUCCESSFULLY

Message:

Text:

The configuration agent has successfully loaded new hotcard salt data into the keystore.

Description:

This event is logged when the Config Agent successfully loads new hotcard salt data into the keystore.

Action:

None.

Event 10165

Severity:

Error

Symbolic Name:

NO_CONFIG_SERVER_SALT

Message:

Text:

The configuration agent attempted to apply a full hotcard update that uses the SHA-2 hashing algorithm. Currently, no salt data for this algorithm has been loaded into the keystore. The update has been aborted.

Description:

This event is logged when a full SHA-2 hotcard update is attempted before salt has been loaded into the keystore.

Action:

Ensure that the hotcard file(s) you are attempting to load are accompanied by a file containing salt data.

Event 10166

Severity:

Informational

Symbolic Name:

ESOCKETPOS_SECURITY_PERMISSIONS_REQUESTED

Message:

Text:

The secure software module with class name %1 has requested the following permission(s) from the eSocket.POS access controller: %2

Parameter %1:

the name of the secure module class

Parameter %2:

the names of the requested permissions

Description:

This event is logged when a secure module requests permissions to access sensitive data from the access controller.

Action:

None.

Event 10167

Severity:

Informational

Symbolic Name:

RKD_SUCCESSFUL_FOR_DEVICE

Message:

Text:

A key exchange was succesfully applied for the RKD device %1.

Parameter %1:

the name of the RKD device

Description:

This event is logged after a successful Remote Key Distribution for a particular device.

Action:

None.

Event 10168

Severity:

Warning

Symbolic Name:

RKD_RETRY_FOR_DEVICE

Message:

Text:

A key exchange was unsuccessful for the RKD device %1. The process will be retried in %2 seconds.

Parameter %1:

the name of the RKD device

Parameter %2:

the delay until the retry attempt

Description:

This event is logged when a key exchange fails for an RKD device, and a retry will be attempted.

Action:

None.

Event 10169

Severity:

Error

Symbolic Name:

RKD_FAILED_FOR_DEVICE

Message:

Text:

A key exchange for the RKD device %1 has failed after the %2 retries configured. No more attempts will be made.

Parameter %1:

the name of the RKD device

Parameter %2:

the configured number of retries

Description:

This event is logged when a key exchange fails for an RKD device, and no more retries remain.

Action:

None.

Event 10170

Severity:

Informational

Symbolic Name:

MESSAGE_ENCRYPTION_ON_SAP

Message:

Text:

The SAP Factory %1 has message encryption enabled

Parameter %1:

SAP class name

Description:

Message encryption enabled on SAP

Action:

Event 10171

Severity:

Warning

Symbolic Name:

ADDITIONAL_SAP_CONFIGURED

Message:

Text:

An additional custom SAP has been configured. The configuration for SAP %1 will not be used

Parameter %1:

Class name of additional SAP

Description:

More than 1 custom SAP Factory configured

Action:

Event 10172

Severity:

Informational

Symbolic Name:

RKD_DECLINED_FOR_DEVICE

Message:

Text:

A key exchange was declined for the RKD device %1 because its key is still valid

Parameter %1:

the name of the RKD device

Description:

This event is logged when a RKD request is declined because the device’s current key is still valid and hasn’t expired.

Action:

None.

Event 10173

Severity:

Informational

Symbolic Name:

RKD_COMPROMISED

Message:

Text:

Terminal %1 has been informed of a RKD key compromise from the upstream entity. Initiating RKD requests for all RKD devices associated with this terminal that require a new key.

Parameter %1:

.

Description:

This event is logged when the terminal has been informed of a RKD key compromise from the upstream entity. All devices associated with the terminal will generate a new RKD request.

Action:

None.

Event 10174

Severity:

Warning

Symbolic Name:

SUPPORT_EVENT_AGGREGATION_MOVE_INTO_HIGH_VOLUME

Message:

Text:

The eSocket.POS Event ID %1 was logged %2 times during the last %3 second(s). The first %4 occurrence(s) of it was recorded to the Central Event Log. The first occurrence was recorded around %5. Please refer to the eSocket.POS User Guide for a description of this event.

Parameter %1:

The eSocket.POS event ID of the high volume of events.

Parameter %2:

The number of times the event was logged to the Central Event Log.

Parameter %3:

The time period during which the events were aggregated.

Parameter %4:

The number of events that were actually recorded to the Central Event Log.

Parameter %5:

The time at which the first event was logged and recorded.

Description:

This event is logged at the start of a potentially prolonged period of a high volume of eSocket.POS events (of a specific ID) being logged to the Central Event Log. Please refer to the eSocket.POS User Guide for a description of this event.

Action:

None.

Event 10175

Severity:

Warning

Symbolic Name:

SUPPORT_EVENT_AGGREGATION_MOVE_INTO_HIGH_VOLUME_PER_TERMINAL

Message:

Text:

eSocket.POS Event ID %1 was logged by terminal %2 %3 times during the last %4 second(s). The first %5 occurrence(s) of it was recorded to the Central Event Log. The first occurrence was recorded around %6. Please refer to the eSocket.POS User Guide for a description of this event.

Parameter %1:

The eSocket.POS event ID of the high volume of events.

Parameter %2:

The terminal ID against which the events were logged.

Parameter %3:

The number of times the event was logged to the Central Event Log.

Parameter %4:

The time period during which the events were aggregated.

Parameter %5:

The number of events that were actually recorded to the Central Event Log.

Parameter %6:

The time at which the first event was logged and recorded.

Description:

This event is logged at the start of a potentially prolonged period of a high volume of eSocket.POS events (of a specific ID) being logged (against a specific terminal ID) to the Central Event Log. Please refer to the eSocket.POS User Guide for a description of this event.

Action:

None.

Event 10176

Severity:

Warning

Symbolic Name:

SUPPORT_EVENT_AGGREGATION_HIGH_VOLUME

Message:

Text:

eSocket.POS Event ID %1 logged around %2, was repeated %3 times during the last %4 second(s). Please refer to the eSocket.POS User Guide for a description of these events.

Parameter %1:

The eSocket.POS event ID of the high volume of events.

Parameter %2:

The time at which the first event was logged and recorded.

Parameter %3:

The number of times the event was logged to the Central Event Log.

Parameter %4:

The time period during which the events were aggregated.

Description:

This event is logged during a prolonged period of a high volume of eSocket.POS events (of a specific ID) being logged to the Central Event Log. Please refer to the eSocket.POS User Guide for a description of these events.

Action:

None.

Event 10177

Severity:

Warning

Symbolic Name:

SUPPORT_EVENT_AGGREGATION_HIGH_VOLUME_PER_TERMINAL

Message:

Text:

eSocket.POS Event ID %1, logged against terminal %2, logged around %3, was repeated %4 times during the last %5 second(s). Please refer to the eSocket.POS User Guide for a description of these events.

Parameter %1:

The event ID of the high volume of events.

Parameter %2:

The terminal ID against which the events were logged.

Parameter %3:

The time at which the first event was logged and recorded.

Parameter %4:

The number of times the event was logged to the Central Event Log.

Parameter %5:

The time period during which the events were aggregated.

Description:

This event is logged during a prolonged period of a high volume of eSocket.POS events (of a specific ID) being logged (against a specific terminal ID) to the Central Event Log. Please refer to the eSocket.POS User Guide for a description of these events.

Action:

None.

Event 10178

Severity:

Informational

Symbolic Name:

CUSTOM_APP_PLUGIN_STARTING

Message:

Text:

eSocket.POS is starting a Custom Application plugin. The Java class name is [%1].

Parameter %1:

The custom application class name

Description:

This event is logged during eSocket.POS startup, and names any custom applications started.

Action:

None.

Event 10179

Severity:

Warning

Symbolic Name:

DOWNLOAD_PROCESSING_DATA_PROPERTY

Message:

Text:

The Processing Data files are in the normalized format. The postilion.esocketpos.DownloadProcessingData property is not applied for the normalized structure. This property is only applied for the legacy single Processing Data file. The Processing Data files are loaded.

Parameter %1:

Description:

The postilion.esocketpos.DownloadProcessingData property is ignored because the normalized file structure is used.

Action:

None.

Event 10180

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_RETRYING_FAILED_FILE_DOWNLOAD

Message:

Text:

The Configuration Agent failed to download the file %1. Reason: %2 The download will be retried in 30 seconds. If the download fails again, it will be retried %3 more time(s).

Parameter %1:

The name of the file in question

Parameter %2:

The reason given for the failure

Parameter %3:

The number of times the download will be retried if it fails again

Description:

An error occurred while attempting to download a particular file via HTTP and the download is going to be retried.

Action:

None.

Event 10181

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_FILE_DOWNLOAD_FAILED

Message:

Text:

The Configuration Agent failed to download the file %1. Reason: %2

Parameter %1:

The name of the file in question

Parameter %2:

The reason given for the failure

Description:

Repeated attempts to download a particular file via http have failed. All retry attempts have been exhausted.

Action:

None.

Event 10182

Severity:

Warning

Symbolic Name:

REMOTE_PROPERTY_HOMEDIR_NOT_SET

Message:

Text:

Remote properties exist in the database with the active timestamp, but the postilion.esocketpos.install.HomeDir property is not set in the properties file. The remote properties will not be used

Description:

Remote properties exist in the database with the active timestamp, but the postilion.esocketpos.install.HomeDir property is not set in the properties file. The remote properties will not be used

Action:

In order to use remote properties, configure the postilion.esocketpos.install.HomeDir property in the properties file.

Event 10183

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_COMMAND_PORT_OPENED

Message:

Text:

The Configuration Agent is now listening for new commands at: %1:%2. Connections will be accepted from these trusted ip addresses: '%3'

Parameter %1:

IP address

Parameter %2:

Port

Parameter %3:

Trusted hosts

Description:

The command port has been successfully opened for the Configuration Agent

Action:

None.

Event 10184

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_COMMAND_RECEIVED_FROM_REMOTE

Message:

Text:

The Configuration Agent has received the command: '%1' from %2 and sent back the response '%3'

Parameter %1:

Command received from client

Parameter %2:

Remote address of client

Parameter %3:

Response sent back to the client

Description:

The Configuration Agent received a command from a client and sent back a response

Action:

None.

Event 10185

Severity:

Error

Symbolic Name:

INVALID_P2PE_HOTCARD_FILE

Message:

Text:

The P2PE Hotcard file that is being loaded is invalid. A P2PE hotcard file that contains a tokenization key check value can only have a hash algorithm indicator of 1 - SHA-2 Salted Hashing. The hotcard loading has been aborted.

Description:

This event is logged when the algorithm indicator in a P2PE hotcard update file is not 1 - SHA2

Action:

Ensure that the hashing algorithm used in all the records in a P2PE Hotcard file is 1 - SHA2

Event 10186

Severity:

Error

Symbolic Name:

INVALID_CHECK_VALUE_INCR_LOAD

Message:

Text:

The P2PE Hotcard file that is being loaded is invalid. The key check value supplied in the incremental file in line "%1" is different than the one supplied in a previous full load file. Hence the incremental load will not be applied. If any keys used to perform PAN tokenization have changed, a full hotcard load should be performed to update all the tokenized hotcard PANs.

Parameter %1:

the invalid record from the file

Description:

This event is logged when the key check value supplied in the incremental file is different than the one supplied in a previous full load file

Action:

Ensure that a full hotcard load is performed after changing any keys used to perform PAN tokenization.

Event 10187

Severity:

Warning

Symbolic Name:

P2PE_HOTCARD_CHECKING_CANNOT_PROCEED

Message:

Text:

Terminal %1 encountered the following problem while attempting to perform hotcard checking: The PIN entry device in use supports P2PE hotcard checking, but the keys used to perform PAN tokenization do not match those that were used by ConfigServer during hotcard file generation. The key check value received from the PED is %2, while the key check value received from ConfigServer is %3. P2PE hotcard checking can therefore not be performed.

Parameter %1:

The terminal ID

Parameter %2:

The key check value received from the PED

Parameter %3:

The key check value received from ConfigServer

Description:

This event is logged when the PAN tokenization keys used by the PED do not match those that were used by ConfigServer during hotcard file generation.

Action:

Ensure that P2PE hotcard checking is enabled for the configuration set corresponding to this eSocket.POS instance. Also ensure that the keys used by the PED to perform PAN tokenization are identical to those used by ConfigServer during hotcard file generation.

Event 10188

Severity:

Error

Symbolic Name:

FAILED_TO_DISPLAY_LINE_ITEM

Message:

Text:

eSocket.POS could not display the line items. The error reported is as follows: %1.

Parameter %1:

Error reported, due to nature of the error, no further information is available.

Description:

This event is logged when eSocket.POS fails to process the line item properly.

Action:

Check the message and do the needful.

Event 10189

Severity:

Error

Symbolic Name:

FAILED_TO_CONVERT_SIG_IMAGE

Message:

Text:

eSocket.POS could not convert the captured signature image. The error reported is as follows: %1.

Parameter %1:

Error reported, due to nature of the error, no further information is available.

Description:

This event is logged when eSocket.POS fails to convert the format of the captured signature image.

Action:

Ensure that the image from the signature capture device is in the correct format

Event 10190

Severity:

Error

Symbolic Name:

DEVICE_NOT_CONNECTED

Message:

Text:

The device is not connected. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when eSocket.POS attemps to communicate with a device that is not connected.

Action:

Check device connection and ensure device is configured correctly.

Event 10191

Severity:

Error

Symbolic Name:

DEVICE_CURRENTLY_BUSY

Message:

Text:

The device is currently busy. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when eSocket.POS attemps to communicate with a device that is currently busy.

Action:

Wait until device is finished processing.

Event 10192

Severity:

Informational

Symbolic Name:

ESOCKETPOS_AUTO_SIGNON

Message:

Text:

The application %1 has successfully auto signed-on terminal with Terminal ID: %2.

Parameter %1:

the application

Parameter %2:

sign on parameters

Description:

Automatic sign-on of terminals has completed.

Action:

None.

Event 10193

Severity:

Error

Symbolic Name:

REMOTE_SINK_DISCARDED_TRAN_ADVICE

Message:

Text:

The RemoteSink discarded a transaction advice message after %1 attempts to reverse it.

Parameter %1:

The number of attempts to reverse the message after which it was discarded.

Description:

The Postilion Interface (RemoteSink) discarded a transaction advice message after exceeding the maximum number of reversal attempts.

Action:

nvestigate why eSocket.POS did not receive a response to the reversal for this advice. This transaction may be resubmitted.

Event 10194

Severity:

Warning

Symbolic Name:

REMOTE_SINK_DISCONNECTED

Message:

Text:

%1.

Parameter %1:

Details

Description:

The Postilion Interface (RemoteSink) was disconnected.

Action:

o action required.

Event 10195

Severity:

Warning

Symbolic Name:

REMOTE_SINK_CONNECTED

Message:

Text:

%1.

Parameter %1:

Details

Description:

The Postilion Interface (RemoteSink) was connected.

Action:

o action required.

Event 10196

Severity:

Error

Symbolic Name:

EMV_CONFIG_ERROR

Message:

Text:

%1.

Parameter %1:

Details

Description:

The EmvConfig Pipeline Component encountered an error.

Action:

o action required.

Event 10197

Severity:

Warning

Symbolic Name:

DEVICE_SAP_CONFIG_INVALID

Message:

Text:

The device connection SAP configuration '%1' has been configured incorrectly. %2

Parameter %1:

The configuration item’s name.

Parameter %2:

Additional information.

Description:

Device connection configuration for the SAP is invalid.

Action:

Please ensure it is set correctly for the SAP.

Event 10198

Severity:

Error

Symbolic Name:

SLIP_UNEXPECTED_TOKEN

Message:

Text:

SRSL Syntax Error in %1, position %2: Expected a label, but found token '%3' instead.

Parameter %1:

name of the receipt definition.

Parameter %2:

position in the receipt.

Parameter %3:

token in the receipt.

Description:

This event is logged when an unexpected token is found in the SRSL.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10199

Severity:

Error

Symbolic Name:

SLIP_UNEXPECTED

Message:

Text:

SRSL Syntax Error in %1, position %2: A '%3' was expected, but a '%4' was found

Parameter %1:

name of the receipt definition.

Parameter %2:

position in the receipt.

Parameter %3:

expected token.

Parameter %4:

found token.

Description:

This event is logged when an incorrect token is found.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10200

Severity:

Error

Symbolic Name:

SLIP_UNEXPECTED_ETX

Message:

Text:

SRSL Syntax Error in %1, position %2: End of definition reached while still expecting more characters.

Parameter %1:

name of the receipt definition.

Parameter %2:

position in the receipt.

Description:

This event is logged when the end of the slip is reached but more data is expected in the slip.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10201

Severity:

Error

Symbolic Name:

SLIP_AMOUNT_TOO_LARGE

Message:

Text:

SRSL Syntax Error in %1, position %2: The amount '%3' is not in a valid range. It must be greater than 0 and less than 1000.

Parameter %1:

name of the receipt definition.

Parameter %2:

the position in the receipt.

Parameter %3:

the amount.

Description:

This event is logged when the amount value is not in the range of 0…​1000.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10202

Severity:

Error

Symbolic Name:

SLIP_DUPLICATE

Message:

Text:

SRSL Syntax Error in %1, position %2: The duplicate statement '\&%3' is not valid.

Parameter %1:

the name of the receipt definition.

Parameter %2:

the position in the receipt.

Parameter %3:

The duplicate token that was encountered.

Description:

This event is logged when a duplicate was encountered in the SRSL.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10203

Severity:

Error

Symbolic Name:

SLIP_TEXT_NOT_CLOSE

Message:

Text:

SRSL Syntax Error in %1, position %2: A closing \" character is missing. Text may not extend over more than one line.

Parameter %1:

the name of the receipt definition.

Parameter %2:

the position in the receipt.

Description:

This event is logged when a closing delimiter was not found.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10204

Severity:

Error

Symbolic Name:

SLIP_CTRL_CHAR

Message:

Text:

SRSL Syntax Error in %1, position %2: The control character '%3' does not exist.

Parameter %1:

the name of the receipt definition.

Parameter %2:

the position in the receipt.

Parameter %3:

control character found.

Description:

This event is logged when an invalid control character was encountered while parsing the slip.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10205

Severity:

Error

Symbolic Name:

SLIP_ALIGN

Message:

Text:

SRSL Syntax Error in %1, position %2: The alignment statement '[ …​ ]%3' is not valid.

Parameter %1:

the name of the receipt definition.

Parameter %2:

the position in the receipt.

Parameter %3:

The alignment parameter.

Description:

This event is logged when an invalid alignment statement is encountered.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10206

Severity:

Error

Symbolic Name:

SLIP_DOWN

Message:

Text:

SRSL Syntax Error in %1, position %2: The parameter for the command 'down(%3)' is not a valid number.

Parameter %1:

the name of the receipt definition.

Parameter %2:

the position in the receipt.

Parameter %3:

parameter to the down command.

Description:

This event is logged when an invalid parameter is passed to the down command in SRSL.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10207

Severity:

Error

Symbolic Name:

SLIP_BLOCK_SIZE

Message:

Text:

SRSL Syntax Error in %1, position %2: The first parameter for the command 'block(%3, …​)' is not a number.

Parameter %1:

the name of the receipt definition.

Parameter %2:

the position in the receipt.

Parameter %3:

first parameter to the block command.

Description:

This event is logged when the first parameter for the command block is not a number.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10208

Severity:

Error

Symbolic Name:

SLIP_ERROR

Message:

Text:

An SRSL error occurred in the definition of slip '%1' at position %2 . %3

Parameter %1:

the name of the receipt definition.

Parameter %2:

the position in the receipt.

Parameter %3:

message containing more information.

Description:

This event is logged when a SRSL error occurs in a slip.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10209

Severity:

Error

Symbolic Name:

SLIP_NAME

Message:

Text:

SRSL Error: The name '%1' is not defined here.

Parameter %1:

the undefined name in receipt.

Description:

This event is logged when an undefined name is used in the slip.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10210

Severity:

Error

Symbolic Name:

SLIP_VALUE_NOT_STRING

Message:

Text:

SRSL Error: The value '%1' is not a string and thus cannot be used as a #value.

Parameter %1:

the value found.

Description:

This event is logged when a value found is not of type string.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10211

Severity:

Error

Symbolic Name:

SLIP_NOT_FORMATTING

Message:

Text:

SRSL Error: A formatting statement (%format) '%1' may not be used here.

Parameter %1:

the format found.

Description:

This event is logged when the format statement is used incorrectly.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10212

Severity:

Error

Symbolic Name:

SLIP_FORMAT

Message:

Text:

SRSL Error: The format '%1' does not exist at this position.

Parameter %1:

the format found.

Description:

This event is logged when the format does not exist at this position.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10213

Severity:

Error

Symbolic Name:

SLIP_FORMAT_USE

Message:

Text:

SRSL Error: Invalid format usage (parameter %1).

Parameter %1:

the format value used.

Description:

This event is logged when the format statement is used incorrectly.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10214

Severity:

Error

Symbolic Name:

SLIP_FORMAT_NOT_STRING

Message:

Text:

SRSL Error: The format '%1' is not a string and thus cannot be used as \%value.

Parameter %1:

the format found.

Description:

This event is logged when the format is not a string.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10215

Severity:

Error

Symbolic Name:

SLIP_LOOKUP_INVALID

Message:

Text:

SRSL Error: Invalid lookup usage of item "%1".

Parameter %1:

the lookup item.

Description:

This event is logged when an invalid lookup is performed.

Action:

Consult the SRSL syntax in the eSocket.POS User Guide.

Event 10216

Severity:

Warning

Symbolic Name:

SLIP_FORBIDDEN_EMV_TAG

Message:

Text:

The value of EMV tag %1 is not allowed to be printed on the receipt. Please remove this tag from the receipt profile definition to prevent this warning from being logged. The current receipt will be printed as if this EMV tag is not present in the message.

Parameter %1:

The forbidden EMV tag.

Description:

This event is logged to report an attempt to print a forbidden EMV tag value.

Action:

Consult the forbidden EMV tag list in the eSocket.POS user guide. These forbidden EMV tag values are not allowed to print on the receipt to avoid exposing sensitive or cryptographic data.

Event 10217

Severity:

Warning

Symbolic Name:

INSECURE_ENCRYPTION_PROTOCOL_ENABLED_ON_CLIENT_SAP

Message:

Text:

The Client Service Access Point (SAP) with name '%1' has the following insecure encryption protocol and/or version enabled: '%2'. Please upgrade to a secure version.

Parameter %1:

The name of the SAP.

Parameter %2:

The name and version of the protocol.

Description:

This event is logged when a client SAP has an insecure encryption protocol enabled.

Action:

No action is required.

Event 10218

Severity:

Error

Symbolic Name:

TRAN_DECLINED_TERM_BLOCKED

Message:

Text:

The Terminal '%1' has been blocked

Parameter %1:

the terminal ID

Description:

This event is logged when the terminal has been blocked

Action:

No action is required.

Event 10219

Severity:

Informational

Symbolic Name:

TERM_UNBLOCKED

Message:

Text:

The Terminal '%1' has been unblocked

Parameter %1:

the terminal ID

Description:

This event is logged when the terminal has been unblocked

Action:

No action is required.

Event 10220

Severity:

Error

Symbolic Name:

P2PE_DEVICE_BLOCK

Message:

Text:

Transaction has failed because of a blocked device. The stack trace is as follows: %1

Parameter %1:

The stack trace

Description:

This event is logged when a transaction fails due to a blocked device.

Action:

No action is required.

Event 10221

Severity:

Informational

Symbolic Name:

UPGRADE_MANAGER_STATUS

Message:

Text:

UpgradeManager: %1

Parameter %1:

The UpgradeManager status description

Description:

This event is logged by UpgradeManager to report status.

Action:

No action is required.

Event 10222

Severity:

Warning

Symbolic Name:

CARD_REMOVED_PREMATURELY

Message:

Text:

The card was removed prematurely.

Description:

This event is logged when the card was removed prematurely.

Action:

No action is required.

Event 10223

Severity:

Error

Symbolic Name:

CONFIG_AGENT_PROGRESS_STATUS_ERROR

Message:

Text:

The Configuration Agent progress status is set to %1.

Parameter %1:

The status on the Configuration Agent file download process.

Description:

ConfigAgent progress status error event.

Action:

No action is required. This is provided for debugging purposes.

Event 10224

Severity:

Informational

Symbolic Name:

CONFIG_AGENT_PROGRESS_STATUS_INFO

Message:

Text:

The Configuration Agent progress status is set to %1.

Parameter %1:

The status on the Configuration Agent file download process.

Description:

ConfigAgent progress status info event.

Action:

No action is required.

Event 10225

Severity:

Informational

Symbolic Name:

DEVICE_UPDATE_NOT_PERFORMED

Message:

Text:

The %1 device driver could not perform a file update for the device connected to terminal %3. Reason: %2.

Parameter %1:

Device Driver

Parameter %2:

Reason why the update was not performed

Parameter %3:

Terminal ID

Description:

This event is logged when a requested update operation, on a given terminal, was not performed.

Action:

No action is required.

Event 10226

Severity:

Informational

Symbolic Name:

FILE_UPDATE_SUCCESS

Message:

Text:

The file %2 of type %3 has been successfully uploaded for the %1 device.

Parameter %1:

the active device

Parameter %2:

the file name

Parameter %3:

the file type(whitelist, firmware)

Description:

This event is logged when a file is successful uploaded

Action:

No action is required.

Event 10227

Severity:

Error

Symbolic Name:

TERMINAL_BLOCKED

Message:

Text:

Terminal %1 is blocked because %2

Parameter %1:

Terminal ID

Parameter %2:

Reason why the terminal is blocked

Description:

This event is logged when a terminal has been blocked.

Action:

No action is required.

Event 10228

Severity:

Informational

Symbolic Name:

ESOCKETPOS_INFO_EVENT

Message:

Text:

Info Description = %1

Parameter %1:

Description of the event.

Description:

Generic info event returned by eSocket.POS.

Action:

No action is required.

Event 10229

Severity:

Error

Symbolic Name:

CHECK_READ_FAILED

Message:

Text:

An error occurred while attempting to read a check

Description:

This ReasonCode is returned if an attempt to read check data failed.

Action:

No action is required.

Event 10230

Severity:

Error

Symbolic Name:

SQL_EXCEPTION_OCCURRED

Message:

Text:

%1 failed to perform a SQL operation. The following error was reported: %2.

Parameter %1:

Application Name

Parameter %2:

The error to be reported.

Description:

This event is logged if a SQL operation failed to complete

Action:

Contact your primary support provider.

Event 10231

Severity:

Error

Symbolic Name:

TERMINAL_ACTIVATION_CSR_GENERATION_FAILED

Message:

Text:

Generating a certificate signing request to be used for TLS connections failed for terminal %1. Reason: %2.

Parameter %1:

Terminal ID

Parameter %2:

Exception associated with the CSR generation failure

Description:

This event is logged when there is a failure during the process of creating a Certificate Signing Request (CSR) for the public key of a TLS key pair.

Action:

Investigate the reason for the CSR creation failing by reviewing the reported exception. Contact your primary support provider should additional assistance be required.

Event 10232

Severity:

Error

Symbolic Name:

TERMINAL_ACTIVATION_MAC_CALC_FAILED

Message:

Text:

Calculating the MAC for a terminal activation request message failed for terminal %1. Reason: %2.

Parameter %1:

Terminal ID

Parameter %2:

Exception associated with the MAC calculation failing

Description:

This event is logged when MAC calculation for a terminal activation request message fails.

Action:

Investigate the reason for the MAC calculation failing by reviewing the reported exception. Contact your primary support provider should additional assistance be required.

Event 10233

Severity:

Error

Symbolic Name:

TERMINAL_ACTIVATION_CERT_UPDATE_FAILED

Message:

Text:

Updating the public key certificate to be used for TLS connections failed for terminal %1. Reason: %2.

Parameter %1:

Terminal ID

Parameter %2:

Exception associated with the certificate update failing

Description:

This event is logged when updating the signed public key certificate for an TLS key pair alias fails.

Action:

Investigate the reason for the certificate update failing by reviewing the reported exception. Contact your primary support provider should additional assistance be required.

Event 10234

Severity:

Error

Symbolic Name:

TERMINAL_ACTIVATION_FAILED

Message:

Text:

Activating terminal %1 for internet connectivity failed for terminal %1. Reason: %2.

Parameter %1:

Terminal ID

Parameter %2:

Exception associated with the failed activation attempt

Description:

This event is logged when an exception occurs while attempting to activate a terminal for internet connectivity. It indicates that terminal activation failed.

Action:

Investigate the reason for terminal activation failing by reviewing the reported exception. Terminal activation can fail due to errors occurring in eSocket.POS in which case the error will be reported by eSocket.POS or it can fail during validation on the switch in which case the error will be reported by the switch. Contact your primary support provider should additional assistance be required.

Event 10235

Severity:

Error

Symbolic Name:

TERMINAL_ACTIVATION_REQUEST_DECLINED

Message:

Text:

A terminal activation request for internet connectivity for terminal %1 was declined by %2.

Parameter %1:

Terminal ID

Parameter %2:

Whether the request was declined by eSocket.POS or the switch

Description:

This event is logged when a terminal activation message is declined by either eSocket.POS or the switch. If declined by eSocket.POS it will be preceded by an event that indicates why the activation message was declined. If declined by the switch, the switch logs will contain information regarding the reasons for the decline.

Action:

Investigate the reason for terminal activation request being declined in the relevant logs. Contact your primary support provider should additional assistance be required.

Event 10236

Severity:

Warning

Symbolic Name:

INVALID_TPR

Message:

Text:

Transaction Processing Result value %1 not found in %2.

Description:

This event is logged when a transaction processing request value cannot be found.

Action:

No action is required.

Event 10237

Severity:

Error

Symbolic Name:

CONFIG_MODULE_PROCESSOR_UPDATE_FAILED

Message:

Text:

Config Agent Config Module Processor update failed. Reason: %1.

Parameter %1:

The reasons for the failure

Description:

This event is logged when a module processor update fails.

Action:

No action is required.

Event 10238

Severity:

Error

Symbolic Name:

UNKNOWN_COMMAND

Message:

Text:

Unknown command received from the acquirer %1.

Parameter %1:

The command received

Description:

This event is logged when an unknown command is received from the acquirer.

Action:

No action is required.

Event 10239

Severity:

Warning

Symbolic Name:

SEC_RISK_SQL_PASSWORD_EMPTY

Message:

Text:

Security Risk: Empty JDBC password configured.

Description:

This event is logged when the JDBC password is configured as empty.

Action:

No action is required.

Event 10240

Severity:

Warning

Symbolic Name:

REMOTE_SINK_TERM_ACT_PORT_NOT_SPECIFIED

Message:

Text:

The RemoteSink entity configured for terminal ID %1 has a terminal activation host specified but not a terminal activation port number. If the intended behaviour is to make use of automated terminal activation, add the port number for the terminal activation destination. If the intended behaviour is not to make use of automated terminal activation, remove the terminal activation host.

Parameter %1:

Terminal ID

Description:

This event is logged when the RemoteSink configuration has a terminal activation host configured but not a terminal activation port number.

Action:

If the intended behaviour is to make use of automated terminal activation, add the port number for the terminal activation destination. If the intended behaviour is not to make use of automated terminal activation, remove the terminal activation host.

Event 10241

Severity:

Warning

Symbolic Name:

REMOTE_SINK_TERM_ACT_HOST_NOT_SPECIFIED

Message:

Text:

The RemoteSink entity configured for terminal ID %1 has a terminal activation port number specified but not a terminal activation host. If the intended behaviour is to make use of automated terminal activation, add the host for terminal activation. If the intended behaviour is not to make use of automated terminal activation, remove the terminal activation port number.

Parameter %1:

Terminal ID

Description:

This event is logged when the RemoteSink configuration has a terminal activation port number configured but not a terminal activation host.

Action:

If the intended behaviour is to make use of automated terminal activation, add the host for terminal activation. If the intended behaviour is not to make use of automated terminal activation, remove the terminal activation port number.

Event 10242

Severity:

Error

Symbolic Name:

TLS_KEY_STORE_FILE_DOES_NOT_EXIST

Message:

Text:

The TLS key store is not configured in the eSocket.POS properties file (property postilion.esocketpos.ssl.KeyStorePath), the key store file does not exist or it cannot be accessed. The key store was not loaded.

Description:

This event is logged when the TLS key store is not configured in the properties file or the key store file does not exist.

Action:

Validate that the TLS key store property is configured in the properties file (postilion.esocketpos.ssl.KeyStorePath), ensure the key store file exists and that the user under which the eSocket.POS process runs can access it.

Event 10243

Severity:

Error

Symbolic Name:

TLS_TRUST_STORE_FILE_DOES_NOT_EXIST

Message:

Text:

The TLS trust store is not configured in the eSocket.POS properties file (postilion.esocketpos.ssl.TrustStorePath), the trust store file does not exist or it cannot be accessed. The trust store was not loaded.

Description:

This event is logged when the TLS trust store is not configured in the properties file or the trust store file does not exist.

Action:

Validate that the TLS trust store property is configured in the properties file (postilion.esocketpos.ssl.TrustStorePath), ensure the trust store file exists and that the user under which the eSocket.POS process runs can access it.

Event 10244

Severity:

Error

Symbolic Name:

TLS_KEY_STORE_PASSWORD_INCORRECT

Message:

Text:

The TLS key store password is not configured in the eSocket.POS properties file (property postilion.esocketpos.ssl.KeyStorePassword) or it is incorrect.

Description:

This event is logged when the password for the TLS key store is not configured in the eSocket.POS properties file or is incorrect.

Action:

Validate that the TLS key store password is configured in the properties file (property postilion.esocketpos.ssl.KeyStorePassword) and that it is correct.

Event 10245

Severity:

Error

Symbolic Name:

TLS_TRUST_STORE_PASSWORD_INCORRECT

Message:

Text:

The TLS trust store password is not configured in the eSocket.POS properties file (property postilion.esocketpos.ssl.TrustStorePassword) or it is incorrect.

Description:

This event is logged when the password for the TLS trust store is not configured in the eSocket.POS properties file or is incorrect.

Action:

Validate that the TLS trust store password is configured in the properties file (postilion.esocketpos.ssl.TrustStorePassword) and that it is correct.

Event 10246

Severity:

Error

Symbolic Name:

FIELD_ENCRYPTION_KEY_MISSING

Message:

Text:

The RSA Public Key required for FIELDS encryption is not available.

Description:

This event is logged when the key required to encrypt sesitive fields such as PAN, TRACK2, ACCOUNT_ID_1, ACCOUNT_ID_2, PAYER_ACCOUNT_ID is not available in the eSocket.POS keystore.

Action:

Check the eSocket.POS configuration.

Event 10247

Severity:

Warning

Symbolic Name:

ORPHANED_MESSAGE_RECEIVED

Message:

Text:

eSocket.POS has received an orphaned message from remote address %2. eSocket.POS does not recognize the terminal ID determined from the message: %1. This typically occurs if the remote entity (e.g. the upstream host) does not populate the terminal ID field(s) in a response message correctly. No further processing will be performed on this message, including tracing (if enabled). Message content: %3

Parameter %1:

terminal ID as determined from orphaned message

Parameter %2:

the remote address

Parameter %3:

the orphaned message’s content

Description:

Orphaned message received by eSocket.POS

Action:

o action required.

Event 10248

Severity:

Warning

Symbolic Name:

SEC_RISK_PROPERTY_BLANK

Message:

Text:

Security Risk: The following sensitive property %1 is configured as blank and hence it will not be encrypted.

Parameter %1:

sensitive property that is configured as blank.

Description:

This event is logged when a sensitive property that has to be encrypted is blank.

Action:

No action is required.

Event 10249

Severity:

Warning

Symbolic Name:

CONFIG_AGENT_INTERNET_CONNECTIVITY_CONFIG_NOT_VERIFIED

Message:

Text:

ConfigAgent is configured to connect over the public internet (postilion.esocketpos.ConfigAgentConnectOverInternet is set) but it is not configured to verify signed files from ConfigServer (postilion.esocketpos.VerifyDistributionFiles is not set). It is a best practice to use signed configuration files when connecting to ConfigServer over the public internet. Set up ConfigServer and ConfigAgent to sign and verify files.

Description:

This event is logged when ConfigAgent is configured to connect over the public internet, but it is not configured to expect signed configuration files and verify those files. In other words configuration property postilion.esocketpos.VerifyDistributionFiles is not set.

Action:

When connecting to ConfigServer over the public internet, it is a best practice to only accept signed configuration files to mitigate risk. Set up ConfigServer and ConfigAgent to sign and verify files.

Event 10250

Severity:

Warning

Symbolic Name:

CONFIG_AGENT_INTERNET_CONNECTIVITY_NO_CLIENT_CERT

Message:

Text:

ConfigAgent is configured to connect over the public internet (postilion.esocketpos.ConfigAgentConnectOverInternet is set) but there are no client TLS certificates to present to ConfigServer during TLS negotiation. It is a best practice to use mutual TLS authentication when connecting to ConfigServer over the public internet. Configure a default TLS key pair and certificate to be used for initial configuration retrieval. Once eSocket.POS has at least one activated terminal or an activated ConfigAgent client certificate (specified using the postilion.esocketpos.ConfigAgentClientCertAlias property) is present in the TLS key store, the activated TLS certificate will be used to connect to ConfigServer.

Description:

This event is logged when ConfigAgent is configured to connect over the public internet, but no client TLS certificate is available to present to ConfigServer during TLS negotiation. This means that there are no terminals configured on eSocket.POS which have been activated, or there is no activated ConfigAgent client TLS certificate (specified using the postilion.esocketpos.ConfigAgentClientCertAlias property) is present in the TLS key store. There is also no default certificate configured (using configuration property postilion.esocketpos.UnactivatedClientCertAlias), or that default certificate is not present or valid in the TLS key store.

Action:

When connecting to ConfigServer over the public internet, it is a best practice to always use mutual TLS authentication when retrieving configuration. Set up a default TLS key pair and certificate in the key store that will be used for initial configuration retrieval. Once there is at least one activated terminal on eSocket.POS, or an activated ConfigAgent client TLS certificate (specified using the postilion.esocketpos.ConfigAgentClientCertAlias property) is present in the TLS key store, the activated TLS certificate will be used to connect to ConfigServer.

Event 10251

Severity:

Warning

Symbolic Name:

OPC_RETRY_EXCEEDED

Message:

Text:

The user selected a payment option (OPC) that is not allowed for the transaction amount. The transaction has been declined after %1 attempts.

Parameter %1:

the configured OPC retry limit.

Description:

This event is logged when an OPC re-selection attempt exceeds the configured retries allowed.

Action:

No action is required.

Event 10252

Severity:

Warning

Symbolic Name:

OPC_RETRY_FILTER_EXHAUSTED

Message:

Text:

The user selected a payment option (OPC) that is not allowed for the transaction amount. Transaction declined as retry filtering removed all available OPCs to display.

Description:

This event is logged when the OPC re-selection filter removed all available OPC’s for display.

Action:

No action is required.

Event 10253

Severity:

Warning

Symbolic Name:

INCORRECT_USER_PARAM

Message:

Text:

Parameter %1 is incorrectly configured. Consult the User Guide for the list of valid values for this parameter.

Parameter %1:

Parameter Name

Description:

This event is logged when user param is not configured correctly.

Action:

Consult the User Guide for the list of valid values for this parameter.

Event 10254

Severity:

Warning

Symbolic Name:

TRUSTED_CERT_UPDATE_FAILED_IN_TLS_TRUSTSTORE

Message:

Text:

ConfigAgent attempted to add a trusted certificate in the TLS trust store but the key store manager being used does not support automated updates. The alias that was used to attempt storing the certificate is %1.

Parameter %1:

the alias that ConfigAgent attempted to add

Description:

This event is logged when ConfigAgent attempts to add a new trusted certificate to the TLS trust store, but the trust store manager implementation does not support automated updates.

Action:

Investigate the reason for the trust store manager implementation reporting this error and rectify it. A possibility is that all JAR files required are not configured on the class path. Refer to the eSocket.POS user guide for guidance on setting the eSocket.POS class path. It is possible to manually add the trusted certificate to the trust store, but preferably the certificate should be sent again as part of a configuration update to be updated in the trust store.

Event 10255

Severity:

Warning

Symbolic Name:

HTTP_CLIENT_SAP_UPDATE_FAILED_OPEN_CONNECTIONS

Message:

Text:

ConfigAgent attempted to update it’s HTTP client’s SAP factory and SAP factory parameters but failed due to the current SAP still having open connections to the server. The attempted SAP factory is %1, the attempted SAP factory parameters are %2 and the attempted server port is %3. ConfigAgent will try to update the SAP again with the next scheduled configuration retrieval attempt. The current number of open connections for the existing SAP is %4.

Parameter %1:

SAP factory

Parameter %2:

SAP factory parameters

Parameter %3:

Server port to connect to

Parameter %4:

Current number of open connections.

Description:

This event is logged when ConfigAgent attempts to update its client SAP used for configuration downloads while the current SAP still has open connections.

Action:

No action is required. The next configuration load will attempt to update the SAP again. If the SAP details are no longer valid (e.g. the client certificate in use has expired), then the upstream entity (i.e. ConfigServer) will decline new connections and updated configuration will not be available until the SAP details have been updated. Restarting ConfigAgent could assist in clearing existing connections, but will also halt all downloads in progress.

Event 10256

Severity:

Error

Symbolic Name:

HTTP_CLIENT_SAP_UPDATE_ERROR

Message:

Text:

ConfigAgent attempted to update it’s HTTP client’s SAP factory and SAP factory parameters but failed. The details of the failure are listed in the provided exception stack trace. The attempted SAP factory is %1, the attempted SAP factory parameters are %2 and the attempted server port is %3. ConfigAgent will try to update the SAP again with the next scheduled configuration retrieval attempt. Exception: %4

Parameter %1:

SAP factory

Parameter %2:

SAP factory parameters

Parameter %3:

Server port to connect to

Parameter %4:

Exception stack trace

Description:

This event is logged when ConfigAgent attempts to update its client SAP used for configuration downloads and an error occurs.

Action:

Investigate the reason for the failure and apply corrective measures as necessary. The next configuration load will attempt to update the SAP again. If the SAP details are no longer valid (e.g. the client certificate in use has expired), then the upstream entity (i.e. ConfigServer) will decline new connections and updated configuration will not be available until the SAP details have been updated.

Event 10257

Severity:

Informational

Symbolic Name:

ADDITIONAL_TCP_CONNECTION_RECEIVED

Message:

Text:

An entity has received an additional TCP connection from the host. Entity %1 has received a new connection from: %2 eSocket.POS will now disconnect from the old connection: %3

Parameter %1:

Entity receiving the new connection

Parameter %2:

Details of new connection (IP/Port)

Parameter %3:

Details of old connection (IP/Port)

Description:

This event is logged when an entity receives an additional connection.

Action:

one

Event 10258

Severity:

Informational

Symbolic Name:

TRANSACTION_PROCESSING_SUSPENDED

Message:

Text:

Transaction processing has been suspended for terminal %1 for the following reason: %2

Parameter %1:

terminal id

Parameter %2:

suspended Reason

Description:

This event is logged when a transaction processing is suspended

Action:

one

Event 10259

Severity:

Warning

Symbolic Name:

OPC_CONFIG_RETRY_REACHED

Message:

Text:

The OPC configuration update retry limit %1 has been reached, a new configuration request will not be generated for the current session - Card Acceptor ID %2 and terminal ID %3.

Parameter %1:

the OPC configuration retry limit

Parameter %2:

Card Acceptor ID

Parameter %3:

terminal ID

Description:

This event is logged when the OPC configuration update retry limit has been exceeded.

Action:

No action is required.

Event 10260

Severity:

Informational

Symbolic Name:

OPC_CONFIGURATION_APPLIED

Message:

Text:

The terminal has successfully applied the new OPC configuration with version %1 for Card Acceptor code %2.

Parameter %1:

OPC configuration applied

Parameter %2:

Card Acceptor ID

Description:

This event is logged to notify that OPC configuration has successfully been applied.

Action:

one

Event 10261

Severity:

Warning

Symbolic Name:

OPC_CONFIG_UNEXPECTED_RESPONSE

Message:

Text:

Unexpected OPC Configuration response encountered, this message has been discarded for Card Acceptor ID %1 and terminal ID %2.

Parameter %1:

Card Acceptor ID

Parameter %2:

terminal ID

Description:

This event is logged when an OPC configuration update retry request is unexpected. Either is does not have the correct message type or the incorrect field 70.

Action:

No action is required.

Event 10262

Severity:

Warning

Symbolic Name:

CAPK_CONFIG_LOAD_FAILED

Message:

Text:

The CA public key configuration load for terminal %1 failed due to the following reason: %2

Parameter %1:

Terminal name

Parameter %2:

Description

Description:

This event is logged when CA public key configuration was not loaded due to the corresponding AID configuration being absent.

Action:

No action is required.

Event 10263

Severity:

Informational

Symbolic Name:

OPC_CONFIG_UNABLE_TO_LOCATE_TIMER

Message:

Text:

Unable to locate counter for timer: %1 for Card Acceptor ID %2 and terminal ID %3.

Parameter %1:

trigger name

Parameter %2:

Card Acceptor ID

Parameter %3:

terminal ID

Description:

Action:

one

Event 10264

Severity:

Informational

Symbolic Name:

OPC_CONFIG_SAME_VERSION

Message:

Text:

Unable to load new OPC configuration with version %1, for Card Acceptor ID %2 and terminal ID %3. Version %1 is already in the database.

Parameter %1:

version

Parameter %2:

Card Acceptor ID

Parameter %3:

terminal ID

Description:

This event is logged when the terminal attempts to apply the same OPC configuration version.

Action:

one

Event 10265

Severity:

Error

Symbolic Name:

OPC_CONFIGURATION_NOT_APPLIED

Message:

Text:

The terminal has not successfully applied the new OPC configuration with version %1 for Card Acceptor ID code %2 due to an error: %3.

Parameter %1:

OPC configuration version

Parameter %2:

Card Acceptor ID

Parameter %3:

Exception

Description:

This event is logged to notify that OPC configuration has not successfully been applied due to an error.

Action:

No action is required.

Event 10266

Severity:

Warning

Symbolic Name:

OPC_CONFIGURATION_NOT_CLEARED

Message:

Text:

The terminal has not successfully cleared the old OPC configuration for the %1 table with version %2 for Card Acceptor code %3 due to an error: %4.

Parameter %1:

Online Table

Parameter %2:

OPC configuration version

Parameter %3:

Card Acceptor ID

Parameter %4:

Exception

Description:

This event is logged to notify that the previous OPC configuration has not successfully been cleared for a specific table.

Action:

No action is required.

Event 10267

Severity:

Informational

Symbolic Name:

RETRY_ABORT

Message:

Text:

A Retry Abort has been received for Card Acceptor ID %1 and Terminal ID %2. No retries shall occur.

Parameter %1:

Card Acceptor ID

Parameter %2:

terminal ID

Description:

This event is logged to notify that an 'Abort Retry' has been received.

Action:

No action is required.

Event 10268

Severity:

Warning

Symbolic Name:

OPC_CONFIG_ERROR

Message:

Text:

An error has occurred during an OPC configuration download for Card Acceptor ID %1 and Terminal ID %2 with a Response Code %3.

Parameter %1:

Card Acceptor ID

Parameter %2:

terminal ID

Parameter %3:

response code

Description:

This event is logged for generic errors that occur during OPC configuration downloads.

Action:

No action is required.

Event 10269

Severity:

Warning

Symbolic Name:

NO_MAPPING_FOR_ACQUIRER_NAME

Message:

Text:

No card acceptor mapping was found for acquirer name %2 for terminal %1. The acquirer name parameter will be ignored.

Parameter %1:

terminal ID

Parameter %2:

acquirer name

Description:

This event is logged when an acquirer name is configured for Pipeline Component OpcConfig but no card acceptor mapping is found.

Action:

Ensure parameter ACQUIRER_NAME is correctly configured and that the relevant configuration exists in the esp_acq_ca_map table.

Event 10270

Severity:

Warning

Symbolic Name:

ESP_PROPERTY_VALUE_ERROR_CORRECTED

Message:

Text:

The value of property %2 for terminal %1 was incorrectly specified, and has been corrected to %3. Description: %4

Parameter %1:

The terminal ID

Parameter %2:

The property name

Parameter %3:

The corrected value used for the property

Parameter %4:

Description of the incorrect value

Description:

This event is logged when a property found in the eSocket.POS properties file is incorrectly specified / formatted, and has been corrected

Action:

Check the eSocket.POS configuration.

Event 10271

Severity:

Error

Symbolic Name:

SAFQ_NOT_CLEARING

Message:

Text:

The eSocket.POS monitoring system detected a delay in the delivery of %1 transactions (excluding the last dequeued transaction that is being delivered upstream) from the store and forward queue (SAFQ) of terminal %3. eSocket.POS has not been able to deliver any transactions from the SAFQ for %2 minutes. 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. Please review the eSocket.POS event log and traces for any errors or warnings. Restart eSocket.POS if this message is logged multiple times. Contact your primary support provider if after a restart this message is still being logged.

Parameter %1:

the size of the SAFQ (excluding the last dequeued transaction that is being delivered upstream, if any)

Parameter %2:

the approximate time in minutes a transaction was last dequeued from the SAFQ in order to be sent upstream

Parameter %3:

terminal ID

Description:

The eSocket.POS monitoring system detected a delay in the delivery of transactions from the store and forward queue (SAFQ) of the specified 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.

Action:

Please review the eSocket.POS event log and traces for any errors or warnings. Restart eSocket.POS if this message is logged multiple times. Contact your primary support provider if after a restart this message is still being logged.

Event 10272

Severity:

Informational

Symbolic Name:

SAFQ_CLEARING_AGAIN

Message:

Text:

The eSocket.POS monitoring system detected that transactions from the store and forward queue (SAFQ) of terminal %1 are being delivered again, after it has been delayed.

Parameter %1:

terminal ID

Description:

The eSocket.POS monitoring system detected that transactions from the store and forward queue (SAFQ) of the specified terminal are being delivered again, after it has been delayed.

Action:

None.

Event 10273

Severity:

Error

Symbolic Name:

INVALID_BARCODE_REQUEST_MSG

Message:

Text:

A message could not be sent to the %1 device because it was invalid.

Parameter %1:

The device name

Description:

An attempt was made to send an invalid barcode display request to a device.

Action:

Contact your primary support provider.

Event 10274

Severity:

Informational

Symbolic Name:

MONITORING_INTERVAL_PARAM_VALUE

Message:

Text:

The value of the 1st parameter(Monitoring Interval) in PipelineComponentMonitor is set to %1s after adding a stagger time of %2s to the originally configured value of %3s. This means, eSocket.POS will send the terminal monitoring message to the upstream entity at an interval of %1 second(s), when no transactional activity from the POS was received during that interval and there was a change in the status of the terminal.

Parameter %1:

The new monitoring interval in seconds

Parameter %2:

The jitter time in seconds

Parameter %3:

The originaly configured monitoring interval in seconds

Description:

The value of the 1st parameter(Monitoring Interval) in PipelineComponentMonitor

Action:

None.

Event 10275

Severity:

Informational

Symbolic Name:

UPDATE_MSG_INTERVAL_PARAM_VALUE

Message:

Text:

The value of the parameter UPDATE_MSG_TIMER(Update message timer) in PipelineComponentMonitor is set to %1s after adding a stagger time of %2s to the originally configured value of %3s. This means, eSocket.POS will send the terminal monitoring message to the upstream entity at an interval of %1 second(s), when no response from the upstream entity was received during that interval.

Parameter %1:

The new update message interval in seconds

Parameter %2:

The jitter time in seconds

Parameter %3:

The originaly configured update message interval in seconds

Description:

The value of the parameter UPDATE_MSG_TIMER(Update message timer) in PipelineComponentMonitor

Action:

None.

Event 10276

Severity:

Error

Symbolic Name:

RKD_FAILED_HOST_MALFUNCTION

Message:

Text:

A key exchange for the RKD device %1 has failed due to a system malfunction at the host level. Please investigate at the host level.

Parameter %1:

the name of the RKD device

Description:

This event is logged when a key exchange fails due to a system malfunction at the host level.

Action:

None.

Event 10277

Severity:

Warning

Symbolic Name:

JDBC_SECURITY_WARNING

Message:

Text:

For security purposes, you should only specify the server name and driver in the URL. For username and password values, use their corresponding configuration properties.

Parameter %1:

Description:

This event is logged when a the JDBC username and/or the JDBC password are configured as part of the JDBC URL. This affects the security of the system and requires technical attention.

Action:

None.

Event 10278

Severity:

Informational

Symbolic Name:

HSQLDB_SERVER_LOG_MESSAGE

Message:

Text:

HSQLDB Message: %1

Parameter %1:

The message logged by the HSQLDB server

Description:

This event encapsulates HSQLDB server log messages that it would normally log to the console i.e. the stdout stream. This event will only be logged when eSocket.POS is started with an embedded HSQDB server instance i.e. when eSocket.POS launches the HSQLDB server and not when HSQLDB is run as a standalone server.

Action:

No action is required.

Event 10279

Severity:

Error

Symbolic Name:

HSQLDB_SERVER_LOG_ERROR_MESSAGE

Message:

Text:

HSQLDB Error Message: %1

Parameter %1:

The HSQLDB error message

Description:

Logged when an HSQLDB-related error occurs.

Action:

Review the error message logged to determine the corrective action to take.

Event 10280

Severity:

Error

Symbolic Name:

CONFIG_AGENT_CLASS_FILES_MISSING

Message:

Text:

Ensure that all dependencies are installed before applying the package. Missing dependency: %1

Parameter %1:

The dependency which is not installed.

Description:

ConfigAgent dependency is not installed for Terminal data configuration.

Action:

Install the required dependency

Event 10281

Severity:

Error

Symbolic Name:

HTTP_SERVER_ERROR

Message:

Text:

Http Server Error details: %1

Parameter %1:

Details on the error received from the server.

Description:

This event encapsulates HTTP server error messages that it would normally log to the console i.e. the stderr stream. This event will only be logged when an HTTP server responds with an error to a request sent from eSocket.POS

Action:

Review the error message logged to determine the action to take to rectify

Event 10282

Severity:

Error

Symbolic Name:

HTTP_CLIENT_ERROR

Message:

Text:

Http Client Error details: %1

Parameter %1:

Details on the error received that occurred while building the HTTP Request.

Description:

This event encapsulates HTTP client error messages that it would normally log to the console i.e. the stderr stream. This event will only be logged when eSocket.POS is not able to build a valid HTTP request from the message received.

Action:

Review the error message logged to determine the action to take to rectify

Event 10283

Severity:

Informational

Symbolic Name:

SAFQ_LIMITS_STATE_CHANGE

Message:

Text:

The eSocket.POS monitoring system detected a SAFQ limits state change of the store and forward queue (SAFQ) of terminal %1. The new state is: %2.

Parameter %1:

terminal ID

Parameter %2:

new safq limits state

Description:

A SAFQ limits state change was detected.

Action:

None.

Event 10284

Severity:

Error

Symbolic Name:

CONFIG_AGENT_HTTP_REQUEST_UNSUCCESSFUL

Message:

Text:

An HTTP request attempted by ConfigAgent was unsuccessful. Method: %1 URI: %2 Error details: %3

Parameter %1:

The HTTP method

Parameter %2:

The URI to which the request was attempted.

Parameter %3:

The error details.

Description:

An HTTP request attempted by ConfigAgent failed to complete successfully.

Action:

Review the error message logged to determine the action to take.

Event 10285

Severity:

Error

Symbolic Name:

CONFIG_AGENT_RETRYING_FAILED_CERTIFICATE_RENEWAL

Message:

Text:

The Configuration Agent failed while attempting the TLS client certificate renewal. Reason: %1. The certificate renewal will be retried in %2 second(s). If the renewal fails again, it will be retried %3 more time(s).

Parameter %1:

The reason given for the failure

Parameter %2:

The number of seconds before the certificate renewal is going to be retried

Parameter %3:

The number of times the certificate renewal will be retried if it fails again

Description:

An error occurred while attempting the certificate renewal and the certificate renewal is going to be retried.

Action:

None.

Event 10286

Severity:

Error

Symbolic Name:

CONFIG_AGENT_RETRYING_FAILED_CERTIFICATE_RENEWAL_ATTEMPTS_EXHAUSTED

Message:

Text:

The Configuration Agent failed while attempting the TLS client certificate renewal. Reason: %1. The certificate renewal will be retried in %2 minute(s).

Parameter %1:

The reason given for the failure

Parameter %2:

The number of minutes before the certificate renewal is going to be retried

Description:

An error occurred while attempting the certificate renewal and the certificate renewal is going to be retried.

Action:

None.

Event 10287

Severity:

Error

Symbolic Name:

CONFIG_AGENT_CLIENT_CERTIFICATE_RENEWAL_FAILURE

Message:

Text:

The renewal of TLS client certificate failed. Reason: %1.

Parameter %1:

Exception associated with the TLS client certificate renewal failing

Description:

This event is logged when TLS client certificate renewal fails.

Action:

Investigate the reason for the TLS certificate renewal failing by reviewing the reported exception. Contact your primary support provider should additional assistance be required.

Event 10288

Severity:

Warning

Symbolic Name:

INVALID_USER_PARAM

Message:

Text:

%1. Consult the User Guide for the list of valid values for this parameter.

Parameter %1:

Message with valid parameter values

Description:

This event is logged when user param is not configured correctly.

Action:

Consult the User Guide for the list of valid values for this parameter.

Event 10289

Severity:

Warning

Symbolic Name:

MANDATE_VIOLATION_WARNING

Message:

Text:

The current configuration for the parameter %1 is violating a %2 mandate. Please consult the User Guide or contact your primary support provider for assistance.

Parameter %1:

Parameter Name

Parameter %2:

Mandate Name

Description:

This event is logged when user parameter configuration violates an existing.

Action:

Consult the User Guide for more information

Event 10290

Severity:

Error

Symbolic Name:

MANDATE_VIOLATION_ERROR

Message:

Text:

The current configuration for the parameter %1 is violating a %2 mandate. Please consult the User Guide or contact your primary support provider for assistance.

Parameter %1:

Parameter Name

Parameter %2:

Mandate Name

Description:

This event is logged when user parameter configuration violates an existing.

Action:

Consult the User Guide for more information

Event 10291

Severity:

Warning

Symbolic Name:

REMOTE_SINK_CONNECTION_ATTEMPT

Message:

Text:

%1.

Parameter %1:

Details

Description:

This event is logged when the Postilion Interface (RemoteSink) attempts to connect to the remote host.

Action:

o action required.

Event 10292

Severity:

Informational

Symbolic Name:

DATABASE_CONNECTION_STATUS

Message:

Text:

Database connection status update: %1.

Parameter %1:

Status message indicating the current state of the database connection.

Description:

This event is logged when the database connection is lost and will be reattempted or when it has recovered.

Action:

None.

Event 10293

Severity:

Informational

Symbolic Name:

LOG_CLEANER_COMPLETED

Message:

Text:

The Service Log Cleaner has completed.

Description:

This event is logged when the Service Log Cleaner has completed.

Action:

None.

 

© Copyright ACI Worldwide 2021

All information contained in this documentation, as well as the software described in it, is confidential and proprietary to ACI Worldwide, Inc., or one of its subsidiaries, is subject to a license agreement, and may be used or copied only in accordance with the terms of such license. Except as permitted by such license, no part of this documentation may be reproduced, stored in a retrieval system, or transmitted in any form or by electronic, mechanical, recording, or any other means, without the prior written permission of ACI Worldwide, Inc., or one of its subsidiaries.

ACI, ACI Worldwide, and the ACI product names used in this documentation are trademarks or registered trademarks of ACI Worldwide, Inc., or one of its subsidiaries.

Other companies' trademarks, service marks, or registered trademarks and service marks are trademarks, service marks, or registered trademarks and service marks of their respective companies.