- Get Started
- Guides
- Integrations
- References
- API Reference
- Basic Payment
- Forex
- Authentication
- Card Account
- Apple Pay
- Virtual Account
- Bank Account
- Token Account
- Customer
- Billing Address
- Merchant Billing Address
- Shipping Address
- Merchant Shipping Address
- Merchant
- Corporate
- Recipient
- Marketplace & Cart
- Airline
- Lodging
- Passenger
- Tokenization
- Recurring Migration
- 3D Secure
- Custom Parameters
- Async Payments
- Webhook notifications
- Job
- Risk
- Point of Sale
- Response Parameters
- Card On File
- Chargeback
- Result Codes
- Payment Methods
- Transaction Flows
- Regression Testing
- Data Retention Policy
- API Reference
- Support
- Impressum
Table of Contents
- eSocket.POS Developer Guide
- Introduction
- 1. Interface specification
- 2. Java API
- 3. XML Interface
- 3.1. Overview
- 3.2. Using Esp:Interface
- 3.3. TCP messages
- 3.4. Initializing a terminal
- 3.5. Closing a terminal
- 3.6. Handling timeouts
- 3.7. Error handling
- 3.8. Transactions
- 3.9. Events and callback
- 3.10. POS XML message flow examples
- 3.11. EFT transactions
- 3.11.1. Balance inquiry
- 3.11.2. Barcode reader
- 3.11.3. Card Read Inquiry
- 3.11.4. Card verification inquiry
- 3.11.5. Check/Cheque verification
- 3.11.6. Credit adjustment
- 3.11.7. Debit adjustment
- 3.11.8. Deposit
- 3.11.9. Line item display
- 3.11.10. Pay At Table initialization
- 3.11.11. Pre-swipe
- 3.11.12. Prompt request
- 3.11.13. Purchase with DCC using explicit rate requests
- 3.11.14. Purchase with DCC using implicit rate requests
- 3.11.15. Purchase (dual message pair)
- 3.11.16. Purchase with consumer-presented QR code
- 3.11.17. Purchase with merchant-presented QR code
- 3.11.18. Purchase with merchant-presented QR code and reversal/void
- 3.11.19. Purchase with referral
- 3.11.20. XML - Purchase with timeout and online reversal/void
- 3.11.21. Purchase with Signature capture
- 3.11.22. Purchase (single message pair)
- 3.11.23. Purchase and reversal/void
- 3.11.24. Purchase with timeout and reversal/void
- 3.11.25. Purchase with Token generation request for online standin with advice
- 3.11.26. Purchase with Token generation request for online standin without advice
- 3.11.27. Reconciliation
- 3.11.28. Refund
- 3.11.29. Signature capture request
- 3.11.30. Signature lookup request
- 3.11.31. Token Lookup (TransArmor)
- 3.11.32. XML - FSA/HSA Purchase
- 3.11.33. EFT Transaction Inquiry
- 3.11.34. Terminal Status
- 3.12. Gift card transactions
- 3.12.1. Gift card activation
- 3.12.2. Gift card activation with load
- 3.12.3. Gift card activation with load - reversal/void
- 3.12.4. Gift card activation with load timeout
- 3.12.5. Gift card load funds
- 3.12.6. Gift card reversal/void
- 3.12.7. Gift card unload funds
- 3.12.8. Gift card unload - reversal/void
- 3.12.9. Gift card activation and refund
- 3.12.10. Gift card activation and refund - reversal/void
- 3.12.11. Gift card de-activation
- 3.12.12. Gift card de-activation
- 3.12.13. Gift card deactivation with unload
- 3.12.14. Gift card balance inquiry
- 3.12.15. Gift card Purchase - reversal/void
- 3.13. EBT transactions
- 3.14. Credit application transactions
- 3.15. Prompts
- 3.16. Display
- 3.17. Receipt printing
- 4. Implement/Extending eSocket.POS components
- 5. Object properties and conditions
- 6. Diagnostic tools
- 7. Copyright
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
Related information
The following resources provide information related to the subjects discussed in this document.
Related eSocket.POS technical documents
-
eSocket.POS User Guide
Related ISO documents
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
Other related documents
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 | ||
---|---|---|---|---|---|
M |
A |
||||
M |
A |
||||
M |
A |
||||
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.
|
|||
O |
- |
||||
C |
T |
Must be set to true for a reversal. The default (if this property is not set) is false . |
|||
O |
C |
Defaults to ADVICE (offline). |
|||
O |
A |
||||
O |
A |
||||
O |
A |
||||
C |
H |
This property must be set to the following values, depending on the transaction type:
|
|||
O |
H |
||||
O |
H |
||||
O |
H |
||||
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. |
|||
O |
C |
||||
O |
- |
||||
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. |
|||
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. |
|||
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. |
|||
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. |
|||
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. |
|||
O |
T |
||||
O |
- |
||||
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. |
|||
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. |
|||
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. |
|||
O |
A |
If not set, this value will be set based on the presence or absence of Track2 . |
|||
O |
A |
If not set, the default value of '00' - Normal Presentment will be assumed. |
|||
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. |
|||
CG |
T |
Required for a transaction involving cashback, unless the Cashback component has been configured to insert the cashback amount. |
|||
OG |
H |
Required for a transaction involving gratuity, unless the Gratuity component has been configured. |
|||
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. |
|||
CG |
T |
Required for a transaction involving an extended payment period, unless the Extended Payment component will insert the extended payment period. |
|||
G |
A |
Required if eSocket.POS is not configured with an Account component. Optional otherwise. |
|||
O |
- |
Required if PIN entry and encryption is performed by the POS. |
|||
C |
- |
Required if PinData is present. |
|||
O |
T |
||||
- |
H |
||||
O |
G |
||||
O |
A |
||||
- |
A |
||||
O |
A |
||||
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. |
|||
- |
C |
Will be present if the authorizer of the transaction was not the card issuer. |
|||
- |
T |
||||
C |
C |
Should be sent when a token-based authentication is used by the upstream entity. |
|||
O |
T |
Will be ignored unless PostalCode property is also set. |
|||
O |
T |
||||
- |
H |
||||
O |
C |
Should be sent when the PIN was bypassed for the contactless transaction. |
|||
- |
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. |
|||
- |
G |
Will be returned if this card product is configured in eSocket.POS. |
|||
- |
G |
Will be returned if set up by a response pipeline component in eSocket.POS. |
|||
- |
G |
Will be returned if set up by a response pipeline component in eSocket.POS. |
|||
- |
C |
Will be provided in a referral authorization response if a referral telephone number is available for this card. |
|||
O |
G |
May be provided in the response if set up by a pipeline component. |
|||
O |
G |
May be provided in the response if set up by a pipeline component. |
|||
- |
G |
May be provided in the response if set up by a pipeline component. |
|||
- |
G |
Will be present if the RPS component is configured and transaction is Rapid Payment Service. |
|||
- |
G |
Will be present if the FallbackIndicator component is configured. Or if it was received in the request. |
|||
- |
G |
Will be present if provided by the FallbackIndicator component. Or if it was received in the xml request. |
|||
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. |
|||
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 |
|||
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. |
|||
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 |
|||
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 |
|||
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 |
|||
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. |
|||
- |
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 |
|||
- |
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
O |
C |
Will be provided in the response if available when an EMV card was used. |
|||
- |
C |
Will be provided in the response if available when an EMV card was used. |
|||
- |
C |
Will be provided in the response if available when an EMV card was used. |
|||
- |
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
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 |
|||
- |
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 |
|||
- |
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 |
|||
- |
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 |
|||
- |
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 |
|||
- |
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 |
|||
- |
C |
Will be provided in the response if it was returned by the upstream entity after online issuer authentication. EMV Tag ID: 91 |
|||
- |
C |
Will be provided in the response if it was returned by the upstream entity after online issuer authentication. EMV Tag ID: 71 |
|||
- |
C |
Will be provided in the response if it was returned by the upstream entity after online issuer authentication. EMV Tag ID: 72 |
|||
O |
HG |
||||
- Name |
M |
A |
|||
- Value |
M |
A |
|||
- Flags |
O |
G |
|||
- - DoNotPersist |
O |
G |
|||
O |
HG |
||||
- Name |
M |
A |
|||
- Value |
M |
A |
|||
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. |
|||
- |
H |
||||
- |
H |
||||
- |
H |
||||
- |
H |
||||
- Sign |
- |
H |
|||
- Amount |
- |
H |
|||
- |
H |
||||
- DateTime |
O |
H |
|||
- |
H |
||||
- |
H |
||||
- |
H |
||||
- |
H |
||||
- |
H |
||||
- |
H |
||||
- |
H |
||||
O |
C |
||||
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 |
- |
|||
O |
- |
||||
O |
- |
||||
O |
- |
||||
O |
- |
||||
O |
C |
Will be provided in the response if the chained transaction information could be retrieved. |
|||
M |
- |
Indicates which set of logical devices will be used. |
|||
O |
C |
Standalone dynamic text that will be displayed on the screens that host the check box prompts. |
|||
O |
C |
Indicates whether or not the image should be included in the transaction response. |
|||
O |
C |
The format of the image to be returned in the response, if requested in the SignatureImagePassedInResponse field. |
|||
O |
C |
This field will be used to populate the scrollable text area on the free text screens. |
|||
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. |
|||
O |
C |
The format of the image in the user interface request. Only to be set for a signature capture transaction. |
|||
O |
C |
The category of the image. Only to be set for a signature capture transaction. |
|||
O |
C |
Indicates whether the image in the user interface message request is encrypted. Only to be set for a signature capture transaction. |
|||
O |
C |
Dynamic text label associated with the first check box on forms. |
|||
O |
C |
Dynamic text label associated with the second check box on forms. |
|||
O |
C |
Dynamic text label associated with the third check box on forms. |
|||
O |
C |
The state of the first check box after user input. |
|||
O |
C |
The state of the second check box after user input. |
|||
O |
C |
The state of the third check box after user input. |
|||
O |
C |
Indicates the button input collected from the user. |
|||
O |
C |
The name of the prompt. Only to be set for a signature capture transaction. |
|||
O |
C |
The full response text as sent by the EBT provider. |
|||
O |
C |
The beginning food stamp account balance. |
|||
O |
C |
The ending food stamp account balance. |
|||
O |
C |
The available food stamp account balance. |
|||
O |
C |
The beginning cash benefits account balance. |
|||
O |
C |
The ending cash benefits account balance. |
|||
O |
C |
The available cash benefits account balance. |
|||
O |
C |
EBT case number. |
|||
O |
C |
EBT voucher number. |
|||
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. |
|||
O |
- |
The amount for the prescription component of the healthcare transaction. |
|||
O |
- |
The amount for the optical component of the healthcare transaction. |
|||
O |
- |
The amount for the dental component of the healthcare transaction. |
|||
O |
- |
The amount for the clinic component of the healthcare transaction. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The lodging facility’s internal invoice or billing identification reference number. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The local phone number of the lodging facility at which the cardholder stayed. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The date on which the cardholder checked in at the lodging facility. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The date on which the cardholder checked out of the lodging facility. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The daily room charges, exclusive of taxes and fees. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The daily room tax amount. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The total amount of phone calls charged to the room. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The total amount of restaurant and/or room service food charged to the room. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The total amount of bar and in-room "mini-bar" items charged to the room. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The total amount of laundry and drycleaning items charged to the room. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The total amount of gift shop and specialty shop items charged to the room. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The total amount of miscellaneous items/services charged to the room, not specified elsewhere. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: Indicates the type of charges provided in LdAmountOtherServices. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The amount of any additional charges incurred after the cardholder’s departure. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: A code allocated by the acquirer that identifies special circumstances. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The customer service number that the cardholder may call to resolve questions or disputes. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The number of guests. |
|||
O |
T |
Lodging (e.g. hotel, motel) transactions: The name of the guest. |
|||
O |
A |
||||
- |
C |
The Visa Available Offline Spending Amount value, if available on the card. |
|||
- |
C |
Represents the amount of offline spending available on the card. |
|||
O |
- |
The Alternative Payment Method. |
|||
O |
- |
The Payment Brand. |
|||
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. |
|||
O |
- |
An additional transaction reference received from the host system in QR code transaction response messages. |
|||
O |
- |
The QR code image encoded in Base64. |
|||
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. |
|||
O |
- |
The QR code type in the QR code transactions. |
|||
O |
- |
The barcode data. e.g. 0123456789. This field will be ignored in request messages if the QRCodeData field is set. |
|||
O |
- |
Can be set to indicate the quantity of items purchased in consumer-presented QR code transaction requests. |
|||
O |
- |
Can be set to indicate the name of the Transaction in consumer-presented QR code transaction requests. |
|||
O |
- |
Can be set to indicate the store ID in consumer-presented QR code transaction requests. |
|||
O |
- |
Can be set to indicate the memo in consumer-presented QR code transaction requests. |
|||
- |
C |
The dynamic currency conversion (DCC) status code. |
|||
- |
C |
An identifier for the external entity that provided the currency conversion information which represents a DCC offer. |
|||
- |
C |
The exchange rate used when performing currency conversion from the amount in the source currency to the amount in the target currency. |
|||
- |
C |
Numeric code of the currency being converted from. |
|||
- |
C |
Alphabetic code of the currency being converted from. |
|||
- |
C |
The number of digits following the decimal separator. |
|||
- |
C |
Numeric code of the currency being converted to. |
|||
- |
C |
Alphabetic code of the currency being converted to. |
|||
- |
C |
The number of digits following the decimal separator. |
|||
- |
C |
The currency conversion service provider. |
|||
- |
C |
The source of conversion data. |
|||
- |
C |
Time the conversion was performed in Coordinated Universal Time (UTC). |
|||
- |
C |
Numeric value representing the foreign exchange markup rate as a fraction. |
|||
- |
C |
Numeric value representing the foreign exchange commission rate as a fraction. |
|||
- |
C |
Numeric value representing the foreign exchange markup, it compares the DCC exchange rate to the European Central Bank rate as a fraction. |
|||
- |
C |
Amount of the transaction in the currency being converted from. |
|||
- |
C |
Amount of the transaction in the currency being converted to. |
|||
- |
C |
The offer expiration date and time in Coordinated Universal Time (UTC). |
|||
- |
C |
Additional disclaimer information required for printing on receipts. |
|||
- |
C |
Additional disclaimer information required for printing on receipts. |
|||
- |
C |
The dynamic currency conversion specific acquirer identifier. |
|||
- |
C |
The dynamic currency conversion specific card acceptor identifier. |
|||
- |
C |
The dynamic currency conversion specific terminal identifier. |
|||
- |
H |
The Credit or Debit network that processed the transaction. |
|||
O |
H |
Payee name and address contains identification and billing information for a payee. |
|||
O |
H |
Contains additional payee name and address details. |
|||
O |
H |
Contains account details needed for a credit application. |
|||
O |
H |
The status response from ADS based on the processor specification. |
|||
O |
H |
The status response that contains information about the account. |
|||
G |
T |
Indicates whether the merchant or cardholder OPC selection mode should be applied. |
|||
O |
T |
Indicates whether the amount requested is a pre-authorization, normal authorization, or the final amount. |
|||
G |
G |
Contains additional card details, as configured in eSocket.POS. |
|||
G |
- |
Can be set to send details for a transaction involving a fleet card. Within this element, all attributes are optional. |
|||
- |
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. |
|||
O |
H |
An optional PosGeographicDataLatitude field can be attached to a transaction. |
|||
O |
H |
An optional PosGeographicDataLongitude field can be attached to a transaction. |
|||
O |
H |
An optional TerminalAddress field can be attached to a transaction. |
|||
O |
- |
Set to disable the welcome and transaction outcome displays on a device. |
|||
O |
H |
Specifies the recurring payment indicator. |
|||
O |
H |
Specifies the stored credential indicator. |
|||
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 |
---|---|---|---|
M |
A |
||
M |
A |
||
M |
A |
||
O |
A |
||
O |
A |
||
O |
A |
||
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'. |
|
O |
H |
||
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. |
|
C |
C |
Should be sent when a token-based authentication is used by the upstream entity. |
|
O |
T |
Will be ignored unless PostalCode property is also set. |
|
O |
C |
Should be sent when the PIN was bypassed for the contactless transaction. |
|
O |
T |
||
O |
H |
||
O |
H |
||
O |
C |
||
O |
C |
||
O |
- |
||
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. |
|
CG |
T |
If eSocket.POS does not read the card, either the Track2 or the CardNumber and ExpiryDate properties must be set. |
|
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. |
|
O |
T |
||
O |
- |
||
O |
- |
Used for transaction inquiries to provide the MessageType of the original transaction that should be retrieved. |
|
O |
- |
Used for transaction inquiries to provide the Type of the original transaction that should be retrieved. |
|
O |
C |
Will be returned in the response of a transaction inquiry with the transaction data if the transaction is found |
|
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. |
|
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. |
|
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. |
|
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 . |
|
O |
A |
If not set, the default value of '00' - Normal Presentment will be assumed. |
|
O |
T |
||
- |
H |
||
O |
G |
||
O |
A |
||
- |
A |
||
- |
A |
||
O |
A |
Must be set if eSocket.POS is not configured with an Account component. Optional otherwise. |
|
O |
- |
Required if PIN entry and encryption is performed by the POS |
|
C |
- |
Required if PIN data is present |
|
C |
T |
May be required in check verification or check guarantee requests. |
|
- |
C |
Will be returned if Track 2 Data is available. |
|
- |
G |
Will be returned if this card product was configured in eSocket.POS. |
|
- |
G |
Will be returned if set up by a response pipeline component in eSocket.POS. |
|
- |
G |
Will be returned if set up by a response pipeline component in eSocket.POS. |
|
O |
G |
This property is deprecated. Rather use an EspCheck object for a check verification or check guarantee transaction. |
|
O |
G |
This property is deprecated. Rather use an EspCheck object for a check verification or check guarantee transaction. |
|
O |
G |
This property is deprecated. Rather use an EspCheck object for a check verification or check guarantee transaction. |
|
- |
C |
Will be present in the response to a Balance Inquiry, an Available Funds Inquiry or else a Mini-statement Inquiry. |
|
- |
C |
Will be present in the response to a Balance or Available Funds Inquiry. May be present in a Mini-statement Inquiry. |
|
- |
C |
Will be present in the response to a Balance or Available Funds Inquiry. |
|
- |
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. |
- |
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 |
- |
H |
May be present in a Mini-statement Inquiry. |
|
- |
H |
May be present in a Mini-statement Inquiry. |
|
- |
H |
May be present in a Mini-statement Inquiry. |
|
- |
H |
May be present in a Mini-statement Inquiry. |
|
- |
H |
May be present in a Mini-statement Inquiry. |
|
- |
H |
May be present in a Mini-statement Inquiry. |
|
- |
H |
May be present in a Mini-statement Inquiry. |
|
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. |
|
O |
HG |
||
- Name |
M |
A |
|
- Value |
M |
A |
|
- Flags |
O |
G |
|
- -DoNotPersist |
O |
G |
|
O |
HG |
||
- Name |
M |
A |
|
- Value |
M |
A |
|
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 |
- |
|
O |
- |
||
O |
- |
||
O |
- |
||
O |
- |
||
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 |
- |
|
O |
- |
||
O |
- |
||
O |
- |
||
O |
- |
||
O |
C |
Will be provided in the response if the chained transaction information could be retrieved. |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F02 |
|
- |
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 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 4F |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 82 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 50 |
|
- |
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 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F12 |
|
- |
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 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F36 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F07 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F26 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F27 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 8E |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F34 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F1E |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F0D |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F0E |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F0F |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F10 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F11 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. |
|
- |
C |
Will be provided in the response if available when an EMV card was used. |
|
- |
C |
Will be provided in the response if available when an EMV card was used. |
|
- |
C |
Will be provided in the response if available when an EMV card was used. |
|
- |
C |
Will be provided in the response if available when an EMV card was used. |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F09 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F33 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F1A |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F35 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 95 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F53 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 5F2A |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9A |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F41 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9B |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9C |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F37 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F6E |
|
O |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F7C |
|
O |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F40 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 9F21 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 87 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 5F28 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. EMV Tag ID: 5F24 |
|
- |
C |
Will be provided in the response if available when an EMV card was used. |
|
O |
C |
The full response text as sent by the EBT provider. |
|
O |
C |
The beginning food stamp account balance. |
|
O |
C |
The ending food stamp account balance. |
|
O |
C |
The available food stamp account balance. |
|
O |
C |
The beginning Cash Benefits account balance. |
|
O |
C |
The ending Cash Benefits account balance. |
|
O |
C |
The available Cash Benefits account balance. |
|
O |
C |
EBT Case Number. |
|
O |
C |
EBT Voucher Number. |
|
O |
A |
||
- |
C |
The Visa Available Offline Spending Amount value, if available on the card. |
|
- |
C |
Represents the amount of offline spending available on the Card. |
|
O |
H |
The payee name and address object contains identification and billing information for the payee. |
|
O |
H |
Contains additional payee name and address details. |
|
O |
H |
Contains account details needed for a credit application. |
|
O |
H |
The status response from ADS based on the processor specification. |
|
O |
H |
The status response containing information about the account. |
|
G |
G |
Contains additional card details, as configured in eSocket.POS. |
|
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 |
---|---|---|---|
M |
A |
||
M |
A |
||
M |
A |
||
O |
A |
||
O |
A |
||
O |
A |
||
O |
H |
||
O |
H |
||
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. |
|
O |
T |
||
O |
C |
||
C |
C |
Should be sent when a token-based authentication is used by the upstream entity. |
|
O |
C |
||
- |
A |
||
M |
A |
Required if the merchandise type is REQUEST or PROCURE. |
|
O |
C |
||
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. |
|
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. |
|
O |
G |
||
O |
- |
||
O |
- |
||
O |
- |
||
- |
H |
||
O |
G |
||
- |
A |
||
- |
A |
||
O |
A |
||
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. |
|
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
- Quantity |
- |
H |
|
- |
H |
||
- |
H |
||
- |
H |
||
- |
H |
||
O |
HG |
||
- Name |
M |
A |
|
- Value |
M |
A |
|
- Flags |
O |
G |
|
- -DoNotPersist |
O |
G |
|
O |
HG |
||
- Name |
M |
A |
|
- Value |
M |
A |
|
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 |
---|---|---|---|
M |
A |
||
M |
A |
||
M |
A |
||
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. |
|
C |
T |
Must be set to true for a reversal. The default (if this property is not set) is false . |
|
O |
A |
||
O |
C |
Defaults to ADVICE (offline). |
|
O |
A |
||
O |
A |
||
O |
A |
||
O |
H |
||
O |
H |
||
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. |
|
C |
C |
Should be sent when a token-based authentication is used by the upstream entity. |
|
- |
A |
||
O |
H |
||
O |
C |
||
O |
- |
||
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 |
|
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. |
|
O |
TCG |
May be set if the CardNumber or Track2 is set. Should not be set otherwise. |
|
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. |
|
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 . |
|
O |
T |
||
O |
G |
||
O |
A |
||
- |
A |
||
O |
A |
||
M |
A |
||
- |
C |
Will be returned if Track 2 Data is available. |
|
- |
G |
Will be returned if set up by a response pipeline component in eSocket.POS. |
|
O |
|||
O |
H |
Should be set to true if this is a Check ID Card transaction. Default is false . |
|
O |
H |
Should be set to true if the ID was validated against a second ID. Default is false . |
|
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
C |
H |
Must be set if a driver’s license is used as the form of identification. |
|
O |
H |
||
C |
H |
Must be set if a generic ID is used as the form of identification. |
|
O |
H |
||
O |
HG |
||
- Name |
M |
A |
|
- Value |
M |
A |
|
- Flags |
O |
G |
|
- -DoNotPersist |
O |
G |
|
O |
HG |
||
- Name |
M |
A |
|
- Value |
M |
A |
|
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. |
|
O |
C |
Will be provided in the response if the chained transaction information could be retrieved. |
|
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
O |
H |
||
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 |
---|---|---|---|
M |
A |
||
M |
A |
||
O |
C |
||
O |
G |
||
O |
A |
||
O |
A |
||
O |
A |
||
O |
HG |
||
- Name |
M |
A |
|
- Value |
M |
A |
|
- |
A |
||
- |
A |
||
- |
A |
9670 - ' Batch Totals Not Available ', if there was any condition that the totals was not retrieved from Postilion Realtime |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
C |
C |
Should be sent when a token-based authentication is used by the upstream entity. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
M |
A |
||
M |
A |
||
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 |
---|---|---|---|
M |
A |
||
M |
A |
||
O |
A |
||
O |
A |
||
O |
A |
||
- |
A |
||
- |
A |
||
- |
A |
||
O |
G |
||
O |
H |
||
M |
H |
||
G |
A |
Required if the message will be sent to Transaction Manager, unless this is populated by a pipeline component. |
|
- |
G |
Will be returned if set up by a response pipeline component in eSocket.POS. |
|
O |
HG |
||
- Name |
M |
A |
|
- Value |
M |
A |
|
- Flags |
O |
G |
|
- -DoNotPersist |
O |
G |
|
O |
HG |
||
- Name |
M |
A |
|
- Value |
M |
A |
|
C |
C |
Should be sent when a token-based authentication is used by the upstream entity. |
|
O |
H |
Contains data passed from the Point-of-Service (POS) system. |
|
M |
A |
||
M |
A |
||
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 |
---|---|---|---|
M |
A |
||
M |
A |
||
- |
A |
||
- |
A |
||
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 |
---|---|---|---|
M |
- |
||
M |
- |
||
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 |
---|---|---|---|
M |
A |
||
M |
A |
||
O |
- |
||
- |
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 |
---|---|---|---|
- |
C |
Will be set if available in the request that resulted in the error. |
|
- |
C |
Will be set if available in the request that resulted in the error. |
|
- |
A |
1 / DECLINE |
|
- |
A |
30 - Format error |
|
- |
A |
9791 - Administrative response |
|
- |
C |
Will be set if available in the Java exception. |
1.3.5. BarcodeData
1.3.6. BarcodeStatusCode
Format
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
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
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 |
---|---|---|
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 |
Attribute |
Indicates how the transaction will be billed to the customer. R - Recurring transaction I - Installment billing transaction D - Deferred billing transaction |
|
PaymentPurchaseIndicator |
Attribute |
Indicates the customer’s income frequency A - Annual M - Monthly W - Weekly |
|
MinimumPaymentDue |
Attribute |
Minimum payment due |
|
PromoCode |
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 |
Attribute |
For SVS, this is returned in the response. Either a SerialNumber or a primary account number (PAN) can be returned. |
|
AccountExpirationDateTime |
Attribute |
Account expiration date/time in UTC format(YYYYMMDDTHHMMZ) |
|
PaymentPlanCode |
Attribute |
Payment plan code or credit plan. |
|
ReferenceNo |
Attribute |
Reference number sent back from the processor |
|
ApplicationReferenceNo |
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 |
---|---|---|
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:
Field | Format | Type (Element, Attribute) | Description |
---|---|---|---|
FirstName |
Attribute |
Customer’s first name |
|
LastName |
Attribute |
Customer’s last name |
|
CardHolderName |
Attribute |
Customer’s actual name as embossed on the credit card |
|
MiddleInitial |
Attribute |
Customer’s middle initial |
|
CustomerSuffix |
Attribute |
Customer’s suffix, for example, Jr, Sr, or II |
|
Gender |
Attribute |
Customer’s gender |
|
CustomerDateOfBirth |
Attribute |
Customer’s date of birth (YYYYMMDD) |
|
MotherMaidenName |
Attribute |
Customer’s mother’s maiden name |
|
LengthAtAddress |
Attribute |
Length of time living at the current address (YYMM) |
|
CustomerCellPhoneNumber |
Attribute |
Customer’s cell phone number |
|
CustomerBusinessPhone |
Attribute |
Customer’s business phone number |
|
CustomerPreviousAddress |
Attribute |
Customer’s previous residential address |
|
CustomerPreviousCity |
Attribute |
Customer’s previous residential city |
|
CustomerPreviousState |
Attribute |
Customer’s previous residential state |
|
CustomerPreviousZip |
Attribute |
Customer’s previous residential zip |
|
CustomerPreviousLengthAtAddress |
Attribute |
Length of time living at the previous address |
|
CustomerPreviousBusinessPhone |
Attribute |
Customer’s previous business phone number |
|
HousingCode |
Attribute |
Housing code: R - Rent |
|
CustomerOccupationCode |
Attribute |
Customer’s occupation code |
|
YearlyIncome |
Attribute |
Customer’s annual income |
|
PrimaryIncomeFrequency |
Attribute |
Customer’s income frequency: W - Weekly |
|
PanderFlag |
Attribute |
Pander flag: 1 - Mail can be sent |
|
InsuranceIndicator |
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 |
|
Attribute |
Additional ID 1 |
||
Attribute |
Additional ID 2 |
||
Attribute |
Additional ID 3 |
||
Attribute |
Additional ID 4 |
||
PatriotPlace |
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 |
Attribute |
Patriot issue date - the issue date of the ID used in the credit application request message. Format YYYYMMDD |
|
PatriotExpirationDate |
Attribute |
Patriot expiration date - the expiration date of the ID used in the credit application request message. Format YYYYMMDD |
|
CustomerAuthorizedUser |
Attribute |
Authorized user |
|
JointAuthFlag |
Attribute |
Joint applicant values for ADS: J - Joint application |
|
RelativeCode |
Attribute |
Authorized buyer relationship: O - Other |
|
SecondaryCustomerFirstName |
Attribute |
Secondary customer’s first name |
|
SecondaryCustomerMiddleInitial |
Attribute |
Secondary customer’s middle initial |
|
SecondaryCustomerLastName |
Attribute |
Secondary customer’s last name |
|
SecondaryCustomerDateOfBirth |
Attribute |
Secondary customer’s date of birth |
|
SecondaryCustomerHomePhone |
Attribute |
Secondary customer’s home phone number |
|
SecondaryCustomerBusinessPhone |
Attribute |
Secondary customer’s business phone number |
|
SecondaryCustomerYearlyIncome |
Attribute |
Secondary customer’s annual income |
|
SecondaryCustomerIncomeFrequency |
Attribute |
Secondary customer’s income frequency: W - Weekly |
|
CardIssuanceLevel |
Attribute |
Card issuance level - indicates the number of times the card has been re-issued. |
|
TextFlag |
Attribute |
Text flag - A flag indicating if the customer can be contacted via text messaging. Y - the customer can be contacted via text message. |
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
AuthorizationToken
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 |
---|---|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
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
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
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
Description
The authorization ID involved in a transaction contained in a line in the mini-statement represented by this balance list item.
CurrencyCode
Format
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
Description
The sequence number for a line in the mini-statement represented by this balance list item.
Sign
Surcharge
Format
Description
The surcharge involved in a transaction contained in a line in the mini-statement represented by this balance list item.
TerminalId
Format
Description
The terminal ID of the transaction contained in a line in the mini-statement represented by this balance list item.
ToAccountType
Format
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
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
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
CardSequenceNumber
Format
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
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
Description
The currency of the transaction amount. See ISO 4217 (1990): Codes for the Representation of Names of Currencies and Funds.
Cvv2
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
ExtendedTransactionType
ExpiryDate
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 |
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
Array of FleetBatchData objects |
|
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 |
String |
|
String |
|
String |
|
String |
MaximumAmount
MaximumMiscellaneousAmount
Format
Description
The maximum miscellaneous amount (in minor denomination) in the transaction’s currency.
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.
Odometer
OilBrandName
Format
Description
The acquirer’s abbreviation for the brand name of the card acceptor’s oil company.
PrintPricePerGallon
Format
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 |
---|---|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
PromptCode
Format
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
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
ReceiptText
RestrictionCode
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
VehicleUsage
Format
Description
The type of service received at the card acceptor location.
Valid values:
-
P - Private
-
B - Business
FleetDataRsp
Properties
Name |
Type |
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
Array of Restriction objects |
HostBasedPurchaseRestriction
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
Restriction
A Restriction is implemented using a Restriction object in the API, or an Esp:Restriction element in the XML interface.
Properties
Name | Type |
---|---|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
Format
Description
Contains the restriction code that applies to the fleet response restriction.
LocalDate
LocalTime
MerchantId
MessageReasonCode
Format
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
PanEntryMode
Format
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
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:
-
The card data input capability (position 1) of the terminal.
-
The cardholder authentication capability (position 2) of the terminal.
-
The card capture capability (position 3) of the terminal.
-
The operating environment (position 4) of the terminal.
-
Indicates whether the cardholder is present (position 5).
-
Indicates whether the card is present (position 6).
-
The actual card data input mode (position 7) of the transaction.
-
The actual cardholder authentication method (position 8) of the transaction.
-
The cardholder authentication entity (position 9) of the transaction.
-
The card data output capability (position 10) of the terminal.
-
The terminal output capability (position 11) of the terminal.
-
The PIN capture capability (position 12) of the terminal.
-
The terminal operator (position 13).
-
The terminal type (positions 14 & 15).
PosOperatorId
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 |
---|---|
String |
|
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
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 | ||
---|---|---|---|
String |
|||
String |
|||
String |
|||
String |
|||
String |
|||
String |
|||
String |
|||
String
|
|||
Array of ItemizedDiscount objects |
|||
String |
|||
String |
|||
String |
|||
String |
|||
Boolean |
|||
String |
|||
String |
|||
String |
|||
String |
|||
String |
|||
String |
|||
String |
|||
String |
|||
String |
|||
Boolean |
|||
String |
|||
String |
|||
String |
|||
String |
|||
String |
|||
Array of LineItem objects |
|||
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). |
|||
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
CardAcceptorVatNr
Format
Description
The VAT number of the card acceptor location, used to identify the card acceptor when reporting taxes.
CardType
InvoiceDiscountTreatment
Comment
CommodityCode
Format
Description
A code assigned by the card acceptor that best categorizes the goods or services purchased.
CorporationVatNr
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 |
---|---|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
Format
Description
The type of contact. Values can include BILL_FROM, BILL_TO, SHIP_FROM and SHIP_TO.
CustomerBillingCode
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
DiscountAmount
Format
Description
The discount amount applied to this transaction. Amounts are given in the minor denomination.
ParticipantDiscountAmount
DiscountAmountSign
DutyAmount
Format
Description
The duty amount to be paid on the total purchase. Amounts are given in the minor denomination.
DutyAmountSign
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 |
String |
|
String |
|
String |
MerchantOrderNumber
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 |
---|---|
String |
|
String |
|
String |
|
boolean |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
Array of up to 4 TaxAmount objects |
|
String |
|
Array of ItemizedDiscount objects |
|
String |
Format
Description
Merchant supplied code or stock keeping unit (SKU) relating to the item purchased.
Format
Description
The discount amount applied to this item. Amounts are given in the minor denomination.
Format
Description
A data element that can be used to pass proprietary data between two institutions.
Format
Description
The number of decimal places implied in the Quantity. If not present, zero is assumed.
Format
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.
Format
Description
Indicates the type of supply. Supported values are Goods (00) or Services (01).
Format
Description
The total amount for this item. Amounts are given in the minor denomination.
Format
Description
Indicates whether the tax amount is included in the total amount (GROSS) or excluded (NET).
Format
Description
The price for one unit of the product. Prices are given in the minor denomination.
OrderDate
OrderTime
PrivateData
Format
Description
A data element that can be used to pass proprietary data between two institutions.
PurchaseDate
PurchaseOrderNumber
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 |
---|---|
String |
|
String |
|
String |
|
boolean |
|
String |
|
String |
|
String |
Format
Description
An identification number used by the card acceptor with the tax authority in relationship to a specific tax amount.
Format
Description
A description of the purpose of the tax amount, for example 'Freight' or 'Alternate Tax'.
Format
Description
Indicates whether the tax amount is included in the final amount for this purchase or line item.
Format
Description
The tax rate. The number of decimal places is given by the RateExponent property.
Format
Description
The number of decimal placed implied in the tax rate. If this is omitted, the number of decimals is assumed to be zero.
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
TaxExempt
TotalAmount
Format
Description
The total purchase amount for this transaction. Amounts are given in the minor denomination.
TotalNonFuelAmount
Format
Description
The total amount (in the minor denomination) of this purchase transaction related to non-fuel items.
PrivateData
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
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
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
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 |
---|---|
String |
|
String |
|
Boolean |
|
Boolean |
|
Boolean |
|
Boolean |
|
Boolean |
eSocket.POS defines the following Name/Value pairs for this field:
Name | Value | Description |
---|---|---|
An XML string conforming to the Prompts DTD |
A set of prompts to be presented to the customer/operator. |
|
A numeric value indicating the number of line items that are present |
The number of line items present in the signature capture request. |
|
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. |
|
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. |
|
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 |
---|---|---|---|
A string value containing a TransArmor-encrypted data block |
The TransArmor-encrypted data block containing the track data destined for First Data. |
Request |
|
A string value containing TransArmor security level indicator |
The security level indicator of the TransArmor-encrypted data. |
Request/Response |
|
A string value containing TransArmor-encryption type |
The encryption type of the TransArmor-encrypted data. |
Request/Response |
|
A string value containing the TransArmor data encryption key ID |
The key ID of the TransArmor-encrypted data encryption type. |
Request/Response |
|
A string value containing the TransArmor token |
The value of the TransArmor token supplied by First Data. |
Request/Response |
|
A string value containing TransArmor token expiry date |
The value of the TransArmor token expiry date supplied by First Data. |
Request/Response |
|
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 |
---|---|
boolean |
|
boolean |
|
boolean |
|
boolean |
|
boolean |
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);
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);
Format
It will be designed so that an element’s Compress attribute can be set to TRUE to mark it to be compressed.
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
Format
Description
Contains the identifier for the EMV CA Public Key File. This field, if returned, will be specified as part of EspStructuredData.
Format
It will be designed so that an element’s Encrypt attribute can be set to TRUE to mark it to be encrypted.
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
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
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
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
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
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:
|
2 |
DCC Available |
Indicates whether a DCC offer has been retrieved successfully for this transaction. Valid values:
|
3 |
DCC Accepted |
Indicates whether the DCC offer has been accepted for this transaction. Valid values:
|
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
DccSrcCurrAlphaCode
DccSrcCurrMinorUnits
DccTgtCurrCode
DccTgtCurrAlphaCode
DccTgtCurrMinorUnits
DccProvider
DccRateSrc
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
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
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
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
DccCardAccptrId
DccTermId
EmvAmount
EmvAmountOther
Format
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
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
EmvApplicationPreferredNameInternational
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
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
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
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
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
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
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
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
EMV Tag ID
9F21
Description
Local time that the transaction was authorized in HHMMSS format.
EmvApplicationPriorityIndicator
EmvIssuerCountryCode
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
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
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:
|
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
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:
-
PassThruPanReference: Sensitive
-
PassThruVolatileP2peData: Sensitive and Persist until authorized
-
-
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 |
---|---|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
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
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.
Rank
Format
Description
Represents which set of logical devices the point of sale (POS) intends to communicate with.
RPS
RecurringPaymentIndicator
Format
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 |
Attribute |
Specifies the recurring amount. |
|
RecurringAmountPaymentType |
Attribute |
Specifies the recurring amount payment type. F - Fixed |
|
RecurringCycle |
Attribute |
Specifies the number of days, weeks, months, or years for each recurring payment cycle. |
|
RecurringInterestRate |
Attribute |
Specifies the interest rate. |
|
RecurringIteration |
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 |
Attribute |
Specifies the maximum recurring payment amount. |
|
RecurringMemberDefinedData |
Attribute |
Specifies the recurring member-defined data. |
|
RecurringPaymentCurrency |
Attribute |
Specifies the recurring payment currency. |
|
RecurringResponsibleEntity |
Attribute |
Specifies the recurring responsible entity. 0 - Issuer |
|
RecurringTenure |
Attribute |
Specifies the total number of iterations that will be applicable for the recurring payment. |
|
RecurringType |
Attribute |
Specifies the recurring type. A - Annually |
|
RecurringUniqueId |
Attribute |
Specifies the recurring unique ID. This value is used to uniquely identify each of the recurring or installment payments. |
|
RecurringValidationFlag |
Attribute |
Specifies the recurring validation flag 1 - Validated |
|
RecurringValidationReference |
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
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
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
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
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
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
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
SignaturePromptName
SignatureLineItemTextCount
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
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
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
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
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
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
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
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
Description
The total amount (in the minor denomination) of bar and in-room "mini-bar" items charged to the room.
LdAmountBillingAdjustment
Format
Description
The amount (in the minor denomination) of any additional charges incurred after the cardholder’s departure from the lodging facility.
LdAmountGiftShop
Format
Description
The total amount (in the minor denomination) of gift shop and speciality shop items charged to the room.
LdAmountLaundryAndDryCleaning
Format
Description
The total amount (in the minor denomination) of laundry and dry cleaning items charged to the room.
LdAmountOtherServices
Format
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
Description
The total amount (in the minor denomination) of phone calls charged to the room.
LdAmountRestaurantAndRoomService
Format
Description
The total amount (in the minor denomination) of restaurant and/or room service food charged to the room.
LdAmountRoomRate
Format
Description
The daily room charges (in the minor denomination), exclusive of taxes and fees.
LdAmountRoomTax
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
LdNameOfGuest
AvailableOfflineSpendingAmount
OfflineAccumulatorBalance
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
QRCodeTranId
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
StoreId
Memo
NetworkLabel
FinalAuthIndicator
Format
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
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 |
Attribute |
The name of the card product |
|
Element |
Details on Accounts that are associated with this card |
|
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 |
Attribute |
Type of Account |
|
Name |
Attribute |
Name of the Account |
|
EmvFallbackAllowed |
Attribute |
Indicates if fallback from EMV to magstripe is allowed |
|
DefaultPreauthAmountMsr |
Attribute |
Default pre-authorization amount allowed for magstripe transactions |
|
DefaultPreauthAmountEmv |
Attribute |
Default pre-authorization amount allowed for contact EMV transactions |
|
DefaultPreauthAmountCtls |
Attribute |
Default pre-authorization amount allowed for contactless transactions |
|
PinRequired |
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 |
Attribute |
Name of the extracted data |
|
Value |
Attribute |
Value of the extracted data |
|
Error |
Attribute |
Error message when data to be extracted is not present |
Type
Format
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 |
Name of the payee |
|
AddressLine1 |
First address line |
|
AddressLine2 |
Second address line |
|
AddressLine3 |
Third address line |
|
City |
City payee is located in. |
|
Region |
Region/state the payee’s city is located in. |
|
PostalCode |
Postal code of the payee’s city |
|
CountryCode |
3-letter ISO country code |
|
Phone |
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:
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).
NoteIn 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
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
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
IssuerId
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 |
---|---|
String |
|
String |
|
String |
|
String |
|
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
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
NetworkName
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
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
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 |
---|---|
String |
|
String |
TokenDescription
Format
Description
A description of a token returned in a response to a merchandise request.
TokenValue
TranSequenceNumber
Format
Description
A number that uniquely identifies a merchandise request transaction to the receiver.
Type
Format
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
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
CheckType
Format
Description
The type of check/cheque that was tendered.
P | Personal |
---|---|
L |
Payroll |
B |
Business |
G |
Government |
K |
Bank |
DriversLicenseNr
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
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 |
Transit Symbol |
T |
|
On-Us Symbol |
U |
||
Amount Symbol |
$ |
||
Dash Symbol |
- |
||
CMC-7 |
SI |
A |
|
SII |
B |
||
SIII |
C |
||
SIV |
D |
||
SV |
E |
For example, a MICR line from a USA personal check is shown here:
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
|
MICRKeyedOrScanned
Format
Description
Indicates if the magnetic ink character recognition (MICR) data is keyed or scanned.
0 | - Keyed |
---|---|
1 |
- Scanned |
DriversLicenseDateOfBirth
DriversLicenseKeyedOrScanned
Format
Description
Indicates if the driver’s license information was keyed or scanned.
0 | - Keyed |
---|---|
1 |
- Scanned |
DriversLicenseExpirationDate
MICRLineFormatCode
CustomerName
Format
Description
Name of the customer (consisting typically of first name, middle initial and last name), as found on the check.
CustomerFirstName
CustomerLastName
CustomerMiddleInitial
CustomerInitials
CustomerPhoneNumber
CustomerAddress
CustomerCity
CustomerState
CustomerZip
CheckIssuedDate
TruncationTransactionID
MICRSequenceNr
TruncationIndicator
ServiceCharge
Format
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
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
Description
The total amount of all credit transactions (in the settlement currency), other than reversals, processed since the last settlement cutover
CreditsReversalAmount
Format
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
Description
The total amount of all debit transactions (in the settlement currency), other than reversals, processed since the last settlement cutover
DebitsReversalAmount
Format
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
Amount
Format
Description
The net settlement amount. Amounts are given in the minor denomination of the settlement currency.
Sign
NumberOfCredits
Format
Description
The total number of credit transactions, other than reversals, processed since the last settlement cutover.
NumberOfCreditsReversal
Format
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
Description
The total number of debit transactions, other than reversals, processed since the last settlement cutover.
NumberOfDebitsReversal
Format
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
Description
The total number of authorization transactions processed since the last settlement cutover.
NumberOfInquiries
SettlementCurrencyCode
Format
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
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 |
---|---|
String |
|
String |
|
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.
|
Optionally indicates the type of update which is underway. Standard values currently include:
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 |
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. |
|
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 |
|
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:
|
The following are possible responses:
Examples:
|
|
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.
|
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.
|
The data string associated with this event is the TransactionId of the transaction being cancelled. |
n/a |
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 |
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:
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.
|
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:
|
Possible responses are:
|
|
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 |
eSocket.POS (device driver) |
A check has been inserted into a check reader. |
None. |
n/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:
Examples:
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:
|
'MSR' - retry using magnetic stripe reader. 'ICC' - retry using smartcard reader. 'CLESS' - retry using contactless smartcard reader. |
n/a |
POS application |
Checks whether there is a card present in the reader.
|
None. |
A code which may be one of the following:
|
|
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).
|
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.
Also see UNSOLICITED_CARD_READ and ENCRYPTED_UNSOLICITED_CARD_READ.
|
The content of the three magnetic stripes, separated by the | character, in the order of <Track1> | <Track2> | <Track3> . |
n/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. |
|
eSocket.POS (generic) |
Notifies the POS that the dynamic currency conversion (DCC) offer has been accepted by the cardholder. |
None. |
n/a |
|
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.
|
Error description if available. |
n/a |
DEVICE_OFFLINE (event) |
eSocket.POS (device driver) |
Notifies the POS that the device has gone offline.
|
Device information formatted into delimited property name and value pairs, in the format: <name>=<val>;<name2>=<val2>;… The following properties are supported:
|
n/a |
DEVICE_ONLINE (event) |
eSocket.POS (device driver) |
Notifies the POS that the device has come online.
|
Device information formatted into delimited property name and value pairs, in the format: <name>=<val>;<name2>=<val2>;… The following properties are supported:
|
n/a |
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:
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:
|
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.
|
|
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.
|
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.
|
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.
|
n/a |
DEVICE_SERIAL_NR_STATUS (event) |
eSocket.POS (generic) |
This event can be raised either:
The status reports on whether access will be allowed to the device to process financial data.
|
The validation status of a device in the format: <name>=<val>;<name2>=<val2>;… The following properties are provided:
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.
|
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.
Also see AUTO_DEVICE_UPDATE. |
Optionally indicates the type of update required. Standard values currently include:
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:
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.
|
A completion code which may be one of the following:
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.
|
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.
|
None. |
A completion code which may be one of the following:
|
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:
Also see UNSOLICITED_CARD_READ and CLEAR_UNSOLICITED_CARD_READ.
<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 |
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.
|
None. |
Device information is returned in the same format as structured data (field 127.22), for example:
Device information returned is driver specific.
|
|
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.
|
None. |
A code indicating whether the POS attendant has successfully obtained the payment media and (if required) the card reader. Possible values are:
|
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
For example, "PaymentInterrupt=DefaultCard;Amount=000000000300;PAN=123456******7890" |
Updated transaction amount in 12 digit minor denomination. For example, "000000000330" |
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:
|
Possible responses are:
|
|
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:
3. lineItemDisplay:tranResult - To display the transaction results on the PED. The transaction result data should be specified in the following format:
|
||
LINE_ITEM_DISPLAY (callback) Continued |
POS application |
4. lineItemDisplay:end - To end the line item session. The following optional data element may be specified:
|
||
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
Examples:
|
The POS will send back a response containing one of the following
|
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:
|
A completion code which may be one of the following:
|
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:
Example data:
|
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:
|
The following data elements in name=value pair format, separated by semi-colons:
|
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
For example, "selectedOpc=CCCCC:long3;amount=000000010000;currencyCode=710;" |
The POS will send back a response containing one of the following
|
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
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
|
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:
Examples:
|
n/a |
eSocket.POS (device driver) |
Initiates the Pay At Table workflow.
|
The following data elements should be provided in name=value pair format, separated by semi-colons:
Example:
|
The following are possible responses:
Examples:
|
|
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.
Also see PERMIT_FALLBACK_TO_PKE. |
None. |
A code indicating whether fallback to magstripe should be permitted, as follows:
|
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.
|
None. |
A code indicating whether fallback to PKE should be permitted, as follows:
|
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.
Also see PERMIT_FALLBACK_TO_PKE. |
None. |
A code indicating how the transaction should proceed, as follows:
|
PIN_BYPASS (event) |
POS application |
Attempts to bypass PIN entry and allow another cardholder verification method, such as signature.
|
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:
|
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.
|
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.
|
None. |
Any response to the callback will result in processing resuming. |
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. |
|
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 :
For example, "Enable ; send0600Msg : true ; scanAheadMessage : Please swipe card ; tranType : 00"; readOnly : true
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:
|
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:
|
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:
|
n/a |
PRINT_FORMATTED_ RECEIPT (callback) |
eSocket.POS (custom component) |
Prompts the POS to print a receipt using the formatted data provided.
|
A formatted string to be used for directly printing on the receipt. |
A success indicator which may be one of the following:
|
PRINT_UNFORMATTED_ RECEIPT (callback)* |
eSocket.POS (custom component) |
Prompts the POS to print a receipt using the data elements provided.
|
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:
|
A success indicator which may be one of the following:
|
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
|
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:
|
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:
|
Possible responses are: Either:
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:
|
RESET_DEVICE (event or callback) |
POS application |
Reboots the device firmware and software.
|
None. |
A completion code which may be one of the following:
|
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.
|
A completion code which may be one of the following:
|
n/a |
SAFQ_LIMITS_STATE_CHANGED (event) |
eSocket.POS |
The eSocket.POS monitoring system detected the store and forward queue (SAFQ) limits state change.
|
The new state which may be one of the following:
|
n/a |
SAF_QUEUE_SIZE (event) |
eSocket.POS (custom component) |
Returns the number of undelivered transactions in the eSocket.POS store-and-forward queue.
|
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:
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> .
|
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 |
eSocket.POS (generic) |
Informs the POS that eSocket.POS will attempt to capture the cardholder’s signature. |
None. |