- 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
- Response Parameters
- Card On File
- Chargeback
- Result Codes
- Payment Methods
- Transaction Flows
- Regression Testing
- Data Retention Policy
- Release Notes
- API Reference
- Support
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. |
n/a |
|
PARTIAL_APPROVAL |
POS application |
Allows the POS to approve or decline the Partial Approval Confirmation. See the eSocket.POS User Guide for further information. |
This callback requests confirmation from the POS for the partially approved transaction amount from the host. Eg of the callback raised/event data is as follows : Transaction partially approved for amount (partially approved amount) Accept ? |
Possible responses are:
|
Prompt events
Prompt events are intended to notify the POS about a change to the customer display. However (if the POS Callback Device is used) these events may in places follow a change in the POS display and not the customer display, in which case they are not so useful. These events are all raised by the standard eSocket.POS product. Note that the Description field describes the standard eSocket.POS component (if any) which will invoke the event.
Event ID | Event Data | Description |
---|---|---|
PROMPT_ACCOUNT |
List of account types and names, comma separated. for example, 10Savings,20Credit |
Indicates that the customer/operator has been presented with a list of accounts and has been requested to select one.
|
PROMPT_ADDRESS |
n/a |
Indicates that the customer/operator has been prompted to enter the customer address.
|
PROMPT_AMOUNT |
The maximum allowed amount for this account. |
Indicates that the customer/operator has been prompted to enter the amount for this card transaction.
|
PROMPT_AUTHORIZATION_NUMBER |
n/a |
Indicates that the customer/operator has been prompted for the authorization number provided by the authorizing agency for this transaction.
|
PROMPT_BALANCE_LIST |
n/a |
Indicates that the customer/operator has been shown a list of balances.
|
PROMPT_BARCODE |
n/a |
Indicates that the customer/operator has been prompted to scan barcode.
|
PROMPT_CARD_SEQUENCE_NUMBER |
n/a |
Indicates that the customer/operator has been prompted for the card’s sequence number.
|
PROMPT_CASHBACK_AMOUNT |
Maximum allowable cashback amount. |
Indicates that the customer/operator has been prompted to enter a cashback amount.
Also see PROMPT_IS_CASHBACK_REQUIRED. |
PROMPT_CASHBACK_SELECTION |
The data will consist of the following named parameters: Name : fixedCashbackOptions Description : Specifies the list of cashback amounts that are available for selection on the PED at the fixed denomination cashback prompt. Value Format : Amount1,Amount2,AmountN Name : allowNumericEntryFallback Description : Indicates whether the customer may choose to enter a custom cashback amount via a numeric entry screen (i.e. whether the 'Other' option is available for selection). Value Format : 0 - Disallowed. 1 - Allowed. Format The above named parameters are specified in the format below. Parameters are delimited by the ';' (semi-colon) character, and within a parameter, the parameter name and parameter value are delimited by the '=' (equals) character. Example allowNumericEntryFallback=1;fixedCashbackOptions=100000,80000,60000,50000,30000,8000 |
Indicates that the customer/operator has been prompted to select a cashback amount.
Also see PROMPT_IS_CASHBACK_REQUIRED. |
n/a |
Indicates that the customer/operator has been prompted to enter the check account number.
|
|
n/a |
Indicates that the customer/operator has been prompted to enter the check institution code.
|
|
PROMPT_CHECK_LIMIT |
n/a |
Indicates that the customer/operator has been prompted to enter the check/cheque guarantee card limit.
|
n/a |
Indicates that the customer/operator has been prompted to enter the check number.
|
|
n/a |
Indicates that the customer/operator has been prompted to insert the check into the check reader.
|
|
n/a |
Indicates to operator that a check read error occurred.
|
|
n/a |
Indicates to the operator that the check printing is in progress.
|
|
Check number, account number and transit number, comma separated. |
Indicates that the customer/operator has been prompted to confirm the check data for this transaction.
|
|
PROMPT_CONFIRM_EFFECTIVE_DATE |
Effective date - YYMM |
Indicates that the customer/operator has been prompted to confirm the card’s effective date.
|
PROMPT_CONFIRM_EXPIRY_DATE |
Expiry date - YYMM |
Indicates that the customer/operator has been prompted to confirm the card’s expiry date.
|
PROMPT_CONFIRM_GRATUITY_AMOUNT |
Gratuity amount |
Indicates that the customer/operator has been prompted to confirm the gratuity amount entered from the POS. |
PROMPT_CONFIRM_MERCHANDISE_USER_ID |
The merchandise type and merchandise ID in the format: <merchandise_type>,<merchandise_id> For example, "MSISDN,0122345677834" |
Indicates that the merchandise item User ID must be confirmed, for example the MSISDN (cell phone number).
See the Prepay component in the eSocket.POS User Guide for further information. |
Amount and account type, comma separated. for example, 000000010000,10 On a transaction with an accepted or declined dynamic currency conversion (DCC) offer, the alpha currency code of the transaction will also included. for example, 000000010000,10,USD |
Indicates that the customer/operator has been prompted to confirm the transaction details (presented in the parameter data).
|
|
Amount and application, comma separated. for example, 000000010000,Visa On a transaction with an accepted or declined dynamic currency conversion (DCC) offer, the alpha currency code of the transaction will also included. for example, 000000010000,Visa,USD |
Indicates that the customer/operator has been prompted to confirm the amount and application used for the transaction.
|
|
PROMPT_CORRECT_PRINTER_ERROR |
The printer error type, which may be one of:
|
Indicates that a printer error needs to be corrected.
|
PROMPT_CVV2 |
The CVV2 length in bytes. |
Indicates that the customer/operator has been prompted to enter the card’s CVV2.
|
PROMPT_EFFECTIVE_DATE |
n/a |
Indicates that the customer/operator has been prompted for the card’s effective date.
|
The currency conversion information in the format: <name>=<val>|<name2>=<val2>|… The following properties are provided (in their corresponding order):
For example, CommRate=0.030456|ExpTimestamp=20170311T15:35|MargRate=0.102345|Provider=FEXCO|Rate=0.123456|RateSrc=US Fed Reserve|SrcAmnt=000000010000|SrcCurr=USD|SrcAmntDec=100.00|TgtAmnt=000000001234|TgtCurr=ZAR|TgtAmntDec=12.34|Timestamp=20160311T15:35 As indicated above, some of these properties are optional as some DCC providers may not provide all of the currency conversion information. |
Indicates that the cardholder has been prompted to accept or decline a dynamic currency conversion (DCC) offer.
|
|
PROMPT_EMBOSSED_DIGITS |
The last 4 digits of the card number embossed on the card. |
Indicates that the customer/operator has been prompted to enter the card embossed digits.
|
PROMPT_EMV_APPLICATION_SELECTION |
Comma separated list of the selection of EMV application names. For example, Visa, MasterCard |
Indicates that the customer/operator has been prompted to select an EMV application.
|
PROMPT_EXPIRY_DATE |
n/a |
Indicates that the customer/operator has been prompted for the card expiry date.
|
PROMPT_EXTENDED_PAYMENT_PERIOD |
Comma separated list of available extended payment periods. For example, 06,09,12,18 |
Indicates that the customer/operator has been prompted to select an extended payment period from the list presented in the parameter.
|
The name of the prompt sent to the PED. |
Indicates that a prompt has been presented to the customer/operator.
See the Prompt component in the eSocket.POS User Guide for further information. |
|
PROMPT_GET_MERCHANDISE_CARD_SWIPE |
The merchandise type. |
Prompts for a merchandise card swipe.
See the Prepay component in the eSocket.POS User Guide for further information. |
PROMPT_GET_MERCHANDISE_USER_ID |
The merchandise type for which the User ID is required. |
Indicates that the merchandise item User ID must be entered, for example the MSISDN (cell phone number).
See the Prepay component in the eSocket.POS User Guide for further information. |
PROMPT_GRATUITY_AMOUNT |
Transaction amount; Array of prompt options; Is custom gratuity amount allowed flag. |
Indicates that the customer/operator has been prompted to select or enter a gratuity amount. The customer/operator can be provided with an option to enter the custom gratuity amount if the Boolean flag is set to true.
|
n/a |
Indicates that the customer/operator has been prompted to insert a card into the card reader. This event is replaced by PROMPT_PRESENT_CARD when the Card Data Input Capability indicates that a contactless card reader is in use.
|
|
PROMPT_IS_CASHBACK_REQUIRED |
n/a |
Indicates that the customer/operator has been prompted to indicate whether cash back is desired.
Also see PROMPT_CASHBACK_AMOUNT. |
PROMPT_IS_EXTENDED_PAYMENT_REQUIRED |
n/a |
Indicates that the customer/operator has been prompted to indicate whether extended payment is desired.
|
PROMPT_MERCHANDISE_CARD_SWIPE |
Indicates that
|
|
PROMPT_PAN |
n/a |
Indicates that the customer/operator has been prompted to enter the PAN manually.
|
n/a |
Indicates that the customer/operator has been prompted to enter their PIN. |
|
n/a |
Indicates that the customer/operator has been prompted to re-enter their PIN.
|
|
PROMPT_POSTAL_CODE |
n/a |
Indicates that the customer/operator has been prompted to enter their postal code.
|
PROMPT_PRESENT_CARD |
n/a |
Indicates that the customer/operator has been prompted to present their card. This event is used instead of PROMPT_INSERT_CARD when the Card Data Input Capability indicates that a contactless card reader is in use.
|
n/a |
Indicates that the eSocket.POS is ready to receive a transaction by means of a card read (EMV or swipe). In other words, the PreSwipe component is listening for a card read.
|
|
n/a |
Indicates that the eSocket.POS is ready to receive a transaction by means of a card swipe. I.e. the Prepay pipeline component is listening for a card swipe.
|
|
The ISO response code received in the transaction response. |
Indicates that the reversal outcome has been reported to the customer/operator.
|
|
PROMPT_SECURE_DATA_INPUT |
n/a |
Indicates that the customer/operator has been prompted to enter secure data.
|
n/a |
Indicates that the customer/operator has been prompted to sign the signature capture device.
|
|
n/a |
Indicates that the customer/operator has been prompted to sign the slip.
|
|
n/a |
Indicates that the customer/operator has been prompted to swipe their card.
|
|
The ISO response code received in the transaction response. |
Indicates that the success or failure of the transaction has been reported to the customer/operator.
|
|
n/a |
Indicates that the customer/operator has been advised that the transaction is being processed.
|
|
PROMPT_VERIFY_SIGNATURE |
n/a |
Indicates that signature verification is required.
|
PROMPT_GET_OPC_SELECTION |
The list of options, comma separated. Note that the first element is the original card name.for example, MasterCard,Opc1,Opc2 |
Indicates that the customer/operator has been prompted to select an OPC from the list (presented in the parameter data).
|
PROMPT_GET_OPC_CONFIRMATION |
The currency (ISO 8583 field 49), amount (ISO 8583 field 4) and OPC label, comma separated.for example, 826,000000200000,Opc2 |
Indicates that the customer/operator has been prompted to confirm the selected OPC (presented in the parameter data).
|
PROMPT_DISPLAY_BARCODE |
n/a |
Indicates that an invalid barcode display request was sent to a device.
|
AUTHORIZE callback event data
The AUTHORIZE callback request and response data is supplied as a string of key-value pairs with the values inside single quotes, and the pairs separated by spaces, as illustrated in the following example:
_Key1='value1' Key2='value2' ... KeyN='valueN'_
Request data
The Callback Sink will provide some or all of the following keys in the authorization callback:
-
CardNumber
-
Track2
-
ExpiryDate
-
CardSequenceNumber
-
ServiceRestrictionCode
-
PanEntryMode
-
Track1
-
EmvAmount
-
EmvAmountOther
-
EmvApplicationIdentifier
-
EmvApplicationInterchangeProfile
-
EmvApplicationTransactionCounter
-
EmvApplicationUsageControl
-
EmvApplicationVersionNumber
-
EmvAuthorizationResponseCode
-
EmvCryptogram
-
EmvCryptogramInformationData
-
EmvCvmResults
-
EmvCvmList
-
EmvInterfaceDeviceSerialNumber
-
EmvIssuerActionCodeDefault
-
EmvIssuerActionCodeDenial
-
EmvIssuerActionCodeOnline
-
EmvIssuerApplicationData
-
EmvIssuerScriptResult
-
EmvTerminalApplicationVersionNumber
-
EmvTerminalCapabilities
-
EmvTerminalCountryCode
-
EmvTerminalType
-
EmvTerminalVerificationResult
-
EmvTransactionCurrencyCode
-
EmvTransactionDate
-
EmvTransactionStatusInformation
-
EmvTransactionType
-
EmvUnpredictableNumber
-
EmvTransactionCategoryCode
-
EmvTransactionSequenceCounter
Response Data
The POS may provide values for the following keys in the response:
-
ResponseCode (mandatory)
-
EmvIssuerAuthenticationData
-
EmvIssuerScriptTemplate1
-
EmvIssuerScriptTemplate2
-
AuthorizationNumber
-
PrivateData
DATA_REQUIRED event data
The POS Callback Device provides a set of logical devices which can be used to 'call back' to the POS in order to retrieve required data. These 'call backs' take the form of DATA_REQUIRED callbacks, where the event data specifies the data required.
DATA_REQUIRED callbacks may also occasionally be raised by custom entities in order to request data from the POS.
Note that, in order to receive the callback, the entity which raises the callback must be configured. For example, if the POS Callback Device keypad raises the event then
postilion.esocketpos.devicemanager.PosCallbackDevice must be configured as the 'Keypad' in the eSocket.POS deployment.
See the eSocket.POS User Guide for detailed information about the POS Callback Device.
The table below describes the expected response data. Alternatively, if the POS returns the string "CANCEL" in the response, this will have the effect of declining the transaction with a response code of 17 (Customer Cancellation).
Note that the Description describes the standard eSocket.POS component (if any) which will invoke the event with the specified event data. See the eSocket.POS User Guide for further information on each pipeline component.
Note that, where possible, the callback event data matches an eSocket.POS property name.
The events have been grouped alphabetically per Source.
Callback event data | Source | Format of expected response data | Description |
---|---|---|---|
Account(<acc_type 1><acc_name 1>,…,<acc_type n><acc_name n>) Where:
For example, Account(10Savings,30Credit) |
POSCallbackDevice (Keypad) |
n2 |
The ISO account type of the selected account.
|
Address |
POSCallbackDevice (Keypad) |
ans..20 |
When used in conjunction with the Postal Code typically just the 1st line of the address is needed. A typical use of this event is for an internet order transaction.
|
Amount |
POSCallbackDevice (Keypad) |
n12 |
The transaction amount in the minor denomination. |
CardNumber |
POSCallbackDevice (Keypad) |
n..19 |
NOTE:: This event requires the PAN pipeline component to be configured in the request pipeline. |
CardSequenceNumber |
POSCallbackDevice (Keypad) |
n3 (Pad with leading zeros if required). |
NOTE:: This event requires the CardSeqNr pipeline component to be configured in the request pipeline. |
CashbackAmount(<max>) Where
|
POSCallbackDevice (Keypad) |
n..12 |
The cashback amount in minor currency units. Zero or empty string if no cashback is required.
|
CashbackSelection(<parameters>) Where
|
POSCallbackDevice (Keypad) |
n..12 |
The cashback amount in minor currency units, or zero if no cashback is required. If numeric fallback is allowed, and the user selected the 'other' option, an empty (zero-length) string should be provided by the POS in the callback response.
|
CheckNr |
POSCallbackDevice (Keypad) |
n..6 |
The check/cheque number in a check verification or check guarantee message.
|
ChequeAccountNumber |
POSCallbackDevice (Keypad) |
ans16 |
The check/cheque account number in a check verification or check guarantee message.
|
ChequeInstitutionCode |
POSCallbackDevice (Keypad) |
ans8 |
The check/cheque institution code in a check verification or check guarantee message.
|
ChequeLimit |
POSCallbackDevice (Keypad) |
n..12 |
The check/cheque limit in minor currency units.
|
Cvv2(<length>) Where
|
POSCallbackDevice (Keypad) |
n3 or n4 if for American Express cards. |
NOTE:: This event requires the CVV2 pipeline component to be configured in the request pipeline. |
EmbossedDigits |
POSCallbackDevice (Keypad) |
n4 |
The last four digits of the PAN embossed on the card.
|
ExpiryDate |
POSCallbackDevice (Keypad) |
n4, YYMM |
NOTE:: This event requires the Expiry Date pipeline component to be configured in the request pipeline. |
ExtendedPaymentPeriod(<periods>) Where <periods> is a comma separated list of extended payment periods (in months) which can be selected for extended payment. For example, ExtendedPaymentPeriod(6,12,24,36) |
POSCallbackDevice (Keypad) |
n2 |
The number of months that the cardholder prefers to pay for this item if permitted by the card issuer. Empty or '00' if extended payment is not required.
|
IsExtendedPaymentRequired |
POSCallbackDevice (Keypad) |
"TRUE" or "FALSE" |
"TRUE" if extended payment is required; "FALSE" or an empty string if extended payment is not required.
|
IsPrinterErrorCorrected(<error_type) Where the printer error type may be one of:
|
POSCallbackDevice (Keypad) |
"TRUE" or "FALSE" |
"TRUE" if the printer error has been corrected; "FALSE" otherwise.
|
PostalCode |
POSCallbackDevice (Keypad) |
an..9 |
Postal or ZIP code.
|
SignatureVerification |
POSCallbackDevice (Keypad) |
n1 |
Signature Verification code which is one of the following:
|
StartDate |
POSCallbackDevice (Keypad) |
n4, YYMM |
NOTE:: This event requires the EffectiveDate pipeline component to be configured in the request pipeline. |
UserId |
POSCallbackDevice (Keypad) |
ans..12 |
NOTE:: This event requires the Prepay pipeline component to be configured in the request pipeline. |
PinData(<pan>,<amount>,<acc_type>) Where:
|
POSCallbackDevice (Pinpad) |
an16 |
The 64-bit encrypted PIN data, expressed in 16 hexadecimal characters.
|
PinKeySequenceNr |
POSCallbackDevice (Pinpad) |
an16 |
The 8-byte DUKPT key sequence number, expressed in 16 hexadecimal characters.
|
MerchandiseCardSwipe(<merchandise_type>) For example, MerchandiseCardSwipe(TELEPHONE PREPAY) Where: <merchandise_type > is the merchandise type, for instance: 'TELEPHONE PREPAY' |
POSCallbackDevice (Card Reader) |
ans..30 |
NOTE:: This event requires the Prepay pipeline component to be configured in the request pipeline. |
Track1 |
POSCallbackDevice (Card Reader) |
ans..76 |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813, including field separators but excluding the begin sentinel, end sentinel, and longitudinal redundancy check characters.
|
Track2 |
POSCallbackDevice (Card Reader) |
z..37 |
The information encoded on Track 2 of the magnetic stripe as defined in ISO 7813, including field separators but excluding the begin sentinel, end sentinel, and longitudinal redundancy check characters. The field separator can be either a "=" or a "D" character.
|
Track3 |
POSCallbackDevice (Card Reader) |
n..104 |
The information encoded on Track 3 of the magnetic stripe, excluding the begin sentinel, end sentinel, and longitudinal redundancy check characters.
|
PosCallbackDeviceV2
POS Callback Device callbacks
The POS Callback Device provides a set of logical devices which can be used to 'call back' to the POS in order to send a command to the device. Each supported device command is implemented by a callback event ID in the form <LogicalDevice><Command>_ , e.g. CardReader_GetCardSwipe - as indicated in the table below.
NOTE:
For the POS to receive a callback, the entity which raises the callback must be configured.
For example, if the POS Callback Device keypad raises an event, then postilion.esocketpos.devicemanager.PosCallbackDeviceV2 must be configured as the keypad in eSocket.POS.
Furthermore, the POS must register for each individual event ID it wants to receive callbacks for. See the eSocket.POS User Guide for detailed information about the POS callback device.
The following table lists the event IDs corresponding to the supported logical devices and commands. The event data and response data are in JSON format. Alternatively:
-
If the POS returns the string 'CANCEL' in the response, the transaction will be declined with a response code of 17 (Customer Cancellation).
-
If the POS returns the string 'ERROR' in the response, the transaction will be declined with a response code of 96 (Remote Device Failure).
Callback event ID | Expected event data | Expected response data | Response data format | Description |
---|---|---|---|---|
CardReader_GetCardSwipe |
N/A |
\{"track1":" <track1_data> ","track2":" <track2_data> ", "track3":" <track3_data> "} Where:
|
track1 data is ans..76 track2 data is z..37 track3 data is n..104 |
Retrieves the track data from a card swipe. |
CardReader_GetMerchandiseCardSwipe |
\{"merchandiseType":" <merchandise_type> "} For example, \{"merchandiseType":"TELEPHONE_PREPAY"} |
" <track_data> " Where:
|
ans..30 |
Retrieves the track data from the merchandise card swipe. |
Display_DisplayPleaseWait |
N/A |
N/A |
N/A |
Sends the command to display "Please Wait" on the display. |
Display_DisplayWelcome |
N/A |
N/A |
N/A |
Sends the command to display "Welcome" on the display. |
Keypad_GetAccount |
\{"accounts":[
\{"type":" <type 1> ", "name":" <name 1> "}, … Where:
For example, \{"accounts":[\{"type":"10","name":"Savings"}, \{"type":"30","name":"Credit"}]} |
" <account_type> " Where:
|
n2 |
Retrieves the account type from a list of accounts sent to the POS in the event data. |
Keypad_GetAddress |
N/A |
" <address> " For example, "2388 Lake Ave" |
ans20 |
When used in conjunction with the postal code, typically just the first line of the address is needed. A typical use case is for an internet order transaction. |
Keypad_GetAmount |
\{"maxAmount":" <max_amount> "} Where:
|
" <amount> " Where:
|
n12 |
Retrieves the transaction amount based on a set maximum amount. |
Keypad_GetCardSequenceNumber |
N/A |
" <card_sequence_number> " Where:
|
n3 |
Retrieves the Card Sequence Number. |
Keypad_GetCashbackAmount |
\{"maxCashbackAmount":" <max_cashback_amount> "} For example, \{"maxCashbackAmount":"10000"} |
" <cashback_amount> " For example, "5000" |
n..12 |
Retrieves the cashback amount based on the maximum cashback amount allowed. The amounts will be in minor denomination. |
Keypad_GetCashbackAmount |
NOTE: There are two instances of Keypad_GetCashbackAmount documented in this table, each with different parameters. You only need to register it once to be able to listen for both. \{"promptOptions":[ Where:
For example, \{"options":[\{"optionText":"$50.00", "optionResult":"5000"}, \{" optionText":"$100.00", "optionResult":"10000"}], "allowNumericEntryFallback":true} |
" <cashback_amount> " For example, "5000" |
n..12 |
Retrieves the cash back amount given a list of possible cash back options. The amounts are in minor denomination. |
Keypad_GetCheckNumber |
N/A |
" <check_number> " For example, "9201" |
n..6 |
Retrieves the check number. |
Keypad_GetCheckAccountNumber |
N/A |
" <check_account_number> " For example, "1234567890123456" |
ans16 |
Retrieves the check account number. |
Keypad_GetCheckInstitutionCode |
N/A |
" <check_institution_code> " For example, "12345678" |
ans8 |
Retrieves the check institution code. |
Keypad_GetCheckLimit |
N/A |
" <check_limit> " For example, "50000" |
n..12 |
Retrieves the check limit in minor denomination. |
Keypad_GetCvv2 |
N/A |
" <cvv2> " For example, "123" |
n3 or n4 if for American Express cards. |
Retrieves the CVV2 of a card. |
Keypad_GetEffectiveDate |
N/A |
" <effective_date> " For example, "2101" |
n4, YYMM |
Retrieves the effective or start date. |
Keypad_GetEmbossedDigits |
N/A |
" <embossed_digits> " For example, "1111" |
n4 |
Retrieves the last four digits of the PAN embossed on the card. |
Keypad_GetExpiryDate |
N/A |
" <expiry_date> " For example, "2701" |
n4, YYMM |
Retrieves the card’s expiration date. |
Keypad_GetExtendedPaymentPeriod |
\{"periods":[" period 1 ",…," period n "]} Where:
For example, \{"periods":["6", "12", "24", "36", "72"]} |
" <extended_payment_period> " For example, "36" |
n2 |
Retrieves selected extended payment periods from a list of available extended payment periods. |
Keypad_GetGratuityAmount |
\{"transactionAmount":" <transaction_amount> ", "promptOptions":[\{"optionText":" <text 1> ", "optionResult":" <result 1> "},…\{"optionText":" <text n> ", "optionResult":" <result n> "}], "allowCustomGratuity": <allow_custom_gratuity> } Where:
For example, \{"transactionAmount":10000, "promptOptions":[\{"optionText":"$10.00", "optionResult":"1000"}, \{"optionText":"$20.00", "optionResult":"2000"}], "allowCustomGratuity":false} |
" <gratuity_amount> " For example, "1000" |
n12 |
Retrieves the gratuity amount selected from the list of gratuity prompt options. |
Keypad_GetMerchandiseUserID |
\{"merchandiseType":"<merchandise_type>"} For example, \{"merchandiseType":"TELEPHONE_PREPAY"} |
" <user_id>" For example, "900001" |
ans..12 |
Retrieves the user ID for the given merchandise type. |
KeyPad_GetPan |
N/A |
" <pan> " For example, "1234567890123456789" |
n..19 |
Retrieves the PAN. |
Keypad_GetPostalCode |
N/A |
" <postal_code> " For example, "85142" |
an..0 |
Retrieves the postal code. |
Keypad_GetSignatureVerification |
N/A |
<signature_verification_code> Where <signature_verification_code> is one of the following:
|
n1 |
Retrieves the signature verification code. |
Keypad_IsExtendedPaymentRequired |
N/A |
<is_extended_payment_required> For example, true |
true or false |
Retrieves a Boolean value indicating whether extended payment is required. |
Keypad_IsPrinterErrorCorrected |
\{"errorType": <error_type> } Where <error_type> is one of the following:
|
<error_corrected> For example, true |
true or false |
Retrieves a Boolean value indicating whether the printer error has been corrected for the given error type. |
Pinpad_CalculateMac |
\{"encMacSessionKey":" <session_key> ", "macData":" <mac_data> "} Where:
|
" <mac> " Where:
|
an |
Calculates the MAC value given the encrypted session key and the MAC data. |
Pinpad_CalculateMacV2 |
\{"macData": "<mac_data>"} Where: <mac_data> is the data for which the MAC should be calculated. |
" <mac> " Where:
|
an |
Calculates the MAC value for the MAC data. |
Pinpad_DoKeyChange |
\{"keyData":" <key> "} Where:
|
" <response_code> " Where:
|
an |
Changes the encryption key on the PIN pad and returns the response code (success or failure). |
Pinpad_GetKeySequenceNumber |
N/A |
" <sequence_number> " Where:
|
an16 |
Retrieves the Key Sequence Number from the PIN pad. |
Pinpad_GetPinData |
\{"pan":" <pan> ", "amount":" <amount> ", "accountType":" <account_type> "} Where: * <pan> is the card account number, format n..19. * <amount> is the transaction amount in the minor denomination, format n12. * <account_type> is the ISO account type, format n2. |
" <pin_data> " Where:
|
an16 |
Creates the encrypted PIN data for the given PAN, amount, and account type. |
Pinpad_LoadPinSessionKey |
\{"pinSessionKey":" <session_key> "} Where: * <session_key> is the new PIN session key to load on the device. |
N/A |
N/A |
Loads a new PIN session key on the device. |
Pinpad_LoadMacSessionKey |
\{"macSessionKey":" <session_key> "} Where:
|
N/A |
N/A |
Loads a new MAC session key on the the device. |
Pinpad_VerifyMac |
\{"encMacSessionKey":" <session_key> ", "macData":" <mac_data> "} Where:
|
" <value> " Where:
|
an |
Verifies the MAC for the given session key and MAC data and returns the value. |
SmartCardReader_GetDeviceInfo |
N/A |
This method will return the device information in the Device Info JSON Structure section that follows. |
See the Device Information Field Description section for the field descriptions. |
Retrieves the device info for the smart card reader. |
SmartCardReader_GetEmvKernelVersion |
N/A |
" <version> " Where:
|
ans |
Retrieves the EMV Kernel Version. |
Device information JSON structure
The device information returned from the POS must use the following JSON structure.
{ "cap" : ["atm", "pos", "cardreader", "keypad", "printer", "display", "checkreader", "pinpad", "sigcap"], "hardware" : { "compliance" : [{ "assigner" : "assigner", "effectiveDate" : "effectiveDate", "expirationDate" : "expirationDate", "issuer" : "issuer"},... "reference" : "reference", "type" : "type", "version" : "version"},... ], "date" : "date", "ipAddress" : "ipAddress", "macAddress" : "macAddress", "manufacturer" : "manufacturer", "manufacturingSerial" : "manufacturingSerial", "modelName" : "modelName", "modelNumber" : "modelNumber", "serial" : "serial", "series" : "series", "version" : "version", "hwId" : "hwId" }, "id" : "id", "properties" : [{ "name" : "name", "value" : "value"},... ], "software" : { "module" : [{ "build" : "build", "compliance" : [{ "assigner" : "assigner", "effectiveDate" : "effectiveDate", "expirationDate" : "expirationDate", "issuer" : "issuer"},... "reference" : "reference", "type" : "type", "version" : "version"},... ] "date" : "date", "hash" : "hash", "majorVersion" : "majorVersion", "minorVersion" : "minorVersion", "name" : "name", "provider" : "provider", "type" : "type", "version" : "version"},... ], "postilionModule" : [{ "alpha" : "alpha", "beta" : "beta", "build" : "build", "compliance" : [{ "assigner" : "assigner", "effectiveDate" : "effectiveDate", "expirationDate" : "expirationDate", "issuer" : "issuer"},... "reference" : "reference", "type" : "type", "version" : "version"},... ], "date" : "date", "dependency" : "dependency", "edition" : "edition", "hash" : "hash", "installType" : "installType", "majorVersion" : "majorVersion", "minorVersion" : "minorVersion", "name" : "name", "package" : "package", "patches" : "patches", "previousInstalledVersion" : "previousInstalledVersion", "sdkMajorVersion" : "sdkMajorVersion", "sdkMinorVersion" : "sdkMinorVersion", "sdkServicePackVersion" : "sdkServicePackVersion", "servicePackVersion" : "servicePackVersion", "version" : "version"},... ] } }
Device information field descriptions
Field | Description | Format | Required |
---|---|---|---|
cap |
The supported capabilities of the connected device. |
Each capability represented with one of the following values:
|
Y |
hardware |
The hardware section contains the hardware information of the connected device. |
See the Hardware section for the field descriptions. |
N |
id |
The unique ID of the connected PED. An example of this could be as follows: hardware_id + "" + _serial_number + "[" + device_name + "" + rank + "]" |
ans |
Y |
properties |
An array of additional properties for the connected device. |
See the Properties section for the field descriptions. |
N |
software |
The software section contains the software information of the connected device. |
See the Software section for the field descriptions. |
N |
Hardware
Field | Description | Format | Required |
---|---|---|---|
compliance |
An array of compliance characteristics for the connected device. |
See the Compliance section for the field descriptions. |
N |
date |
The manufactured date of the connected device. |
ns |
N |
ipAddress |
The IP Address of the device. Set this if applicable. |
ans39 Can be in either IPv4 or IPv6 format. |
N |
macAddress |
The MAC address of the PED. Set this if applicable. |
ans17 Can be formatted as follows:
|
N |
manufacturer |
The manufacturer of the PED |
ans |
N |
manufacturingSerial |
The terminal’s unique serial number, set by the manufacturer. |
ans |
N |
modelName |
The model name of the PED, for example, iPP350. |
ans |
N |
modelNumber |
The model number of the PED, for example, 350. |
ans |
N |
serial |
The terminal’s unique injected serial number. |
ans |
N |
series |
The hardware series of the PED, for example, iPP. |
ans |
N |
version |
The hardware version of the PED. |
ans |
N |
hwId |
The hardware identifier of the PED. |
ans |
N |
Properties
Field | Description | Format | Required |
---|---|---|---|
name |
The name of the property |
ans |
Y |
value |
The value of the property |
ans |
Y |
Software
Field | Description | Format | Required |
---|---|---|---|
module |
An array of software modules |
See the Module section for the field descriptions. |
N |
postilionModule |
An array of Postilion Modules |
See the Postilion Module section for the field descriptions. |
N |
Module
Field |
Description |
Format |
Required |
build |
The software module build number |
ans |
N |
compliance |
The software module compliance characteristics |
See the Compliance section for the field descriptions. |
N |
date |
The software module build date |
ns |
N |
hash |
The software module hash/CRC |
ans |
N |
majorVersion |
The major version of the software module |
ans |
N |
minorVersion |
The minor version of the software module |
ans |
N |
name |
The software module name |
ans |
Y |
type |
The software module type |
Types of the software module include:
|
Y |
version |
The software module version |
ans |
Y |
Postilion Module
Field |
Description |
Format |
Required |
alpha |
Indicates if the Postilion module is alpha |
|
N |
beta |
Indicates if the Postilion module is beta |
|
N |
build |
The software Postilion module build number |
ans |
N |
compliance |
The software Postilion module compliance characteristics |
See the Compliance section for the field descriptions. |
N |
date |
The software Postilion module build date |
ns |
N |
dependency |
The software Postilion module dependency |
ans |
N |
edition |
The software Postilion module edition |
ans |
N |
hash |
The software Postilion module hash/CRC |
ans |
N |
installType |
The software Postilion module Install Type |
ans |
N |
majorVersion |
The major version of the software Postilion module |
ans |
N |
minorVersion |
The minor version of the software Postilion module |
ans |
N |
name |
The software Postilion module name |
ans |
Y |
package |
The software Postilion module package |
ans |
N |
patches |
The software Postilion module patches |
ans |
N |
previousInstalledVersion |
The previously installed version of the software Postilion module |
ans |
N |
sdkMajorVersion |
The SDK major version of the software Postilion module |
ans |
N |
sdkMinorVersion |
The SDK minor version of the software Postilion module |
ans |
N |
sdkServicePackVersion |
The SDK service pack version of the software Postilion module |
ans |
N |
servicePackVersion |
The software Postilion module service pack version |
ans |
N |
version |
The software Postilion module version |
ans |
N |
Compliance
Field | Description | Format | Required |
---|---|---|---|
assigner |
Assigner of the compliance |
ans |
N |
effectiveDate |
Effective date of the compliance |
ns |
N |
expirationDate |
Expiration date of the compliance |
ns |
N |
issuer |
Issuer of the compliance |
ans |
N |
reference |
Reference of the compliance |
ans |
N |
type |
Type of the compliance |
ans |
Y |
version |
Version of the compliance |
ans |
N |
An example of the device information JSON structure response:
{ "cap" : ["cardreader", "keypad", "display", "pinpad"], "id" : "IPP350_0070295588 [Ingenico EMV 0]", "hardware" : { "manufacturer" : "INGENICO", "modelName" : "IPP350", "modelNumber" : "IPP350", "serial" : "0070295588", }, "properties" : [ {"name" : "short_hw_id", "value" : "TI350"}, {"name" : "full_hw_id", "value" : "IPP350"}, {"name" : "sec_fw_id", "value" : "0101"}, {"name" : "icc_reader_hw_v", "value" : "0001"}, {"name" : "icc_reader_sw_v", "value" : "0104"}, {"name" : "sec_v", "value" : "46560360"}, {"name" : "sec_crc", "value" : "435B"}, {"name" : "emv_l2_v", "value" : "30650465"}, {"name" : "emv_l2_crc", "value" : "CD39"}, {"name" : "retail_pinpad_rel", "value" : "RAM0922"}, {"name" : "retail_app_v", "value" : "RA10922"}, {"name" : "verify_lib_v", "value" : "RA20102"}, {"name" : "verify_lib_crc", "value" : "9EE6"}, {"name" : "sec_file_v", "value" : "0001"}, {"name" : "nr_ctls_mods", "value" : "03"}, {"name" : "ctls_mod_name_0", "value" : "8133540025"}, {"name" : "ctls_mod_crc_0", "value" : "70C6"}, {"name" : "ctls_mod_name_1", "value" : "8133500204"}, {"name" : "ctls_mod_crc_1", "value" : "16AD"}, {"name" : "ctls_mod_name_2", "value" : "8133510211"}, {"name" : "ctls_mod_crc_2", "value" : "A373"} ], "software" : { "module" : [ { "name" : "Telium", "type" : "os" }, { "name" : "RAM0922", "type" : "app", "version" : "RA10922" }, { "hash" : "CD39", "name" : "EMV L2", "type" : "emv_kernel", "version" : "30650465" }, { "hash" : "9EE6", "name" : "Verify library", "type" : "lib", "version" : "RA20102" }, { "hash" : "435B", "name" : "Security component", "type" : "lib", "version" : "46560360" }, { "name" : "Security file", "type" : "file", "version" : "0001" }, { "hash" : "70C6", "name" : "8133540025", "type" : "cntctls_kernel", "version" : "version" }, { "hash" : "16AD", "name" : "8133500204", "type" : "cntctls_kernel" }, { "hash" : "A373", "name" : "8133510211", "type" : "cntctls_kernel" } ] } }
SmartCardReader_GetDeviceInfo Flow
-
The POS registers the callback SmartCardReader_GetDeviceInfo with ACI’s eSocket.POS during ESP INIT, similar to registering other callbacks:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin TerminalId="TestTerm" Action="INIT"> <Esp:Register Type="CALLBACK" EventId="SmartCardReader_GetDeviceInfo"/> </Esp:Admin> </Esp:Interface>
-
The POS sends the XML ADMIN request to eSocket.POS as follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionId="170818" Type="ADMIN" MessageType="ADMIN_REQUEST" ExtendedTransactionType="2113" > </Esp:Transaction> </Esp:Interface>
-
eSocket.POS PipelineComponentDeviceDataCapture sends the SmartCardReader_GetDeviceInfo callback to the POS to retrieve the device data.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="TestTerm" EventId="SmartCardReader_GetDeviceInfo"> </Esp:Callback> </Esp:Interface>
-
The POS will retrieve the device data from the terminal and supply it to eSocket.POS in the form of the callback response in the ResponseData field using the JSON structure described previously.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="TestTerm" EventId="SmartCardReader_GetDeviceInfo" ResponseData="{"cap" : ["cardreader", "keypad", "display", "pinpad"], "id" : "IPP350_0070295588 [Ingenico EMV 0]", "hardware" : { "manufacturer" : "INGENICO", "modelName" : "IPP350", "modelNumber" : "IPP350", "serial" : "0070295588",}, "properties" : [{"name" : "short_hw_id", "value : "TI350"}, {"name" : "full_hw_id", "value" : "IPP350"}, {"name" : "sec_fw_id", "value" : "0101"}, {"name" : "icc_reader_hw_v", "value" : "0001"}, {"name" : "icc_reader_sw_v", "value" : "0104"}], "software" : {"module" : [{"name" : "Telium", "type" : "os"}, {"name" : "RAM0922", "type" : "app", "version" : "RA10922"}, {"hash" : "CD39","name" : "EMV L2", "type" : "emv_kernel", "version" : "30650465"}]} }"> </Esp:Callback>
- NOTE
-
The PED details from the terminal to the POS are formatted to the JSON structure format (described previously) by the POS to send it in the ResponseData field in the callback response.
-
eSocket.POS PosCallbackDeviceV2 intercepts the callback response and converts it to Term.XSD format. eSP PipelineComponentDeviceDataCapture will send a 0620-request containing the device data in Term.XSD format in Structured Data to Postilion Realtime.
-
eSocket.POS PipelineComponentDeviceDataCapture receives the 0630-response.
-
eSocket.POS sends an XML ADMIN response back to the POS including the device data in Term.DTD format set in Structured Data:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ActionCode="APPROVE" BusinessDate="0806" DateTime="0829200820" ExtendedTransactionType="2113" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" MessageReasonCode="9790" MessageType="ADMIN_REQUEST" PanEntryMode="00" PosCondition="00" PosDataCode="010101054005101" ResponseCode="00" RetrievalRefNr="000000000120" TerminalId="TestTerm" TransactionId="170818" Type="ADMIN"> <Esp:StructuredData Name="Term" Value="<?xml version="1.0" encoding="UTF-8"?> <Term> <Poi Id="IPP350_0070295588 [Ingenico EMV 0]"> <Cap>cardreader</Cap> <Cap>keypad</Cap> <Cap>display</Cap> <Cap>pinpad</Cap> <Hw ModNr="IPP350" Manuf="INGENICO" Serial="0070295588" ModName="IPP350"></Hw> <Props> <Prop Name="short_hw_id" Val="TI350" /> <Prop Name="full_hw_id" Val="IPP350" /> <Prop Name="sec_fw_id" Val="0101" /> <Prop Name="icc_reader_hw_v" Val="0001" /> <Prop Name="icc_reader_sw_v" Val="0104" /> </Props> <Sw> <Mod Type="os" Name="Telium" /Mod> <Mod Type="app" Name="RAM0922" Ver="RA10922" /Mod> <Mod Type="emv_kernel" Name="EMV L2" Ver="30650465" Hash="CD39" /Mod> </Sw> </Poi> </Term>"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
ResponseData
Description
Format
Description
A description of a software exception that occurred during processing. More details will usually be found in the eSocket.POS event log.
EspRegister
Type
Format
Description
Indicates whether this registration is for an event or callback.
Possible values:
EVENT CALLBACK
1.5. Interface Specification - Concepts
1.5.1. Events and callbacks
Description
eSocket.POS events and callbacks provide a means of direct communication between eSocket.POS entities and the POS.
-
An event is an unsolicited status message from one entity to another. Events use a fire-and-forget model and may be broadcast to more than one listener.
-
A callback is an unsolicited request for a value to be returned.
Both eSocket.POS and the POS application can raise events and callbacks and be notified of events and callbacks. However they will only be notified of events/callbacks for which they have registered.
The events and callbacks available to an eSocket.POS deployment are limited to those supported by the POS application, the eSocket.POS device driver and the eSocket.POS components used. Apart from the standard list of events and callbacks on the Event ID page, it is possible to have a custom list of events and callbacks depending on the device driver being used as well as any other custom pipeline components. See the device driver and custom component documentation for further information about the events they support.
The details of how to send, receive and register for events and callbacks vary between the API and XML interfaces. See the relevant interface definition for details.
Examples of events sent to the POS
Information about the status of the interaction between the customer and external devices:
-
Prompt for a card to be inserted
-
Report PIN entry status
-
Display a custom message (requires implementation in a custom component)
Examples of callback sent to the POS
eSocket.POS requests further information from the POS:
-
Get a value (e.g. when manual entry is not supported on the devices controlled by eSocket.POS)
Examples of events from the POS to eSocket.POS
The POS sends an event during processing of a transaction which alters how eSocket.POS processes the transaction:
-
POS forces PIN Entry to be bypassed
-
POS causes eSocket.POS to perform a custom action (requires implementation in a custom component)
Examples of callback from the POS to eSocket.POS
The POS requests a value from eSocket.POS during the life of the transaction
-
POS requests custom information from eSocket.POS (requires implementation in a custom component)
Note that the mechanism provided for events and callbacks is generic, and whether these events or callbacks are sent or handled will depend on the configuration and customization of eSocket.POS. The scenarios described above are examples of what may be implemented through this mechanism. These requirements should be defined as part of the integration phase between the POS application and eSocket.POS.
1.5.2. Gift card transactions
eSocket.POS supports the following gift card transactions:
-
Gift card activation
-
Gift card activation with deposit
-
Gift card load
-
Gift card deactivation
-
Gift card deactivation with cashback
-
Gift card unload
-
Gift card activation refund
Gift card transactions are processed as EspTransaction objects in the API (or Esp:Transaction elements in the XML interface). In order to send a gift card transaction, the POS must set the relevant properties for an EspTransaction object and set the Type property to one of CARD_ACTIVATE, LOAD, CARD_DEACTIVATE, UNLOAD or CARD_ACTIVATE_REFUND
Gift card transactions are usually sent as Transaction Request (0200) messages if they have a financial impact (e.g. card activation with deposit, load or card deactivation with cashback transactions). However, it is possible to use other ISO 8583 message types for gift card transactions with financial impact by setting the MessageType property. Gift card transactions that have no financial importance (e.g. pure card activation or card deactivation) are always sent as Administration Request (0600) messages.
If the TransactionAmount property is set to a non-zero value for a CARD_ACTIVATE transaction, the card will be activated and the specified amount deposited into the gift card account. If the TransactionAmount property is set to a non-zero value for a CARD_DEACTIVATE transaction, the card will be deactivated and the specified amount debited from the account and given to the customer.
Depending on the capabilities of the host system, responses to certain gift card transactions, such as card activation with deposit, load and card deactivation transactions, may contain the remaining balance on the card in the Additional Amounts field (field 54), which will then be available as a BalanceListItem in the response to the POS.
Note that gift card transaction processing requires PosConnect v2.0 with Patch 2 applied or later.
1.5.3. Healthcare benefit transactions
Healthcare benefit transactions are processed as EspTransaction objects in the API (or Esp:Transaction elements in the XML interface). These transactions are performed using a healthcare benefits card, which is typically a Flexible Savings Account (FSA), Health Reimbursement Arrangement (HRA) or Health Savings Account (HSA) card. In order to send a healthcare benefit transaction, the POS must set the relevant properties for an EspTransaction object. The extended transaction type property must be set to "7111 - Healthcare Benefit". If not, and the card is a healthcare benefit card, eSocket.POS sets it as such.
eSocket.POS checks if the card is a valid healthcare card and declines the transaction if it is not.
Healthcare benefit transactions are usually sent as transaction request (0200) messages with the following fields :
If the merchant supports partial approval, the property PosCondition is set to '41'. Any other value indicates that the merchant does not support partial approvals.
The response code in the response message indicates how the transaction amount was approved:
-
00 - full amount was approved
-
10 - partial amount was approved
1.5.4. Electronic benefits transfer
There are two types of EBT benefits:
-
EBT cash benefit (account type 96)
-
EBT food stamp (account type 98)
eSocket.POS supports the following EBT transactions. Unless stated explicitly, they apply to both cash benefit and food stamp benefits:
-
EBT balance inquiry
-
EBT purchase (including cash back under the cash benefit)
-
EBT food stamp electronic voucher
-
EBT reversal/void
-
EBT refund
-
EBT time out reversal
EBT balance inquiries are processed as EspInquiry objects in the API (or Esp:Inquiry elements in the XML interface). All other EBT transactions are processed as EspTransaction objects in the API (or Esp:Transaction elements in the XML interface). See "POS XML message flow examples" under the POS XML message flow examples > EBT transactions section for more details.
See the eSocket.POS User Guide for the required configuration to correctly process EBT transactions.
1.5.5. Character encodings
eSocket.POS supports the transfer of non-standard character encoded strings, e.g. UTF-8, downstream through the Pipeline Components, down to the POS. This is done by storing the encoded string in StructuredData , together with an eSP:Encoding entry in StructuredData .
eSP:Encoding is a reserved StructuredData entry, which should be a table, constructed with a HashtableMessage, of the character encodings associated with encoded string entries in StructuredData . The Name / Value pairing that should exist in eSP:Encoding is illustrated below.
eSP:Encoding
Name | Value |
---|---|
The StructuredData field name, that contains the non-standard character encoding, e.g. EncodedData |
The Java recognized Charset name of the character encoding used, e.g. UTF-8 |
An entry in eSP:Encoding is necessary only when the string is encoded with a character encoding other than ASCII . If no entry for a StructuredData field is present in eSP:Encoding , no additional processing will be performed on field, and it will be processed normally.
Example
As an example of a message with a non-standard character encoded string, assume that a message is received by eSocket.POS, with field 127.22 containing: *212eSP:Encoding221211EncodedData15UTF-8211EncodedData251(BINARY_DATA)* This entry consists of:
-
*211EncodedData251(BINARY_DATA)* : The field EncodedData together with the binary representation of the encoded string, in its encoded format.
-
*212eSP:Encoding221211EncodedData15UTF-8* : The field eSP:Encoding together the contents of this table. The contents include:
-
*211EncodedData15UTF-8* : This indicates that the field EncodedData is encoded using the character encoding UTF-8 .
-
Limitations
This feature is limited to the following:
-
Only downstream messages, passing through the Pipeline Components and sent to the POS, support the Character Encoding feature.
-
Only the following StructuredData fields may contain non-standard character encodings:
-
PosPrivateData
-
All other StructuredData field names that are not reserved.
-
1.5.6. Mapping to ISO 8583
The eSocket.POS API allows the POS programmer to create transaction objects and set various properties. Internally, these properties are mapped onto the fields of an ISO 8583 message, and the fields in the ISO 8583 response are mapped back to transaction properties.
A developer using the eSocket.POS API will usually not have to be concerned with the details of the ISO 8583 protocol, or how properties are mapped to fields, and vice versa. However, an understanding of the mapping will sometimes be useful, for instance to set certain properties required upstream, or when working with the eSocket.POS trace file.
API Property | ISO 8583 Field | Description of Mapping |
---|---|---|
Account From in Processing Code (field 3) |
The account property is used to set the Account From subfield of Processing Code (field 3) and vice versa. If the transaction is a credit transaction (Transaction type in the range 20 - 29) the Account To subfield is used instead. |
|
- |
The Response Code (field 39) is mapped to a limited set of action codes |
|
Address Verification Result (field 127.16) |
One-to-one |
|
Amount, Transaction Fee (field 28) |
One-to-one |
|
Authorization ID Response (field 38) |
One-to-one |
|
Authorizing Agent Institution (field 58) |
One-to-one |
|
- Account Type of an amount in Additional Amounts (field 54) for a Balance Inquiry
|
One-to-one |
|
|
One-to-one |
|
Amount Type of an amount in Additional Amounts (field 54) |
One-to-one |
|
- Currency Code of an amount in Additional Amounts (field 54) for a Balance Inquiry
|
One-to-one |
|
Sign of an amount in Additional Amounts (field 54) |
One-to-one |
|
Tag SEQ_NR of Additional Data (field 48) |
One-to-one |
|
Tag DATE_TIME of Additional Data (field 48) |
One-to-one |
|
Tag TERM_ID of Additional Data (field 48) |
One-to-one |
|
Tag TRAN_TYPE of Additional Data (field 48) |
One-to-one |
|
Tag TO_ACC of Additional Data (field 48) |
One-to-one |
|
Tag ACC_ID_1 of Additional Data (field 48) |
One-to-one |
|
Tag ACC_ID_2 of Additional Data (field 48) |
One-to-one |
|
Tag AUTH_ID of Additional Data (field 48) |
One-to-one |
|
Tag SURCHARGE of Additional Data (field 48) |
One-to-one |
|
- Additional Amounts (field 54) for a Balance Inquiry
|
|
|
Date, Settlement (field 15) |
One-to-one |
|
Cardholder Address in Address Verification Data (field 127.15) |
One-to-one |
|
Element named 'CardholderName' in Structured Data (field 127.22) |
One-to-one |
|
Cardholder Information (field 127.17) |
One-to-one |
|
Element named 'CARDHOLDER_INITIATED_PAYMENT' in Structured Data (field 127.22) |
One-to-one |
|
Primary Account Number (PAN) (field 2) |
One-to-one |
|
Element named 'CardProductName' in Structured Data (field 127.22) |
One-to-one |
|
Card Sequence Number (field 23) |
One-to-one |
|
Card Verification Result (field 127.27) |
One-to-one |
|
Amount in Additional Amounts (field 54) |
If cashback amount is set, a cash amount is inserted into Additional Amounts (field 54) |
|
Check fields (apart from those listed below) |
Elements in CheckData element in StructuredData (field 127.22) |
One-to-one |
Account Number in Check Data (field 127.7) |
One-to-one |
|
Institution Code in Check Data (field 127.7) |
One-to-one |
|
Check Number in Check Data (field 127.7) |
One-to-one |
|
Original Key (field 127.11) |
One-to-one within the pipeline |
|
Credits, Amount (field 86) |
One-to-one |
|
Credits, Reversal Amount (field 87) |
One-to-one |
|
Currency Code, Transaction (field 49) |
One-to-one |
|
- CVV2 (field 127.10) if the CVV2 consists of 3 digits.
|
One-to-one |
|
Transmission Date and Time (field 7) |
One-to-one |
|
Dynamic Currency Conversion Status Code (field 127.48) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.ProviderRoutingId' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.Rate' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.SrcCurr.Code' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.SrcCurr.AlphaCode' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.SrcCurr.MinorUnits' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.TgtCurr.Code' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.TgtCurr.AlphaCode' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.TgtCurr.MinorUnits' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.Provider' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.RateSrc' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.Timestamp' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.MargRate' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.CommRate' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.SrcAmt' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.TgtAmt' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.ExpTimestamp' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.RcptTxt1' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.RcptTxt2' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.DccAcqId' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.DccCardAccptrId' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Key 'Postilion:CurrencyConvInfo', value 'CurrencyConvInfo.DccTermId' in currency conversion information XML in Structured Data (field 127.22) |
One-to-one |
|
Debits, Amount (field 88) |
One-to-one |
|
Debits, Reversal Amount (field 89) |
One-to-one |
|
Element named 'ResponseDisplay' in Structured Data (field 127.22) |
One-to-one |
|
EBT properties |
Elements in ElectronicBenefitTransfer element in StructuredData (field 127.22) |
One-to-one |
EMV properties (apart from fields below) |
Elements from IccData (field 127.25) |
One-to-one |
Element of the same name in Structured Data (field 127.22) |
One-to-one |
|
Element of the same name in Structured Data (field 127.22) |
One-to-one |
|
Element of the same name in Structured Data (field 127.22) |
One-to-one |
|
Element of the same name in Structured Data (field 127.22) |
One-to-one |
|
Element of the same name in Structured Data (field 127.22) |
One-to-one |
|
Element named 'EspCardInfo' in Structured Data (field 127.22) |
Contains additional card details, as configured in eSocket.POS. |
|
Date, Expiration (field 14) |
One-to-one |
|
Extended Payment Code (field 67) |
One-to-one |
|
Extended Transaction Type (field 127.33) |
If ExtendedTransactionType is not set this is based on the Type and TransactionAmount properties, otherwise the mapping is one-to-one. |
|
Extended Authorization ID Response (field 127.51) |
If AuthorizationNumber is not set and a response contain an extended authorization number with length between n7- n8. |
|
Element named 'AuthorizationId' in Structured Data (field 127.22) |
One-to-one |
|
Transaction Amount in Replacement Amounts (field 95) |
One-to-one |
|
Element named 'FleetData' in Structured Data (field 127.22), in XML format |
One-to-one |
|
Element named 'FleetDataRsp' in Structured Data (field 127.22), in XML format |
One-to-one |
|
Amount in Additional Amounts (field 54) |
If gratuity amount is set, a tip (amount type 56) amount is inserted into Additional Amounts (field 54). |
|
Date, Local Transaction (field 13) |
One-to-one |
|
Time, Local Transaction (field 12) |
One-to-one |
|
Card Acceptor ID Code (field 42) |
One-to-one |
|
Message Reason Code (field 56) |
One-to-one |
|
PAN Entry Mode in POS Entry Mode (field 22) |
One-to-one |
|
Elements named 'PassThruPanReference' and 'PassThruMaxReliableBinLength' in Structured Data (field 127.22) |
Structured Data field 'PassThruPanReference' has the hash table message format. The XML fields will be mapped to the hash table message fields as follows: Scheme, Data, SensitiveDataBlock, and WhitelistFileName will be mapped one-to-one. Ksn will be mapped to KSN. TlvMapping will be mapped to TLVMapping. XML field MaxReliableBinLength will be mapped to Structured Data field 'PassThruMaxReliableBinLength'. MaxReliableBinLength can exist in one or both XML elements PassThruPanReference and PassThruVolatileP2peData. If it exists in both, their values must match and either one of them will be mapped to Structured Data field PassThruMaxReliableBinLength. |
|
Elements named 'PassThruVolatileP2peData' and 'PassThruMaxReliableBinLength' in Structured Data (field 127.22) |
Structured Data field 'PassThruVolatileP2peData' has the hash table message format. The XML fields will be mapped to the hash table message fields as follows: Scheme, Data, SensitiveDataBlock, and WhitelistFileName will be mapped one-to-one. Ksn will be mapped to KSN. TlvMapping will be mapped to TLVMapping. XML field MaxReliableBinLength will be mapped to Structured Data field 'PassThruMaxReliableBinLength'. MaxReliableBinLength can exist in one or both XML elements PassThruPanReference and PassThruVolatileP2peData. If it exists in both, their values must match and either one of them will be mapped to Structured Data field PassThruMaxReliableBinLength. |
|
PIN Data (field 52) |
The 8 bytes of the ISO field are set using the 16-character hexadecimal value. |
|
Security Related Control Information (field 53) |
The first 8 bytes of the ISO field are set using the 16-character hexadecimal value, and the rest are zero-filled. |
|
POS Condition Code (field 25) |
One-to-one |
|
POS Data (field 127.4) |
One-to-one |
|
POS Operator ID in POS Data (field 127.4) |
One-to-one |
|
Postal/Zip Code in Address Verification Data (field 127.15) |
One-to-one |
|
Element named 'PurchasingCardData' in Structured Data (field 127.22), in XML format. If the first LineItem in the PurchasingCardData contains only the ProductCode, the ProductCode value is used to populate the XML element named 'PrepaidMerchandise' in Structured Data (field 127.22). If the 'PrepaidMerchandise' element is populated in this way, the source LineItem is cleared. If the only field populated in all of the PurchasingCardData was the ProductCode of the first LineItem, the entire PurchasingCardData element is cleared. |
One-to-one or One-to-two (for gift card transactions) |
|
PurchasingCardData with only the ProductCode of the first LineItem populated |
Element named 'PrepaidMerchandise' in Structured Data (field 127.22), in XML format |
One-to-one |
Payee Name and Address (field 127.23) |
Contains identification and billing information for a payee. |
|
Element named 'AdditionalPayeeInformation' in Structured Data (field 127.22) |
Contains additional payee name and address details. |
|
Element named 'AccountData' in Structured Data (field 127.22) |
Contains account details needed for credit application. |
|
Element named 'DisplayData' in Structured Data (field 127.22) |
The status response from ADS based on the processor specification. |
|
Element named 'PrintData' in Structured Data (field 127.22) |
The status response that contains information about the account. |
|
Element named 'RECURRING_PAYMENT' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'RecurringPaymentDetail' in Structured Data (field 127.22), in XML format. |
One-to-one |
|
MessageType - Check |
ISO 8583 message type |
If MessageType is not set, the ISO 8583 message type is set to 0100 - Authorization Request. Otherwise, one-to-one: AUTHADV maps to 0120 - Authorization Advice, TRANREQ maps to 0200 - Transaction Request, and CONFIRM maps to 0220 - Transaction Advice. |
MessageType - Transaction |
ISO 8583 message type |
If the MessageType is set then the ISO 8583 message type will be mapped as follows:
If the MessageType is not set, the message type will be set according to the Type property. Note that the above mappings are overridden if the Reversal property is set to true . In a response, the MessageType is set as follows:
|
Amount, Net Settlement (Field 97) |
The sign is stored in the first character of Amount, Net Settlement (Field 97). |
|
Amount, Net Settlement (Field 97) |
The amount is stored in the last sixteen digits of the Amount, Net Settlement (Field 97). |
|
Network Management Information Code (field 70) |
One-to-one |
|
Authorizations, Number (field 81) |
One-to-one |
|
Credits, Number (field 74) |
One-to-one |
|
Credits, Reversal Number (field 75) |
One-to-one |
|
Debits, Number (field 76) |
One-to-one |
|
Debits, Reversal Number (field 77) |
One-to-one |
|
Inquiries, Number (field 80) |
One-to-one |
|
Element named 'PosStructuredData' in Structured Data (field 127.22) |
Within the element in field 127.22, multiple name/value pairs are included, themselves also in Postilion Structured Data format (that is, nesting of one Structured Data string inside another). |
|
Element named 'PosPrivateData' in Structured Data (field 127.22) |
One-to-one |
|
Receiving Institution ID Code (field 100) |
One-to-one |
|
Additional Response Data (field 44) |
One-to-one |
|
Response Code (field 39) |
One-to-one |
|
Retrieval Reference Number (field 37) |
One-to-one |
|
ISO 8583 message type |
If the Reversal property is set to true , the ISO 8583 message type is set to 0420 - Reversal Advice. If the response has a message type of 0430 - Reversal Advice Response, the Reversal property is set to true |
|
ISO 8583 message type |
If the Reversal Type property is set to REQUEST, the ISO 8583 message type is set to 0400. If the Reversal Type property is set to ADVICE, the ISO 8583 message type is set to 0420. |
|
Security Related Control Information (field 53) |
The ISO field is set by converting to binary representation and right padding with binary zeros to 48 bytes. |
|
Service Restriction Code (field 40) |
One-to-one |
|
Currency Code, Settlement (field 50) |
One-to-one |
|
Element named 'SignatureAdditionalText' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureButtonValue' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureCheckbox1State' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureCheckbox1Text' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureCheckbox2State' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureCheckbox2Text' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureCheckbox3State' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureCheckbox3Text' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureImageFormat' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureImagePassedInResponse' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignaturePromptName' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureScrollableText' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureStandAloneDynamicText' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureData' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureFormat' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureImageCategory' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureImageEncrypted' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureImageSequence' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureOriginalFormat' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'SignatureRequired' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'StartDate' in Structured Data (field 127.22) |
One-to-one |
|
Element named 'APM' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'PaymentBrand' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'QRCodeType' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'QRCodeData' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'QRCodeImage' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'QRCodeTranId' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'QRCodeHostRef' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'BarcodeData' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'Quantity' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'TransactionName' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'StoreId' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'Memo' in Structured Data (field 127.22). |
One-to-one |
|
Element named 'MerchantOpcSelection' in Structured Data (field 127.22). This field is specific to OPC transactions. |
One-to-one |
|
Structured Data (field 127.22) |
One-to-one, excluding reserved name s from the mapping. |
|
Track 1 Data (field 45) |
One-to-one |
|
Track 2 Data (field 35) |
One-to-one |
|
Track 3 Data (field 36) |
One-to-one |
|
Systems Trace Audit Number (field 11) |
One-to-one |
|
Transaction Amount (field 4) |
One-to-one |
|
Type - Check |
Transaction Type in Processing Code (field 3) and Extended Transaction Type (field 127.33) |
Extended Transaction Type:
Transaction Type:
|
Type - Inquiry |
Iso8583 message type and Transaction Type in Processing Code (field 3) |
CARD_READ maps to an Iso8583 0600 - Administration Request message. All other transaction types map to the ISO 8583 message type 0100 - Authorization Request. Mapping for types is one-to-one: AVAILABLE_FUNDS maps to a Transaction Type of 30 - Available Funds Inquiry BALANCE maps to 31 - Balance Inquiry CHEQUE_VERIFICATION maps to 04 - Cheque Verification CHEQUE_GUARANTEE maps to 03 - Cheque Guarantee CARD_READ maps to the internal value of 95 - Card Read GENERAL_INQ maps to 32 - General Inquiry CARD_VERIFICATION maps to 37 - Card Verification Inquiry |
Type - Merchandise |
Iso8583 message type and Transaction Type in Processing Code (field 3) |
REQUEST maps to a 0100. PROCURE and REVERSE map to a 0200. CONFIRM maps to a 0220. The Transaction Type is set to '28' - Merchandise, except for REVERSE in which case it is set to '02' - Adjustment. |
Type - Network |
Iso8583 message type. |
Iso8583 message type maps to a 0800. |
Type - Reconciliation |
Iso8583 message type. |
Iso8583 message type maps to a 0500. |
Type - Transaction |
transaction type subfield of Processing Code (field 3), and ISO 8583 message type. |
The mapping of this field will be described below. |
The transaction type from Type - Transaction is mapped as follows:
-
PURCHASE maps to '00' - Goods and Services, or to '09' - Goods and Services with Cashback if the CashbackAmount is set.
-
DEPOSIT maps to '21' - Deposit.
-
DEPOSIT maps to '51' - Payment by Deposit if extended transaction type is set to '7116' - Credit Admin Payment on Account with Cash transaction, or '7117' - Credit Admin Payment on Account with Check transaction.
-
REFUND maps to '20' - Returns.
-
DEBIT_ADJUSTMENT maps to '02' - Adjustment.
-
CREDIT_ADJUSTMENT maps to '22' - Adjustment.
-
ADMIN maps to '91' - General Admin
-
CARD_ACTIVATE maps to '91' - General Admin if the TransactionAmount is not set or is set to a zero amount with the extended transaction type set to '3100' - Card Activate. Otherwise, it maps to '25' - General Credit, with the extended transaction type set to '6500' (CardActivation with Deposit verified by operator)'.
-
LOAD maps to '25' - General Credit.
-
CARD_DEACTIVATE maps to '91' - General Admin if the TransactionAmount is not set or is set to a zero amount with the extended transaction type set to '3101' - Card Deactivate. Otherwise, it maps to '12' - General Debit with the extended transaction type set to '6502' - Card Deactivate with cashback.
The ISO message type is set based on the MessageType property. If this property is not set, then the message type is mapped as follows:
-
0100 - Authorization Request if the Type is AUTH __ (deprecated).
-
0220 - Transaction Advice if the Type is REFERRAL of CONFIRM (both deprecated).
-
0600 - Administration Request if the Type is CARD_ACTIVATE / CARD_DEACTIVATE and the TransactionAmount property is not set or is set to a zero amount.
-
0620 - Administration Advice if the Type is ADMIN.
-
0200 - Transaction Request otherwise.
The above mappings are overridden if the Reversal property has a value of true , in which case the message type is set to 0420 - Reversal Advice.
If the response has a message type of 0630, the transaction type is set to ADMIN. Otherwise, the Type is set according to the Transaction Type subfield of Processing Code (field 3) as follows:
-
20 - Returns is mapped to REFUND.
-
21 - Deposit is mapped to DEPOSIT.
-
51 - Payment by Deposit with an Extended Transaction Type (field 127.33) of 7116 - Credit Admin Payment on Account with Cash or 7117 - Credit Admin Payment on Account with Check is mapped to DEPOSIT.
-
02 - Adjustment is mapped to DEBIT_ADJUSTMENT.
-
22 - Adjustment is mapped to CREDIT_ADJUSTMENT.
-
91 - General Admin with an Extended Transaction Type (field 127.33) of 3100 - Card activation is mapped to CARD_ACTIVATE.
-
91 - General Admin with an Extended Transaction Type (field 127.33) of 3101 - Card deactivation is mapped to CARD_DEACTIVATE.
-
91 - General Admin with the Extended Transaction Type (field 127.33) not set to 3100 - Card activation or 3101 - Card deactivation is mapped to ADMIN.
-
25 - General Credit with an Extended Transaction Type (field 127.33) of 6500 - Card activation with deposit verified by operator is mapped to CARD_ACTIVATE.
-
25 - General Credit with an Extended Transaction Type (field 127.33) of 6501 - Deposit verified by operator is mapped to LOAD.
-
12 - General Debit with an Extended Transaction Type (field 127.33) of 6502 - Card deactivation with cash back is mapped to CARD_DEACTIVATE.
-
Otherwise, this is set to PURCHASE.
The deprecated values of AUTH, CONFIRM and REFERRAL are never used in responses.
1.5.7. Data Element Format
The following notation conventions have been employed throughout the developers guide to describe the format of the eSocket.POS object properties (data elements).
This notation is based on the ISO 8583 (1987) specification.
a | Alphabetic characters, A through Z and a through z |
---|---|
n |
Numeric digits, 0 through 9 |
p |
Pad character, space |
s |
Special characters, i.e. other printable characters |
an |
Alphabetic and numeric characters |
as |
Alphabetic and special characters |
ns |
Numeric and special characters |
anp |
Alphabetic, numeric and pad characters |
ans |
Alphabetic, numeric and special characters |
object |
The property (data element) is a reference to an object. Refer to the definitions of the object’s properties (data elements). |
boolean |
"TRUE" or "FALSE" when using the XML interface, otherwise true or false in Java API. |
YY |
Year, 00 through 99 |
YYYY |
Year, 0001 through 9999 |
MM |
Month, 01 through 12 |
dd |
Day, 01 through 31 |
HH |
Hour, 00 through 23 |
mm |
Minute, 00 through 59 |
ss |
Second, 00 through 59 |
3 |
Fixed length of 3 characters |
..17 |
Variable length up to 17 characters. |
x |
C for credit, D for debit. |
h |
Hexadecimal representation of binary data |
z |
Track 2 as defined in ISO 7813 |
2. Java API
2.1. Overview
The Java application programming interface (API) for eSocket.POS was designed to be used by other applications to perform the following tasks:
-
Provide a Java interface between the application program and the eSocket.POS application. The eSocket.POS application provides a connection with Postilion.
-
Allow an EFT transaction with the necessary data elements to be created, in the form of a collection of objects and their properties.
-
Translate transaction objects into messages and pass the messages to eSocket.POS.
-
Receive response messages from eSocket.POS and presents them to the local application as a new transaction or merchandise object with the response code and other properties set.
-
Facilitate sending and receiving of events and callbacks between the POS and eSocket.POS.
The local application need not concern itself with the construction of messages to eSocket.POS or the Postilion system. All the local application needs to do is to create various objects and set their properties to the required values. The objects and their descriptions have been specifically designed to be intuitive to the developer of the local application, without requiring understanding of the underlying ISO 8583 message protocol. The construction of messages from the objects is handled transparently by eSocket.POS.
The transaction objects and their properties are defined in the Interface Specification section of this document.
2.1.1. Java
eSocket.POS is developed in Java (conforming to SUN Java v1.8). This means that local Java-based applications making use of eSocket.POS can run on any operating system, provided that there is an implementation of a Java virtual machine (JVM) available for the operating system. Through Java’s platform independence, eSocket.POS is supported on Windows, most distributions of Unix, Macintosh, and others.
Note: The eSocket.POS application contains various configurable components which allow it to be integrated with different operating systems, database environments and devices at the point-of-sale. Depending on your choice of operating system, database and devices, some of these components may be available, while others may need to be developed. This integration and configuration is beyond the scope of this developer guide. Please discuss this with your primary support provider.
2.1.2. Design principles
eSocket.POS implements an object-oriented design. Each transaction supported by eSocket.POS is represented as an object. The data elements associated with a transaction are the properties of the transaction object.
Each property must conform to a specific data element format. For example, the Card Number should consist of numeric values only, and be no greater than 19 characters in length. The Interface Specification section defines the data element format of each property.
2.2. Using EspInterface
The eSocket.POS API provides a single point of access to the POS developer. This is the EspInterface object.
EspInterface provides an interface for one or more terminals to connect to eSocket.POS. A single interface should be used for all POS terminals controlled by the application program. If the POS application is installed on a POS terminal, that interface will handle only that terminal. If the POS application runs on a store server and handles more than one POS terminal, a single EspInterface should be created to handle transactions from all connected POS terminals. The POS application should not create a separate interface for each physical terminal.
The POS program should create the instance of EspInterface as follows:
EspInterface esp_interface = new EspInterface();
The interface exposes methods which can be used for the following functions:
-
initializing eSocket.POS to receive transactions for a particular terminal
-
pre-initialize all terminals that run in a store server environment according to the level required by the configuration in the properties file
-
closing eSocket.POS for a particular terminal
-
sending a transaction from a terminal to eSocket.POS
-
inquiring the status of the transaction previously sent to eSocket.POS
-
sending an event or callback from a terminal to eSocket.POS
-
registering a terminal to receive events or callback from eSocket.POS
-
starting and closing Config Agent
These methods are dealt with on the subsequent pages of the developer guide.
2.3. Initialization
eSocket.POS can be run using two types of deployment: It can be implemented on each till or it can be implemented on a store server. The API provides means for either initializing per terminal or per store server .
2.4. Initializing a terminal
Once the EspInterface object has been created, each connecting terminal needs to be initialized via the interface. This is done using the initTerminal method with the Terminal ID and properties file name as parameters. It is also possible to supply the properties file to the initTerminal method as a Java Properties object instead of supplying the file name as a String. Refer to the eSocket.POS User Guide for the properties which must be supplied in this object.
The Terminal ID identifies which terminal parameters to apply, so data for that Terminal ID must be present in the eSocket.POS database before that terminal can be initialized. The Terminal ID must be unique across all the terminals connecting to the upstream Postilion system.
In the case of a POS application controlling a single terminal, the initTerminal method should be called once as follows
esp_interface.initTerminal("Term1234", "c:\\esocketpos\\properties.txt");
(Change the filename and path to reflect location of the properties file on the local system.)
If the POS application controls more than one POS terminal, each terminal should be initialized separately:
esp_interface.initTerminal("Term1234", "c:\\esocketpos\\properties.txt"); esp_interface.initTerminal("Term5678", "c:\\esocketpos\\properties.txt");
or by calling the overridden initTerminal method with the second parameter set to a Properties object.
This may be done at the discretion of the POS application: either all terminals can be initialized at startup, or terminals can be initialized as they come into action. Unused terminals may be closed using the close method (described later).
Note that the initTerminal command is memory and processor intensive, and should only be called once per POS terminal, typically when the application starts, or at the start of the day. Terminals should not be initialized per transaction.
Failure to initialize
If eSocket.POS can’t be started for the terminal ID specified, the initTerminal command will throw an XConfig exception. This might happen for any of a wide range of reasons, including:
-
problems with the properties file
-
the terminal ID not being found in the eSocket.POS database
-
inconsistent or incorrect configuration in the database
-
classes not being found
-
a connection problem to a device
-
many other possible causes
The cause of the problem is reported in the XConfig exception, and typically additional information about the error is logged in the eSocket.POS event log. The integrator or POS developer should refer to this event log to determine the reason that eSocket.POS failed to start, and fix the problem.
If the initTerminal method fails, no transactions can be sent using the send method for that terminal ID. The problem must be solved and initTerminal must be called successfully before transactions can be sent.
2.5. Initializing the store server
eSocket.POS instances can be initialized in the EspInterface by calling the initStoreServer method.
The store server can be initialized once as follows:
esp_interface.initStoreServer("c:\\esocketpos\\properties.txt"); *Note:* Change the filename and path to reflect location of the properties file on the local system.
This will allow eSocket.POS to deliver store-and-forward transactions by initializing the POS terminal when processing the first transaction. The level of POS terminal auto-initialization can be set in the eSocket.POS properties file by specifying one of the following values for the postilion.esocketpos.storeserver.AutoInitTerminals property:
-
None - No terminals will be pre-initialized.
-
Saf - Only pre-initialize the terminals that have transactions in the store-and-forward queue.
-
All - Pre-initialize all terminals.
-
AllSignOn - Pre-initialize and automatically sign-on all terminals. Note: Sign-on enables terminals to connect to and do initial setup for the PED devices.
Note: It is not necessary to call the initTerminal method for the terminals that will be auto-initialized.
2.6. Closing a terminal
When no more transactions are required, and a particular terminal is no longer needed, the POS application should close that terminal with eSocket.POS. This uses the close method:
esp_interface.close("Term1234"); esp_interface.close("Term5678");
Alternately, all terminal connections on that EspInterface can be closed with the closeAll method:
esp_interface.closeAll();
Terminals should not normally be closed and reopened between transactions as this process is memory and processor intensive. Typically a terminal should be closed before the POS application terminates, but the POS developer might also decide to close a terminal with eSocket.POS while it is inactive, for instance overnight. The decision about when to close a terminal is left to the POS application developer.
2.7. Starting and closing Config Agent
The EspInterface gives the ability to start and stop Config Agent.
Config Agent can be started by calling
esp_interface.startConfigAgent("c:\\esocketpos\\properties.txt");
(Change the filename and path to reflect location of the properties file on the local system.)
or by calling the startConfigAgent method with a Properties object as the parameter.
The closeConfigAgent method will close Config Agent if it is running.
2.8. Error handling
Overview
When an error occurs in EspInterface , an exception is raised. An error may occur for various reasons. Exceptions that are specific to EspInterface will also include a description of the exception. Errors that may occur include:
-
Errors during initialization
-
Attempting to set a transaction property to an invalid value
-
Attempting to send a message on behalf of a non-configured terminal
-
An invalid response received, either constructed by eSocket.POS or received from upstream
Java Exceptions
Exceptions raised by EspInterface may be caught by try/catch clauses. The following exceptions are specific to EspInterface :
-
XConfig - This exception is thrown during initialization in case the properties file is invalid or missing, or if eSocket.POS can’t start because of a configuration error or a problem with an external device.
-
XInvalidPropertyAssignment - This exception is thrown when invalid values are assigned to a property.
-
XPropertyNotSet - Certain properties are mandatory for transactions sent to eSocket.POS. This exception is thrown when mandatory properties have not been set.
-
XTransactionFailure - This exception is thrown when a serious problem is encountered while trying to send a message or receiving a response from eSocket.POS (e.g. when the message or response is null)
-
XUnknownTerminal - This exception is thrown when a Terminal ID is used that has not been successfully initialized.
-
XUnsupportedTransaction - This exception is thrown when an unknown transaction is received.
2.9. Transactions
2.9.1. Sending a transaction
The eSocket.POS API exposes objects and properties that can be used to send various types of transactions using eSocket.POS. These transactions are based on the following objects:
-
EspTransaction
-
EspInquiry
-
EspMerchandise
-
EspCheck
-
EspReconciliation
-
EspNetwork
Each time a transaction is required, a method is called to create the appropriate transaction object:
EspTransaction tran_purchase = esp_interface.newTransaction();
The necessary properties are set, for example:
tran_purchase.setTransactionId("123456"); tran_purchase.setType(EspTransaction.Type.PURCHASE); tran_purchase.setTransactionAmount("1000");
The transaction is sent to eSocket.POS, and the response is returned. The Terminal ID used in the send method must be for a terminal which has already been initialized successfully:
EspTransaction tran_rsp = (EspTransaction) esp_interface.send("Term1234", tran_purchase);
Note that this method may take a considerable time to return, as eSocket.POS may need to interact with the customer via external devices, and wait for an online response.
Finally, the response properties are extracted, for instance to check for a successful response:
if (!"0".equals(tran_rsp.getActionCode())) //approved \ { System.out.println("The transaction was not successful."); }
Other transaction properties might be printed on the receipt, saved to the POS database, etc.
2.9.2. Transaction flows
The EspTransaction object is used in a variety of contexts. Most importantly, it is used to effect a purchase transaction. This can be done in a single step, or through multiple steps, depending on the EFT model chosen by the merchant.
Purchase and possibly reverse:
With this model, most transactions will be completed with a single message flow (a 0200 message in ISO 8583 terms).
-
Create an EspTransaction object, set the Type to PURCHASE, set the required properties, and send the object.
-
If the response is successful, the purchase has been completed.
-
If it is then decided to void the transaction, the following steps must be taken:
-
Create another EspTransaction object, set the Reversal property to true , set the Type to PURCHASE, set the TransactionId to match the original transaction, set any other required properties, and send it.
NoteThe ReversalType property can optionally be set to REQUEST for online reversal (a 0400 message in ISO 8583 terms). If the ReversalType is not set, or set to ADVICE, it will be an offline reversal (a 0420 message in ISO 8583 terms). -
If the ReversalType is ADVICE, the reversal will be approved, unless a format error or software error has occurred. In such cases, the transaction should be logged for possible exception processing.
-
-
Authorize and confirm or reverse:
With this model, transactions will require an authorization message and a fulfillment message (0100 followed by 0220 in ISO terms).
-
Create an EspTransaction object, set the Type to PURCHASE, set the MessageType to AUTH, set the required properties, and send the object.
-
If the response is not successful, the authorization has been declined and another tender should be attempted. No reversal is required.
-
If the response is successful, funds might have been reserved against the cardholder’s account, but a fulfillment is required to confirm the transaction before the account is actually debited.
-
If the transaction is to be fulfilled, the following steps must be taken:
-
Create another EspTransaction object, set the Type to PURCHASE, set the MessageType to CONFIRM, set the TransactionId to match the original transaction, set any other required properties, and send it.
-
The reversal will be approved, unless a format error or software error occurs. In such cases, the transaction should be logged for possible exception processing.
-
-
If it is instead decided not to fulfill the transaction, the authorization must be reversed to remove the hold on the funds on the cardholder’s account. To do this, the following steps must be taken:
-
Create another EspTransaction object, set the Reversal property to true, set the TransactionId to match the original transaction, set any other required properties, and send it.
NoteThe ReversalType property can optionally be set to REQUEST for online reversal (a 0400 message in ISO 8583 terms). If the ReversalType is not set, or set to ADVICE, it will be an offline reversal (a 0420 message in ISO 8583 terms). -
If the ReversalType is ADVICE, the reversal will be approved, unless a format error or software error has occurred. In such cases, the transaction should be logged for possible exception processing.
-
-
Some merchants might elect to perform the fulfillment stage through an offline batch process and not through eSocket.POS. In this case, the POS application is responsible for generating the settlement files.
-
- NOTE
-
AUTH and CONFIRM are deprecated Types and must no longer be used. These are equivalent to a PURCHASE Type and an AUTH or CONFIRM MessageType.
Refund:
A refund is a request for a refund (credit) against a cardholder’s account, usually when goods are returned. Although proof of purchase is usually required, the refund transaction is not usually linked to the original purchase transaction. A refund can be sent as a Transaction Advice (0220) or as a Transaction Request (0200). Device interaction is only possible if the refund is sent using a Transaction Request (0200).
-
Both methods require the creation of an EspTransaction object and that the Type is set to REFUND.
-
Thereafter, if you wish to send the refund as a Transaction Advice (0220), set the MessageType to CONFIRM. Otherwise, by default, the refund will be sent as a Transaction Request (0200).
-
Lastly, set the required properties, and send the object.
-
If the response is not successful, the refund has been declined.
Referral:
A referral transaction is used to give notice of a transaction that was approved by referral. This usually occurs when the original transaction is declined with a referral response code, and the transaction is then approved using an external authorization process, such as a telephone call. A referral can be a standalone transaction and does not necessarily occur on the same terminal as the original transaction. Since it is an advice message, and the customer may no longer be present, no device interaction is possible. This means that all required fields must be present in the transaction sent to eSocket.POS.
-
Create an EspTransaction object, set the Type to PURCHASE and the MessageType to CONFIRM, set the required properties, and send the object.
-
The referral will be approved, unless a format error or software error occurs. In such cases, the transaction should be logged for possible exception processing.
Note
|
REFERRAL is a deprecated Type and should no longer be used. This is equivalent to a PURCHASE Type and a CONFIRM MessageType. |
2.9.3. Inquiry flows
The EspInquiry object is used for a number of inquiries, including balance, available funds, and card verification.
To perform an inquiry, the application programmer must perform the following steps:
-
create an EspInquiry object, set the required properties, and send the inquiry
-
if the inquiry was successful, unpack the requested information from the response object (e.g. a list of balances for a balance inquiry).
2.9.4. merchandise transaction flows
The EspMerchandise object is used to request a merchandise item, for example a telephone prepay purchase from a merchandise host.
To request merchandise, the application programmer may follow one of two approaches:
Request and Confirm or Reverse:
-
create an EspMerchandise object, set the Type to REQUEST, set the required properties, and send the object.
-
If the response is successful, a tender is required. This may be an EFT tender using eSocket.POS, or a cash or other tender which does not interact with eSocket.POS.
-
If the tender was successful, create a new EspMerchandise object, set the Type to CONFIRM, set the required properties, and send the object. At this stage, information in the original EspMerchandise response may be given to the customer, for instance a PIN for prepay services may be printed on a voucher.
-
If the tender was unsuccessful (the customer was unable to pay), create an EspMerchandise object, set the Type to REVERSE, set the required properties, and send the object.
-
If the REVERSE response is unsuccessful, the merchandise request could not be reversed. This may mean that the merchandise host regards the merchandise as dispensed and will expect payment for it. The steps to be taken in this situation are beyond the scope of eSocket.POS.
-
Procure and possibly Reverse:*
-
create an EspMerchandise object, set the Type to PROCURE, set the required properties, and send the object.
-
If the response is successful, a tender is required. This may be an EFT tender using eSocket.POS, or a cash or other tender which does not interact with eSocket.POS.
-
If the tender was successful, information in the original EspMerchandise response may be given to the customer, for instance a PIN for prepay services may be printed on a voucher. (No CONFIRM message is required.)
-
If the tender was unsuccessful (the customer was unable to pay), create an EspMerchandise object, set the Type to REVERSE, set the required properties, and send the object.
-
If the REVERSE response is unsuccessful, the merchandise request could not be reversed. This may mean that the merchandise host regards the merchandise as dispensed and will expect payment for it. The steps to be taken in this situation are beyond the scope of eSocket.POS.
2.10. Events and callback
2.10.1. Registering for events and callback
In order to receive events or callbacks from eSocket.POS, the POS application must register to receive particular events or callbacks for particular event IDs.
This is done by means of the registerEvent and registerCallback methods, and by providing an object which implements the IEspEventProcessor interface.
The IEspEventProcessor interface provides onEvent and callback methods. A sample implementation of this interface, supporting both events and callback, is given below. The POS application would need to provide the relevant method bodies.
public class EspProcessor implements IEspEventProcessor { public void onEvent(String term_id, String event_id, String data) { System.out.println("EVENT " + event_id + ": '" + data + "'"); } public String callback(String term_id, String event_id, String data) { System.out.print("CALLBACK " + event_id + ": '" + data + "'"); System.out.println(", returning '123'"); return "123"; } }
In order to register for events or callback, the POS application should create a processor and register it to receive events and/or callback as follows:
EspProcessor proc = new EspProcessor(); esp_interface.registerEvent("Term1234", proc , "EVENT_ID_1"); esp_interface.registerCallback("Term1234", proc , "CALL_ID_1");
This means that the POS application will receive any events with the ID EVENT_ID_1 or callbacks with the ID CALL_ID_1 which might be sent by eSocket.POS.
2.10.2. Receiving events and callback
The POS application may register an object implementing the IEspEventProcessor interface to receive events or callbacks with particular event IDs from eSocket.POS.
If it registers in this way, and eSocket.POS sends an event or callback with that particular event ID, the object’s onEvent or callback method will be called.
The POS application is free to handle events and callbacks in any way necessary. It is recommended that the onEvent method return as quickly as possible, so as not to delay the eSocket.POS application. The callback method may require longer, particularly if the return value requires customer or operator interaction.
If the POS does not want to process an event which it receives, it is free to ignore it. If the POS does not want to process a callback which it receives, it should return null .
2.10.3. Sending events and callback
The eSocket.POS API exposes methods which allow the POS application to send events or callbacks to eSocket.POS. These are the onEvent and callback methods on the EspInterface object.
Events use a fire-and-forget model, so the POS will not be aware of whether any internal entity in eSocket.POS has registered to receive the event, or what the results of receiving it were. Events are sent as follows:
esp_interface.onEvent("Term1234", "POS_EVENT", "pos event data");
Callbacks are handled within eSocket.POS by whatever entity has registered to receive the callback. If no entity has registered, null will be returned. Callbacks may take some time to return, for instance if customer interaction is required via an external device. Callbacks are sent as follows:
String rsp = esp_interface.callback("Term1234", "POS_CALLBACK", "pos callback data");
Whether these events or callbacks are handled by eSocket.POS depends on internal entities of eSocket.POS being registered for the particular event IDs used. This will be based on the configuration and customization of eSocket.POS, and should be determined during the integration phase between eSocket.POS and the POS application.
2.11. Reference guide
2.11.1. Reference Guide
The Java API Reference Guide can be found in the zip file dg_esocketpos_java_api.zip which is distributed alongside this document. It describes the specific features of the API more precisely and should be used as the core reference when implementing this API.
Package-postilion.esocketpos.api.html serves as an index of all the files in the Reference Guide.
3. XML Interface
3.1. Overview
The eSocket.POS XML interface provides remote access to eSocket.POS through a message interface based on an XML message format. This may be used when the POS application is not on the same machine as eSocket.POS, or when the POS application is unable to use Java method calls in the eSocket.POS API.
3.1.1. XML message format
The XML interface is based on an XML format which closely mirrors the eSocket.POS API. Message types are represented using XML elements, and the fields within the message are represented as attributes. XML elements representing repeated data sets may also be contained within the message element. For example, a successful inquiry response may contain up to six Esp:Balance elements, which in turn contain attributes with the balance information. In Esp:Transaction or Esp:Inquiry requests, a single purchasing card element may be used to include attributes related to purchasing cards, and this element may in turn include repeated line item, tax amount and contact elements.
Request and response messages use the same XML element, unless an error occurs (see below). Generally, the response message will contain attributes that are related to the response, for example, ActionCode would appear only in an Esp:Transaction response message, and not in the request message.
3.1.2. Initializing and closing
Before sending an EFT request message to the XML interface, an initialization message must be sent to register the terminal with eSocket.POS. When the terminal is finished operating, for instance at the end of the day, it can send a close message to eSocket.POS. These operations use an Esp:Admin request.
The Esp:Admin element takes the place of the init and close methods in the eSocket.POS API. There is no equivalent of the closeAll method.
3.1.3. Errors
If the XML interface is unable to process a message it receives, an Esp:Error response is returned. An example would be a message format error or a message received for an uninitialized terminal ID. If the XML interface is able to process the message, but an application error occurs within the eSocket.POS processing, a normal decline message will be returned of the same type as the request.
The Esp:Error element takes the place of the Java Exceptions that may be thrown when using the API.
3.1.4. MessageInterface DTD
The DTD MessageInterface.dtd is installed along with eSocket.POS and can be viewed with a text editor. Elements and attributes are defined in the Interface Specification section of this document.
Important
|
The subelements of Esp:Transaction, Esp:Inquiry, etc. must appear in the same order in the message as in the DTD. Subelement Esp:PurchasingCardData must appear before the Esp:Balances, and so on. |
3.1.5. Communications protocol
Due to the fact that messages are sent from the POS to eSocket.POS to initiate transaction processing, the message protocol must provide integrity in cases where message transmissions fail. Such failure may occur as a result of network connection failure or corrupted message data.
It is important to realize that any message transmissions from eSocket.POS to the Postilion Realtime engine are not part of this discussion, as eSocket.POS takes care of the message integrity on this leg. For example, if eSocket.POS sends a transaction request to Postilion Realtime, and does not receive a response, eSocket.POS will time out, respond negatively to the POS, and generate a reversal to Postilion Realtime. However, in the case where the POS sends a message to eSocket.POS, and does not receive a response from eSocket.POS, the POS must time out, and generate a reversal message to eSocket.POS.
Transaction requests and responses are communicated with eSocket.POS in XML format, sent using TCP with each message preceded by a length indicator .
3.2. Using Esp:Interface
All messages sent and received via the eSocket.POS XML interface are contained within the Esp:Interface element. A typical message to or from the XML interface will have the following form:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> ... </Esp:Interface>
Within this element, various other elements can be contained to perform the following functions:
-
initializing eSocket.POS to receive transactions for a particular terminal ( Esp:Admin with Type set to 'INIT')
-
closing eSocket.POS for a particular terminal ( Esp:Admin with Type set to 'CLOSE')
-
sending a transaction from a terminal to eSocket.POS ( Esp:Transaction , Esp:Inquiry, Esp:Merchandise , Esp:Network or Esp:Check )
-
sending an event or callback from a terminal to eSocket.POS ( Esp:Event or Esp:Callback )
-
registering a terminal to receive events or callback from eSocket.POS ( Esp:Register element within Esp:Admin )
These elements are dealt with on the subsequent pages of the developer guide.
3.3. TCP messages
Communication between the POS and the XML interface uses a TCP message beginning with a header to indicate the length of the data segment of the message. This header must precede all messages sent to the XML interface, and will be sent at the beginning of all TCP responses from the XML interface.
If the message length is less than 2 16 -1 or 65,535 then a two-byte header will be used.
The first byte of the header contains the quotient of the length of the message (excluding this header) and 256. The second byte contains the remainder of this division. Both these values are represented in binary as unsigned integer values ranging from 0 to 255 (bytes 0x00 to 0xFF).
If the message length is greater than or equal to 2 16 -1 or 65,535 bytes then a six-byte header will be used.
In this case the bytes FF FF should be sent followed by a four-byte length indicator, i.e. six bytes in total.
3.4. Initializing a terminal
Before transactions can be sent from a terminal, the terminal must be initialized with eSocket.POS. This is done via the Esp:Admin element with the Type property set to 'INIT'.
The Terminal ID identifies which terminal parameters to apply, so data for that Terminal ID must be present in the eSocket.POS database before that terminal can be initialized. The Terminal ID must be unique across all the terminals connecting to the upstream Postilion system.
In the case of a POS application controlling a single terminal, the initTerminal method should be called once as follows
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin TerminalId="Term1234" Action="INIT" /> </Esp:Interface>
To indicate that the terminal has been successfully initialized, a response of the following form will be returned:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin Action="INIT" ActionCode="APPROVE" MessageReasonCode="9791" TerminalId="Term1234"></Esp:Admin> </Esp:Interface>
See Terminal administration for a simple example of how to do this.
If the POS application controls more than one POS terminal, each terminal should be initialized in a separate message. This may be done at the discretion of the POS application: either all terminals can be initialized at startup, or terminals can be initialized as they come into action. Unused terminals may be closed using the Esp:Admin element with the Type property set to 'CLOSE' (as described later).
Note that the initialization process is memory and processor intensive and is typically called when the application starts, at the start of the day or after losing the TCP connection. Terminals should not be initialized per transaction.
3.5. Closing a terminal
When no more transactions are required, and a particular terminal is no longer needed, the POS application should close that terminal with eSocket.POS. This is done via the Esp:Admin element with the Type property set to 'CLOSE'.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin TerminalId="Term1234" Action="CLOSE" /> </Esp:Interface>
To indicate that the terminal has been successfully closed, a response of the following form will be returned:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin Action="CLOSE" ActionCode="APPROVE" MessageReasonCode="9791" TerminalId="Term1234"></Esp:Admin> </Esp:Interface>
See Terminal administration for a simple example of how to do this.
Terminals should not normally be closed and reopened between transactions as this process is memory and processor intensive. Typically a terminal should be closed before the POS application terminates, but the POS developer might also decide to close a terminal with eSocket.POS while it is inactive, for instance overnight. The decision about when to close a terminal is left to the POS application developer.
3.6. Handling timeouts
Once a transaction has been sent to eSocket.POS, the response may take a considerable time to be returned, as eSocket.POS may need to interact with the customer via external devices, and wait for an online response.
If no response is received within a reasonable time, the POS application needs to decide whether to ignore this, or to reverse the transaction, or send a repeat. Note that it is not necessary for the POS to handle a timeout if a valid response is received from eSocket.POS (even if the response code indicates a timeout), because in this case, eSocket.POS will take care of the repeat or reversal processing.
Message that timed out | Result |
---|---|
Esp:Inquiry |
Ignore. Inquiries do not have financial impact so no reversal is required. |
Esp:Transaction with Type of PURCHASE, DEPOSIT or REFUND, and MessageType not set or set to AUTH |
Send a reversal. |
Esp:Transaction with Type of ADMIN, CONFIRM or REFERRAL, or MessageType of CONFIRM, or Reversal set. |
Send a repeat of the message. Repeats may be sent indefinitely (until a response is received from eSocket.POS), or limited in number, after which the transaction should be logged by the POS application for exception processing, for instance through an offline process. |
Esp:Check with MessageType not set or set to TRANREQ |
Ignore. Check verifications do not have financial impact so no reversal is required. |
Esp:Check with MessageType of AUTHADV or CONFIRM |
Send a repeat of the message. Refer to notes above about sending repeats indefinitely. |
Esp:Merchandise with Type of REQUEST or PROCURE |
Send a reversal. If the reversal response code indicates that the reversal was unsuccessful, it means the merchandise request could not be reversed. This may mean that the merchandise host regards the merchandise as dispensed and will expect payment for it. The steps to be taken in this situation are beyond the scope of eSocket.POS. |
Esp:Merchandise with Type of REVERSAL |
Send a repeat of the reversal. Refer to notes above about sending repeats indefinitely, and dealing with declined merchandise reversals. |
Esp:Merchandise with Type of CONFIRM |
Send a repeat of the message. |
Esp:Admin |
Send a repeat of the message. |
Esp:Callback |
Continue as if no ResponseData was returned. |
Esp:Event |
Not applicable: events use a fire-and-forget model, and no response is received. |
Note that it is not necessary for the POS to handle the timeout if a valid response is received from eSocket.POS (even if the response code indicates a timeout), because in this case, eSocket.POS will take care of the repeat or reversal processing.
3.7. Error handling
3.7.1. Overview
When an error occurs and the XML interface is unable to process a message, an exception is raised and logged in the Java application, and an error response is returned to the POS application. Errors that may occur include:
-
Attempting to set the property of an object to an invalid value
-
An unsupported transaction type
-
Attempting to send a message on behalf of a non-configured terminal
-
A configuration error
-
A timeout while waiting for a response to a request
-
Errors during initialization
3.7.2. Error messages
Error messages use an Esp:Error element inside the Esp:Interface element, and take the following form:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Error ActionCode="DECLINE" MessageReasonCode="9791" ResponseCode="30" TerminalId="Term1234" TransactionId="123456"></Esp:Error> </Esp:Interface>
In some cases the error response may not include the TerminalId and TransactionId attributes, for instance when an incoming XML message from the POS could not be parsed and these elements could not be extracted.
The error response can also contain a Description attribute, which contains a description of a software exception that occurred during the processing of the message. Typically this occurs when a terminal fails to initialize because the configuration is incorrect or a device is not available. The description contains an indication of the cause, and more complete details will usually be found in the eSocket.POS event log.
3.8. Transactions
3.8.1. Sending a transaction
The eSocket.POS XML interface includes elements and attributes that that can be used to send various types of transactions to eSocket.POS. These transactions are based on the following elements:
-
Esp:Transaction
-
Esp:Inquiry
-
Esp:Merchandise
-
Esp:Check
-
Esp:Reconciliation
-
Esp:Network
A transaction message has the following form:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="Term1234" TransactionAmount="10000" TransactionId="123456" Type="PURCHASE"/> </Esp:Interface>
Other attributes may be set within the Esp:Transaction element depending on what is available on the POS.
The response from eSocket.POS will have the following form:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="10" ActionCode="APPROVE" CardNumber="1111222233334444" CurrencyCode="840" DateTime="0721084817" ExpiryDate="0912" MerchantId="123456 " MessageReasonCode="9790" PanEntryMode="00" PosCondition="00" ResponseCode="91" ServiceRestrictionCode="101" TerminalId="Term1234" Track2="1111222233334444=09121011234" TransactionAmount="10000" TransactionId="123456" Type="PURCHASE"></Esp:Transaction> </Esp:Interface>
The POS application may then extract the attributes in the response, for instance using the ActionCode to determine whether the transaction was approved. Other attributed might be printed on the receipt, saved to the POS database, etc.
3.9. Events and callback
3.9.1. Registering for events and callback
In order to receive events or callbacks from eSocket.POS, the POS application must register to receive particular events or callbacks for particular event IDs.
This is done in the initialization message for that terminal, by including one or more Esp:Register elements inside the initialization Esp:Admin message. This will take the following form:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin TerminalId="Term1234" Action="INIT"><Esp:Register Type="CALLBACK" EventId="CALL_ID_1" /> <Esp:Register Type="EVENT" EventId="EVENT_ID_1" /> </Esp:Admin> </Esp:Interface>
See Terminal administration for a simple example of how to do this.
This means that the POS application will receive any events with the ID EVENT_ID_1 or callbacks with the ID CALL_ID_1 which might be sent by eSocket.POS. These will take the form of additional messages from the XML interface. Depending on which entities within eSocket.POS initiate these events or callbacks, they might occur at any stage during or outside normal transaction processing for an initialized terminal.
3.9.2. Receiving events and callback
The POS application may register with the XML interface in order to receive events or callbacks with particular event IDs from eSocket.POS.
If it registers in this way, and eSocket.POS sends an event or callback with that event ID, the XML interface will send a message to the POS, using the Esp:Event or Esp:Callback element.
An event message will take the following form:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Event TerminalId="TestTerm" EventId="EVENT_ID_1" EventData="event data"/> </Esp:Interface>
The POS may process the event in any way that it chooses, and no response should be sent.
A callback message will take the following form:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="TestTerm" EventId="CALL_ID_1" EventData="callback data"/> </Esp:Interface>
The POS must return a response message to eSocket.POS, of the following form:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="TestTerm" EventId="CALL_ID_1" ResponseData="response data" /> </Esp:Interface>
The POS application may process the callback any way it chooses, but it must return a response containing the ResponseData attribute. If no response data is available, this should be indicated by an empty string inside quotes: ResponseData="". The response may require a certain amount of time, particularly if the return value requires customer or operator interaction. eSocket.POS allows a maximum of 60 seconds, after which an empty return value is assumed.
If the POS does not want to process an event which it receives, it is free to ignore it. If the POS does not want to process a callback which it receives, it must still return a response.
3.9.3. sending events and callback
The eSocket.POS XML interface provides a mechanism to allow the POS application to send events or callbacks to eSocket.POS. These take the form of additional messages using the Esp:Event or Esp:Callback elements inside the main Esp:Interface element.
Events use a fire-and-forget model, so the POS will not be aware of whether any internal entity in eSocket.POS has registered to receive the event, or what the results of receiving it were. Event messages sent to eSocket.POS take the following form:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Event TerminalId="Term1234" EventId="POS_EVENT" EventData="data"/> </Esp:Interface>
Callbacks are handled within eSocket.POS by whatever entity has registered to receive the callback. Callbacks are sent as follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="Term1234" EventId="POS_CALLBACK" EventData="pos callback data" /> </Esp:Interface>
Callbacks may take some time to return, for instance if customer interaction is required via an external device. A callback return message is sent as follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="Term1234" EventId="POS_CALLBACK" ResponseData="response data"/> </Esp:Interface>
If no entity has registered, or no response data is available, the empty string ResponseData="" will be returned.
Whether these events or callbacks are handled by eSocket.POS depends on internal entities of eSocket.POS being registered for the particular event IDs used. This will be based on the configuration and customization of eSocket.POS, and should be determined during the integration phase between eSocket.POS and the POS application.
3.10. POS XML message flow examples
3.10.1. Terminal administration
Introduction
A number of administrative interactions between the POS and eSocket.POS are required during the start-up of the environment, as well as during the shutdown. The message flow here is an example of a successful transaction. The following are possible administrative interactions:
-
Terminal initialization
-
Event and callback registration
-
Terminal close
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends an administration XML message to eSocket.POS containing a terminal initialization, a terminal initialization with event and callback registration, or a terminal close action.
-
eSocket.POS performs the administrative task and responds to the POS to indicate the success or failure of the task.
Note: The registration of events and callbacks occurs in the same message as terminal initialization, and an initialization message may register multiple events and callbacks.
Events and callbacks between the POS device and eSocket.POS
No events and callbacks typically occur during terminal administration messages, as none are typically registered at this time.
For a complete list of all events and callbacks that may be registered with eSocket.POS, see EventId .
XML mappings in a terminal administration message
This section contains the XML properties and values that are typically associated with terminal administration messages. In the Value column, example values are in italics and mandatory values are in bold.
-
Terminal initialization XML message.
Property Condition Value M
TestTerm
M
INIT
-
Terminal initialization with events and callbacks registration XML message.
Property Condition Value M
TestTerm
M
INIT
O
M
EVENT
M
O
M
EVENT
M
O
M
CALLBACK
M
-
Terminal close XML message.
Property Condition Value M
TestTerm
M
CLOSE
For a full list of possible properties in these messages, see Administration Properties .
For an explanation of the Condition column of these tables, see Object and Property Conditions .
Examples of terminal administration XML messages
Three examples are presented.
-
Terminal initialization
-
Terminal initialization with events and callbacks registration
-
Terminal close
The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above for all the examples.
Example 1: Terminal initialization
The POS sends an Admin (request) terminal initialization XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin Action="INIT" TerminalId="TestTerm"> </Esp:Admin> </Esp:Interface>
eSocket.POS initializes the terminal and responds with an Admin (response) XML message [2]:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin Action="INIT" ActionCode="APPROVE" MessageReasonCode="9791" TerminalId="TestTerm"> </Esp:Admin> </Esp:Interface>
Example 2: Terminal initialization with events and callbacks registration
The POS sends an Admin (request) terminal initialization XML message containing events and callbacks to register [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin Action="INIT" TerminalId="TestTerm"> <Esp:Register EventId="CARD_INFO" Type="EVENT"> </Esp:Register> <Esp:Register EventId="PROMPT_SWIPE_CARD" Type="EVENT"> </Esp:Register> <Esp:Register EventId="CARD_INFO" Type="CALLBACK"> </Esp:Register> </Esp:Admin> </Esp:Interface>
eSocket.POS initializes the terminal, registers all specified events and callbacks, and responds with an Admin (response) XML message [2]:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin Action="INIT" ActionCode="APPROVE" MessageReasonCode="9791" TerminalId="TestTerm"> </Esp:Admin> </Esp:Interface>
Example 3: Terminal close
The POS sends an Admin (request) terminal close XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin Action="CLOSE" TerminalId="TestTerm"> </Esp:Admin> </Esp:Interface>
eSocket.POS closes the terminal and responds with an Admin (response) XML message [2]:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Admin Action="CLOSE" ActionCode="APPROVE" MessageReasonCode="9791" TerminalId="TestTerm"> </Esp:Admin> </Esp:Interface>
3.10.2. Network
Introduction
When the POS needs to communicate with an upstream entity, a network transaction can be used. This example is of an echo message from the POS, to check the network connectivity. The POS sends a network message upstream and the first entity able to answer will do so. In this example, it is the Postilion system that sends the response back.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a EspNetwork XML message to eSocket.POS.
-
eSocket.POS sends a network request message (0800) to Postilion.
-
Postilion sends a network response (0810) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a network transaction:
If registered, the following callbacks are called during a network transaction:
-
POS Callback Device callbacks or DATA_REQUIRED (deprecated)
XML mappings in a network transaction
This section contains the XML properties and values that are typically associated with a network transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
198546 |
|
M |
301 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Network Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Examples of network transaction XML messages
Two examples are presented.
-
Echo network transaction
-
EMV CAPK download transaction
Example 1: Echo network transaction This is an example of a network transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
This example is an echo network transaction. This transaction is defined in the value of the NetworkMngInfoCode field.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Network NetworkMngInfoCode="301" TerminalId="TestTerm" TransactionId="198546"> </Esp:Network> </Esp:Interface>
The resulting EspNetwork (response) XML message [4] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Network ActionCode="APPROVE" DateTime="1025205546" LocalDate="1025" LocalTime="225546" MerchantId="111111111111111" MessageReasonCode="9790" NetworkMngInfoCode="301" ResponseCode="00" TerminalId="TestTerm" TransactionId="198546" <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion" </Esp:StructuredData> </Esp:Network> </Esp:Interface>
Example 2: EMV CAPK download transaction This is an example of an EMV CAPK download transaction.
The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
This example is an EMV CAPK download transaction. This transaction is defined in the value of 130 in the NetworkMngInfoCode field.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Network NetworkMngInfoCode="130" TerminalId="TestTerm" TransactionId="198546"> </Esp:Network> </Esp:Interface>
The resulting EspNetwork (response) XML message [4] from eSocket.POS indicating that the requested CAPK records are available, and have been returned: NOTE: See EMV CA Public Key File , outlining the format of the EMV_CA_PKF field. And see EMV CA Public Key File Version , outlining the format of the EMV_FILE_VERSION field.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Network ActionCode="APPROVE" DateTime="1025205546" LocalDate="1025" LocalTime="225546" MerchantId="111111111111111" MessageReasonCode="9791" NetworkMngInfoCode="301" ResponseCode="00" TerminalId="TestTerm" TransactionId="198546" <Esp:StructuredData Name="EMV_FILE_VERSION" Value="031720150000011523006" Name="EMV_CA_PKF" Value="031720150000011523006" </Esp:StructuredData> </Esp:Network> </Esp:Interface>
The resulting EspNetwork (response) XML message [4] from eSocket.POS indicating that the requested CAPK records are not available, and eSocket.POS has scheduled an online retrieval:
NOTE: After the scheduled retrieval has completed successfully, the CAPK_RETRIEVAL_COMPLETE event will be triggered.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Network ActionCode="DECLINE" DateTime="1025205546" LocalDate="1025" LocalTime="225546" MerchantId="111111111111111" MessageReasonCode="9791" NetworkMngInfoCode="301" ResponseCode="06" TerminalId="TestTerm" TransactionId="198546" </Esp:Network> </Esp:Interface>
3.10.3. Device administrative message
Introduction
Device administrative messages are used to send data relating to a device to an upstream entity. Specifically, it sends device registration data and key encryption data.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends an ADMIN_REQUEST (request) XML message to eSocket.POS with a device administration extended transaction type.
-
eSocket.POS sends an administration request (0600) to Postilion.
-
Postilion sends the administration request (0600) upstream.
-
Postilion receives an administration request response (0610) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the administration request response (0610) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Events and callbacks are not displayed in the above diagram.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following callbacks are called to collect data for a device administration message:
XML mappings in a device administration transaction
This section contains the XML properties and values that are typically associated with device administration transactions. In the Value column, example values are in italics and mandatory values are in bold.
Device administration request:
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
170818 |
|
M |
ADMIN |
|
M |
ADMIN_REQUEST |
|
M |
2111 |
Device administration response:
Property | Condition | Value |
---|---|---|
O |
String (Specified as part of EspStructuredData) |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in device administration transaction
This is an example of an administration request transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a Device Administration transaction with an ADMIN (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionId="170818" Type="ADMIN" MessageType="ADMIN_REQUEST" ExtendedTransactionType="2111"> </Esp:Transaction> </Esp:Interface>
When the transaction completes successfully, eSocket.POS sends the ADMIN (response) XML message [6]:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" DateTime="0829200820" ExtendedTransactionType="2111" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" MessageReasonCode="9790" MessageType="ADMIN_REQUEST" PanEntryMode="00" PosCondition="00" PosDataCode="010101054005101" ResponseCode="00" RetrievalRefNr="000000000120" TerminalId="TestTerm" TransactionId="170818" Type="ADMIN"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.10.4. Device Data Capture
Introduction
This section discusses a Device Data capture flow, started at the POS and sent upstream via Postilion for Device data. The example is of a successful transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends an ADMIN (request) XML message to eSocket.POS.
-
eSocket.POS sends a request for device to the connected device.
-
The connected device responds with device information to eSocket.POS.
-
eSocket.POS sends an administrative advice (0620) to Postilion.
-
Postilion sends the administrative advice response (0630) to eSocket.POS.
-
eSocket.POS sends an ADMIN (response) back to the POS. The response includes the retrieved device information.
Note: The eSocket.POS interface sends multiple requests to the PED and Postilion to get the information.
XML mappings in a single message pair Device data capture transaction
This section contains the XML properties and values that are typically associated with a single message pair purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property |
Condition |
Value |
M |
TestTerm |
|
M |
195322 |
|
M |
ADMIN |
|
M |
ADMIN_REQUEST |
|
O |
2113 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
Example: XML messages in a single message pair admin transaction
This is an example of a single message pair purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts an admin transaction with a ADMIN_REQUEST (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionId="195322" Type="ADMIN" MessageType="ADMIN_REQUEST" ExtendedTransactionType="2113" > </Esp:Transaction> </Esp:Interface>
The resulting Device Data Capture (response) XML message [6] from eSocket.POS following the successful completion of the transaction follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ActionCode="APPROVE" BusinessDate="0806" DateTime="0829200820" ExtendedTransactionType="2113" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" MessageReasonCode="9790" MessageType="ADMIN_REQUEST" PanEntryMode="00" PosCondition="00" PosDataCode="010101054005101" ResponseCode="00" RetrievalRefNr="000000000120" TerminalId="TestTerm" TransactionId="195322" Type="ADMIN"> <Esp:StructuredData Name="Term" Value="<?xml version="1.0" encoding="UTF-8"?> <Term> <Poi> <Hw ManufacturingSerial="13333750" HwId="LAN30AA" IPAddress="10.0.2.15" Manuf="Ingenico" Serial="3011087713333750" ModName="L3000"></Hw> <Sw><Mod Ver="0390" Type="os" Name="OS"></Mod><Mod Ver="6.80.10-0033" Type="app" Name="APPLICATION"></Mod></Sw> </Poi></Term>" > </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11. EFT transactions
3.11.1. Balance inquiry
To determine the balance of a cardholder’s account from the POS, a balance inquiry is sent upstream via Postilion. The response that comes back will contain the balance amount in that cardholder’s account at the time of the inquiry.
A balance inquiry is identical to a gift card balance inquiry. Refer to the gift card balance inquiry page for the complete message flow, events and callbacks, XML mappings, and examples.
3.11.2. Barcode reader
Introduction
The eSocket.POS barcode reader feature allows barcode data to be retrieved from a supported and configured barcode reader. The following diagram describes the message flow.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a BARCODE_READER (Enable) callback XML message to eSocket.POS.
-
eSocket.POS enables the barcode reader.
-
eSocket.POS sends the BARCODE_READ (Enable) callback response to the POS.
-
PED sends the scanned barcode data to eSocket.POS.
-
eSocket.POS raises the BARCODE_READ event.
-
POS sends a BARCODE_READER (Disable) callback XML message to eSocket.POS.
-
eSocket.POS disables the barcode reader.
-
eSocket.POS sends the BARCODE_READ (Disable) callback response to the POS.
Note: When using multi-scan mode, multiple barcodes can be scanned until the barcode reader is disabled with the BARCODE_READER (Disable) callback.
After receiving a BARCODE_READ event with BarcodeStatusCode set to 2 - Timeout or 3 - Cancelled, even when in multi-scan mode, the barcode reader will be disabled.
Events and callbacks between the POS device and eSocket.POS
The events and callbacks listed here are typical to this scenario:
The BARCODE_READER callback is used to enable or disable the barcode reader.
The BARCODE_READ event is raised when a barcode is scanned.
XML mappings when reading barcodes
This section contains the XML properties and values that are typically associated with the barcode scanner. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
BARCODE_READER |
|
M |
Enable |
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
BARCODE_READER |
|
M |
Disable |
See Event Properties for a full list of possible properties in these messages.
See Object and Property Conditions for an explanation of the Condition column in this table.
Example: XML messages to enable the barcode reader
The following are examples of enabling and disabling barcode scanning.
Enable barcode in multi-scan mode
This is an example of a successful request to enable the barcode reader. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the message flow diagram.
The POS sends a Callback XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="BARCODE_READER" EventData="Enable"> </Esp:Callback> </Esp:Interface>
eSocket.POS responds with a Callback XML message [3] to the POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback EventId="BARCODE_READER" ResponseData="scanMode:2;readerEnabled:true;OK" TerminalId="SoftTerm"> </Esp:Callback> </Esp:Interface>
Disable barcode scan
The POS sends a Callback XML message [6] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="BARCODE_READER" EventData="Disable"> </Esp:Callback> </Esp:Interface>
eSocket.POS responds with a Callback XML message [8] to the POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback EventId="BARCODE_READER" ResponseData="readerEnabled:false;OK" TerminalId="SoftTerm"> </Esp:Callback> </Esp:Interface>
3.11.3. Card Read Inquiry
Introduction
This retrieves the details of a card that is being read, as configured in eSocket.POS. The card can be read by a PED driven either by eSocket.POS or the POS. In the message flow outlined here, eSocket.POS drives the PED.
Message flow
Refer to the diagram while stepping through the message flow that follows.
-
The POS sends an INQUIRY (request) XML message to eSocket.POS.
-
eSocket.POS sends a card read request to the PED.
-
The PED sends a response, with data read from the card, to eSocket.POS.
-
eSocket.POS sends the appropriate response, with card details, to the POS.
Note: No action is taken on the transaction (display transaction outcome, signature, and so on). eSocket.POS solely returns the card data back to the POS.
CardProductName is always retuned. Depending on the configuration, additional card details are also returned in an embedded EspCardInfo object within the response.
XML mappings in a transaction inquiry
This section contains the XML properties and values that are typically associated with a card read inquiry. In the Value column, example values are shown italics and mandatory values are shown in bold.
Property |
Condition |
Value |
M |
SoftTerm |
|
M |
195322 |
|
M |
CARD_READ |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Inquiry Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a transaction inquiry
This is an example of a card read inquiry where eSocket.POS drives the PED. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the previous diagram.
The POS starts a card read inquiry with a CARD_READ (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry TerminalId="SoftTerm" TransactionId="195322" Type="CARD_READ"> </Esp:Inquiry> </Esp:Interface>
If the card that is read by the PED is configured in eSocket.POS, then all the card-related data is populated in the CARD_READ (response) XML message [4] from eSocket.POS to the POS.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry MessageReasonCode="9791" ResponseCode="00" TransactionId="195322" ActionCode="APPROVE"> CardProductName="DefaultCard"> TerminalId="term1"> Track2="333333*********3339=2101"> Type="CARD_READ"> Type="TRAN_INQUIRY"> <Esp:EspCardInfo CardProductName="DefaultCard"> <Esp:EspAccount DefaultPreauthAmountCtls="1000" DefaultPreauthAmountEmv="1000" DefaultPreauthAmountMsr="1000" EmvFallbackAllowed="FALSE" Name="Savings" PinRequired="TRUE" Type="10"> </Esp:EspAccount> <Esp:EspAccount DefaultPreauthAmountCtls="2000" DefaultPreauthAmountEmv="2000" DefaultPreauthAmountMsr="2000" EmvFallbackAllowed="TRUE" Name="Credit" PinRequired="FALSE" Type="30"> </Esp:EspAccount> <Esp:Extracted Name="MEMBERSHIPID" Value="************"> </Esp:Extracted> </Esp:EspCardInfo> </Esp:Inquiry> </Esp:Interface>
If the card that is read by the PED is not configured in eSocket.POS, then the resulting CARD_READ (response) XML message [4] from eSocket.POS to the POS will be a decline message and will not contain any card information.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry MessageReasonCode="9751" ResponseCode="56" ActionCode="DECLINE"> Track2="333333*********3339=2101"> TransactionId="195322" TerminalId="term1"> Type="CARD_READ"> </Esp:Inquiry> </Esp:Interface>
3.11.4. Card verification inquiry
Introduction
To send the merchant’s intent to store the card details to a network (for example, VISA), a card verification inquiry is started at the POS and sent upstream using Postilion. This section discusses a successful card verification inquiry.
Message flow
The message flow is as follows. View the flow together with the diagram.
-
The POS sends a CARD_VERIFICATION (request) XML message to eSocket.POS.
-
eSocket.POS sends an authorization request (0100) to Postilion.
-
Postilion sends the authorization request (0100) upstream.
-
Postilion receives an authorization request response (0110) from the entity upstream.
-
Postilion sends the authorization request response (0110) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate authorization response (0110) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a card verification inquiry:
If registered, the following callbacks are called during a card verification inquiry:
XML mappings in a card verification inquiry
This section contains the XML properties and values that are typically associated with a card verification inquiry. In the Value column, italics is used to indicate example values. Bold is used to indicate mandatory values.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
CARD_VERIFICATION |
|
O |
000000000354 |
|
O |
PosOp001 |
For information describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Inquiry Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a card verification inquiry
This is an example of a card verification inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram in the "Message flow" section of this page.
The POS starts a card verification inquiry with a CARD_VERIFICATION (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry CardNumber="333333*********3339" CardholderAddress="Cape Town" CurrencyCode="840" ExpiryDate="1912" PanEntryMode="90" PosCondition="08" PostalCode="7449" RetrievalRefNr="000000000072" TerminalId="SoftTerm" Track2="333333*********3339=1912" TransactionAmount="0" TransactionId="172128" Type="CARD_VERIFICATION"> </Esp:Inquiry> </Esp:Interface>
The resulting CARD_VERIFICATION (response) XML message [6] from eSocket.POS following the successful completion of the card verification inquiry:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry Account="10" ActionCode="APPROVE" CardNumber="333333*********3339" CardProductName="DefaultCard" CurrencyCode="840" DateTime="0806061528" LocalDate="0806" LocalTime="081528" MerchantId="000000000000000" MessageReasonCode="9790" PanEntryMode="90" PosCondition="08" PosDataCode="51020125414C002" ResponseCode="00" TerminalId="SoftTerm" Track2="333333*********3339=1912" TransactionAmount="0" TransactionId="172128" Type="CARD_VERIFICATION" <Esp:StructuredData Name="RequestMerchantCategoryCode" Value="1234"> </Esp:StructuredData> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Inquiry> </Esp:Interface>
3.11.5. Check/Cheque verification
Introduction
When a check is presented as payment, a check verification message is used to verify the validity of the check or the account holder. After verifying and accepting the check, it must either be manually deposited at the bank to receive payment or processed as an Electronic Check Conversion (ECC) transaction, where the check is cancelled at the POS and the funds are processed through the ACH network. Below are examples of two kinds of check transactions started at the POS and sent upstream via Postilion for authorization.
-
A successful check verification transaction where the check is deposited manually.
-
A successful Electronic Check Conversion (ECC).
Message flow
Check Verification
Note: For the purposes of this example, a check guarantee (GAURANTEE) request is handled in the same way as a check verification (VERIFICATION) request. It is however handled differently upstream.
Follow the message flow and refer to the diagram. . The POS sends a VERIFICATION (request) XML message to eSocket.POS with the final amount of the transaction. . eSocket.POS sends a purchase request (0200) to Postilion. . Postilion sends the purchase request (0200) upstream. . Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction. . Postilion sends the purchase response (0210) to eSocket.POS. . eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate purchase response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Electronic Check Conversion
Note: For the purposes of this example, an electronic check guarantee (ECCGAURANTEE) and electronic check autorization (ECC) request is handled in the same way as an electronic check verification (ECCVERIFY) request. It is however handled differently upstream.
Follow the message flow and refer to the diagram. . The POS sends an ECCVERIFY (request) XML message to eSocket.POS with the final amount of the transaction. . eSocket.POS sends an authorization request (0100) to Postilion. . Postilion sends the authorization request (0100) upstream. . Postilion receives an authorization response (0110) back from the entity upstream responsible for authorizing the transaction. . Postilion sends the authorization response (0110) to eSocket.POS. . eSocket.POS sends the appropriate response to the POS device. . The POS sends an ECCVERIFY (request) XML message with a MessageType CONFIRM to eSocket.POS. . eSocket.POS sends the appropriate response to the POS device. . eSocket.POS sends a confirmation request (0220) to Postilion. . Postilion sends the confirmation response (0230) to eSocket.POS. . Postilion sends the confirmation request (0220) upstream. . Postilion receives a confirmation response (0230) back from the entity upstream responsible for confirm]ing the transaction.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a check verification transaction:
If registered, the following callbacks are called during a check verification transaction:
XML mappings in a check verification transaction
This section contains the XML properties and values that are typically associated with a check verification transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
146691 |
|
M |
VERIFICATION |
|
O |
TRANREQ |
|
O |
000000000083 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
710 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Check Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages
Check Verification
This is an example of a check verification transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a transaction with a VERIFICATION (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Check MessageType="TRANREQ" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="146691" Type="VERIFICATION"> </Esp:Check> </Esp:Interface>
The resulting VERIFICATION (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Check ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CurrencyCode="710" DateTime="0927115132" ExpiryDate="2012" LocalDate="0927" LocalTime="135132" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" ResponseCode="00" RetrievalRefNr="000000000082" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="146691" Type="VERIFICATION"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Check> </Esp:Interface>
Electronic Check Conversion
This is an example of a electronic check verification transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS sends an authorization transaction with a ECCVERIFY (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Check TerminalId="TestTerm" TransactionAmount="30000" TransactionId="146691" Type="ECCVERIFY"> </Esp:Check> </Esp:Interface>
The resulting ECCVERIFY (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Check ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CurrencyCode="710" DateTime="0927115132" ExpiryDate="2012" ExtendedTransactionType="7112" LocalDate="0927" LocalTime="135132" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" ResponseCode="00" RetrievalRefNr="000000000082" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="146691" Type="ECCVERIFY"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Check> </Esp:Interface>
The POS sends an completion transaction with a ECCVERIFY (request) XML message with MessageType:CONFIRM [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Check TerminalId="TestTerm" TransactionAmount="30000" TransactionId="146691" Type="ECCVERIFY"> MessageType="CONFIRM"> </Esp:Check> </Esp:Interface>
The resulting ECCVERIFY (response) XML message [8] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Check ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CurrencyCode="710" DateTime="0927115132" ExpiryDate="2012" ExtendedTransactionType="7112" LocalDate="0927" LocalTime="135132" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" ResponseCode="00" RetrievalRefNr="000000000082" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="146691" Type="ECCVERIFY"> MessageType="CONFIRM"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Check> </Esp:Interface>
3.11.6. Credit adjustment
Introduction
When a credit adjustment is made from the POS, a credit adjustment transaction is sent upstream for authorization. The credit adjustment transaction credits the amount to the account.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a CREDIT_ADJUSTMENT (request) XML message to eSocket.POS with the amount.
-
eSocket.POS sends a credit adjustment request (0200) to Postilion.
-
Postilion sends the credit adjustment request (0200) upstream.
-
Postilion receives a credit adjustment response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the credit adjustment response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate credit adjustment response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a credit adjustment transaction:
If registered, the following callbacks are called during a credit adjustment transaction:
XML mappings in a credit adjustment transaction
This section contains the XML properties and values that are typically associated with a credit adjustment transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
135265 |
|
M |
CREDIT_ADJUSTMENT |
|
G |
30000 |
|
O |
710 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Example: XML messages in a credit adjustment transaction
This is an example of a credit adjustment transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a credit adjustment with a CREDIT_ADJUSTMENT (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="135265" Type="CREDIT_ADJUSTMENT"> </Esp:Transaction> </Esp:Interface>
The resulting CREDIT_ADJUSTMENT (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="1025" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="1026070745" ExpiryDate="2012" LocalDate="1026" LocalTime="090745" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000009" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="135265" Type="CREDIT_ADJUSTMENT"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.7. Debit adjustment
Introduction
For transactions that are not defined by eSocket.POS, and where a debit is required, a debit adjustment can be used to initiate an adjustment to a cardholders account. An example of this is the scenario where a cheque/check is used for a deposit to a cardholder’s account, but the check is returned unpaid. The deposited funds are reversed with a debit adjustment transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a DEBIT_ADJUSTMENT (request) XML message to eSocket.POS with the card details.
-
eSocket.POS sends a debit adjustment request (0200) to Postilion.
-
Postilion sends the debit adjustment request (0200) upstream.
-
Postilion receives a debit adjustment request response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the debit adjustment request response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate debit adjustment request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a debit adjustment transaction:
If registered, the following callbacks are called during a debit adjustment transaction:
XML mappings in a debit adjustment transaction
This section contains the XML properties and values that are typically associated with debit adjustment transactions. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
159937 |
|
M |
DEBIT_ADJUSTMENT |
|
O |
000000000085 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
710 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a debit adjustment transaction
This is an example of a debit adjustment request transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a debit adjustment transaction with a DEBIT_ADJUSTMENT (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="159937" Type="DEBIT_ADJUSTMENT"> </Esp:Transaction> </Esp:Interface>
The resulting DEBIT_ADJUSTMENT (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="1024062600" ExpiryDate="2012" LocalDate="1024" LocalTime="082600" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000085" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="159937" Type="DEBIT_ADJUSTMENT"> <Esp:Balance AccountType="00" Amount="30000" AmountType="53" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.8. Deposit
Introduction
When a deposit is made into an account from the POS, a deposit transaction is sent upstream for authorization. The deposit transaction debits the amount to the account.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a DEPOSIT (request) XML message to eSocket.POS with the amount.
-
eSocket.POS sends a deposit request (0200) to Postilion.
-
Postilion sends the deposit request (0200) upstream.
-
Postilion receives a deposit request response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the deposit request response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate deposit request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a deposit transaction:
If registered, the following callbacks are called during a deposit transaction:
XML mappings in a deposit transaction
This section contains the XML properties and values that are typically associated with a deposit transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
170809 |
|
M |
DEPOSIT |
|
G |
30000 |
|
O |
710 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Example: XML messages in a deposit transaction
This is an example of a deposit transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a deposit with a DEPOSIT (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170808" Type="DEPOSIT"> </Esp:Transaction> </Esp:Interface>
The resulting DEPOSIT (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0829200729" ExpiryDate="2012" LocalDate="0829" LocalTime="220729" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000101" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170808" Type="DEPOSIT"> </Esp:Transaction> </Esp:Interface>
3.11.9. Line item display
Introduction
The line item display is used to display certain data on the PIN entry device (PED). The following two options are available:
-
The individual items purchased as they are scanned at the point of sale (POS).
-
The result of a transaction that was processed by the POS such as a Purchase Transaction.
Here are examples of the successful display of the 2 types of line item details on the PED.
Scanned item details
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a LINE_ITEM_DISPLAY (start) callback XML message to eSocket.POS.
-
eSocket.POS puts the PED in line item display mode.
-
eSocket.POS sends a PRE_SWIPE (enable) event to eSocket.POS if the scanAhead parameter is set to ON.
-
eSocket.POS sends the display configuration back to the POS.
-
The POS sends a LINE_ITEM_DISPLAY (first scanned item details) callback XML message to eSocket.POS.
-
eSocket.POS displays the line item details on the PED.
-
The POS sends a LINE_ITEM_DISPLAY (second scanned item details) callback XML message to eSocket.POS.
-
eSocket.POS displays the line item details on the PED.
-
The POS sends a LINE_ITEM_DISPLAY (end) callback XML message to eSocket.POS.
-
eSocket.POS removes the PED from line item display mode.
-
eSocket.POS sends a PRE_SWIPE (stop_listen) event to eSocket.POS.
Transaction results
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a LINE_ITEM_DISPLAY (start) callback XML message to eSocket.POS.
-
eSocket.POS puts the PED in line item display mode.
-
eSocket.POS sends the display configuration back to the POS.
-
The POS sends a LINE_ITEM_DISPLAY (transaction results) callback XML message to eSocket.POS.
-
eSocket.POS displays the transaction results on the PED.
-
The POS sends a LINE_ITEM_DISPLAY (end) callback XML message to eSocket.POS.
-
eSocket.POS removes the PED from line item display mode.
Events and callbacks between the POS device and eSocket.POS
The events and callbacks listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a line item display:
If registered, the following callbacks are called during a line item display:
XML mappings in a line item display
This section contains the XML properties and values that are typically associated with a line item display. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
LINE_ITEM_DISPLAY |
|
M |
1. lineItemDisplay:start Note: The additionalInfoItems are optional. |
For a full list of possible properties in these messages, see Event Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a line item display
Here are examples of the two possible line item display. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
Scanned line items
The POS starts a line item display with a LINE_ITEM_DISPLAY (start) callback XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="LINE_ITEM_DISPLAY" EventData="lineItemDisplay : start; scanAhead : on; scanAheadMessage : Please Swipe Card;"> </Esp:Callback> </Esp:Interface>
The POS sends a LINE_ITEM_DISPLAY (first scanned item details) callback XML message [5] to eSocket.POS: This message can have the EventData in two different formats:
Format 1:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="LINE_ITEM_DISPLAY" EventData='lineItemDisplay : itemDetail; formattedItemDisplayLine :"itemNum : 1 ; quantity : 1 ; unitPrice : 10.21 ; lineTotal : 10.21 ; " " voided : True ; itemDescription : Item 1 ;" "34.32" '> </Esp:Callback> </Esp:Interface>
Format 2:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="LINE_ITEM_DISPLAY" EventData="lineItemDisplay : itemDetail; itemNum : 1 ; quantity : 1 ; unitPrice : 10.21 ; lineTotal : 10.21 ; voided : True ; itemDescription : Item 1 ; subtotal : 34.32 ;"> </Esp:Callback> </Esp:Interface>
The POS completed a line item display with a LINE_ITEM_DISPLAY (end) callback XML message [9] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="LINE_ITEM_DISPLAY" EventData="lineItemDisplay : end;"> </Esp:Callback> </Esp:Interface>
Transaction Results
The POS starts a line item display with a LINE_ITEM_DISPLAY (start) callback XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="LINE_ITEM_DISPLAY" EventData="lineItemDisplay : start; "> </Esp:Callback> </Esp:Interface>
The POS sends a LINE_ITEM_DISPLAY (transaction result) callback XML message [4] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="LINE_ITEM_DISPLAY" EventData='lineItemDisplay : tranResult; formattedItemDisplayLine :"The card authorization was successful" '> </Esp:Callback> </Esp:Interface>
The POS completed a line item display with a LINE_ITEM_DISPLAY (end) callback XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="LINE_ITEM_DISPLAY" EventData="lineItemDisplay : end;"> </Esp:Callback> </Esp:Interface>
3.11.10. Pay At Table initialization
Introduction
The Pay At Table initialization is used to initialize a transaction from the PIN entry device (PED). The example below describes the message flow.
Message flow
Follow the message flow and refer to the diagram.
-
eSocket.POS displays the Pay At Table start screen.
-
The start button is pressed on the PED.
-
eSocket.POS sends a card swipe request for the employee ID.
-
PED sends the employee card data to eSocket.POS.
-
eSocket.POS sends a PAY_AT_TABLE_INIT callback XML message to the POS.
-
The Pos sends a response for the PAY_AT_TABLE_INIT callback message to eSocket.POS
-
eSocket.POS displays the Pay At Table result on the PED.
Events and callbacks between the POS device and eSocket.POS
The events and callbacks listed here are a sub-set of the total list possible and are typical to this scenario.
The PAY_AT_TABLE_INIT callback is used to send the employee ID to the POS for processing.
XML mappings in a Pay At Table initialization
This section contains the XML properties and values that are typically associated with a Pay At Table initialization. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
PAY_AT_TABLE_INIT |
|
M |
CashierID=12345678 |
For a full list of possible properties in these messages, see Event Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML message in a Pay At Table initialization
Pay At Table initialization
The eSocket.POS starts a Pay At Table initialization with a PAY_AT_TABLE_INIT callback XML message to the POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="PAY_AT_TABLE_INIT" EventData="cashierID=123456789"> </Esp:Callback> </Esp:Interface>
The POS sends a PAY_AT_TABLE_INIT callback XML message response to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="SoftTerm" EventId="PAY_AT_TABLE_INIT" ResponseData='Success=0;ResponseText=Cashier ID valid'> </Esp:Callback> </Esp:Interface>
3.11.11. Pre-swipe
Introduction
The card pre-swipe is used to obtain card data while store items are still being processed, before the POS enters tender mode. This is an example of a successful pre-swipe.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PRE_SWIPE (enable) event XML message to eSocket.POS.
-
eSocket.POS sends a PROMPT_READY_FOR_SWIPE event XML message to the POS for magstripe pre-swipe environments. For enviroments that support EMV pre-swipe/pre-reads, eSocket.POS sends a PROMPT_READY_FOR_CARD_READ event.
-
After successfully obtaining the card data, eSocket.POS sends a CARD_READ event XML message to the POS.
Events and callbacks between the POS device and eSocket.POS
The events and callbacks listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are raised during a pre-swipe:
-
PROMPT_READY_FOR_SWIPE or PROMPT_READY_FOR_CARD_READ , depending on whether the environment supports magstripe-only pre-swipe or EMV pre-swipe.
If registered, the following callbacks are called during a pre-swipe:
-
POS Callback Device callbacks or DATA_REQUIRED (deprecated)
XML mappings in a pre-swipe
This section contains the XML properties and values that are typically associated with a pre-swipe. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
PRE_SWIPE |
|
O |
Enable |
For a full list of possible properties in these messages, see Event Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a pre-swipe
This is an example of a pre-swipe. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a pre-swipe with a PRE_SWIPE (Enable) event XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Event TerminalId="SoftTerm" EventId="PRE_SWIPE" EventData="Enable"> </Esp:Event> </Esp:Interface>
The PROMPT_READY_FOR_SWIPE event XML message [2] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Event TerminalId="SoftTerm" EventId="PROMPT_READY_FOR_SWIPE" EventData=""> </Esp:Event> </Esp:Interface>
The resulting CARD_READ event XML message [3] from eSocket.POS following a successful read of the card data:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Event TerminalId="SoftTerm" EventId="CARD_READ" EventData="PanEntryMode='90'"> </Esp:Event> </Esp:Interface>
3.11.12. Prompt request
Introduction
This example describes the typical flow resulting from a set of prompts being sent by the point of sale (POS) to eSocket.POS. eSocket.POS processes these prompts and sends them, one prompt request at a time, to the PIN-entry device (PED). When it has received all the prompt responses from the PED, it populates the message with the retrieved data, and sends it upstream for further processing.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends an ADMIN request to eSocket.POS which contains a Prompts XML string.
-
eSocket.POS then generates an administrative request (0600 message) with an Extended Transaction Type field set to '4300' (Customer Prompt), populating its StructuredData field with the Prompts XML. eSocket.POS sends the first prompt request to the PED.
-
The PED sends back the prompt response.
The process of eSocket.POS sending a prompt request and receiving the response from the PED repeats for items 4-7. The Value attribute of each Prompt element is populated with the prompt response.
-
eSocket.POS sends the 0600 message, which contains the prompts results in the Prompts XML, upstream. Depending on how the Prompts pipeline component is configured, the 0600 message is not sent upstream by default.
-
eSocket.POS expects an administrative response (0610 message) to be sent by the upstream entity.
-
eSocket.POS converts the 0610 message into an ADMIN response which it then sends to the POS.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following event is called during a Prompt request:
XML mappings in a single message prompt request
This section contains the XML properties and values that are typically associated with a Prompt request. In the Value column, example values are in italics and mandatory values are in bold.
-
Prompt request
Property Condition Value M
2121
M
XML String
-
Prompt response
Property Condition Value M
2121
M
XML String
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties and Callback Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a Prompt request
This is an example of a Prompt request. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts the Prompt transaction with an ADMIN (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="2121" MessageType="ADMIN_REQUEST" Type="ADMIN"> <Esp:StructuredData Name="Prompts" Value="<?xml version="1.0"?><Prompts><Prompt Id="1" Name="PromptDlNumber"></Prompt><Prompt Id="2" Name="PromptDlState"></Prompt><Prompt Id="3" Name="PromptSsn"></Prompt></Prompts>"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The resulting ADMIN (response) XML message [10] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="2121" MessageType="ADMIN_REQUEST" ResponseCode="00" Type="ADMIN"> <Esp:StructuredData Name="Prompts" Value="<?xml version="1.0"?><Prompts><Prompt Id="1" Name="PromptDlNumber" Value="1234567"></Prompt><Prompt Id="2" Name="PromptDlState" Value="CA"></Prompt><Prompt Id="3" Name="PromptSsn" Value="98765432"></Prompt></Prompts>"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.13. Purchase with DCC using explicit rate requests
Introduction
In the case where a purchase transaction is eligible for dynamic currency conversion (DCC) , an administration request (i.e. the explicit rate request) is sent before the authorization to retrieve the DCC offer. The message flow here is an example of a DCC offer that is available and accepted by the cardholder on a successful transaction.
Message flow
Follow the message flow (dual message pair) and refer to the diagram.
-
The POS sends a PURCHASE AUTH (request) to eSocket.POS with the final amount of the transaction.
-
eSocket.POS converts the PURCHASE AUTH (request) into an authorization request (0100) and determines that DCC is allowed on transaction (see the DCC pipeline component in the eSocket.POS User Guide for more details). eSocket.POS sends an explicit rate request (0600) to Postilion.
-
Postilion sends a DCC rate request to the DCC provider.
-
Postilion receives a DCC rate response containing a DCC offer from the DCC provider.
-
Postilion sends an explicit rate response (0610) containing a DCC offer to eSocket.POS.
-
eSocket.POS displays the DCC offer to the cardholder on the PED.
-
The cardholder accepts the offer.
-
eSocket.POS updates the following DCC-related fields in the authorization request (0100) before sending it to Postilion:
-
The DCC Status Code (ISO 8583 field 127.48) is updated to reflect the cardholder decision, the host decision and the terminal configuration.
-
The Transaction Amount (field 4) and Transaction Currency Code (field 49) are updated to reflect the cardholder/foreign amount and currency.
-
The DCC Reference Number (field 127.22.CurrencyConvInfo.DccReferenceNumber) is set to the corresponding value received in the explicit rate response (0110) [5].
-
-
Postilion sends the authorization request (0100) upstream.
-
Postilion receives an authorization response (0110) from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the authorization response (0110) to eSocket.POS.
-
eSocket.POS converts this authorization response (0110) into a PURCHASE AUTH (response) and sends it to the POS. The PURCHASE AUTH (response) contains the DCC information, most of which will be included on the printed receipt.
-
The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.
-
eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.
-
Postilion receives the transaction advice request (0220) and sends a transaction advice response (0230) to eSocket.POS.
-
Postilion sends the transaction advice request (0220) upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.
-
Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.
Notes :
-
If the single message pair flow is used for DCC, the message types in steps 1 and 12 are PURCHASE (request) and PURCHASE (response). The message types in steps 8 to 12 are 0200 and 0210, and steps 13 to 18 are absent.
-
If Postilion is the card issuer, the appropriate authorization response (0110) and transaction advice response (0230) is sent from Postilion, and steps 9, 10, 17, and 18 are eliminated. If the PURCHASE AUTH (response) in step 12 is not an approval, the transaction will cease after step 12.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a DCC purchase transaction:
If registered, the following callbacks are called during a DCC purchase transaction:
XML mappings in a DCC purchase transaction
This section contains the XML properties and values that are typically associated with a DCC purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase authorization request XML message.
Property Condition Value M
TestTerm
M
AUTH
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
30000
O
710
-
Purchase confirmation request XML message.
Property Condition Value M
TestTerm
M
CONFIRM
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
2500
O
840
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in these tables, see Object and Property Conditions .
Example: XML messages in a DCC purchase transaction
This is an example of a DCC purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a DCC purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction MessageType="AUTH" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE AUTH (response) XML message [11] from eSocket.POS following the successful completion of the authorization:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="840" DateTime="0906065846" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9790" MessageType="AUTH" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000084" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="2200" TransactionId="114726" Type="PURCHASE" DccStatusCode="YYY" DccProviderRoutingId="12345" DccAcqId="00000000001" DccCardAccptrId="000000000000002" DccTermId="00000003" DccRate="0.766666" DccSrcCurrCode="710" DccSrcCurrAlphaCode="ZAR" DccSrcCurrMinorUnits="2" DccTgtCurrCode="840" DccTgtCurrAlphaCode="USD" DccTgtCurrMinorUnits="2" DccProvider="FEXCO" DccRateSrc="REUTERS INTERBANK RATE" DccTimestamp="20170426T15:35" DccMargRate="0.03" DccDiffOverECB="0.001" DccIsEEA="Y" DccCommRate="0.01" DccSrcAmt="30000" DccTgtAmt="2200" DccExpTimestamp="20170429T15:35" DccRcptTxt1="I recognise I was given the choice of payment currencies. I accept the exchange rate. My decision to pay in my currency is final."> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS sends a PURCHASE CONFIRM (request) XML message [12] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction CurrencyCode="840" MessageType="CONFIRM" TerminalId="TestTerm" TransactionAmount="2200" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE CONFIRM (response) XML message [13] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="840" DateTime="0906065853" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9792" MessageType="CONFIRM" PanEntryMode="90" PosCondition="00" ResponseCode="00" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="2200" TransactionId="114726" Type="PURCHASE" DccStatusCode="YYY" DccProviderRoutingId="12345" DccAcqId="00000000001" DccCardAccptrId="000000000000002" DccTermId="00000003" DccRate="0.766666" DccSrcCurrCode="710" DccSrcCurrAlphaCode="ZAR" DccSrcCurrMinorUnits="2" DccTgtCurrCode="840" DccTgtCurrAlphaCode="USD" DccTgtCurrMinorUnits="2" DccProvider="FEXCO" DccRateSrc="REUTERS INTERBANK RATE" DccTimestamp="20170426T15:35" DccMargRate="0.03" DccDiffOverECB="0.001" DccIsEEA="Y" DccCommRate="0.01" DccSrcAmt="30000" DccTgtAmt="2200" DccExpTimestamp="20170429T15:35" DccRcptTxt1="I recognise I was given the choice of payment currencies. I accept the exchange rate. My decision to pay in my currency is final."> </Esp:Transaction> </Esp:Interface>
3.11.14. Purchase with DCC using implicit rate requests
Introduction
In the case where a purchase transaction is eligible for implicit dynamic currency conversion (DCC), the authorization request will serve as an implicit DCC rate request. The message flow here is an example of an implicit DCC offer that is available and accepted by the cardholder.
Message flow
Follow the message flow (dual message pair) and refer to the diagram.
-
The POS sends a PURCHASE AUTH (request) to eSocket.POS with the final amount of the transaction.
-
eSocket.POS converts the PURCHASE AUTH (request) into an authorization request (0100) and determines that implicit DCC is allowed on transaction (see the DCC pipeline component in the eSocket.POS User Guide for more details). eSocket.POS sends an implicit rate request (0100) to Postilion.
-
Postilion sends a DCC rate request to the DCC provider.
-
Postilion receives a DCC rate response containing a DCC offer from the DCC provider.
-
Postilion sends an implicit rate response (0110) containing a DCC offer to eSocket.POS.
-
eSocket.POS displays the DCC offer to the cardholder on the PED.
-
The cardholder accepts the offer.
-
eSocket.POS updates the following DCC-related fields in the authorization request (0100) before sending it to Postilion:
-
The DCC Status Code (ISO 8583 field 127.48) is updated to reflect the cardholder decision, the host decision and the terminal configuration.
-
The Transaction Amount (field 4) and Transaction Currency Code (field 49) are updated to reflect the cardholder/foreign amount and currency.
-
The DCC Reference Number (field 127.22.CurrencyConvInfo.DccReferenceNumber) is set to the corresponding value received in the implicit rate response (0610) [5].
-
-
Postilion sends the authorization request (0100) upstream.
-
Postilion receives an authorization response (0110) from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the authorization response (0110) to eSocket.POS.
-
eSocket.POS converts this authorization response (0110) into a PURCHASE AUTH (response) and sends it to the POS. The PURCHASE AUTH (response) contains the DCC information, most of which will be included on the printed receipt.
-
The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.
-
eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.
-
Postilion receives the transaction advice request (0220) and sends a transaction advice response (0230) to eSocket.POS.
-
Postilion sends the transaction advice request (0220) upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.
-
Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.
Notes :
-
If the single message pair flow is used for DCC, the message types in steps 1 and 12 are PURCHASE (request) and PURCHASE (response). The message types in steps 8 to 12 are 0200 and 0210, and steps 13 to 18 are absent.
-
If Postilion is the card issuer, the appropriate authorization response (0110) and transaction advice response (0230) is sent from Postilion, and steps 9, 10, 17, and 18 are eliminated. If the PURCHASE AUTH (response) in step 12 is not an approval, the transaction will cease after step 12.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a DCC purchase transaction:
If registered, the following callbacks are called during a DCC purchase transaction:
XML mappings in a DCC purchase transaction
This section contains the XML properties and values that are typically associated with a DCC purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase authorization request XML message.
Property Condition Value M
TestTerm
M
AUTH
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
30000
O
710
-
Purchase confirmation request XML message.
Property Condition Value M
TestTerm
M
CONFIRM
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
2500
O
840
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in these tables, see Object and Property Conditions .
Example: XML messages in a DCC purchase transaction
This is an example of a DCC purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a DCC purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction MessageType="AUTH" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE AUTH (response) XML message [11] from eSocket.POS following the successful completion of the authorization:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="840" DateTime="0906065846" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9790" MessageType="AUTH" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000084" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="2200" TransactionId="114726" Type="PURCHASE" DccStatusCode="YYY" DccProviderRoutingId="12345" DccAcqId="00000000001" DccCardAccptrId="000000000000002" DccTermId="00000003" DccRate="0.766666" DccSrcCurrCode="710" DccSrcCurrAlphaCode="ZAR" DccSrcCurrMinorUnits="2" DccTgtCurrCode="840" DccTgtCurrAlphaCode="USD" DccTgtCurrMinorUnits="2" DccProvider="FEXCO" DccRateSrc="REUTERS INTERBANK RATE" DccTimestamp="20170426T15:35" DccMargRate="0.03" DccDiffOverECB="0.001" DccIsEEA="Y" DccCommRate="0.01" DccSrcAmt="30000" DccTgtAmt="2200" DccExpTimestamp="20170429T15:35" DccRcptTxt1="I recognise I was given the choice of payment currencies. I accept the exchange rate. My decision to pay in my currency is final."> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS sends a PURCHASE CONFIRM (request) XML message [12] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction CurrencyCode="840" MessageType="CONFIRM" TerminalId="TestTerm" TransactionAmount="2200" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE CONFIRM (response) XML message [13] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="840" DateTime="0906065853" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9792" MessageType="CONFIRM" PanEntryMode="90" PosCondition="00" ResponseCode="00" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="2200" TransactionId="114726" Type="PURCHASE" DccStatusCode="YYY" DccProviderRoutingId="12345" DccAcqId="00000000001" DccCardAccptrId="000000000000002" DccTermId="00000003" DccRate="0.766666" DccSrcCurrCode="710" DccSrcCurrAlphaCode="ZAR" DccSrcCurrMinorUnits="2" DccTgtCurrCode="840" DccTgtCurrAlphaCode="USD" DccTgtCurrMinorUnits="2" DccProvider="FEXCO" DccRateSrc="REUTERS INTERBANK RATE" DccTimestamp="20170426T15:35" DccMargRate="0.03" DccDiffOverECB="0.001" DccIsEEA="Y" DccCommRate="0.01" DccSrcAmt="30000" DccTgtAmt="2200" DccExpTimestamp="20170429T15:35" DccRcptTxt1="I recognise I was given the choice of payment currencies. I accept the exchange rate. My decision to pay in my currency is final."> </Esp:Transaction> </Esp:Interface>
3.11.15. Purchase (dual message pair)
Introduction
In the case when a purchase transaction requires authorization before it can be sent, a dual message pair purchase transaction flow can be used. An online authorization request is sent from the POS to determine, amongst other things, if the cardholder’s account contains sufficient funds for the purchase transaction. Once this authorization is received, the purchase transaction can proceed. The message flow here is an example of a successful transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE AUTH (request) to eSocket.POS with the final amount of the transaction.
-
eSocket.POS converts this PURCHASE AUTH (request) into an authorization request (0100) and sends it to Postilion.
-
Postilion sends the authorization request (0100) upstream.
-
Postilion receives an authorization response (0110) from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the authorization response (0110) to eSocket.POS.
-
eSocket.POS converts this authorization response (0110) into a PURCHASE AUTH (response) and sends it to the POS.
-
The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.
-
eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.
-
Postilion receives the transaction advice request and sends a transaction advice response (0230) to eSocket.POS.
-
Postilion sends the transaction advice request (0220) and sends it upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.
-
Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.
Note: If Postilion is the card issuer, the appropriate authorization response (0110) and transaction advice response (0230) is sent from Postilion, and steps 3, 4, 11, and 12 are eliminated. If the PURCHASE AUTH (response) in step 6 is not an approval, the transaction will cease after step 6.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a dual message pair purchase transaction:
If registered, the following callbacks are called during a dual message pair purchase transaction:
XML mappings in a dual message pair purchase transaction
This section contains the XML properties and values that are typically associated with a dual message pair purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase authorization request XML message.
Property Condition Value M
TestTerm
M
AUTH
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
30000
O
710
-
Purchase confirmation request XML message.
Property Condition Value M
TestTerm
M
CONFIRM
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
30000
O
710
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in these tables, see Object and Property Conditions .
Example: XML messages in a dual message pair purchase transaction
This is an example of a dual message pair purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a dual message pair purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction MessageType="AUTH" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE AUTH (response) XML message [6] from eSocket.POS following the successful completion of the authorization:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0906065846" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9790" MessageType="AUTH" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000084" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> <Esp:Balance AccountType="00" Amount="30000" AmountType="53" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS sends a PURCHASE CONFIRM (request) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction MessageType="CONFIRM" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE CONFIRM (response) XML message [8] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0906065853" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9792" MessageType="CONFIRM" PanEntryMode="90" PosCondition="00" ResponseCode="00" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
3.11.16. Purchase with consumer-presented QR code
Introduction
This section discusses a QR code transaction, started at the POS and sent upstream via Postilion for authorization. The example is of a successful transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction, QRCodeType field set to a valid QRCodeType, and QRCodeData or BarcodeData.
-
eSocket.POS sends a purchase request (0200) to Postilion Realtime.
-
Postilion Realtime sends the purchase request (0200) upstream.
-
Postilion Realtime receives a purchase response (0210) back from the upstream entity responsible for authorizing the transaction.
-
Postilion Realtime sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a QR code transaction:
If registered, the following callbacks are called during a QR code transaction:
XML mappings in a QR code transaction
This section contains the XML properties and values that are typically associated with a QR code transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property |
Condition |
Value |
M |
SoftTerm |
|
M |
195322 |
|
M |
PURCHASE |
|
M |
PAYPAL_CPQRC |
|
M |
793456782312 |
|
O |
000000000083 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
710 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a QR code transaction
This is an example of a QR code transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a QR code transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE" QRCodeType="PAYPAL_CPQRC" QRCodeData="793456782312" </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0831" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0831064214" ExpiryDate="2012" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000083" ServiceRestrictionCode="***" TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE" QRCodeType="PAYPAL_CPQRC" QRCodeTranId="123456789" QRCodeHostRef="1234567ACDS"> <Esp:Balance AccountType="00" Amount="30000" AmountType="53" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.17. Purchase with merchant-presented QR code
Introduction
This section discusses a merchant-presented QR code transaction, started at the POS and sent upstream via Postilion for processing. The example is of a successful transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS initiates a merchant-presented QR code transaction by sending a QR_CODE_INITIATE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends an admin request (0600) to Postilion Realtime.
-
Postilion Realtime sends the admin response (0610) to eSocket.POS. The response will contain sufficient data for the merchant to display a QR code for the customer.
-
eSocket.POS sends the appropriate response to the POS device.
-
The POS uses the response data to display the QR code.
-
The POS sends a message to check whether the payment was completed using the QR code by sending a QR_CODE_STATUS_REQUEST containing either the TransactionId from the original payment request, or the QRCodeTranId that was received in the original response.
-
eSocket.POS sends an admin request (0600) to Postilion Realtime.
-
Postilion Realtime sends the admin response (0610) to eSocket.POS.
-
If the admin response has a response code of 09 (request in progress) eSocket.POS will repeat sending up the status request until the maximum number of retries have been attempted as per the eSocket.POS configuration.
-
After an admin response with a response code other than 09 (request in progress) is received, eSocket.POS sends the response to the POS.
-
The response code indicates the state of the payment.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following callbacks are called during a merchant-presented QR code transaction:
XML mappings in a merchant-presented QR code transaction
This section contains the XML properties and values that are typically associated with a merchant-presented QR code transaction. In the Value column, example values are in italics and mandatory values are in bold.
XML mappings in a merchant-presented QR code Initiate request
Property |
Condition |
Value |
M |
SoftTerm |
|
G |
30000 |
|
M |
195322 |
|
M |
ACI_URL_MPQRC |
|
M |
QR_CODE_INITIATE |
XML mappings in a merchant-presented QR code Status request
Property |
Condition |
Value |
M |
SoftTerm |
|
C |
195322 |
|
M |
QR_CODE_STATUS_REQUEST |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a merchant-presented QR code transaction
This is an example of a merchant-presented QR code transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
Example: QR code initiate (request)
The POS starts a merchant-presented QR code transaction with a QR code initiate (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="QR_CODE_INITIATE" QRCodeType="ACI_URL_MPQRC" </Esp:Transaction> </Esp:Interface>
The resulting QR code initiate (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Type="QR_CODE_INITIATE" ExtendedTransactionType="2400" CurrencyCode="710" TransactionId="195322" TerminalId="SoftTerm" QRCodeTranId="1234" QRCodeData="https://mycheckout.merchant.com/qrc/somepage?session=1234" QRCodeImage="NzkxMDIzMTk3ODYw" QRCodeType="ACI_URL_MPQRC" <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
Example: QR code status request
The POS sends a message to check whether the payment was completed QR code status request XML message [8] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionId="195322" Type="QR_CODE_STATUS_REQUEST" </Esp:Transaction> </Esp:Interface>
The resulting QR code status request (response) XML message [14] from eSocket.POS following the successful response from upstream:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" Type="QR_CODE_STATUS_REQUEST" ResponseCodequot;00" TerminalId="SoftTerm" ActionCode="APPROVE" PosCondition="00" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" CardNumber="0000000000000000000" DateTime="0829200820" TransactionId="195322" PanEntryMode="00" LocalTime="220820" MessageReasonCode="9790" AuthorizationProfile="11" ExtendedTransactionType="2401" QRCodeTranId="1234" QRCodeType="ACI_URL_MPQRC" <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.18. Purchase with merchant-presented QR code and reversal/void
Introduction
This section discusses a reversal/void for a merchant-presented QR code transaction, started at the POS and sent upstream via Postilion for processing. The example is of a successful transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS initiates a merchant-presented QR code transaction by sending a QR_CODE_INITIATE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends an admin request (0600) to Postilion Realtime.
-
Postilion Realtime sends the admin response (0610) to eSocket.POS. The response will contain sufficient data for the merchant to display a QR code for the customer.
-
eSocket.POS sends the appropriate response to the POS device.
-
The POS uses the response data to display the QR code.
-
The POS sends a message to check whether the payment was completed using the QR code by sending a QR_CODE_STATUS_REQUEST containing either the TransactionId from the original payment request or the QRCodeTranId that was received in the original response.
-
eSocket.POS sends an admin request (0600) to Postilion Realtime.
-
Postilion Realtime sends the admin response (0610) to eSocket.POS.
-
If the admin response has a response code of 09 (request in progress), eSocket.POS will repeat sending up the status request until the maximum number of retries have been attempted as per the eSocket.POS configuration.
-
Once an admin response with a response code other than 09 (request in progress) is received, eSocket.POS sends the response to the POS.
-
The response code indicates the state of the payment.
-
The POS sends a QR code cancelation XML message to eSocket.POS to reverse/cancel the original QR transaction request.
-
eSocket.POS sends a QR code cancelation advice (0620) to Postilion Realtime.
-
Postilion Realtime sends the QR code cancelation advice response (0630) to eSocket.POS.
-
eSocket.POS sends a QR code cancelation response to the POS device.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
The reversal message does not call any events. If registered, the following callbacks are called during a merchant-presented QR code transaction:
XML mappings in a merchant-presented QR code transaction
This section contains the XML properties and values that are typically associated with a merchant-presented QR code transaction. In the Value column, example values are in italics and mandatory values are in bold.
-
Merchant-presented QR code Initiate request
Property
Condition
Value
M
SoftTerm
G
30000
M
195322
M
ACI_URL_MPQRC
M
QR_CODE_INITIATE
-
Merchant-presented QR code Status request
Property
Condition
Value
M
SoftTerm
C
195322
M
QR_CODE_STATUS_REQUEST
-
Reversal transaction
Property
Condition
Value
M
TestTerm
M
195322
M
PURCHASE
C
TRUE
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a merchant-presented QR code transaction
Some examples of merchant-presented QR code transactions are outlined here. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
Example: QR code initiate (request)
The POS starts a merchant-presented QR code transaction with a QR code initiate (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="QR_CODE_INITIATE" QRCodeType="ACI_URL_MPQRC" </Esp:Transaction> </Esp:Interface>
The resulting QR code initiate (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Type="QR_CODE_INITIATE" ExtendedTransactionType="2400" CurrencyCode="710" TransactionId="195322" TerminalId="SoftTerm" QRCodeTranId="1234" QRCodeData="https://mycheckout.merchant.com/qrc/somepage?session=1234" QRCodeImage="NzkxMDIzMTk3ODYw" QRCodeType="ACI_URL_MPQRC" <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
Example: QR code status request
The POS sends a message to check whether the payment was completed with a QR code status request XML message [8] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionId="195322" Type="QR_CODE_STATUS_REQUEST" </Esp:Transaction> </Esp:Interface>
The resulting QR code status request (response) XML message [14] from eSocket.POS following the successful response from upstream:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" Type="QR_CODE_STATUS_REQUEST" ResponseCodequot;00" TerminalId="SoftTerm" ActionCode="APPROVE" PosCondition="00" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" CardNumber="0000000000000000000" DateTime="0829200820" TransactionId="195322" PanEntryMode="00" LocalTime="220820" MessageReasonCode="9790" AuthorizationProfile="11" ExtendedTransactionType="2401" QRCodeTranId="1234" QRCodeType="ACI_URL_MPQRC" <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
Example: QR code reversal (request)
The POS starts a reversal transaction with a PURCHASE (reversal) XML message [12] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="SoftTerm" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (reversal response) XML message [15] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="0000000000000000000" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="00" PosCondition="00" PosDataCode="A1010105434C101" QRCodeTranId="D4C64D28692E758596C3D493AA6DDED8" QRCodeType="ACI_URL_MPQRC" ResponseCode="00" Reversal="TRUE" TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
3.11.19. Purchase with referral
Introduction
This example represents a POS transaction that is declined upstream and returned with a referral response code. The transaction is then approved using an external authorization process, such as a telephone call. To complete the transaction, a referral advice which includes all relevant data must be sent upstream.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion receives a purchase response (0210) - with a referral response code - back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
-
The POS sends a PURCHASE REFERRAL (request) XML message to eSocket.POS with the relevant data and transaction amount.
-
eSocket.POS sends the appropriate response to the POS device.
-
eSocket.POS generates a referral advice request (0220) and sends it to Postilion. eSocket.POS will resend the referral advice request (0220) to Postilion until it receives a response.
-
Postilion receives the referral advice request and sends a referral advice response (0230) to eSocket.POS.
-
Postilion sends the referral advice request (0220) upstream. Postilion will resend the referral advice request (0220) to the network until it receives a response.
-
Postilion receives a referral advice response (0230) from the entity upstream responsible for authorizing the transaction.
Note: If Postilion is the card issuer, the appropriate purchase response (0210) and referral advice response (0230) is sent from Postilion, and steps 3, 4, 11, and 12 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a purchase transaction:
If registered, the following callbacks are called during a purchase transaction:
XML mappings in a purchase transaction with referral
This section contains the XML properties and values that are typically associated with a purchase transaction and referral advice. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase transaction
Property Condition Value M
SoftTerm
M
195322
M
PURCHASE
O
000000000083
O
PosOp001
G
30000
O
710
-
Referral advice
Property Condition Value M
SoftTerm
M
195322
M
PURCHASE
M
REFERRAL
G
30000
O
710
O
000000000083
O
PosOp001
C
123456
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in these tables, see Object and Property Conditions .
Example: XML messages in a purchase transaction with referral
This is an example of a purchase transaction with referral. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction PosOperatorId="PosOp001" RetrievalRefNr="000000000083" TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (response) XML message [6] from eSocket.POS with a referral response code:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="AUTH" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0831" CardProductName="VisaDebit" CurrencyCode="710" DateTime="0831064214" ExpiryDate="2012" LocalDate="0831" LocalTime="084214" MerchantId="311111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="01" RetrievalRefNr="000000000083" TerminalId="SoftTerm" TransactionAmount="0" TransactionId="195322" Type="PURCHASE"> <Esp:Balance AccountType="00" Amount="0" AmountType="53" CurrencyCode="710" Sign="C"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS sends a PURCHASE REFERRAL (request) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction AuthorizationNumber="123456" MessageType="REFERRAL" PosOperatorId="PosOp001" ResponseCode="00" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE REFERRAL (response) XML message [8] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AuthorizationNumber="123456" CardNumber="111122******4444" CardProductName="VisaDebit" CurrencyCode="710" DateTime="0906065853" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="311111111111111" MessageReasonCode="9792" MessageType="REFERRAL" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000084" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
3.11.20. XML - Purchase with timeout and online reversal/void
Introduction
When a purchase transaction at the POS does not receive the required response within a certain time period, the transaction is reversed. This example is of a transaction that is approved upstream via Postilion. The response is received by eSocket.POS, but not by the POS. At the POS, the transaction times out and an online reversal is initiated to reverse the transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion receives a purchase response (0210) back from the upstream entity responsible for authorizing the transaction.
-
Postilion sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS receives the purchase response (0210) and converts this into an appropriate PURCHASE (response) to forward to the POS. The POS times out while waiting for the PURCHASE (response) from eSocket.POS.
-
The POS sends a PURCHASE (Online reversal) to eSocket.POS
-
eSocket.POS generates a Reversal Request (0400) and sends it to Postilion.
-
Postilion receives a Reversal Request(0400) and generates an Online Reversal Response(410).
-
Postilion sends an Online Reversal Response(410) back to eSocket.POS.
-
eSocket.POS receives an Online Reversal Response(410) and sends it to the POS.
-
The POS receives an Online Reversal Response(410).
For more information on handling timeouts, see XML - handling timeouts.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the full list and are typical to this scenario.
If registered, the following events are called during a purchase transaction:
If registered, the following callbacks are called during a purchase transaction:
XML mappings in a purchase transaction timeout and reversal
The first table contains the XML properties and values that are typically associated with a purchase transaction. The second table contains the XML properties and values that are typically associated with a reversal request. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase transaction
Property
Condition
Value
M
SoftTerm
M
195322
M
PURCHASE
O
000000000083
O
PosOp001
G
30000
O
710
-
Reversal request
Property
Condition
Value
M
SoftTerm
M
195322
M
PURCHASE
O
TRUE
O
REQUEST
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in the above tables, see Object and Property Conditions .
Example: XML messages in a purchase transaction timeout and reversal
This is an example of a purchase transaction timeout and reversal. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The POS starts a reversal request with a PURCHASE (reversal) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="SoftTerm" TransactionId="195322" Type="PURCHASE" ReversalType="REQUEST"> </Esp:Transaction> </Esp:Interface>
An example of the resulting PURCHASE (reversal response) XML message [8] from eSocket.POS follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0831064214" ExpiryDate="2012" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="90" PosCondition="00" ResponseCode="00" Reversal="TRUE" ServiceRestrictionCode="***" TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE" ReversalType="REQUEST"> </Esp:Transaction> </Esp:Interface>
3.11.21. Purchase with Signature capture
Introduction
This section discusses a purchase transaction with signature capture. eSocket.POS determines if a signature is required, while processing an approved response (0110/0210/0230). If a signature is required, eSocket.POS sends a SIGNATURE_PROMPT event indicating that it will attempt to capture the cardholder’s signature. The captured signature data is sent upstream before completing the transaction.
This example makes use of events and callbacks. It also includes cashback and extended payment scenarios. A cashback is when a cardholder withdraws cash at a POS. An extended payment refers to the option given to cardholders to pay the transaction amount into their account over a number of months (e.g. 6 or 12 months).
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a DATA_REQUIRED (request) callback XML message to the POS to verify the cashback amount.
-
The POS sends a DATA_REQUIRED (response) callback XML message to eSocket.POS with the final cashback amount.
-
eSocket.POS sends a DATA_REQUIRED (request) callback XML message to the POS to determine whether to use extended payment.
-
The POS sends a DATA_REQUIRED (response) callback XML message to eSocket.POS with a valid response.
-
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS sends a SIGNATURE_PROMPT event XML message to the POS.
-
eSocket.POS sends the appropriate response to the POS device.
-
eSocket.POS generates an admin advice (0620) which contains the signature data and sends it to Postilion. eSocket.POS will resend the admin advice to Postilion until it receives a response.
-
Postilion sends an admin advice response (0630) back to eSocket.POS.
-
Postilion forwards the admin advice (0620) to the relevant network. Postilion will resend the admin advice until it receives a response.
-
Postilion receives an admin advice response (0630) from the network.
Note: If Postilion is the card issuer, the appropriate purchase response (0210) and admin advice response (0630) is sent from Postilion, and steps 7, 8, 14 and 15 are eliminated.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a purchase transaction with signature capture:
If registered, the following callbacks are called during a purchase transaction with signature capture:
XML mappings in a single message pair purchase transaction
This section contains the XML properties and values that are typically associated with a purchase transaction with signature capture. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase transaction
Property Condition Value M
TestTerm
M
161499
M
PURCHASE
O
000000000122
O
PosOp001
G
30000
O
710
-
DATA_REQUIRED callback response for cashback amount
Property Condition Value M
TestTerm
M
DATA_REQUIRED
-
1000
-
DATA_REQUIRED callback response for extended payment
Property Condition Value M
TestTerm
M
DATA_REQUIRED
-
FALSE
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties and Callback Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a purchase transaction with signature capture
This is an example of a purchase transaction with signature capture. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts the purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="161499" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
eSocket.POS sends a DATA_REQUIRED (request) callback XML message [2] to the POS to verify the cashback amount:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="TestTerm" EventId="DATA_REQUIRED" EventData="CashbackAmount(3000)"/> </Esp:Interface>
The POS sends a DATA_REQUIRED (response) callback XML message [3] to eSocket.POS with the final cashback amount:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="TestTerm" EventId="DATA_REQUIRED" ResponseData="1000"> </Esp:Callback> </Esp:Interface>
eSocket.POS sends a DATA_REQUIRED (request) callback XML message [4] to the POS to determine whether to use extended payment:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="TestTerm" EventId="DATA_REQUIRED" EventData="IsExtendedPaymentRequired"/> </Esp:Interface>
The POS sends a DATA_REQUIRED (response) callback XML message [5] to eSocket.POS with response data:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Callback TerminalId="TestTerm" EventId="DATA_REQUIRED" ResponseData="FALSE"> </Esp:Callback> </Esp:Interface>
The SIGNATURE_PROMPT event XML message [10] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Event TerminalId="TestTerm" EventId="SIGNATURE_PROMPT" EventData=""/> </Esp:Interface>
The resulting PURCHASE (response) XML message [11] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="30" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="1031" CardProductName="MCCredit" CashbackAmount="1000" CurrencyCode="710" DateTime="1101091819" ExpiryDate="1912" LocalDate="1101" LocalTime="111819" MerchantId="211111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000122" ServiceRestrictionCode="***" SignatureData="Signature Data" SignatureFormat="FMT" TerminalId="TestTerm" TransactionAmount="31000" TransactionId="161499" Type="PURCHASE"> <Esp:Balance AccountType="30" Amount="31000" AmountType="53" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:Balance AccountType="30" Amount="1000" AmountType="40" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.22. Purchase (single message pair)
Introduction
This section discusses a single message pair purchase transaction, started at the POS and sent upstream via Postilion for authorization. The example is of a successful transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate purchase response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a single message pair purchase transaction:
If registered, the following callbacks are called during a single message pair purchase transaction:
XML mappings in a single message pair purchase transaction
This section contains the XML properties and values that are typically associated with a single message pair purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
PURCHASE |
|
O |
000000000083 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
710 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a single message pair purchase transaction
This is an example of a single message pair purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a single message pair purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0831" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0831064214" ExpiryDate="2012" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000083" ServiceRestrictionCode="***" TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> <Esp:Balance AccountType="00" Amount="30000" AmountType="53" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.23. Purchase and reversal/void
Introduction
When a purchase transaction is approved and for some reason we need the transaction to be reversed, a reversal is required. The following example describes a purchase transaction, finalized successfully, and then followed by a reversal advice. The example is of a successful transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device. At this stage, the purchase transaction is completed.
-
The POS sends a PURCHASE (reversal) XML message to eSocket.POS to reverse the original request transaction.
-
eSocket.POS sends a PURCHASE (reversal response) to the POS device.
-
eSocket.POS sends a reversal advice (0420) to Postilion.
-
Postilion sends the reversal advice response (0430) to eSocket.POS.
-
Postilion sends the reversal advice (0420) upstream.
-
Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.
Note: If Postilion is the card issuer, the appropriate purchase response (0210) is sent from Postilion, and steps 3 and 4 are eliminated. In this scenario steps 11 and 12 are also eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
The reversal message does not call any events. If registered, the following events are called during a purchase transaction:
The reversal message does not get any callbacks. If registered, the following callbacks are called during a purchase transaction:
XML mappings in a purchase transaction reversal
This section contains the XML properties and values that are typically associated with a purchase transaction. The second table contains the XML properties typically associated with a purchase transaction reversal. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase transaction
Property Condition Value M
TestTerm
M
141790
M
PURCHASE
O
00000000008
O
PosOp001
G
30000
O
710
-
Reversal transaction
Property Condition Value M
TestTerm
M
141790
M
PURCHASE
C
TRUE
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Example: XML messages in a purchase transaction reversal
This is an example of a purchase transaction, followed by a transaction to reverse the purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="141790" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="086082950" ExpiryDate="2012" LocalDate="0806" LocalTime="102950" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="00000000008" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="141790" Type="PURCHASE"> <Esp:Balance AccountType="00" Amount="30000" AmountType="53" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS starts a reversal transaction with a PURCHASE (reversal) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="TestTerm" TransactionId="141790" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0806082951" ExpiryDate="2012" LocalDate="0806" LocalTime="102950" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="90" PosCondition="00" ResponseCode="00" Reversal="TRUE" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="141790" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
3.11.24. Purchase with timeout and reversal/void
Introduction
When a purchase transaction at the POS does not receive the required response within a certain time period, the transaction is reversed. This example is of a transaction that is approved upstream via Postilion. The response is received by eSocket.POS, but not by the POS. At the POS, the transaction times out and a reversal is initiated to reverse the transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS receives the purchase response (0210) and converts this into an appropriate PURCHASE (response) to forward to the POS. The POS times out while waiting for the PURCHASE (response) from eSocket.POS.
-
The POS sends a PURCHASE (reversal) to eSocket.POS to cancel any impact the original purchase request may have had on the cardholder’s account.
-
eSocket.POS generates a PURCHASE (reversal response) and sends it to the POS.
-
eSocket.POS generates a reversal advice (0420) and sends it to Postilion. eSocket.POS will resend the Reversal Advice to Postilion until it receives a response.
-
Postilion sends a reversal advice response (0430) back to eSocket.POS.
-
Postilion forwards the reversal advice (0420) to the relevant network. Postilion will resend the reversal advice until it receives a response.
-
Postilion receives a reversal advice response (0430) from the network.
Note: If Postilion is the card issuer, the appropriate purchase response (0210) and reversal advice response (0430) is sent from Postilion, and steps 3, 4, 11 and 12 are eliminated.
For more information on handling timeouts, refer to XML - handling timeouts .
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a purchase transaction:
If registered, the following callbacks are called during a purchase transaction:
XML mappings in a purchase transaction timeout and reversal
The first table contains the XML properties and values that are typically associated with a purchase transaction. The second table contains the XML properties and values that are typically associated with a reversal advice. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase transaction
Property Condition Value M
SoftTerm
M
195322
M
PURCHASE
O
000000000083
O
PosOp001
G
30000
O
710
-
Reversal advice
Property Condition Value M
SoftTerm
M
195322
M
PURCHASE
O
TRUE
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in the above tables, see Object and Property Conditions .
Example: XML messages in a purchase transaction timeout and reversal
This is an example of a purchase transaction timeout and reversal. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The POS starts a reversal advice with a PURCHASE (reversal) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="SoftTerm" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (reversal response) XML message [8] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0831064214" ExpiryDate="2012" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="90" PosCondition="00" ResponseCode="00" Reversal="TRUE" ServiceRestrictionCode="***" TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
3.11.25. Purchase with Token generation request for online standin with advice
Introduction
In the case where a purchase transaction is eligible for online stand-in, an administration request (create card token) is sent before the authorization to create a card token. The message flow here is an example of online stand-in transaction with a successful token generation.
Message flow
Follow the message flow (dual message pair) and refer to the diagram.
-
The POS sends a PURCHASE AUTH (request) to eSocket.POS with the amount of the transaction lesser than floor limits.
-
eSocket.POS converts the PURCHASE AUTH (request) into an authorization request (0100). Once it determines that the transaction is eligible of online stand-in, it converts the message to authorization advice request(0120) and sends a create card token request (0600) to Postilion.
-
Postilion sends the create card token request to the Token Engine.
-
Postilion receives a create card token response containing a card token from the Token Engine.
-
Postilion sends an create card token response (0610) containing a card token to eSocket.POS.
-
eSocket.POS updates the authorization advice request (0120) with the card token and sends the authorization advice response(0130).It then converts the authorization advice response(0130) to authorization response (0110) and then to PURCHASE AUTH (response) and sends it to the POS. The PURCHASE AUTH (response) contains the card token which will be used in furture transactions.
-
eSocket.POS sends the authorization advice request (0120) to Postilion. eSocket.POS will resend the authorization advice request (0120) to Postilion until it receives a response.
-
Postilion receives the authorization advice request (0120) and sends a authorization advice response (0130) to eSocket.POS.
-
Postilion sends the authorization advice request (0120) upstream. Postilion will resend the authorization advice request (0120) to the network until it receives a response.
-
Postilion receives a authorization advice response (0130) from the entity upstream responsible for authorizing the transaction.
-
The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.
-
eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.
-
Postilion receives the transaction advice request (0220) and sends a transaction advice response (0230) to eSocket.POS.
-
Postilion sends the transaction advice request (0220) upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.
-
Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.
Notes :
-
If the single message pair flow is used, the message types in steps 1 and 6 are PURCHASE (request) and PURCHASE (response). The message types in steps 2 and 6 to 10 are 0200,0220,0230 and 0210, and steps 11 to 16 are absent.
-
If Postilion is the card issuer, the appropriate authorization response (0130) and transaction advice response (0230) is sent from Postilion, and steps 9, 10, 15, and 16 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a purchase transaction:
If registered, the following callbacks are called during a purchase transaction:
XML mappings in a purchase transaction
This section contains the XML properties and values that are typically associated with a purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase authorization request XML message.
Property Condition Value M
TestTerm
M
AUTH
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
30000
O
710
-
Purchase confirmation request XML message.
Property Condition Value M
TestTerm
M
CONFIRM
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
2500
O
710
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in these tables, see Object and Property Conditions .
Example: XML messages is purchase transaction that generates a card token.
This is an example of a purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction MessageType="AUTH" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE AUTH (response) XML message [12] from eSocket.POS following the successful completion of the authorization:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0906065846" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9790" MessageType="AUTH" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000084" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> <Esp:Balance AccountType="00" Amount="30000" AmountType="53" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> <Esp:StructuredData Name="CardToken" Value="7114062501124444"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS sends a PURCHASE CONFIRM (request) XML message [13] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction MessageType="CONFIRM" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE CONFIRM (response) XML message [14] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0906065853" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9792" MessageType="CONFIRM" PanEntryMode="90" PosCondition="00" ResponseCode="00" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> <Esp:StructuredData Name="CardToken" Value="7114062501124444"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.26. Purchase with Token generation request for online standin without advice
Introduction
In the case where a purchase transaction is eligible for online stand-in, an administration request (create card token) is sent before the authorization to create a card token. The message flow here is an example of online stand-in transaction with a successful token generation.
Message flow
Follow the message flow (dual message pair) and refer to the diagram.
-
The POS sends a PURCHASE AUTH (request) to eSocket.POS with the amount of the transaction lesser than floor limits.
-
eSocket.POS converts the PURCHASE AUTH (request) into an authorization request (0100). Once it determines that the transaction is eligible of online stand-in, it approves the transaction and sends a create card token request (0600) to Postilion.
-
Postilion sends the create card token request to the Token Engine.
-
Postilion receives a create card token response containing a card token from the Token Engine.
-
Postilion sends the create card token response (0610) containing a card token to eSocket.POS.
-
eSocket.POS updates the authorization response(0110) with the card token and then coverts it to PURCHASE AUTH (response) and sends it to the POS. The PURCHASE AUTH (response) contains the card token which will be used in furture transactions.
-
The POS sends a PURCHASE CONFIRM (request) to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a PURCHASE CONFIRM (response) to the POS.
-
eSocket.POS generates a transaction advice request (0220) and sends it to Postilion. eSocket.POS will resend the transaction advice request (0220) to Postilion until it receives a response.
-
Postilion receives the transaction advice request (0220) and sends a transaction advice response (0230) to eSocket.POS.
-
Postilion sends the transaction advice request (0220) upstream. Postilion will resend the transaction advice request (0220) to the network until it receives a response.
-
Postilion receives a transaction advice response (0230) from the entity upstream responsible for authorizing the transaction.
Notes :
-
If the single message pair flow is used, the message types in steps 1 and 6 are PURCHASE (request) and PURCHASE (response). The message types in steps 2 and 6 are 0200 and 0210, and steps 7 to 12 are absent.
-
If Postilion is the card issuer, the appropriate transaction advice response (0230) is sent from Postilion, and steps 10 and 11 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a purchase transaction:
If registered, the following callbacks are called during a purchase transaction:
XML mappings in a purchase transaction
This section contains the XML properties and values that are typically associated with a purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.
-
Purchase authorization request XML message.
Property Condition Value M
TestTerm
M
AUTH
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
30000
O
710
-
Purchase confirmation request XML message.
Property Condition Value M
TestTerm
M
CONFIRM
M
114726
M
PURCHASE
O
000000000084
O
PosOp001
G
2500
O
710
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in these tables, see Object and Property Conditions .
Example: XML messages is purchase transaction that generates a card token.
This is an example of a purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a purchase transaction with the PURCHASE AUTH (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction MessageType="AUTH" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE AUTH (response) XML message [6] from eSocket.POS following the successful completion of the authorization:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0906065846" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9790" MessageType="AUTH" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000084" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> <Esp:Balance AccountType="00" Amount="30000" AmountType="53" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> <Esp:StructuredData Name="CardToken" Value="7114062501124444"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS sends a PURCHASE CONFIRM (request) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction MessageType="CONFIRM" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE CONFIRM (response) XML message [8] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0906065853" ExpiryDate="2012" LocalDate="0906" LocalTime="085846" MerchantId="111111111111111" MessageReasonCode="9792" MessageType="CONFIRM" PanEntryMode="90" PosCondition="00" ResponseCode="00" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="114726" Type="PURCHASE"> <Esp:StructuredData Name="CardToken" Value="7114062501124444"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.27. Reconciliation
Introduction
This section discusses a reconciliation transaction, started at the POS and sent upstream to Postilion for authorization. The purpose of the reconciliation transaction is to perform a batch cutover and to determine if the totals maintained by the POS match those maintained by Postilion. The example is of a successful reconciliation.
Note: The reconciliation message is not supported when using eSocket.POS with a dual sink configuration.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a Reconciliation (request) XML message to eSocket.POS.
-
eSocket.POS sends an reconciliation request (0500) to Postilion.
-
Postilion sends the reconciliation response (0510) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If there are transactions in the eSocket.POS store and forward queue, eSocket.POS will queue a 0520 in the store and forward queue instead of sending a 0500 to Postilion. In this scenario, transaction totals will not be sent to the POS. See the reconciliation pipeline component in the eSocket.POS User Guide.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. There are no events and callbacks typically associated to this message.
XML mappings in a reconciliation transaction
This section contains the XML properties and values that are typically associated with a reconciliation transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Reconciliation Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a reconciliation transaction
This is an example of a reconciliation transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a reconciliation transaction with a RECONCILIATION (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Reconciliation TerminalId="SoftTerm" TransactionId="195322" </Esp:Reconciliation> </Esp:Interface>
The resulting RECONCILIATION (response) XML message [4] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Reconciliation ActionCode="APPROVE" CreditsAmount="0" CreditsReversalAmount="0" DateTime="1026105736" DebitsAmount="60000" DebitsReversalAmount="0" LocalDate="1026" LocalTime="125736" MessageReasonCode="9790" NumberOfAuthorizations="0" NumberOfCredits="0" NumberOfCreditsReversal="0" NumberOfDebits="2" NumberOfDebitsReversal="0" NumberOfInquiries="0" ResponseCode="00" SettlementCurrencyCode="840" TerminalId="SoftTerm" TransactionId="195322"> <Esp:NetSettlementAmount Amount="60000" Sign="D"> </Esp:NetSettlementAmount> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Reconciliation> </Esp:Interface>
3.11.28. Refund
Introduction
This section discusses a refund transaction, started at the POS and sent upstream via Postilion for authorization. The example is of a successful refund.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a REFUND (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a refund request (0200) to Postilion.
-
Postilion sends the refund request (0200) upstream.
-
Postilion receives a refund response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the refund response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate refund response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a refund transaction:
If registered, the following callbacks are called during a refund transaction:
XML mappings in a refund transaction
This section contains the XML properties and values that are typically associated with a refund transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
REFUND |
|
O |
000000000083 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
710 |
|
O |
String (Specified as part of EspStructuredData) |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a refund transaction
This is an example of a refund transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a refund transaction with a REFUND (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="REFUND"> </Esp:Transaction> </Esp:Interface>
The resulting REFUND (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0831" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0831064214" ExpiryDate="2012" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000083" ServiceRestrictionCode="***" TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="REFUND"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.29. Signature capture request
Introduction
When the POS requires signature data, it sends a request to the PED via eSocket.POS. The PED prompts for the signature, captures the image, and sends it back to the POS, via eSocket.POS.
Message flow
Follow the message flow and refer to the diagram.
1. The POS sends an ADMIN (request) to eSocket.POS. The message contains a request for signature capture. 2. eSocket.POS generates an admin request (0600) and sends a request to the PED to prompt for a signature. 3. The PED prompts for a signature, captures the data, and sends it back to eSocket.POS. eSocket.POS translates the data to an admin request response (0610). 4. eSocket.POS sends an ADMIN (response) back to the POS. The response includes the signature image data. Note : Transactions that qualify for rapid payment service (RPS) and have an account that is configured for RPS must not request a signature capture.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a signature capture request:
XML mappings in a single message pair signature capture request
This section contains the XML properties and values that are typically associated with a signature capture request. In the Value column, example values are in italics and mandatory values are in bold.
-
Signature capture request
Property Condition Value M
3030
M
String
M
TRUE or FALSE
M
TIFF,JPEG,ASCII, or PNG
M
String
M
String
M
String
M
String
O
YES or NO
O
String
O
String (Specified as part of EspStructuredData)
O
String (Specified as part of EspStructuredData)
-
Signature capture response
Property Condition Value C
3030
C
TRUE or FALSE
C
TRUE or FALSE
C
TRUE or FALSE
C
ACCEPT, CANCEL or CLEAR
C
String of Base64 data
C
String
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties and Callback Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a signature capture request
This is an example of a signature capture request. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts the signature capture transaction with an ADMIN (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="3030" SignatureStandAloneDynamicText="Hello" SignatureImagePassedInResponse="TRUE" SignatureImageFormat="ASCII" SignatureScrollableText="Hello" SignatureCheckbox1Text="Click me" SignatureCheckbox2Text="Select me too" SignatureCheckbox2Text="Select me as well" Type="ADMIN"> MessageType="ADMIN_REQUEST"> <Esp:StructuredData Name="SignatureLineItemText1" Value="line1"> </Esp:StructuredData> <Esp:StructuredData Name="SignatureLineItemText2" Value="line2"> </Esp:StructuredData> <Esp:StructuredData Name="SignatureLineItemText3" Value="line3"> </Esp:StructuredData> <Esp:StructuredData Name="SignatureLineItemTextCount" Value="3"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
If the transaction completes successfully, then the following is the ADMIN (response) XML message [4] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="3030" SignatureCheckbox1State="TRUE" SignatureCheckbox2State="TRUE" SignatureCheckbox3State="TRUE" SignatureButtonValue="ACCEPT" SignatureData="ZjAuXiBfO14gPF9fUyBfPSBfPCBfLCBfLCBfKSBfIS" SignatureFormat="ASCII" Type="ADMIN"> MessageType="ADMIN_REQUEST"> </Esp:Transaction> </Esp:Interface>
Multiple request signature capture using SignatureAdditionalText
When the SignatureAdditionalText field is set to YES, you can initiate a signature capture over multiple request messages. Each message provides different signature details to eSocket.POS.
If SignatureAdditionalText is set to YES, you can set the following fields in the message:
-
Signature capture request
Property Condition Value M
3030
M
String
M
String
M
String
M
String
M
String
O
YES or NO
O
String
O
String (Specified as part of EspStructuredData)
O
String (Specified as part of EspStructuredData)
-
Signature capture response
Property Condition Value C
3030
C
TRUE or FALSE
C
TRUE or FALSE
C
TRUE or FALSE
C
NEXT, CANCEL or CLEAR
Example: XML messages in a signature capture request with additional text
This is an example of a signature capture request using SignatureAdditionalText. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts the signature capture transaction with additional text by sending an ADMIN (request) XML message to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="3030" SignatureAdditionalText="YES" SignatureStandAloneDynamicText="Hello" SignatureScrollableText="This is page 1 of 2" SignatureCheckbox1Text="Click me" SignatureCheckbox2Text="Select me too" SignatureCheckbox3Text="Select me as well" Type="ADMIN"> MessageType="ADMIN_REQUEST"> </Esp:Transaction> </Esp:Interface>
The resulting ADMIN (response) XML message from eSocket.POS indicates the user interaction with the signature capture form, but no signature data is returned in this response:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="3030" SignatureCheckbox1State="TRUE" SignatureCheckbox2State="TRUE" SignatureCheckbox3State="TRUE" SignatureButtonValue="NEXT" Type="ADMIN"> MessageType="ADMIN_REQUEST"> </Esp:Transaction> </Esp:Interface>
The POS must initiate the signature capture transaction with the next and final screen of additional text by sending an ADMIN (request) XML message to eSocket.POS. The SignatureAdditionalText is omitted or set to NO:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="3030" SignatureAdditionalText="NO" SignatureStandAloneDynamicText="Hello" SignatureImagePassedInResponse="TRUE" SignatureImageFormat="ASCII" SignatureScrollableText="This is page 2 of 2" SignatureCheckbox1Text="Click me" SignatureCheckbox2Text="Select me too" SignatureCheckbox3Text="Select me as well" Type="ADMIN"> MessageType="ADMIN_REQUEST"> <Esp:StructuredData Name="SignatureLineItemText1" Value="line1"> </Esp:StructuredData> <Esp:StructuredData Name="SignatureLineItemText2" Value="line2"> </Esp:StructuredData> <Esp:StructuredData Name="SignatureLineItemText3" Value="line3"> </Esp:StructuredData> <Esp:StructuredData Name="SignatureLineItemTextCount" Value="3"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
If the transaction completes successfully, then the ADMIN (response) XML message from eSocket.POS contains the signature data:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="3030" SignatureCheckbox1State="TRUE" SignatureCheckbox2State="TRUE" SignatureCheckbox3State="TRUE" SignatureButtonValue="ACCEPT" SignatureData="ZjAuXiBfO14gPF9fUyBfPSBfPCBfLCBfLCBfKSBfIS" SignatureFormat="ASCII" Type="ADMIN"> MessageType="ADMIN_REQUEST"> </Esp:Transaction> </Esp:Interface>
3.11.30. Signature lookup request
Introduction
Previously captured signature data may be retrieved from the eSocket.POS database at the request of the POS.
Message flow
Follow the message flow and refer to the diagram.
1. The POS sends an ADMIN (request) to eSocket.POS that contains a request for signature lookup. The message is linked, via the transaction ID, to a previous transaction that required signature capture. 2. eSocket.POS sends an ADMIN (response) back to the POS. The response includes the retrieved signature image data.
Events and callbacks between the POS device and eSocket.POS
There are no events and callbacks associated with this message.
XML mappings in a single message pair signature lookup request
This section contains the XML properties and values that are typically associated with a signature lookup request. In the Value column, example values are in italics and mandatory values are in bold.
-
Signature lookup request
Property Condition Value M
3031
M
195322
O
JPEG
If the SignatureImageFormat property is not set, a default value of TIFF will be used. Signature images stored in the eSocket.POS database are encoded in this format.
-
Signature lookup response
Property Condition Value A
3031
A
195322
A
JPEG
A
A string of Base64 data
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a signature lookup request
This is an example of a signature lookup request. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts the signature lookup transaction with an ADMIN (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="3031" TransactionId="195322" SignatureImageFormat="TIFF" Type="ADMIN"> MessageType="ADMIN_REQUEST"> </Esp:Transaction> </Esp:Interface>
The resulting ADMIN (response) XML message [2] from eSocket.POS following the successful retrieval of the signature image data:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="3031" TransactionId="195322" SignatureImageFormat="TIFF" SignatureData="ZjAuXiBfO14gPF9fUyBfPSBfPCBfLCBfLCBfKSBfIS" Type="ADMIN"> MessageType="ADMIN_REQUEST"> </Esp:Transaction> </Esp:Interface>
3.11.31. Token Lookup (TransArmor)
Introduction
This section discusses a token lookup admin transaction, started at the POS and sent upstream via Postilion for authorization. An example of a successful transaction is provided.
Limitations
The token lookup request from the POS is only supported only for TransArmor tokens and not for tokens generated by the Postilion tokenization solution.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a TOKEN_LOOKUP (request) XML message to eSocket.POS.
-
eSocket.POS sends an admin request (0600) to Postilion.
-
Postilion sends the admin request (0600) upstream.
-
Postilion receives an admin response (0610) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the admin response (0610) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the token issuer, the appropriate admin response (0610) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Events and callbacks are typically not associated with this message.
XML mappings in a token lookup transaction
This section contains the XML properties and values that are typically associated with a token lookup transaction. In the Value column, example values are shown in italics and mandatory values are shown in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
TOKEN_LOOKUP |
|
O |
000000000083 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a token lookup transaction
This is an example of a token lookup transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a token lookup transaction with a TOKEN_LOOKUP (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionId="195322" Type="TOKEN_LOOKUP"> </Esp:Transaction> </Esp:Interface>
The resulting TOKEN_LOOKUP (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" BusinessDate="0831" DateTime="0831064214" ExpiryDate="2012" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000083" TerminalId="SoftTerm" TransactionId="195322" Type="TOKEN_LOOKUP"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> <Esp:StructuredData Name="TRANSARMOR_TOKEN" Value="1234567890123"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.32. XML - FSA/HSA Purchase
Introduction
This section discusses a FSA/HSA purchase transaction, started at the POS and sent upstream via Postilion for authorization. The example is of a successful transaction.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS containing healthcare totals.
-
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Events and callbacks are not displayed in the above diagram.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a single message pair purchase transaction:
If registered, the following callbacks are called during a single message pair purchase transaction:
XML mappings for HSA/FSA
This section contains the XML properties and values that are typically associated with a single message pair purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
285078 |
|
M |
PURCHASE |
|
O |
000000000083 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
710 |
|
C |
30000 |
|
O |
15000 |
|
O |
4000 |
|
O |
5000 |
|
C |
15000 |
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a FSA/HSA transaction
This is an example of a single message pair purchase transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a single message pair purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction RtsClinicAmount="15000" RtsDentalAmount="5000" RtsOpticalAmount="6000" RtsPrescriptionAmount="4000" RtsTotalHealthcareAmount="30000" TerminalId="SoftTerm" TransactionAmount="40000" TransactionId="285078" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="10" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" AuthorizationNumber="935030" BusinessDate="0831" CardProductName="FSA" CurrencyCode="840" DateTime="0831064214" ExtendedTransactionType="7111" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" ExpiryDate="2012" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" TerminalId="SoftTerm" TransactionAmount="40000" TransactionId="285078" Type="PURCHASE"> <Esp:Balance AccountType="00" Amount="40000" AmountType="53" CurrencyCode="840" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.11.33. EFT Transaction Inquiry
Introduction
To inquire the status of a transaction previously sent to eSocket.POS after a timeout or any communication failure between eSocket.POS and the POS.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a INQUIRY (request) XML message to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: No action is taken on the transaction (display transaction outcome, signature etc..), eSocket.POS solely returns the transaction data back to the POS in an embedded EspTransaction object within the response.
XML mappings in a transaction inquiry
This section contains the XML properties and values that are typically associated with a transaction inquiry. The values sent here should match the ones for the original transaction being looked up. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
TRAN_INQUIRY |
|
O |
1231235959 |
|
O |
AUTH |
|
O |
PURCHASE |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Inquiry Properties .
If the MessageType is set, only transactions for the given message type will be considered.
If the DateTime is set, only the transaction received at that specific time will be considered.
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a transaction inquiry
This is an example of a transaction inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a transaction inquiry with a TRAN_INQUIRY (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry TerminalId="SoftTerm" TransactionId="195322" DateTime="1231235959" OriginalTransactionType="PURCHASE" Type="TRAN_INQUIRY"> </Esp:Inquiry> </Esp:Interface>
If, the transaction is found, the resulting TRAN_INQUIRY (response) XML message [2] from eSocket.POS will include an instance of Esp:Transaction with the transaction data:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry MessageReasonCode="9790" ResponseCode="00" TransactionId="195322" Type="TRAN_INQUIRY"> OriginalTransactionType="PURCHASE" <Esp:Transaction CardNumber="333333******3339" CurrencyCode="840" ExpiryDate="1912" ResponseCode="00" MessageReasonCode="9790" PanEntryMode="05" RetrievalRefNr="000000000072" FinalAmount="000000000395"> </Esp:Transaction> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Inquiry> </Esp:Interface>
If, the transaction is not found, the resulting TRAN_INQUIRY (response) XML message [2] from eSocket.POS will be a decline message and will not include an Esp:Transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry MessageReasonCode="9720" ResponseCode="25" TransactionId="195322" Type="TRAN_INQUIRY"> </Esp:Inquiry> </Esp:Interface>
If eSocket.POS is busy processing a transaction while the transaction inquiry is received, an error is immediately sent back with response code P3 (Device busy) and message reason code 9647 (Device Currently Busy).
Transaction Inquiry used for token retrieval for offline-approved transactions
If a situation arises where eSocket.POS approves a transaction offline for a particular transaction and neither the TransArmor token nor the card token is returned in Structured Data, in the transaction response to the POS (due to the transaction not reaching Postilion Realtime), then the transaction inquiry mechanism is the recommended approach to retrieve the token after receiving the stand-in advice response from the SINK.
To support this feature, the Transaction Inquiry component must be setup to prioritize advice messages. This is achieved by setting the ADVICE_PRIORITY parameter for the component to give precedence to advice messages over regular requests.
A typical transaction flow for such a scenario would look as follows:
-
eSocket.POS loses connection to Postilion
-
The POS sends a purchase (request) XML message to eSocket.POS
-
eSocket.POS sends the approval response to the POS system. It is important to note that this response will not contain the token since it is not available yet.
-
At this point, the POS system can commence a "polling" procedure where it sends transaction inquiries to eSocket.POS to retrieve a token.
-
If a token is not accessible eSocket.POS will send a response without a token
-
The connection is restored between eSocket.POS and Postilion
-
eSocket.POS retrieves the token from Postilion by sending up a Transaction Advice
-
Transaction Advice Response (processed by Token Server) contains the token
-
The POS system can repeat the "polling" procedure to retrieve a token
-
eSocket.POS can now send a response that contains the token retrieved from Postilion
By following the aforementioned steps, the POS system can retrieve the TransArmor or card token even when initial communication with Postilion Realtime is disrupted or delayed.
NOTE: The TransactionToken Structured Data field can’t be returned to the POS using transaction Inquiries.
Example: TRAN_INQUIRY (response) with a TransArmor token.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry Account="99" ActionCode="APPROVE" CardProductName="DefaultCard" ExtendedTransactionType="2116" MessageReasonCode="9799" ResponseCode="00" TerminalId="term1 " TransactionId="126378" Type="TRAN_INQUIRY"> <Esp:Transaction MessageReasonCode="9790" PanEntryMode="00" PosDataCode="51020105414C002" ResponseCode="00"> <Esp:StructuredData Name="TRANSARMOR_TOKEN" Value="1234567890"> </Esp:StructuredData> </Esp:Transaction> </Esp:Inquiry> </Esp:Interface>
Example: TRAN_INQUIRY (response) with a card token.
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry Account="99" ActionCode="APPROVE" CardProductName="DefaultCard" ExtendedTransactionType="2116" MessageReasonCode="9799" ResponseCode="00" TerminalId="term1 " TransactionId="176394" Type="TRAN_INQUIRY"> <Esp:Transaction AuthorizationNumber="1234 " CardNumber="333333*********3339" CurrencyCode="840" ExpiryDate="2312" FinalAmount="000000002000" MessageReasonCode="9790" PanEntryMode="05" PosDataCode="51020150014C002" ResponseCode="00" RetrievalRefNr="000000000072"> <Esp:StructuredData Name="CardToken" Value="1234567890123"> </Esp:StructuredData> </Esp:Transaction> </Esp:Inquiry> </Esp:Interface>
3.11.34. Terminal Status
Introduction
To inquire the status of a eSocket.POS that serves a terminal.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a INQUIRY (request) XML message to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
XML mappings in a terminal status inquiry
This section contains the XML properties and values that are typically associated with a terminal status inquiry. The values sent here should match the ones for the original terminal status being looked up. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
TERMINAL_STATUS |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Inquiry Properties.
For an explanation of the Condition column in this table, see Object and Property Conditions.
Example: XML messages in a transaction inquiry
This is an example of a transaction inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a transaction inquiry with a TERMINAL_STATUS (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry TerminalId="SoftTerm" TransactionId="195322" Type="TERMINAL_STATUS"> </Esp:Inquiry> </Esp:Interface>
TERMINAL_STATUS (response) XML message [2] from eSocket.POS will return monitoring information regrading the all the entities monitored by eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry MessageReasonCode="9791" ResponseCode="00" TransactionId="195322" Type="TERMINAL_STATUS" TerminalId="SoftTerm" TerminalStatus="000001000000020300#010101010101#Magnetic Stripe Card Reads~1~2|~1 successful~2 reads|#2|1|243|#1"> </Esp:Inquiry> </Esp:Interface>
3.12. Gift card transactions
3.12.1. Gift card activation
Introduction
A gift card must be activated before it is used as a form of payment. This example is of a successful card activation, started at the POS and sent upstream for authorization via Postilion.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a CARD_ACTIVATE (request) XML message to eSocket.POS with the card details.
-
eSocket.POS sends an administration request (0600) to Postilion.
-
Postilion sends the administration request (0600) upstream.
-
Postilion receives an administration request response (0610) back from the entity upstream responsible for authorizing the activation.
-
Postilion sends the administration request response (0610) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate administration request response (0610) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a gift card activation:
If registered, the following callbacks are called during a gift card activation:
XML mappings in a gift card activation
This section contains the XML properties and values that are typically associated with gift card activations. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
170818 |
|
M |
CARD_ACTIVATE |
Note : If the transaction amount is present, it has to be zero (which is equivalent to the amount being absent).
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a gift card activation
This is an example of an administration request. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card activation with a CARD_ACTIVATE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionId="170818" Type="CARD_ACTIVATE"> </Esp:Transaction> </Esp:Interface>
Note : The POS can also populate the transaction amount, but then it has to be zero (which is equivalent to the amount being absent):
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionId="170818" Type="CARD_ACTIVATE" TransactionAmount="0"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_ACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" DateTime="0829200820" ExpiryDate="2012" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000120" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionId="170818" Type="CARD_ACTIVATE"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.12.2. Gift card activation with load
Introduction
This transaction is performed when the purchase of a gift card occurs and funds are loaded to a gift card. The gift card is activated and loaded with the funds.This example is of a successful gift card activation with load amount, started at the POS and sent upstream for authorization via Postilion.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a CARD_ACTIVATE (request) XML message to eSocket.POS with the card details.
-
eSocket.POS sends the Refund request (0200) to Postilion.
-
Postilion sends the Refund request (0200) to upstream.
-
Postilion receives the Refund response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends Refund response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate Refund response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a gift card activation transaction:
If registered, the following callbacks are called during a gift card activation transaction:
XML mappings in a gift card activation with load transaction
This section contains the XML properties and values that are typically associated with gift card activation with load transactions. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
170818 |
|
M |
CARD_ACTIVATE |
|
M |
30000 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a gift card activation transaction
This is an example of an administration request transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card activation transaction with a CARD_ACTIVATE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionId="170818" Type="CARD_ACTIVATE"> TransactionAmount="30000"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_ACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" DateTime="0829200820" ExpiryDate="2012" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000120" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionId="170818" PreviousBalance="450" Type="CARD_ACTIVATE"> TransactionAmount="30000"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.12.3. Gift card activation with load - reversal/void
Introduction
When a gift card is activated and simultaneously loaded with funds and for some reason the activation should not have happened, a reversal is required. The following example describes a gift card which is successfully activated and loaded with funds, and then followed by a reversal advice.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a CARD_ACTIVATE (request) XML message to eSocket.POS with the card details.
-
eSocket.POS sends a general credit request (0200) to Postilion.
-
Postilion sends a general credit request (0200) upstream.
-
Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the general credit request response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
-
The POS sends a CARD_ACTIVATE (reversal) XML message to eSocket.POS to reverse the original request transaction.
-
eSocket.POS sends a CARD_ACTIVATE (reversal response) to the POS device.
-
eSocket.POS sends a reversal advice (0420) to Postilion.
-
Postilion sends the reversal advice response (0430) to eSocket.POS.
-
Postilion sends the reversal advice (0420) upstream.
-
Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.
Note: If Postilion is the card issuer, the appropriate card activate response (0210) is sent from Postilion, and steps 3 and 4 are eliminated. In this scenario steps 11 and 12 are also eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
The reversal message does not call any events. If registered, the following events are called during a card activate transaction:
The reversal message does not get any callbacks. If registered, the following callbacks are called during a card activate transaction:
XML mappings in a card activate transaction reversal
This section contains the XML properties and values that are typically associated with a card activate transaction. The second table contains the XML properties typically associated with a card activate transaction reversal. In the Value column, example values are in italics and mandatory values are in bold.
-
Card activate transaction
Property Condition Value M
TestTerm
M
141790
M
CARD_ACTIVATE
O
00000000008
O
PosOp001
G
30000
O
710
-
Reversal transaction
Property Condition Value M
TestTerm
M
141790
M
30000
M
CARD_ACTIVATE
C
TRUE
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Example: XML messages in a card activate transaction reversal
This is an example of a card activate transaction, followed by a transaction to reverse the card activate transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a card activate transaction with a CARD_ACTIVATE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="141790" Type="CARD_ACTIVATE"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_ACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="086082950" ExpiryDate="2012" LocalDate="0806" LocalTime="102950" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="00000000008" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="141790" Type="CARD_ACTIVATE"> <Esp:Balance AccountType="00" Amount="30000" AmountType="53" CurrencyCode="710" Sign="D"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS starts a reversal transaction with a CARD_ACTIVATE (reversal) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="TestTerm" TransactionId="141790" TransactionAmount="30000" Type="CARD_ACTIVATE"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_ACTIVATE (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0806082951" ExpiryDate="2012" LocalDate="0806" LocalTime="102950" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="90" PosCondition="00" ResponseCode="00" Reversal="TRUE" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="141790" Type="CARD_ACTIVATE"> </Esp:Transaction> </Esp:Interface>
3.12.4. Gift card activation with load timeout
Introduction
A gift card activation with load transaction is used to activate a gift card while simultaneously loading funds onto the gift card. If a gift card activation with load times out before the POS receives a response, the transaction must be reversed. Reversing a gift card activation with load, will reverse both the activation of the gift card and the loading of funds onto the card. This example describes the activation with load timeout and subsequent reversal.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a CARD_ACTIVATE (request) XML message to eSocket.POS with the card details and the final amount to be loaded.
-
eSocket.POS sends a general credit request (0200) to Postilion.
-
Postilion sends the general credit request (0200) upstream.
-
Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the general credit request response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device. However, the response doesn’t reach the POS and a timeout occurs.
-
The POS sends a CARD_ACTIVATE (reversal) XML message to eSocket.POS to reverse the original request transaction.
-
eSocket.POS sends a CARD_ACTIVATE (reversal response) to the POS device.
-
eSocket.POS sends a reversal advice (0420) to Postilion. eSocket.POS will resend the reversal advice (0420) to Postilion until it receives a response.
-
Postilion sends the reversal advice response (0430) to eSocket.POS.
-
Postilion sends the reversal advice (0420) upstream. Postilion will resend the reversal advice (0420) to the network until it receives a response.
-
Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.
Note: If Postilion is the card issuer, the appropriate general credit request response (0210) and reversal advice response (0430) is sent from Postilion, and steps 3, 4, 11, and 12 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a general credit transaction:
If registered, the following callbacks are called during a general credit transaction:
XML mappings in a gift card activation with load timeout
This section contains the XML properties and values that are typically associated with a gift card activation with load timeout. In the Value column, example values are in italics and mandatory values are in bold.
-
Gift card activation with load
Property Condition Value M
TestTerm
M
125872
M
CARD_ACTIVATE
O
30000
O
000000000086
O
PosOp001
-
Gift card activation with load reversal
Property Condition Value M
TestTerm
M
125872
M
CARD_ACTIVATE
C
TRUE
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of these tables, see Object and Property Conditions .
Example: XML messages in a gift card activation with load timeout
This is an example of a gift card activation with load transaction, followed by a transaction to reverse the activation with load when a timeout occurs between eSocket.POS and the POS. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts an general credit request transaction with a CARD_ACTIVATE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionId="125872" Type="CARD_ACTIVATE"> TransactionAmount="30000"> </Esp:Transaction> </Esp:Interface>
The POS starts a reversal transaction with a CARD_ACTIVATE (reversal) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="TestTerm" TransactionId="125872" Type="CARD_ACTIVATE"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_ACTIVATE (reversal response) XML message [8] from eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0913084441" ExpiryDate="2012" ExtendedTransactionType="3100" LocalDate="0913" LocalTime="104440" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="90" PosCondition="00" ResponseCode="00" Reversal="TRUE" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="125872" Type="CARD_ACTIVATE"> </Esp:Transaction> </Esp:Interface>
3.12.5. Gift card load funds
Introduction
This is an example is of a successful funds load to a gift card, performed at the POS and sent upstream for authorization.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a LOAD (request) XML message to eSocket.POS with the amount.
-
eSocket.POS sends a general credit request (0200) to Postilion.
-
Postilion sends the general credit request (0200) upstream.
-
Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the general credit request response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate general credit request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a gift card funds load:
If registered, the following callbacks are called during a gift card funds load:
XML mappings in a gift card funds load
This section contains the XML properties and values that are typically associated with a gift card funds load transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
170822 |
|
M |
LOAD |
|
G |
30000 |
|
O |
710 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Example: XML messages in a gift card funds load
This is an example of a gift card funds load. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card with a LOAD (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170822" Type="LOAD"> </Esp:Transaction> </Esp:Interface>
The resulting LOAD (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0829200907" ExpiryDate="2012" ExtendedTransactionType="6501" LocalDate="0829" LocalTime="220907" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000126" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170822" Type="LOAD"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.12.6. Gift card reversal/void
Introduction
Where a gift card is loaded with money and for some reason the load should not have happened, a reversal is required. The following example describes a gift card, loaded successfully, and then followed by a reversal advice.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a LOAD (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS sends a general credit request (deposit verified by operator) (0200) to Postilion.
-
Postilion sends the general credit request (0200) upstream.
-
Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the general credit request response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device. At this stage, the general credit request transaction is completed.
-
The POS sends a LOAD (reversal) XML message to eSocket.POS to reverse the original request transaction.
-
eSocket.POS sends a LOAD (reversal response) to the POS device.
-
eSocket.POS sends a reversal advice (0420) to Postilion.
-
Postilion sends the reversal advice response (0430) to eSocket.POS.
-
Postilion sends the reversal advice (0420) upstream.
-
Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.
Note: If Postilion is the card issuer, the appropriate general credit request response (0210) and the reversal advice (0420) is sent from Postilion, and steps 3, 4, 11 and 12 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
The reversal message does not call any events. If registered, the following events are called during a gift card load:
The reversal message does not get any callbacks. If registered, the following callbacks are called during a gift card:
XML mappings in a gift card load reversal
This section contains the XML properties and values that are typically associated with a gift card load transaction. The second table contains the XML properties typically associated with a gift card load reversal. In the Value column, example values are in italics and mandatory values are in bold.
-
Gift card load
Property Condition Value M
TestTerm
M
170823
M
LOAD
G
30000
O
710
-
Reversal transaction
Property Condition Value M
TestTerm
M
170823
M
LOAD
C
TRUE
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Example: XML messages in a gift card load reversal
This is an example of a gift card load, followed by a transaction to reverse the load transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card with a LOAD (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170823" Type="LOAD"> </Esp:Transaction> </Esp:Interface>
The resulting LOAD (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0829200910" ExpiryDate="2012" ExtendedTransactionType="6501" LocalDate="0829" LocalTime="220910" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000127" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170823" Type="LOAD"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS starts a reversal transaction with a LOAD (reversal) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="TestTerm" TransactionId="170823" Type="LOAD"> </Esp:Transaction> </Esp:Interface>
The resulting LOAD (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0829200912" ExpiryDate="2012" ExtendedTransactionType="6501" LocalDate="0829" LocalTime="220910" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="90" PosCondition="00" ResponseCode="00" Reversal="TRUE" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170823" Type="LOAD"> </Esp:Transaction> </Esp:Interface>
3.12.7. Gift card unload funds
Introduction
This transaction is performed when funds have to be removed from the gift card account but the account will remain active. This is an example of a successful transaction that removes funds from a gift card account(status remains active), performed at the POS and sent upstream for authorization.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a UNLOAD (request) XML message to eSocket.POS with the amount.
-
eSocket.POS sends a general credit request (0200) to Postilion.
-
Postilion sends the general credit request (0200) upstream.
-
Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the general credit request response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate general credit request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a gift card funds unload:
If registered, the following callbacks are called during a gift card funds unload:
XML mappings in a gift card funds unload
This section contains the XML properties and values that are typically associated with a gift card funds unload transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
170822 |
|
M |
UNLOAD |
|
O |
30000 |
|
O |
710 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Example: XML messages in a gift card funds unload
This is an example of a gift card funds unload. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card with a UNLOAD (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170822" Type="UNLOAD"> </Esp:Transaction> </Esp:Interface>
The resulting UNLOAD (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0829200907" ExpiryDate="2012" ExtendedTransactionType="6501" LocalDate="0829" LocalTime="220907" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000126" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170822" Type="UNLOAD"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.12.8. Gift card unload - reversal/void
Introduction
This transaction is performed when funds were removed from a gift card account(status remains active) and for some reason that should not have happened and hence a reversal is required. This example is of a successful gift card unload, started at the POS and sent upstream for authorization via Postilion and then followed by a reversal advice.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a UNLOAD (request) XML message to eSocket.POS with the amount.
-
eSocket.POS sends a general credit request (0200) to Postilion.
-
Postilion sends the general credit request (0200) upstream.
-
Postilion receives a general credit request response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the general credit request response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
-
The POS sends a UNLOAD (reversal) XML message to eSocket.POS to reverse the original request transaction.
-
eSocket.POS sends a UNLOAD (reversal response) to the POS device.
-
eSocket.POS sends a reversal advice (0420) to Postilion.
-
Postilion sends the reversal advice response (0430) to eSocket.POS.
-
Postilion sends the reversal advice (0420) upstream.
-
Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.
Note: If Postilion is the card issuer, the appropriate general credit request response (0210) and the reversal advice (0420) is sent from Postilion, and steps 3, 4, 11 and 12 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a gift card funds unload:
If registered, the following callbacks are called during a gift card funds unload:
XML mappings in a gift card funds unload
This section contains the XML properties and values that are typically associated with a gift card funds unload transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
170822 |
|
M |
UNLOAD |
|
O |
30000 |
|
O |
710 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Example: XML messages in a gift card funds unload reversal
This is an example of a gift card funds unload, followed by a transaction to reverse the unload transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card with a UNLOAD (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170822" Type="UNLOAD"> </Esp:Transaction> </Esp:Interface>
The resulting UNLOAD (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0829200907" ExpiryDate="2012" ExtendedTransactionType="6501" LocalDate="0829" LocalTime="220907" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000126" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170822" Type="UNLOAD"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS starts a reversal transaction with a UNLOAD (reversal) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="TestTerm" TransactionId="170823" Type="UNLOAD"> </Esp:Transaction> </Esp:Interface>
The resulting UNLOAD (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0829200912" ExpiryDate="2012" ExtendedTransactionType="6501" LocalDate="0829" LocalTime="220910" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="90" PosCondition="00" ResponseCode="00" Reversal="TRUE" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170823" Type="UNLOAD"> </Esp:Transaction> </Esp:Interface>
3.12.9. Gift card activation and refund
Introduction
This transaction is performed when the purchase of a gift card occurs for merchandise returns or unfulfilled orders. The gift card is activated and loaded with the funds. This transaction differs from regular activations in that the customer does not tender funds to provide the value. This example is of a successful gift card refund activation, started at the POS and sent upstream for authorization via Postilion.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a CARD_ACTIVATE_REFUND (request) XML message to eSocket.POS with the card details.
-
eSocket.POS sends the Refund request (0200) to Postilion.
-
Postilion sends the Refund request (0200) to upstream.
-
Postilion receives the Refund response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends Refund response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate Refund response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a gift card activation transaction:
If registered, the following callbacks are called during a gift card activation transaction:
XML mappings in a gift card activation transaction
This section contains the XML properties and values that are typically associated with gift card activation transactions. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
170818 |
|
M |
CARD_ACTIVATE_REFUND |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a gift card activation transaction
This is an example of an administration request transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card activation transaction with a CARD_ACTIVATE_REFUND (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionId="170818" Type="CARD_ACTIVATE_REFUND"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_ACTIVATE_REFUND (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" DateTime="0829200820" ExpiryDate="2012" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000120" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionId="170818" PreviousBalance="450" Type="CARD_ACTIVATE_REFUND"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.12.10. Gift card activation and refund - reversal/void
Introduction
This transaction is performed when the purchase of a gift card occurs for a merchandise returns or unfulfilled orders and for some reason it needs to be reversed. This example is of a successful gift card refund activation, started at the POS and sent upstream for authorization via Postilion and then followed by a reversal advice.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a CARD_ACTIVATE_REFUND (request) XML message to eSocket.POS with the card details.
-
eSocket.POS sends the Refund request (0200) to Postilion.
-
Postilion sends the Refund request (0200) to upstream.
-
Postilion receives the Refund response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends Refund response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
-
The POS sends a CARD_ACTIVATE_REFUND (reversal) XML message to eSocket.POS to reverse the original request transaction.
-
eSocket.POS sends a CARD_ACTIVATE_REFUND (reversal response) to the POS device.
-
eSocket.POS sends a reversal advice (0420) to Postilion.
-
Postilion sends the reversal advice response (0430) to eSocket.POS.
-
Postilion sends the reversal advice (0420) upstream.
-
Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.
Note: If Postilion is the card issuer, the appropriate general credit request response (0210) and the reversal advice (0420) is sent from Postilion, and steps 3, 4, 11 and 12 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
The reversal message does not call any events. If registered, the following events are called during a gift card load:
The reversal message does not get any callbacks. If registered, the following callbacks are called during a gift card:
XML mappings in a gift card activate refund reversal
This section contains the XML properties and values that are typically associated with a gift card activate refund transaction. The second table contains the XML properties typically associated with a gift card activate refund reversal. In the Value column, example values are in italics and mandatory values are in bold.
-
Gift card activate refund reversal
Property Condition Value M
TestTerm
M
170823
M
CARD_ACTIVATE_REFUND
-
Reversal transaction
Property Condition Value M
TestTerm
M
170823
M
CARD_ACTIVATE_REFUND
C
TRUE
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column of this table, see Object and Property Conditions .
Example: XML messages in a gift card activate refund reversal
This is an example of a gift card activate refund , followed by a transaction to reverse of card activate refund transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card with a CARD_ACTIVATE_REFUND (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170823" Type="CARD_ACTIVATE_REFUND"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_ACTIVATE_REFUND (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0829200910" ExpiryDate="2012" ExtendedTransactionType="6501" LocalDate="0829" LocalTime="220910" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000127" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170823" Type="CARD_ACTIVATE_REFUND"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS starts a reversal transaction with a CARD_ACTIVATE_REFUND (reversal) XML message [7] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="TestTerm" TransactionId="170823" Type="CARD_ACTIVATE_REFUND"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_ACTIVATE_REFUND (reversal response) XML message [8] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0829200912" ExpiryDate="2012" ExtendedTransactionType="6501" LocalDate="0829" LocalTime="220910" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="90" PosCondition="00" ResponseCode="00" Reversal="TRUE" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="30000" TransactionId="170823" Type="CARD_ACTIVATE_REFUND"> </Esp:Transaction> </Esp:Interface>
3.12.11. Gift card de-activation
3.12.12. Gift card de-activation
Introduction
This section discusses gift card de-activation, started at the POS and sent upstream via Postilion for authorization. The example is of a successful de-activation.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a CARD_DEACTIVATE (request) XML message to eSocket.POS.
-
eSocket.POS sends an administration request (0600) to Postilion.
-
Postilion sends the administration request (0600) upstream.
-
Postilion receives an administration response (0610) back from the entity upstream.
-
Postilion sends the administration response (0610) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate administration response (0610) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a gift card de-activation:
If registered, the following callbacks are called during a gift card de-activation:
XML mappings in a gift card de-activation
This section contains the XML properties and values that are typically associated with a gift card de-activation. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
375329 |
|
M |
CARD_DEACTIVATE |
|
O |
000000000354 |
|
O |
PosOp001 |
Note : If the transaction amount is present, it has to be zero (which is equivalent to the amount being absent).
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a gift card de-activation.
This is an example of a gift card de-activation. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card de-activation with a CARD_DEACTIVATE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionId="375329" Type="CARD_DEACTIVATE"> </Esp:Transaction> </Esp:Interface>
Note : The POS can also populate the transaction amount, but then it has to be zero (which is equivalent to the amount being absent):
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="SoftTerm" TransactionId="375329" Type="CARD_DEACTIVATE" TransactionAmount="0"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_DEACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the de-activation:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0831" CardProductName="AllOtherCard" DateTime="0831064214" ExpiryDate="2012" ExtendedTransactionType="3101" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000354" ServiceRestrictionCode="***" TerminalId="SoftTerm" TransactionId="375329" Type="CARD_DEACTIVATE"> <Esp:Balance AccountType="00" Amount="50000" AmountType="02" CurrencyCode="710" Sign="C"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.12.13. Gift card deactivation with unload
Introduction
This transaction is performed when the gift card is de-activated following the removal of remaining funds on the card (i.e. cashback). This is an example of a successful transaction that removes remaining funds from a gift card account and then de-activates the card, performed at the POS and sent upstream for authorization.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a CARD_DEACTIVATE (request) XML message to eSocket.POS with the card details and amount.
-
eSocket.POS sends a general debit request (0200) to Postilion.
-
Postilion sends the general debit request (0200) to upstream.
-
Postilion receives a general debit request response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the general debit request response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate general debit request response (0210) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a gift card de-activation with unload transaction:
If registered, the following callbacks are called during a gift card de-activation with unload transaction:
XML mappings in a gift card de-activation with unload transaction
This section contains the XML properties and values that are typically associated with gift card de-activation with unload transactions. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
170818 |
|
M |
CARD_DEACTIVATE |
|
M |
30000 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Transaction Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a gift card de-activation with unload transaction
This is an example of a gift card de-activation with unload transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card de-activation with unload transaction with a CARD_DEACTIVATE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionId="170818" Type="CARD_DEACTIVATE"> TransactionAmount="30000"> </Esp:Transaction> </Esp:Interface>
The resulting CARD_DEACTIVATE (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="AllOtherCard" DateTime="0829200820" ExpiryDate="2012" ExtendedTransactionType="6502" LocalDate="0829" LocalTime="220820" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000120" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionId="170818" Type="CARD_DEACTIVATE" TransactionAmount="30000"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.12.14. Gift card balance inquiry
Introduction
To confirm the funds available on a gift card, a balance inquiry is started at the POS and sent upstream via Postilion. This section discusses a successful balance inquiry.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a BALANCE (request) XML message to eSocket.POS.
-
eSocket.POS sends an authorization request (0100) to Postilion.
-
Postilion sends the authorization request (0100) upstream.
-
Postilion receives an authorization request response (0110) back from the entity upstream.
-
Postilion sends the authorization request response (0110) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Note: If Postilion is the card issuer, the appropriate authorization response (0110) is sent from Postilion, and steps 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, refer to the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during a gift card balance inquiry:
If registered, the following callbacks are called during a gift card balance inquiry:
XML mappings in a gift card balance inquiry
This section contains the XML properties and values that are typically associated with a gift card balance inquiry. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
BALANCE |
|
O |
000000000354 |
|
O |
PosOp001 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Inquiry Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a gift card balance inquiry
This is an example of a gift card balance inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a gift card balance inquiry with a BALANCE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry TerminalId="SoftTerm" TransactionId="195322" Type="BALANCE"> </Esp:Inquiry> </Esp:Interface>
The resulting BALANCE (response) XML message [6] from eSocket.POS following the successful completion of the balance inquiry:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry Account="00" ActionCode="APPROVE" AmountTransactionFee="C0" BusinessDate="0831" CardProductName="AllOtherCard" CurrencyCode="710" DateTime="0831064214" ExpiryDate="2012" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000354" ServiceRestrictionCode="***" TerminalId="SoftTerm" TransactionAmount="0" TransactionId="195322" Type="BALANCE"> <Esp:Balance AccountType="70" Amount="500000" AmountType="01" CurrencyCode="710" Sign="C"> </Esp:Balance> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Inquiry> </Esp:Interface>
3.12.15. Gift card Purchase - reversal/void
Introduction
When a purchase transaction using gift card is approved and for some reason the transaction needs to be reversed, a reversal is required.
A gift card purchase reversal/void is identical to a normal purchase reversal/void. Refer to the Purchase and reversal/void page for the complete message flow, events and callbacks, XML mappings, and examples.
3.13. EBT transactions
3.13.1. XML - EBT balance inquiry
Introduction
To confirm the cash benefit or food stamp account balances available on an EBT card, a balance inquiry is started at the POS and sent upstream via Postilion. In the message flow outlined in this topic, eSocket.POS drives the PED and prompts for the account.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a BALANCE (request) XML message to eSocket.POS.
-
eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS.
-
The cardholder selects the account type.
-
eSocket.POS sends an authorization request (0100) to Postilion.
-
Postilion sends the authorization request (0100) upstream.
-
Postilion receives an authorization request response (0110) back from the entity upstream.
-
Postilion sends the authorization request response (0110) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during an EBT balance inquiry:
If registered, the following callbacks are called during an EBT balance inquiry:
-
POS Callback Device callbacks or DATA_REQUIRED (deprecated)
XML mappings in an EBT balance inquiry
The following table contains the XML properties and values that are typically associated with an EBT balance inquiry request. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
BALANCE |
|
O |
000000000354 |
|
O |
PosOp001 |
The following table contains the XML properties and values specific to an EBT balance inquiry response. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
C |
EBT Response Text |
|
C |
D00000003000 |
|
C |
D00000002500 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Inquiry Properties.
For an explanation of the Condition column in this table, see Object and Property Conditions.
Example: XML messages in an EBT balance inquiry
This is an example of a successful EBT balance inquiry. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts an EBT balance inquiry with a BALANCE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry TerminalId="SoftTerm" TransactionId="195322" Type="BALANCE"> </Esp:Inquiry> </Esp:Interface>
The resulting BALANCE (response) XML message [8] from eSocket.POS following the successful completion of the balance inquiry follows, assuming the benefit type selected by the cardholder was the cash benefit (account type 96):
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry Account="96" ActionCode="APPROVE" AmountTransactionFee="C0" BusinessDate="0831" CardProductName="EbtCard" CurrencyCode="840" DateTime="0831064214" ExpiryDate="2030" LocalDate="0831" LocalTime="084214" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000354" ServiceRestrictionCode="***" TerminalId="SoftTerm" TransactionAmount="0" TransactionId="195322" EbtResponseText="EBT Response Text" EbtAvailableCashBenefitsAccountBalance="D00000002500" Type="BALANCE"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Inquiry> </Esp:Interface>
3.13.2. XML - EBT food stamp purchase with electronic voucher
Introduction
This example represents an EBT food stamp purchase transaction that is declined upstream with response code 91 (host unavailable). The transaction is then approved using an external authorization process, such as a telephone call. To complete the transaction, an EBT food stamp electronic voucher advice, which includes all relevant data, is sent upstream. In the message flow outlined here:
-
eSocket.POS drives the PED and prompts for the account.
-
The timeout occurs between Postilion and the upstream host.
NoteThe timeout can also occur between eSocket.POS and Postilion, or between the POS and eSocket.POS. In the latter case, the POS needs to send a timeout reversal before the purchase referral. See Purchase with timeout and reversal/void for details.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS. The cardholder selects 98 (food stamp).
-
The cardholder selects the account type.
-
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion times out while waiting for a purchase response (0210) from the entity upstream responsible for authorizing the transaction.
NoteAlthough not indicated on the diagram, Postilion sends a reversal advice (0420) upstream at this point to cancel any impact the original purchase request may have had on the cardholder’s account. -
Postilion sends a purchase response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
-
After receiving approval through the external voice authorization process, the POS sends a PURCHASE REFERRAL (request) XML message to eSocket.POS with the relevant data and transaction amount.
-
eSocket.POS sends the appropriate response to the POS device.
-
eSocket.POS generates a referral advice request (0220) and sends it to Postilion. eSocket.POS will resend the referral advice request (0220) to Postilion until it receives a response.
-
Postilion receives the referral advice request and sends a referral advice response (0230) to eSocket.POS.
-
Postilion sends the referral advice request (0220) upstream. Postilion will resend the referral advice request (0220) to the network until it receives a response.
-
Postilion receives a referral advice response (0230) from the entity upstream responsible for authorizing the transaction.
Note
|
The message flow assumes the voice authorization occurs while the cardholder is in the lane and the original purchase transaction (with the card details) can be looked up in eSocket.POS. If the cardholder needs to leave the lane for the voice authorization (for example, to go to a customer service desk), and the EBT food stamp electronic voucher is initiated on a different POS which only supports manual PAN entry, eSocket.POS will prompt for manual PAN entry when receiving the PURCHASE REFERRAL (request) XML message [9]. |
Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during an EBT purchase transaction:
If registered, the following callbacks are called during an EBT purchase transaction:
-
POS Callback Device callbacks or DATA_REQUIRED (deprecated)
XML mappings in an EBT food stamp purchase transaction with electronic voucher
The following table contains the XML properties and values that are typically associated with an EBT food stamp purchase transaction. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
PURCHASE |
|
O |
00000000083 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
710 |
The following table contains the XML properties and values that are typically associated with an EBT food stamp electronic voucher advice. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
SoftTerm |
|
M |
195322 |
|
M |
PURCHASE |
|
M |
REFERRAL |
|
G |
30000 |
|
O |
710 |
|
O |
000000000083 |
|
O |
PosOp001 |
|
C |
*123456* |
|
C |
*123456* |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Transaction Properties.
For an explanation of the Condition column in these tables, see Object and Property Conditions.
Example: XML messages in a purchase transaction with referral
This is an example of a purchase transaction with referral. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts a purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction PosOperatorId="PosOp001" RetrievalRefNr="000000000083" TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (response) XML message [8] from eSocket.POS with a host unavailable response code follows, assuming the benefit type selected by the cardholder was food stamp (account type 98):
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="98" ActionCode="AUTH" AmountTransactionFee="C0" AuthorizationProfile="30" BusinessDate="0831" CardProductName="EbtCard" CurrencyCode="710" DateTime="0831084214" ExpiryDate="2012" LocalDate="0831" LocalTime="084214" MerchantId="311111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="91" RetrievalRefNr="000000000083" TerminalId="SoftTerm" TransactionAmount="0" TransactionId="195322" Type="PURCHASE"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS sends a PURCHASE REFERRAL (request) XML message [9] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction MessageType="REFERRAL" PosOperatorId="PosOp001" ResponseCode="00" TerminalId="SoftTerm" TransactionAmount="30000" TransactionId="195322" AuthorizationNumber="123456" EbtVoucherNumber="123456" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE REFERRAL (response) XML message [10] from eSocket.POS follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="98" ActionCode="APPROVE" AuthorizationNumber="123456" CardNumber="111122******4444" CardProductName="EbtCard" CurrencyCode="710" DateTime="0831084215" ExpiryDate="2012" LocalDate="0831" LocalTime="084215" MerchantId="311111111111111" MessageReasonCode="9792" MessageType="REFERRAL" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="000000000084" TerminalId="SofttTerm" TransactionAmount="30000" TransactionId="195322" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
3.13.3. XML - EBT purchase (including with cash back)
Introduction
This section discusses an EBT purchase transaction, started at the POS and sent upstream via Postilion for authorization and approval. In the message flow outlined here, eSocket.POS drives the PED and prompts for the account.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS.
-
The cardholder selects the account type.
-
If account type 96 (cash benefit) was selected, eSocket.POS displays a prompt on the PED to the cardholder for the cash back amount.
-
If account type 96 (cash benefit) was selected, the cardholder is given the option to enter a cash back amount. If an amount was entered, eSocket.POS changes the ISO 8583 transaction type to 09 (goods and services with cash back).
NoteIf the transaction amount from the POS is zero while the cashback amount is non-zero, it indicates a cashback only (withdrawal) transaction. -
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device.
Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during an EBT purchase transaction:
If registered, the following callbacks are called during an EBT purchase transaction:
-
POS Callback Device callbacks or DATA_REQUIRED (deprecated)
XML mappings in an EBT purchase transaction
The following table contains the XML properties and values that are typically associated with an EBT purchase transaction request. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
141790 |
|
M |
PURCHASE |
|
O |
00000000008 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
810 |
The following table contains the XML properties and values specific to an EBT purchase transaction response. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
C |
123456 |
|
C |
1234567890 |
|
C |
EBT Response Text |
|
C |
D00000003000 |
|
C |
D00000002000 |
|
C |
D00000002000 |
|
C |
D00000002500 |
|
C |
D00000001500 |
|
C |
D00000001500 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Transaction Properties.
For an explanation of the Condition column in this table, see Object and Property Conditions.
Example: XML messages in an EBT purchase transaction
This is an example of a successful EBT purchase transaction The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts an EBT purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="1000" TransactionId="141790" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (response) XML message [10] from eSocket.POS following the successful completion of the transaction follows, assuming the benefit type selected by the cardholder was the cash benefit (account type 96):
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="96" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="EbtCard" CurrencyCode="840" DateTime="0806082950" ExpiryDate="2030" LocalDate="0806" LocalTime="082950" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="00000000008" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="1000" TransactionId="141790" EbtVoucherNumber="123456" EbtCaseNumber="1234567890" EbtResponseText="EBT Response Text" EbtEndingCashBenefitsAccountBalance="D00000002000" Type="PURCHASE"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.13.4. XML - EBT purchase and reversal/void
Introduction
This section discusses an EBT purchase transaction, started at the POS and sent upstream via Postilion for authorization and approval. After the transaction is approved, it needs to be reversed/voided for some reason. The purchase transaction is therefore followed by a reversal advice. In the message flow outlined here, eSocket.POS drives the PED and prompts for the account.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a PURCHASE (request) XML message to eSocket.POS with the final amount of the transaction.
-
eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS.
-
The cardholder selects the account type.
-
If account type 96 (cash benefit) was selected, eSocket.POS displays a prompt on the PED to the cardholder for the cash back amount.
-
If account type 96 (cash benefit) was selected, the cardholder is given the option to enter a cash back amount. If an amount was entered, eSocket.POS changes the ISO 8583 transaction type to 09 (goods and services with cash back).
NoteIf the transaction amount from the POS is zero while the cashback amount is non-zero, it indicates a cashback only (withdrawal) transaction. -
eSocket.POS sends a purchase request (0200) to Postilion.
-
Postilion sends the purchase request (0200) upstream.
-
Postilion receives a purchase response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the purchase response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device. At this stage, the purchase transaction is completed.
-
The POS sends a PURCHASE (reversal) XML message to eSocket.POS to reverse the original request transaction.
-
eSocket.POS sends a PURCHASE (reversal response) to the POS device.
-
eSocket.POS sends a reversal advice (0420) to Postilion.
-
Postilion sends the reversal advice response (0430) to eSocket.POS.
-
Postilion sends the reversal advice (0420) upstream.
-
Postilion receives the reversal advice response (0430) back from the entity upstream responsible for authorizing the transaction.
Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
The reversal message does not call any events. If registered, the following events are called during an EBT purchase transaction:
The reversal message does not get any callbacks. If registered, the following callbacks are called during an EBT purchase transaction:
-
POS Callback Device callbacks or DATA_REQUIRED (deprecated)
XML mappings in an EBT purchase transaction reversal
The following table contains the XML properties and values that are typically associated with an EBT purchase transaction request. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
141790 |
|
M |
PURCHASE |
|
O |
00000000008 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
810 |
The following table contains the XML properties and values that are specific to an EBT purchase transaction response. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
C |
123456 |
|
C |
1234567890 |
|
C |
EBT Response Text |
|
C |
D00000003000 |
|
C |
D00000002000 |
|
C |
D00000002000 |
|
C |
D00000002500 |
|
C |
D00000001500 |
|
C |
D00000001500 |
The following table contains the XML properties and values that are typically associated with an EBT purchase reversal. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
141790 |
|
M |
PURCHASE |
|
C |
TRUE |
|
O |
4000 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Transaction Properties.
For an explanation of the Condition column of this table, see Object and Property Conditions.
Example: XML messages in an EBT purchase transaction reversal
This is an example of a successful EBT purchase transaction, followed by an EBT purchase reversal to reverse the purchase transaction due to a customer cancellation (for example, the MessageReasonCode is set to 4000). The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts an EBT purchase transaction with a PURCHASE (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="1000" TransactionId="141790" MessageReasonCode="4000" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (response) XML message [10] from eSocket.POS following the successful completion of the transaction follows, assuming the benefit type selected by the cardholder was food stamp (account type 98):
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="98" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="EbtCard" CurrencyCode="840" DateTime="0806082950" ExpiryDate="2030" LocalDate="0806" LocalTime="082950" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="00000000008" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="1000" TransactionId="141790" EbtVoucherNumber="123456" EbtCaseNumber="1234567890" EbtResponseText="EBT Response Text" EbtEndingFoodStampAccountBalance="D00000002000" Type="PURCHASE"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
The POS starts an EBT purchase reversal with a PURCHASE (reversal) XML message [11] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Reversal="TRUE" TerminalId="TestTerm" TransactionId="141790" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
The resulting PURCHASE (reversal response) XML message [12] from eSocket.POS following the successful completion of the transaction follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="98" ActionCode="APPROVE" CardNumber="111122******4444" CardProductName="EbtCard" CurrencyCode="840" DateTime="0806083350" ExpiryDate="2030" LocalDate="0806" LocalTime="083350" MerchantId="111111111111111" MessageReasonCode="9792" PanEntryMode="90" PosCondition="00" ResponseCode="00" Reversal="TRUE" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="1000" TransactionId="141790" EbtVoucherNumber="123456" Type="PURCHASE"> </Esp:Transaction> </Esp:Interface>
3.13.5. XML - EBT refund
Introduction
This section discusses an EBT refund transaction, started at the POS and sent upstream via Postilion for authorization and approval. In the message flow outlined here, eSocket.POS drives the PED and prompts for the account.
Message flow
Follow the message flow and refer to the diagram.
-
The POS sends a REFUND (request) XML message to eSocket.POS.
-
eSocket.POS displays a prompt on the PED to the cardholder to select the account type reflecting the benefit type: EBT cash benefit (96) or EBT food stamp (98). This prompt is based on the EBT card’s BIN range and the card’s configuration in eSocket.POS.
-
The cardholder selects the account type.
-
eSocket.POS sends a refund request (0200) to Postilion.
-
Postilion sends the refund request (0200) upstream.
-
Postilion receives a refund response (0210) back from the entity upstream responsible for authorizing the transaction.
-
Postilion sends the refund response (0210) to eSocket.POS.
-
eSocket.POS sends the appropriate response to the POS device. At this stage, the refund transaction is completed.
Note
|
If the refund needs to be reversed for some reason, the POS sends a REFUND (reversal) XML message to eSocket.POS. See the Purchase and reversal/void page for the complete message flow, events and callbacks, XML mappings, and examples. In the case of a refund, the Type field in the XML messages must be set to REFUND. |
Events and callbacks are not displayed in the diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a sub-set of the total list possible and are typical to this scenario.
If registered, the following events are called during an EBT refund transaction:
If registered, the following callbacks are called during an EBT refund transaction:
-
POS Callback Device callbacks or DATA_REQUIRED (deprecated)
XML mappings in an EBT refund transaction
The following table contains the XML properties and values that are typically associated with an EBT refund transaction request. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
M |
TestTerm |
|
M |
141790 |
|
M |
REFUND |
|
O |
00000000008 |
|
O |
PosOp001 |
|
G |
30000 |
|
O |
810 |
|
O |
*123456* |
The following table contains the XML properties and values that are specific to an EBT refund transaction response. In the Value column, example values are in italics and mandatory values are in bold.
Property | Condition | Value |
---|---|---|
H |
123456 |
|
H |
1234567890 |
|
H |
EBT Response Text |
|
C |
D00000003000 |
|
C |
D00000002000 |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Transaction Properties.
For an explanation of the Condition column of this table, see Object and Property Conditions.
Example: XML messages in a refund transaction void
This is an example of a successful EBT refund transaction, followed by an EBT refund void to reverse the refund transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
The POS starts an EBT refund transaction with a REFUND (request) XML message [1] to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction TerminalId="TestTerm" TransactionAmount="1000" TransactionId="141790" EbtVoucherNumber="123456" Type="REFUND"> </Esp:Transaction> </Esp:Interface>
The resulting REFUND (response) XML message [8] from eSocket.POS following the successful completion of the transaction follows, assuming the benefit type selected by the cardholder was food stamp (account type 98):
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction Account="98" ActionCode="APPROVE" AmountTransactionFee="C0" AuthorizationProfile="11" BusinessDate="0806" CardProductName="EbtCard" CurrencyCode="840" DateTime="0806082950" ExpiryDate="2030" LocalDate="0806" LocalTime="082950" MerchantId="111111111111111" MessageReasonCode="9790" PanEntryMode="90" PosCondition="00" ResponseCode="00" RetrievalRefNr="00000000008" ServiceRestrictionCode="***" TerminalId="TestTerm" TransactionAmount="1000" TransactionId="141790" EbtVoucherNumber="123456" EbtCaseNumber="1234567890" EbtResponseText="EBT Response Text" EbtEndingFoodStampAccountBalance="D00000002000" Type="REFUND"> <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> </Esp:Transaction> </Esp:Interface>
3.13.6. XML - EBT timeout reversal
See Handling timeouts for when to send timeout reversals for EBT purchases and refunds. The message flow is very similar to EBT purchase and reversal/void, for example, except for the following:
-
The purchase response (0210) [7] sent by Postilion is not received by eSocket.POS (similar to what happens with a purchase with timeout and reversal/void).
-
In the PURCHASE (reversal) XML message [9] to eSocket.POS, the MessageReasonCode is either not set, or it is set to 4021 (timeout waiting for response).
3.14. Credit application transactions
3.14.1. Credit admin account lookup
Introduction
This section discusses a Credit Admin Account Lookup inquiry transaction.
Message flow
The Credit Admin Account Lookup inquiry transaction message flow description follows. Use the numbering in the diagram together with the numbered flow descriptions:
-
The POS sends a GENERAL_INQ (request) XML message to eSocket.POS (1).
-
eSocket.POS sends an authorization request (0100) to Postilion (2).
-
Postilion sends the authorization request (0100) upstream (3).
-
Postilion receives an authorization response (0110) back from the entity upstream (4).
-
Postilion sends the authorization response (0110) to eSocket.POS (5).
-
eSocket.POS sends the valid response to the POS device (6).
Note
|
If Postilion is the card issuer, the valid authorization response (0110) is sent from Postilion, and message legs 3 and 4 are eliminated. |
Events and callbacks are not displayed in the preceding diagram. For an example of events and callbacks in a diagram, see the signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.
If registered, the following events are called during a Credit Admin Account Lookup inquiry transaction:
If registered, the following callbacks are called during a Credit Admin Account Lookup inquiry transaction:
XML mappings in a Credit Admin Account Lookup
This section contains the XML properties and values that are typically associated with a Credit Admin Account Lookup inquiry transaction.
Property | Description | Condition | Request | Response |
---|---|---|---|---|
The type of the transaction. For this type of transaction, Type = GENERAL_INQ. |
M |
Yes |
Yes |
|
A code used to further distinguish between transactions with the same type. For this type of transaction, ExtendedTransactionType = 7001 |
M |
Yes |
Yes |
|
Payee name and address. Contains identification and billing information for a payee. |
O |
Yes |
Yes |
|
Contains additional payee name and address details, if any. |
O |
Yes |
Yes |
|
Contains account details needed for a credit application, if any. |
O |
Yes |
Yes |
|
The status response from ADS based on the processor specification. |
O |
No |
Yes |
|
The status response that contains information about the account. |
O |
No |
Yes |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Inquiry Properties.
For an explanation of the Condition column in this table, see Object and Property Conditions.
Example: XML messages in a Credit Admin Account Lookup
This is an example of a Credit Admin Account Lookup inquiry transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the preceding diagram.
Note
|
The XML element order must be followed exactly as shown in the examples that follow. |
The POS starts a Credit Admin Account Lookup inquiry transaction with a GENERAL_INQ (request) XML message to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry ExtendedTransactionType="7001" TerminalId="term1" TransactionId="242459" Type="GENERAL_INQ"> <Esp:PayeeNameAndAddress AddressLine1="Mill St" AddressLine2="Montello" AddressLine3="" City="Marquette" CountryCode="USA" Name="Lawrence" Phone="1234567890" PostalCode="411014" Region="Wisconsin"> </Esp:PayeeNameAndAddress> <Esp:AdditionalPayeeInformation> <Esp:PayeeContact FirstName="Lawrence" MiddleInitial="S" LastName="Williams" CardHolderName="Lawrence Williams" CustomerDateOfBirth="01031986" AdditionalID1="010212345678"> </Esp:PayeeContact> </Esp:AdditionalPayeeInformation> <Esp:AccountData> <Esp:Account ReferenceNo="1234"> </Esp:Account> </Esp:AccountData> </Esp:Inquiry> </Esp:Interface>
The resulting GENERAL_INQ (response) XML message from eSocket.POS after the successful completion of the Credit Admin Account Lookup inquiry transaction follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry ActionCode="APPROVE" ExtendedTransactionType="7001" MessageReasonCode="9790" ResponseCode="00" TerminalId="term1" TransactionId="242459" Type="GENERAL_INQ" PrintData="0008A1Approved" DisplayData="Approved"> <Esp:AccountData> <Esp:Account ReferenceNo="1234" ApplicationReferenceNo="987654321"> </Esp:Account> </Esp:AccountData> </Esp:Inquiry> </Esp:Interface>
XML mappings in a Driver’s License Account Lookup
This section contains the XML properties and values that are typically associated with a Driver’s License Account Lookup transaction.
Property | Description | Condition | Request | Response |
---|---|---|---|---|
The type of the transaction. For this transaction, Type = GENERAL_INQ. |
M |
Yes |
Yes |
|
A code used to further distinguish between transactions with the same type. For this transaction, ExtendedTransactionType = 7001 |
M |
Yes |
Yes |
|
Contains additional payee name and address details, if any. For this type of transaction, it contains the SSN in the AccountID1 subfield.
|
M |
Yes |
Yes |
|
StructuredData DriverLicenseData |
Contains the scanned driver’s license information encoded in Base64 format. See the example that follows this table. |
M |
Yes |
Yes |
Contains account details needed for a credit application, if any. |
O |
Yes |
Yes |
|
The status response from ADS based on the processor specification. |
O |
No |
Yes |
|
The status response that contains information about the account. |
O |
No |
Yes |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Inquiry Properties.
For an explanation of the Condition column in this table, see Object and Property Conditions.
Example: XML messages in a Driver’s License Account Lookup
This is an example of a Driver’s License Account Lookup transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the previous diagram.
Note
|
The XML element order must be followed exactly as shown in the examples that follow. |
The POS starts a Driver’s License Account Lookup transaction with a GENERAL_INQ (request) XML message to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry ExtendedTransactionType="7001" TerminalId="term1" TransactionId="242459" Type="GENERAL_INQ"> <Esp:StructuredData Name="DriverLicenseData" Value="MjUwMTAxNTQwMCRJMTUwVDBXNDA3NEowMUNBODBCXUxACh4NSURDSEs5ODk4OTUwMTAxREwwMDI5MDE3OERMMVpBQVBQUk9WRSxBTFdBWVMsLAoxWkIzMTAwIEVBU1RPTiBTUVVBUkUgUExBQ0UKMVpVCjFaQ0NPTFVNQlVTCkRBSk9ICjFaRTQzMjE5CjFaRjQ1NTY0OTgyNgoxWkc1CjFaSAoxWkkKMVpKMjAxNTA"> </Esp:StructuredData> <Esp:AdditionalPayeeInformation> <Esp:PayeeContact AdditionalID1="0107000006789"> </Esp:PayeeContact> </Esp:AdditionalPayeeInformation> </Esp:Inquiry> </Esp:Interface>
The example that follows shows the resulting GENERAL_INQ (response) XML message from eSocket.POS after the successful completion of the Driver’s License Account Lookup transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry ActionCode="APPROVE" ExtendedTransactionType="7001" MessageReasonCode="9790" ResponseCode="00" TerminalId="term1" TransactionId="242459" Type="GENERAL_INQ" PrintData="0008A1Approved" DisplayData="Approved"> <Esp:AccountData> <Esp:Account ReferenceNo="1234" ApplicationReferenceNo="987654321"> </Esp:Account> </Esp:AccountData> </Esp:Inquiry> </Esp:Interface>
3.14.2. Credit admin status application
Introduction
The POS sends a Credit Admin Status Application request upstream via Postilion. This section discusses a successful Status Application General Inquiry transaction.
Message flow
A successful Status Application General Inquiry transaction message flow is described below
-
The POS sends a GENERAL_INQ (request) XML message to eSocket.POS (1).
-
eSocket.POS sends an authorization request (0100) to Postilion (2).
-
Postilion sends the authorization request (0100) upstream (3).
-
Postilion receives an authorization response (0110) back from the entity upstream (4).
-
Postilion sends the authorization response (0110) to eSocket.POS (5).
-
eSocket.POS sends the valid response to the POS device (6).
Note: If Postilion is the card issuer, the valid authorization response (0110) is sent from Postilion, and message legs 3 and 4 are eliminated.
Events and callbacks are not displayed in the above diagram. For an example of events and callbacks in a diagram, see signature capture transaction example.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.
If registered, the following events are called during a General Inquiry transaction:
If registered, the following callbacks are called during a General Inquiry transaction:
XML mappings in a Credit Admin Status Application
This section contains the XML properties and values that are typically associated with a Status Application General Inquiry transaction.
Property | Description | Condition | Request | Response |
---|---|---|---|---|
The type of the transaction. For this transaction, Type = GENERAL_INQ. |
M |
Yes |
Yes |
|
A code used to further distinguish between transactions with the same type. For this transaction, ExtendedTransactionType = 7007 |
M |
Yes |
Yes |
|
Payee name and address contains identification and billing information for a payee. |
O |
Yes |
Yes |
|
Contains additional payee name and address details, if any. |
O |
Yes |
Yes |
|
Contains account details needed for a credit application, if any. |
O |
Yes |
Yes |
|
The status response from ADS based on the processor specification. |
O |
No |
Yes |
|
The status response that contains information about the account. |
O |
No |
Yes |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583 .
For a full list of possible properties in these messages, see Inquiry Properties .
For an explanation of the Condition column in this table, see Object and Property Conditions .
Example: XML messages in a Credit Admin Status Application
This is an example of a Status Application General Inquiry transaction. The labels in bold and the numbers in square brackets refer to the corresponding labels and numbered arrows in the diagram above.
Note: The order of xml elements must be followed exactly as shown in the examples that follow.
The POS starts a Status Application General Inquiry transaction with a GENERAL_INQ (request) XML message to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry ExtendedTransactionType="7007" TerminalId="term1 " TransactionId="242459" Type="GENERAL_INQ"> <Esp:PayeeNameAndAddress AddressLine1="Mill St " AddressLine2="Montello " AddressLine3=" " City="Marquette " CountryCode="USA" Name="Lawrence " Phone="1234567890 " PostalCode="411014 " Region="Wisconsin "> </Esp:PayeeNameAndAddress> <Esp:AdditionalPayeeInformation> <Esp:PayeeContact FirstName="Lawrence" MiddleInitial="S" LastName="Williams" CardHolderName="Lawrence Williams" CustomerDateOfBirth="01031986" AdditionalID1="010212345678"> </Esp:PayeeContact> </Esp:AdditionalPayeeInformation> <Esp:AccountData> <Esp:Account ReferenceNo="1234"> </Esp:Account> </Esp:AccountData> </Esp:Inquiry> </Esp:Interface>
The resulting GENERAL_INQ (response) XML message from eSocket.POS following the successful completion of the Status Application General Inquiry transaction follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Inquiry ActionCode="APPROVE" ExtendedTransactionType="7007" MessageReasonCode="9790" ResponseCode="00" TerminalId="term1 " TransactionId="242459" Type="GENERAL_INQ" PrintData="0008A1Approved" DisplayData="Approved"> <Esp:AccountData> <Esp:Account ReferenceNo="1234" ApplicationReferenceNo="987654321"> </Esp:Account> </Esp:AccountData> </Esp:Inquiry> </Esp:Interface>
3.14.3. Credit application prescreen acceptance
Introduction
This section discusses a Credit Application Prescreen (Preapproval) Acceptance transaction that is used when the customer accepts a preapproved offer of credit.
Message flow
The Credit Application Prescreen Acceptance transaction message flow description follows. Use the numbering in the diagram together with the numbered flow descriptions:
-
The POS sends a Prescreen Acceptance ADMIN (request) XML message to eSocket.POS (1) containing the customer’s address and demographic information, as well as the Prescreen ID.
-
eSocket.POS sends an administrative request (0600) to Postilion (2).
-
Postilion sends the administrative request (0600) upstream (3).
-
Postilion receives an administrative response (0610) back from the entity upstream (4).
-
Postilion sends the administrative response (0610) to eSocket.POS (5).
-
eSocket.POS sends the response to the POS device (6).
Events and callbacks are not displayed in the preceding diagram. For an example of events and callbacks, see the signature capture transaction page.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.
If registered, the following events are called during an administrative transaction:
XML mappings in a Credit Application Prescreen Acceptance transaction
This section contains the XML properties and values that are typically associated with a Credit Application Prescreen Acceptance transaction.
Property | Description | Condition | Request | Response |
---|---|---|---|---|
Set to ADMIN. |
M |
Yes |
Yes |
|
Set to ADMIN_REQUEST. |
M |
Yes |
Yes |
|
Set to 1012 (Preapproval Credit Offer Acceptance). |
M |
Yes |
Yes |
|
Contains the customer contact information. The PurchasingCardData.Contact.Type field must be set to BILL_TO. |
M |
Yes |
Yes |
|
Contains additional customer information, such as the SSN, yearly annual income, and so on, that are required in the Prescreen Acceptance transaction. |
C |
Yes |
Yes |
|
The AccountData.Account.ApplicationReferenceNo field must contain the Prescreen ID - a unique number assigned to a preapproved offer. This ID is obtained either in the online Prescreen Request response, or sent to the customer via email or direct mail if a batch prescreen process was used. |
M |
Yes |
Yes |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Transaction Properties.
For an explanation of the Condition column in this table, see Object and Property Conditions.
Example: Credit Application Prescreen Acceptance transaction
The POS starts a Credit Application Prescreen Acceptance transaction with an ADMIN (request) XML message to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="1012" TerminalId="term1 " TransactionId="242459" Type="ADMIN" MessageType="ADMIN_REQUEST"> <Esp:PurchasingCardData> <Esp:Contact Type="BILL_TO" Telephone="5551238888" Email="lsmith@mailserve.com" Address="1 Street Road" Address2="Greenville" City="My City" PostalCode="19103"> </Esp:Contact> </Esp:PurchasingCardData> <Esp:AdditionalPayeeInformation> <Esp:PayeeContact FirstName="Lawrence" LastName="Smith" CustomerDateOfBirth="19900102" AdditionalID1="010712345678" HousingCode="0" LengthAtAddress="0102" YearlyIncome="200000" PrimaryIncomeFrequency="M"> </Esp:PayeeContact> </Esp:AdditionalPayeeInformation> <Esp:AccountData> <Esp:Account ApplicationReferenceNo="123450987654321"> </Esp:Account> </Esp:AccountData> </Esp:Transaction> </Esp:Interface>
The resulting ADMIN (response) XML message from eSocket.POS after the successful completion of the transaction follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ActionCode="APPROVE" ExtendedTransactionType="1012" MessageReasonCode="9790" ResponseCode="00" TerminalId="term1 " TransactionId="242459" Type="ADMIN" MessageType="ADMIN_REQUEST" DisplayData="OP"> <Esp:AccountData> <Esp:Account ApplicationReferenceNo="123450987654321"> </Esp:Account> </Esp:AccountData> </Esp:Transaction> </Esp:Interface>
3.14.4. Credit application prescreen request
Introduction
This section discusses a Credit Application Prescreen (Preapproval) transaction. This type of transaction is also referred to as an Online Prescreen. The customer is prescreened in real time by the host system using the customer’s address and demographic information to extend preapproved offers of credit. If preapproved, the offer can be accepted by the customer using a Prescreen Acceptance transaction.
Message flow
The Credit Application Prescreen transaction message flow description follows. Use the diagram together with the numbered flow descriptions:
-
The POS sends a Prescreen ADMIN (request) XML message to eSocket.POS (1) containing the customer’s address and demographic information.
-
eSocket.POS sends an administrative request (0600) to Postilion (2).
-
Postilion sends the administrative request (0600) upstream (3).
-
Postilion receives an administrative response (0610) back from the entity upstream (4).
-
Postilion sends the administrative response (0610) to eSocket.POS (5).
-
eSocket.POS sends the response to the POS device (6).
Events and callbacks are not displayed in the preceding diagram. For an example of events and callbacks, see the signature capture transaction page.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.
If registered, the following events are called during an administrative transaction:
XML mappings in a Credit Application Prescreen transaction
This section contains the XML properties and values that are typically associated with a Credit Application Prescreen transaction.
Property | Description | Condition | Request | Response |
---|---|---|---|---|
Set to ADMIN. |
M |
Yes |
Yes |
|
Set to ADMIN_REQUEST. |
M |
Yes |
Yes |
|
Set to 1011 (Credit Application Preapproval). |
M |
Yes |
Yes |
|
Contains the customer contact information. The PurchasingCardData.Contact.Type field must be set to BILL_TO. |
M |
Yes |
Yes |
|
Contains additional customer information, such as the SSN, yearly annual income, and so on, that are required to prescreen the customer. |
C |
Yes |
Yes |
|
In responses, the AccountData.Account.ApplicationReferenceNo field contains the Prescreen ID - a unique number assigned to a preapproved offer. This must be provided in the Prescreen Acceptance transaction when the customer accepts the preapproved offer. |
C |
No |
Yes |
|
The status response from the host system. |
O |
No |
Yes |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Transaction Properties.
For an explanation of the Condition column in this table, see Object and Property Conditions.
Example: Credit Application Prescreen transaction
The POS starts a Credit Application Prescreen transaction with an ADMIN (request) XML message to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="1011" TerminalId="term1 " TransactionId="242459" Type="ADMIN" MessageType="ADMIN_REQUEST"> <Esp:PurchasingCardData> <Esp:Contact Type="BILL_TO" Telephone="5551238888" Email="lsmith@mailserve.com" Address="1 Street Road" Address2="Greenville" City="My City" PostalCode="19103"> </Esp:Contact> </Esp:PurchasingCardData> <Esp:AdditionalPayeeInformation> <Esp:PayeeContact FirstName="Lawrence" LastName="Smith" CustomerDateOfBirth="19900102" AdditionalID1="010712345678" HousingCode="0" LengthAtAddress="0102" YearlyIncome="200000" PrimaryIncomeFrequency="M"> </Esp:PayeeContact> </Esp:AdditionalPayeeInformation> </Esp:Transaction> </Esp:Interface>
The resulting ADMIN (response) XML message from eSocket.POS after the successful completion of the transaction follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ActionCode="APPROVE" ExtendedTransactionType="1011" MessageReasonCode="9790" ResponseCode="00" TerminalId="term1 " TransactionId="242459" Type="ADMIN" MessageType="ADMIN_REQUEST" DisplayData="OP"> <Esp:AccountData> <Esp:Account ApplicationReferenceNo="123450987654321"> </Esp:Account> </Esp:AccountData> </Esp:Transaction> </Esp:Interface>
3.14.5. Express/instant credit application
Introduction
This section discusses an Express/Instant Credit Application transaction.
Message flow
The Express/Instant Credit Application transaction message flow description follows. Use the numbering in the diagram together with the numbered flow descriptions:
-
The POS sends an Express/Instant Credit Application ADMIN (request) XML message to eSocket.POS (1) containing the customer’s information.
-
eSocket.POS sends an administrative request (0600) to Postilion (2).
-
Postilion sends the administrative request (0600) upstream (3).
-
Postilion receives an administrative response (0610) back from the entity upstream (4).
-
Postilion sends the administrative response (0610) to eSocket.POS (5).
-
eSocket.POS sends the response to the POS device (6).
Events and callbacks are not displayed in the preceding diagram. For an example of events and callbacks, see the signature capture transaction page.
Events and callbacks between the POS device and eSocket.POS
Events and callbacks are optional. Those listed here are a subset of the total list possible and are typical to this scenario.
If registered, the following events are called during an administrative transaction:
XML mappings in an Express/Instant Credit Application transaction
This section contains the XML properties and values that are typically associated with an Express/Instant Credit Application transaction.
Property | Description | Condition | Request | Response |
---|---|---|---|---|
Set to ADMIN. |
M |
Yes |
Yes |
|
Set to ADMIN_REQUEST. |
M |
Yes |
Yes |
|
Identifies the administrative message as a credit application transaction. The following values may be specified, depending on the host system to which the transaction is sent:
|
M |
Yes |
Yes |
|
Contains the customer’s contact information such as the AddressLine1, AddressLine2, AddressLine3, City, Region, PostCode, and CountryCode.
|
C |
Yes |
Yes |
|
Contains the customer contact information. The PurchasingCardData.Contact.Type field must be set to BILL_TO.
|
C |
Yes |
Yes |
|
Contains additional customer information, if any. It may contain the alternate phone number, mobile phone number, SSN, and annual income amount in the CustomerBusinessPhone, CustomerCellPhoneNumber, AdditionalID1, and YearlyIncome subfields, respectively, if required. |
O |
Yes |
Yes |
|
StructuredData.DriverLicenseData |
Contains the scanned driver’s license information encoded in Base64 format. This is required for Instant Credit Applications with Driver’s License transactions. |
C |
Yes |
No |
StructuredData.CUSTOMER_EMAIL |
Contains the customer email address.
|
O |
Yes |
No |
Contains account details, if any. In the response, the AccountData.Account.ApplicationReferenceNo field contains the Credit Application ID. |
O |
Yes |
Yes |
|
The status response from the host system. |
O |
No |
Yes |
|
The status response that contains information about the account. |
O |
No |
Yes |
For a table describing how the XML properties map to the ISO 8583 message, see Mapping to ISO 8583.
For a full list of possible properties in these messages, see Transaction Properties.
For an explanation of the Condition column in this table, see Object and Property Conditions.
Example 1: Express/Instant Credit Application transaction
The POS starts an Express Credit Application transaction with an ADMIN (request) XML message to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="1000" TerminalId="term1" TransactionId="242459" Type="ADMIN" MessageType="ADMIN_REQUEST"> <Esp:PayeeNameAndAddress AddressLine1="Mill St" AddressLine2="Montello" AddressLine3="" City="Marquette" CountryCode="USA" Name="Lawrence" Phone="1234567890" PostalCode="411014" Region="Wisconsin"> </Esp:PayeeNameAndAddress> <Esp:AdditionalPayeeInformation> <Esp:PayeeContact FirstName="Lawrence" MiddleInitial="S" LastName="Williams" CardHolderName="Lawrence Williams" CustomerDateOfBirth="01031986" AdditionalID1="010212345678"> </Esp:PayeeContact> </Esp:AdditionalPayeeInformation> <Esp:AccountData> <Esp:Account ReferenceNo="1234"> </Esp:Account> </Esp:AccountData> </Esp:Transaction> </Esp:Interface>
The resulting ADMIN (response) XML message from eSocket.POS after the successful completion of the transaction follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ActionCode="APPROVE" ExtendedTransactionType="1000" MessageReasonCode="9790" ResponseCode="00" TerminalId="term1" TransactionId="242459" Type="ADMIN" MessageType="ADMIN_REQUEST" PrintData="0008A1Approved" DisplayData="IC"> <Esp:AccountData> <Esp:Account ReferenceNo="1234" ApplicationReferenceNo="123450987654321"> </Esp:Account> </Esp:AccountData> </Esp:Transaction> </Esp:Interface>
Example 2: Instant Credit Application with Driver’s License transaction
The POS starts an Instant Credit with Driver’s License transaction with an ADMIN (request) XML message to eSocket.POS:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="1000" TerminalId="term1" TransactionId="242459" Type="ADMIN" MessageType="ADMIN_REQUEST"> <Esp:StructuredData Name="DriverLicenseData" Value="MjUwMTAxNTQwMCRJMTUwVDBXNDA3NEowMUNBODBCXUxACh4NSURDSEs5ODk4OTUwMTAxREwwMDI5MDE3OERMMVpBQVBQUk9WRSxBTFdBWVMsLAoxWkIzMTAwIEVBU1RPTiBTUVVBUkUgUExBQ0UKMVpVCjFaQ0NPTFVNQlVTCkRBSk9ICjFaRTQzMjE5CjFaRjQ1NTY0OTgyNgoxWkc1CjFaSAoxWkkKMVpKMjAxNTA"> </Esp:StructuredData> <Esp:StructuredData Name="CUSTOMER_EMAIL" Value="abc@xyz.com"> </Esp:StructuredData> <Esp:PayeeNameAndAddress AddressLine1="Mill St" AddressLine2="Montello" AddressLine3="" City="Marquette" CountryCode="USA" Name="Lawrence" Phone="1234567890" PostalCode="411014" Region="Wisconsin"> </Esp:PayeeNameAndAddress> <Esp:AdditionalPayeeInformation> <Esp:PayeeContact CustomerCellPhoneNumber="987654321" CustomerBusinessPhone="123456789" AdditionalID1="0107000006789" YearlyIncome="100000"> </Esp:PayeeContact> </Esp:AdditionalPayeeInformation> <Esp:AccountData> <Esp:Account ReferenceNo="1234"> </Esp:Account> </Esp:AccountData> </Esp:Transaction> </Esp:Interface>
The resulting ADMIN (response) XML message from eSocket.POS after the successful completion of the transaction follows:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ActionCode="APPROVE" ExtendedTransactionType="1000" MessageReasonCode="9790" ResponseCode="00" TerminalId="term1" TransactionId="242459" Type="ADMIN" MessageType="ADMIN_REQUEST" PrintData="0008A1Approved" DisplayData="IC"> <Esp:AccountData> <Esp:Account ReferenceNo="1234" ApplicationReferenceNo="987654321"> </Esp:Account> </Esp:AccountData> </Esp:Transaction> </Esp:Interface>
3.15. Prompts
Format
Description
XML String containing a list of Prompt elements, each of which map to a Generic Prompt to be presented to the user.
The DTD that defines how the XML elements are represented in the message is available here:
-
Prompts.dtd
Key value = "Prompts" , Top level element = "Prompts" | ||||||
---|---|---|---|---|---|---|
Field |
Type |
Condition |
Format |
Description |
||
Prompts |
The top-level element of the Prompts XML document, which can contain one or more Prompt elements. |
|||||
Prompt |
Element |
Zero or more |
A list of prompts that are displayed to the user. The prompts are displayed in the order in which they are received in the XML. |
|||
Id |
Attribute |
Optional |
ans.. |
A unique number assigned to this prompt. This value need only be unique per Prompt element. |
||
Name |
Attribute |
Mandatory |
ans.. |
The name of the prompt. This must always be present in all Prompt requests and Prompt responses. |
||
DataType |
Attribute |
Optional |
a1 |
The type of data that will be entered for the prompt. Valid values are:
|
||
MinLength |
Attribute |
Optional |
n.. |
The minimum length of the prompt value to be entered. |
||
MaxLength |
Attribute |
Optional |
n.. |
The maximum length of the prompt value to be entered. |
||
InputType |
Attribute |
Optional |
a1 |
The visibility of the data entered. This field provides backwards compatibility for legacy applications. Valid values are:
|
||
Timeout |
Attribute |
Optional |
n.. |
The length of time (in milliseconds) that the device should wait for the user to enter an answer, before aborting the prompt. |
||
AcceptText |
Attribute |
Optional |
ans.. |
The actual text displayed on the Accept Button on the device.
|
||
DeclineText |
Attribute |
Optional |
ans.. |
The actual text displayed on the Decline Button on the device.
|
||
Source |
Attribute |
Optional |
a1 |
The source of the prompt, that is, where the prompt is displayed. This field provides backwards compatibility for legacy applications. Valid values are:
|
||
DisplayText |
Attribute |
Optional |
ans.. |
This field provides backwards compatibility for legacy applications. |
||
Image |
Attribute |
Optional |
ans.. |
This field provides backwards compatibility for legacy applications. |
||
Value |
Attribute |
Optional |
ans.. |
The answer to the prompt. This field is required in the prompt response. |
||
SignatureFormat |
Attribute |
Optional |
ans.. |
The format of the signature. This field is required in the signature prompt response. |
||
AdditionalButton |
Element |
Zero or more |
ans.. |
Represents a single additional button. Note: Limited device driver support. |
||
Text |
Attribute |
Optional |
ans.. |
The actual text displayed on an Additional Button on the device. |
||
Result |
Attribute |
Optional |
ans.. |
The value that will be returned if the additional button on the device is pressed. |
||
DisplayTextLine |
Element |
Zero or more |
A line of text associated with the prompt. |
|||
Text |
Attribute |
Optional |
ans.. |
The actual text displayed on the device, associated with a single DisplayTextLine. |
||
Option |
Element |
Zero or more |
This element provides backwards compatibility for legacy applications. |
|||
Value |
Attribute |
Optional |
ans.. |
This field provides backwards compatibility for legacy applications. |
||
Text |
Attribute |
Optional |
ans.. |
This field provides backwards compatibility for legacy applications. |
||
CustomProperty |
Element |
Zero or more |
A custom property associated with the prompt. |
|||
Key |
Attribute |
Optional |
ans.. |
The key for the custom property. |
||
Value |
Attribute |
Optional |
ans.. |
The value for the custom property. |
||
OptionTextLine |
Element |
Zero or more |
Represents a single option, when sending an option type generic prompt. |
|||
Text |
Attribute |
Optional |
ans.. |
The text that will be displayed on the device representing the option. |
||
Result |
Attribute |
Optional |
ans.. |
The value that will be returned on successful selection of the option. |
3.16. Display
Format
Description
An XML string containing a list of display elements. Each element maps to a display message that is presented to the user.
See Display.dtd to see how the XML elements are represented in the message.
The following table describes the structure of the XML string.
Field | Type | Condition | Format | Description |
---|---|---|---|---|
Display |
Top level element of the Display XML message which can contain one DisplayData element and zero or more DisplayResult elements. |
|||
DisplayData |
Element |
One |
List of Display messages and parameters associated with a Display message. These must be sent to the device in the order received. |
|
ResponseRequired |
Attribute |
Optional |
a |
Indicates whether eSocket.POS requires a response to the display message. |
DisplayTime |
Attribute |
Optional |
n.. |
Time period (in seconds) that the message must be displayed for. |
Device |
Attribute |
Mandatory |
an |
Device on which the message must be displayed:
|
DisplayType |
Attribute |
Optional |
a |
Type of information to be displayed. |
BacklightEnabled |
Attribute |
Optional |
a |
Indicates whether the backlight on the device should be switch on or not. |
FormID |
Attribute |
Optional |
a |
Specifies the form used for display. |
DisplayContent |
Element |
Optional |
Content to be displayed. |
|
Format |
Attribute |
Optional |
a |
Format of the output:
|
OutputText |
Element |
Zero or more |
Text object to display - must be present if the Format field is equal to "Text". |
|
Text |
Attribute |
Optional |
ans |
Actual text to display. |
Font |
Attribute |
Optional |
an |
Font of the text to display. |
StartRow |
Attribute |
Optional |
n |
Row from which to start the text display - vertical alignment. |
StartColumn |
Attribute |
Optional |
n |
Column from which to start the text display - horizontal alignment. |
Color |
Attribute |
Optional |
a |
Color of the text to display:
|
CharStyle |
Attribute |
Optional |
a |
Style of the characters to display:
|
NewLineFlag |
Attribute |
Optional |
a |
Indicates whether a carriage return must be displayed. |
Alignment |
Attribute |
Optional |
a |
Positional alignment of the characters to display:
|
OutputXHTML |
Attribute |
Optional |
ans |
Base64 representation of XHTML data to display - must be present if the Format field is equal to "XHTML". |
CustomDisplayData |
Element |
Zero or more |
Custom parameters associated with a DisplayData object - the order of this list must match the list of DisplayData objects. |
|
DisplayContent |
Element |
Optional |
Custom content object. |
|
PredefinedContent |
Element |
Zero or One |
a |
Predefined display content - must be present if the Format field is equal to "MessageReference". |
ReferenceID |
Attribute |
Optional |
an |
Referenced to the predefined content. |
Language |
Attribute |
Optional |
a |
Language of the predefined content. |
OutputText |
Element |
Zero or more |
Custom Output text object - must match the order of the DisplayContent.OutputText structure. |
|
CharSet |
Attribute |
Optional |
an |
IANA character encoding of the text to display. |
CharWidth |
Attribute |
Optional |
a |
Width of the characters to display:
|
CharHeight |
Attribute |
Optional |
a |
Height of the characters to display:
|
OutputBarcode |
Element |
Optional |
Must be present if the Format field is equal to "Barcode". |
|
Type |
Attribute |
Optional |
an |
Type of barcode encoding:
|
Value |
Attribute |
Optional |
an |
Barcode value to display. |
OutputSignature |
Attribute |
Optional |
ans |
Signature associated with the text - in base64 format. |
DisplayResult |
Element |
Zero or more |
Lists the display results, matching them to the DisplayData items, and in the same order. |
|
Result |
Attribute |
Optional |
a |
Indicates the result of the transaction:
|
ErrorCondition |
Attribute |
Optional |
an |
Error condition, if the Result field is equal to "Failure". |
AdditionalResponse |
Attribute |
Optional |
an |
Additional information associated with the response. |
3.17. Receipt printing
Description: eSocket.POS is responsible for formatting, validating, and printing receipts. Receipts are defined using the eSocket.POS Structured Receipt Scripting Language (SRSL), the HTML template file, or a template defined on the PIN Entry Device (PED). The terminal can be configured to print the receipt for the purchase and/or reversal transaction and the customer and/or merchant. See the eSocket.POS User Guide for information on how to configure the PipelineComponentReceiptPrinter that handles receipt printing.
The following is a flow describing how receipt reprint works.
Receipt reprint administration request
Details of the receipt reprint administration request flow:
-
A receipt reprint administration request is sent from the POS interface with the extended transaction type set to 2130 and a reprint transaction linking number (this is the original transaction reference number).
-
eSocket.POS maps the reprint administration request to a 0600 message, retrieves the original transaction from the database, then sends a request to the device printer, which displays the "please wait" message.
-
The device printer sends a response to the request indicating that the request was received.
-
eSocket.POS sends the receipt data to the device printer, and the device printer prints the receipt.
-
The device printer sends a response to the request indicating the receipt was printed.
-
The transaction is approved offline, and a receipt reprint administration response is sent back to the POS.
Below is an example of how XML messages work during a Prompt request. The POS starts the Prompt transaction with an ADMIN (request) XML message [1] to eSocket.POS, as indicated in the above diagram:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="2121" <Esp:StructuredData Name="RetrievalRefNr" Value="OriginalTransactionRefNr"> Name="ExtendedTransactionType" Value="2130"> </Esp:StructuredData> Type="ADMIN"> MessageType="ADMIN_REQUEST"> </Esp:Transaction> </Esp:Interface>
The resulting ADMIN (response) XML message [6] from eSocket.POS following the successful completion of the transaction:
<?xml version="1.0" encoding="UTF-8"?> <Esp:Interface Version="1.0" xmlns:Esp="http://www.mosaicsoftware.com/Postilion/eSocket.POS/"> <Esp:Transaction ExtendedTransactionType="2121" <Esp:StructuredData Name="ResponseFromPostilion" Value="ResponseFromPostilion"> </Esp:StructuredData> Type="ADMIN"> MessageType="ADMIN_REQUEST"> </Esp:Transaction> </Esp:Interface>
Note: The OriginalTransactionRefNr on the request message is the original transaction reference number of the original message that you want to print the receipt for. This can be the STAN (Field 11) or Retrieval Reference Number (Field 37) depending on the eSocket.POS configuration.
4. Implement/Extending eSocket.POS components
4.1. Overview - Implementing/Extending eSocket.POS components
eSocket.POS provides multiple interfaces which may be implemented to extend or enhance functionality provided by eSocket.POS.
The following topics are covered in this document:
-
Transaction Processing Result (TPR)
-
Using Caches in eSocket.POS
-
SensitiveTimedHashtable
A more detailed introduction to the eSocket.POS application can be found in the eSocket.POS User Guide .
4.2. Implement Transaction Processing Results (TPR)
Transaction Processing Results (TPR) tracks decisions made while processing a message. The decisions, stored in a bitmap, are placed into the message under a provided TPR key. The purpose of the tracking is to record which decisions were made when processing a message.
In ISO 8583 messages, the TPR is placed in structured data (field 127.22) under the provided key.
The bitmap is defined by extending ATransactionDecision . Due to the limitations of Java 1.4, a static list must be created and the itemList() method must return that static list. After this, public static final objects of the extending class will automatically be assigned positions in the bitmap, starting at byte 1 bit 8 and continuing until byte 1 bit 1 after which it rolls over to byte 2 bit 8 and this pattern continues.
An example of ATransactionDecision implementation follows:
public static class MyDecision extends ATransactionDecision { public static List items = new LinkedList(); public MyDecision() { super(name); } protected List itemList() { return items; } public static final MyDecision _1_8_DECISION_ONE = new MyDecision("FirstDecision"); public static final MyDecision _1_7_DECISION_TWO = new MyDecision("SecondDecision"); public static final MyDecision _1_6_DECISION_THREE = new MyDecision("ThirdDecision"); ... }
By default the key will be the name of the class. Optionally the getGroupName() method may be overridden to specify which structured data tag, the decision will reside under.
Note: Recording always prepends "TPR:" to the key. In the following example, the output will be recorded into structured data, under the key "TPR:MyStructuredDataTag".
protected String getGroupName() { return "MyStructuredDataTag"; }
4.3. Recording decisions
eSocket.POS includes convenience methods for recording decisions in both device drivers and pipeline components.
4.3.1. Recording decisions in a device driver
Decisions usually made in the device driver are provided by GenericDeviceDriverTransactionDecision . All device drivers that extend APhysicalDevice have a convenience method setDecision which should be used to set the devices decisions. These decisions will automatically be recorded by the PAN and EMV pipeline components. For example:
setDecision(GenericDeviceDriverTransactionDecision._1_5_PAN_ENTERED_MANUALLY);
4.3.2. Recording decisions in a pipeline component
Each pipeline component must define its own set of decisions. All pipelines that extend APipelineComponent provide the convenience method setDecision . Any decisions set in the pipeline component will automatically be recorded in the message after processing the request, and again after processing the response.
For example, the following could be used to set a decision:
setDecision(PanDecision._1_7_GET_PAN_FROM_CARD_READ);
4.3.3. General recording of decisions
When recording decisions outside the device driver or pipeline component, a TransactionProcessingResults object should be created to contain the decision bits. The TprRecorder provides convenience methods to set the decisions, directly or by recording the contents of the TransactionProcessingResults object, into the ISO 8583 message.
The following examples only record the second decision in the message.
Example 1:
TransactionProcessingResults tpr = new TransactionProcessingResults(MyDecision._1_8_DECISION_ONE); tpr.setDecision(MyDecisions._1_7_DECISION_TWO); TprRecorder.record(tpr, msg);
Example 2:
TprRecorder.record(MyDecisions._1_7_DECISION_TWO, msg);
4.3.4. Recording multiple different Transaction Processing Results
Multiple separate TransactionProcessingResults objects may be recorded using a TprRegistry object. The TprRegistry is a container that may contain multiple TransactionProcessingResults . Each of these TPRs will be recorded individually.
For example:
TprRecorder.record(tprRegistry, msg);
4.4. Retrieving decisions
TprRecorder should be used to obtain the correct structured data key for a given ATransactionDecision when reading a TPR from a message. The contents of the key can be decoded using TransactionProcessingResults.decode(String) method. Next, the isDecisionSet method can be used to check whether a specific bit is set.
For example:
String structDataValue = structuredData.get(TprRecorder.getGroupName(MyDecision._1_8_DECISION_ONE); TransactionProcessingResults tpr = new TransactionProcessingResults(MyDecision._1_8_DECISION_ONE); tpr.decode(structDataValue); boolean isSet = tpr.isDecisionSet(MyDecision._1_7_DECISION_TWO);
4.5. Using Caches in eSocket.POS
eSocket.POS provides a framework to handle the creation and access to in-memory caches. These caches can be used to store any Java object for the lifetime of the cache.
4.5.1. General concepts
A cache is logically divided into the objects placed into the cache ( AObjectCache ), the cache manager ( ACacheManager ) that keeps track of multiple named caches, the cache accessor ( ACacheAccessor ) which is used to access a cache, and finally the cache factory ( CacheAcessorFactory ) which is used to create the accessors
Local vs cross terminal caches
There are two types of cache managers, those that maintain local caches (a cache that can only accessed from the current eSocket.POS terminal), and those that maintain cross terminal caches. Both of these manager types have their own limitations, for example, the local cache cannot share its information with other terminals in a store server. A cross terminal cache cannot be resetForNextTran nor can it be closed and for this reason, a cross terminal cache cannot have a TranLifeObjectCache registered in it.
Cache lifetime
All caches described here are in-memory caches and are not persisted between eSocket.POS shutdowns, restarts or resyncs. When a cache is registered, the contents are given a time period for which they will exist. For example, a TranLifeObjectCache has its cache contents cleared when the eSocket.POS resets for the next transaction i.e. the cache only lasts for the duration of the current transaction in eSocket.POS. The TranLinkedObjectCache , on the other hand, is backed by a timed hash table and clears its contents based on the expiry time provided.
Registering and accessing the cache
The caches are registered and accessed through an accessor which, in turn, is provided by the accessor factory. The accessor factory can be obtained from the information server.
An example of registering a transaction life cache is as follows:
infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().registerTranLifeCache("my_cache_name", String.class);
An example of registering a timed cache is as follows:
infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().registerTimedCache("my_cache_name", String.class, 5 * 60 * 1000);
A value can be placed into the same cache as follows:
infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().set("my_cache_name", isoMsg,"Content String");
The value may be retrieved from the cache as follows:
String value = (String) infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().get("my_cache_name", isoMsg);
The value may be removed from the cache as follows:
String value = (String) infoServer.getCacheAccessorFactory().getTranLinkedCacheAccessor().remove("my_cache_name", isoMsg);
To access the same cache, it is important to use the same accessor object and also specify the same cache name. The different accessors specify what makes their cache elements distinct i.e. what value is used to key to different values in the cache.
The same cache can be registered with the same name, however, if the cache contains different configuration values to an existing cache with the same name, an exception will be thrown.
4.5.2. Cache Accessors Overview
This section gives a brief overview of the different available accessors.
BooleanTranLinkedCacheAccessor
This accessor provides convenience methods to store boolean values in the cache, otherwise this functions as a TranlinkedCacheAccessor .
MessageCacheAccessor
This accessor is used exclusively by the MessageCache in InformationServer to cache ISO8583 messages based on the transaction linking number in the messages and the terminal ID. This cache is used throughout eSocket.POS and should be handled with care. Since it caches the whole ISO8583 message and might contain sensitive data, the message is kept encrypted.
infoServer.getMessageCache().addRequestMessageToCache(isoMsg); Iso8583Post cachedMsg = infoServer.getMessageCache().getCachedRequestMessage(isoMsg); Iso8583Post cachedMsg = infoServer.getMessageCache().removeRequestMessageFromCache(isoMsg);
TranLinkedCacheAccessor
The content of this cache is keyed off the transaction linking number in the provided message and the current terminal ID. When registering a cache, a class type must be provided which is used to validate that only the allowed type is placed into the cache.
TranLinkMsgTypeCacheAccessor
The content of this cache is keyed off the transaction linking number and message type in the provided message and the current terminal ID. When registering a cache, a class type must be provided which is used to validate that only the allowed type is placed into the cache.
5. Object properties and conditions
The transaction table indicates which objects and properties should be set in a particular transaction.
The condition ( Cond ) of each property is indicated as:
-
M (mandatory) - the property should always be set;
-
C (conditional) - the property should only be set if certain conditions apply;
-
G (configuration) - the property should be set depending on eSocket.POS configuration; for instance if a particular Pipeline Component is configured, or a device is configured which is capable of retrieving and inserting the property, it may not be necessary for this property to be set;
-
O (optional) - the property may be set if applicable data is available.
Once the transaction has been performed, a response will be received. The response to a transaction will be returned in another Transaction object. In the response object - depending on the issuer’s response - some properties will be unmodified, others might be modified, and yet others not set in the original transaction might be set in the response.
The response condition ( Rsp ) of each property is indicated as:
-
A (always present) - the property will always be present;
-
T (original transaction) - the property will be present if it was present in the original transaction object;
-
G (configuration) - the property may be set depending on eSocket.POS configuration;
-
C (conditional) - the property may be set if certain conditions apply;
-
H (host) - the property will be set if sent by the upstream host system.
6. Diagnostic tools
6.1. Event log
A number of informational and error events are logged by eSocket.POS. Events are logged either to a text file or to the Windows event log, depending on configuration.
Configuring the Event log is described in the eSocket.POS User Guide .
6.1.1. Events
Event 10000
Severity: |
Informational |
Symbolic Name: |
ESOCKETPOS_STARTED |
Message: |
|
Text: |
The application %1 was started with parameters %2. |
Parameter %1: |
the application |
Parameter %2: |
startup parameters |
Description: |
The application has started successfully |
Action: |
None. |
Event 10001
Severity: |
Error |
Symbolic Name: |
COMMAND_PORT_NOT_LOADED |
Message: |
|
Text: |
eSocket.POS could not retrieve the command port from the Information Server for terminal %1. |
Parameter %1: |
the terminal ID |
Description: |
This event is logged when eSocket.POS fails to load the port number (on which it should receive commands) from the Information Server |
Action: |
Check the eSocket.POS configuration. |
Event 10002
Severity: |
Error |
Symbolic Name: |
COMPONENT_FAILURE |
Message: |
|
Text: |
The %1 component could not process a transaction it received from Terminal %3. The reason reported is: %2. |
Parameter %1: |
Component name |
Parameter %2: |
Description of the failure |
Parameter %3: |
Terminal ID |
Description: |
This event is logged when eSocket.POS component fails to function properly. The error may be caused by incorrect configuration, invalid data supplied to the component, or an error in the component. The event includes the name of the component that failed, and the description of the cause of the failure |
Action: |
Contact your primary support provider. |
Event 10003
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_DATASET_ACTIVATE_FAILED |
Message: |
|
Text: |
An error occurred while attempting to set the dataset "%1" active. When the command was issued dataset "%2" was active. The next message logged contains related technical information |
Parameter %1: |
the timestamp of the dataset that was requested to be made active |
Parameter %2: |
the timestamp of the dataset that was active when the command was issued. |
Description: |
An error occurred while attempting to mark the requested data set active. |
Action: |
Contact your primary support provider. |
Event 10004
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_FILE_FORMAT_INVALID |
Message: |
|
Text: |
The Configuration Agent was unable to validate the file "%1". The following fault was reported: %2 |
Parameter %1: |
the name of the file that could not be validated |
Parameter %2: |
the error that was reported |
Description: |
The named file could not be validated by the Configuration Agent |
Action: |
Determine the cause of the validation error and modify the file accordingly. |
Event 10005
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_INCR_LOAD_PREP_FAILED |
Message: |
|
Text: |
The Configuration Agent was unable to prepare the database for an incremental upload. The next event logged contains related technical information |
Description: |
An error occurred while preparing the database for the application of and incremental load |
Action: |
Contact your primary support provider. |
Event 10006
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_INVALID_PROPERTY |
Message: |
|
Text: |
The value "%2" is not a valid option for the key "%1". Please consult the User Guide for the appropriate values for this key. The Configuration Agent has not been started. |
Parameter %1: |
the key for which an incorrect value has been supplied |
Parameter %2: |
the incorrect value |
Description: |
An invalid value has been specified for an entry in the Configuration Agent’s properties file. |
Action: |
Consult the User Guide for the list of values are valid for this key and correct the entry in the properties file. |
Event 10007
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_LOAD_FAILED |
Message: |
|
Text: |
The Configuration Agent was unable to complete processing of the upload file "%1". This entire upload has been aborted and rolled back. The next message logged contains related technical information. |
Parameter %1: |
the name of the upload file that was being processed when the error |
Parameter %2: |
occurred |
Description: |
An error occurred while writing the contents of an upload file to the database |
Action: |
Contact your primary support provider. |
Event 10008
Severity: |
Warning |
Symbolic Name: |
CONFIG_AGENT_FILE_DELETE_FAILED |
Message: |
|
Text: |
The Configuration Agent was unable to complete deleting of the file "%1". |
Parameter %1: |
the name of the file that was being processed when the error |
Parameter %2: |
occurred |
Description: |
An error occurred while Configuration Agent was attempting to delete old configuration files. |
Action: |
Contact your primary support provider. |
Event 10009
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_LOAD_STATUS_MARK_FAILED |
Message: |
|
Text: |
The Configuration Agent was unable to mark the upload set as "%1". This upload has been aborted and rolled back. The next message logged contains related technical information. |
Parameter %1: |
the status mark that the Configuration Agent attempted to write |
Parameter %2: |
to the database |
Description: |
The status of the upload could not be written to the eSocket.POS database |
Action: |
If it was an attempt to mark an upload as 'loading' that failed, then ensure that a data set with the same timestamp as the aborted load does not yet exist in the database. If one does not exist then contact your primary support vendor. |
Event 10010
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_CLEANER_FAILED |
Message: |
|
Text: |
An SQL error occurred while the Configuration Agent was cleaning old configuration. The error occurred while the Configuration Agent was busy processing the %1 table. The previous event will contain more information on the nature of the SQL error. |
Parameter %1: |
the table that was being processed when the error occurred. |
Description: |
A SQL error occurred while cleaning old configuration data from the eSocket.POS database. |
Action: |
Contact your primary support provider. |
Event 10011
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_NO_EXTANT_DATA_FOR_INCREMENTAL_LOAD |
Message: |
|
Text: |
An incremental upload could not be applied because the eSocket.POS database contained no data. The upload has been aborted. |
Description: |
The Configuration Agent found and attempted to load an incremental upload file. However, the eSocket.POS database did not contain any data to which the incremental upload could be applied. |
Action: |
Apply a full upload file before attempting the incremental upload. |
Event 10012
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_PROPERTIES_FILE_NOT_FOUND |
Message: |
|
Text: |
The configuration file "%1" could not be loaded. The Configuration Agent has not been started |
Parameter %1: |
the name of the properties file from which the Configuration Agent |
Parameter %2: |
attempted to read its configuration options |
Description: |
The eSocket.POS Configuration Agent cannot load the properties file containing its configuration parameters |
Action: |
Ensure that a correctly named properties file is present in the directory from which the config agent was started |
Event 10013
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_PROPERTY_NOT_FOUND |
Message: |
|
Text: |
The required key "%1" has not been specified in the Configuration Agent’s properties file. The Configuration Agent has not been started. |
Parameter %1: |
the required key |
Description: |
A required property has not been specified in the Configuration Agent’s properties file. |
Action: |
Consult the User Guide for the correct name of the key and the values that are associated with it. |
Event 10014
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_PROPERTY_INVALID_VALUE |
Message: |
|
Text: |
The "%1" property has an invalid value "%2". Please refer to the user guide for information on the values allowed for this property. Until such time as this property is correctly specified the Config Agent will continue processing as if this property is not present. |
Parameter %1: |
the key of the property with invalid value. |
Parameter %2: |
the invalid value specified for the property. |
Description: |
A property has been populated with an invalid value in the Configuration Agent’s properties file. |
Action: |
Consult the User Guide for information on the allowed values for this property. |
Event 10015
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_UPLOAD_DIRECTORY_NOT_FOUND |
Message: |
|
Text: |
The specified upload directory "%1" could not be found |
Parameter %1: |
the name of the directory specified in the Configuration Agent’s |
Parameter %2: |
properties file as the one into which upload files are to be placed. |
Description: |
The upload directory specified in the properties file does not exist |
Action: |
Create the directory, or correct the name of the directory in the properties file and restart the Configuration Agent. |
Event 10016
Severity: |
Error |
Symbolic Name: |
DEVICE_CONNECT_FAILED |
Message: |
|
Text: |
A device connection failed for terminal ID %1 (IP address %2, port %3). |
Parameter %1: |
The terminal ID |
Parameter %2: |
The IP address |
Parameter %3: |
The port |
Description: |
A device connection failed. |
Action: |
Contact your primary support provider. |
Event 10017
Severity: |
Error |
Symbolic Name: |
DEVICE_DISCONNECTED |
Message: |
|
Text: |
eSocket.POS attempted to access a device which was not available. |
Description: |
eSocket.POS attempted to access a device which was not available. |
Action: |
Check that the device is connected and properly configured. |
Event 10018
Severity: |
Error |
Symbolic Name: |
DEVICE_INIT_FAILED |
Message: |
|
Text: |
The %1 device could not be initialized. |
Parameter %1: |
The device name |
Description: |
A device could not be initialized. |
Action: |
Contact your primary support provider. |
Event 10019
Severity: |
Error |
Symbolic Name: |
ENTITY_CLASS_NOT_FOUND |
Message: |
|
Text: |
The %1 configured class %2 could not be found. Terminal %3 affected. |
Parameter %1: |
Name of the entity for which the class is missing |
Parameter %2: |
Name of the missing class |
Parameter %3: |
Terminal ID |
Description: |
This event is logged when one of the classes specified in the configuration is not found. |
Action: |
Check the eSocket.POS configuration. |
Event 10020
Severity: |
Error |
Symbolic Name: |
ESP_PROPERTIES_FILE_NOT_FOUND |
Message: |
|
Text: |
eSocket.POS could not be started by terminal %1 because the properties file "%2" could not be found |
Parameter %1: |
The Terminal ID |
Parameter %2: |
The name of the properties file |
Description: |
This event is logged when the eSocket.POS properties file could not be found |
Action: |
Check the eSocket.POS configuration. |
Event 10021
Severity: |
Error |
Symbolic Name: |
ESP_PROPERTY_NOT_FOUND |
Message: |
|
Text: |
eSocket.POS could not be started because the property "%1" could not be found in the properties file |
Parameter %1: |
The Property that could not be found in the file |
Description: |
This event is logged when a required property could not be found in the eSocket.POS properties file |
Action: |
Check the eSocket.POS configuration. |
Event 10022
Severity: |
Error |
Symbolic Name: |
FAILED_TO_START |
Message: |
|
Text: |
eSocket.POS could not be started for terminal %1. The error reported is as follows: %2 |
Parameter %1: |
The Terminal ID |
Parameter %2: |
Error reported, or name of the entity which could not be instantiated |
Description: |
This event is logged when eSocket.POS fails to start properly. |
Action: |
Check the eSocket.POS configuration. |
Event 10023
Severity: |
Error |
Symbolic Name: |
FAILED_TO_START_DESCRIPTION |
Message: |
|
Text: |
eSocket.POS could not be started for terminal %1. The error reported is as follows: %2. Details of the error are as follows: %3 |
Parameter %1: |
The Terminal ID |
Parameter %2: |
Error reported, or name of the entity which could not be instantiated |
Parameter %3: |
The exception that resulted in the entity not starting |
Description: |
This event is logged when an eSocket.POS fails to start properly. |
Action: |
Check the eSocket.POS configuration. |
Event 10024
Severity: |
Error |
Symbolic Name: |
HOTCARD_LOAD_ERROR |
Message: |
|
Text: |
A record in a hotcard file could not be loaded and was ignored, or the hotcard file could not be loaded. The following error was reported: %1. |
Parameter %1: |
Text describing the error or the invalid record from the file |
Description: |
An error occurred while loading the hotcard file. |
Action: |
Determine the cause of the error and modify the file accordingly. If the error still occurs contact your primary support provider. |
Event 10025
Severity: |
Error |
Symbolic Name: |
DEPRECATED_EVENT_1 |
Message: |
|
Text: |
An unconfigured account type of %2 was entered for PAN %1. |
Parameter %1: |
The Primary Account Number |
Parameter %2: |
The account type entered |
Description: |
An account type was entered which was not configured for this card. This event previously called INVALID_ACCOUNT_TYPE is not used and should not be used in future since it contains the PAN in the clear. |
Action: |
Consult your primary support provider. |
Event 10026
Severity: |
Error |
Symbolic Name: |
DEPRECATED_EVENT_2 |
Message: |
|
Text: |
A card with PAN %1 was used but no BIN is configured for this PAN. |
Parameter %1: |
The Primary Account Number |
Description: |
A card was used with a BIN which was not configured. This event previously called INVALID_BIN is not used and should not be used in future since it contains the PAN in the clear. |
Action: |
Consult your primary support provider. |
Event 10027
Severity: |
Error |
Symbolic Name: |
INVALID_DEVICE_MSG |
Message: |
|
Text: |
A message could not be sent to the %1 device because it was invalid. |
Parameter %1: |
The device name |
Description: |
An attempt was made to send an invalid message to a device. |
Action: |
Contact your primary support provider. |
Event 10028
Severity: |
Error |
Symbolic Name: |
INVALID_DEVICE_RSP |
Message: |
|
Text: |
An invalid response was received from the %1 device. |
Parameter %1: |
The device name |
Description: |
An invalid response was received from a device. |
Action: |
Contact your primary support provider. |
Event 10029
Severity: |
Error |
Symbolic Name: |
KEYCHANGE_FAILED |
Message: |
|
Text: |
A PIN key change failed for terminal %1 with code %2. No PIN-based transactions can be processed. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The key change response code |
Description: |
The key change failed. This is usually a cryptographic configuration problem between the PIN Pad and the upstream entity. The key change will be retried at regular intervals until successful. |
Action: |
Identify the reason that the key change failed. |
Event 10030
Severity: |
Error |
Symbolic Name: |
MISSING_DATA |
Message: |
|
Text: |
Data required for mandatory field %1 could not be retrieved. |
Parameter %1: |
Field number |
Description: |
This event is logged when an eSocket.POS component fails to retrieve information which is required for a mandatory Iso8583 field. |
Action: |
Contact your primary support provider. |
Event 10031
Severity: |
Error |
Symbolic Name: |
NO_ORIGINAL_TRAN |
Message: |
|
Text: |
An original transaction was required but could not be found. |
Description: |
An original transaction was required but was not found by the information server. |
Action: |
Contact your primary support provider. |
Event 10032
Severity: |
Error |
Symbolic Name: |
REMOTE_SINK_RECVD_MSG_CONTAINS_NO_SWITCH_KEY |
Message: |
|
Text: |
The Sink Driver returned a message to the RemoteSink that does not contain a switch key ( 127.002 ). The message has been ignored |
Description: |
The Postilion Interface ( RemoteSink ) received a message with no switch key |
Action: |
Contact your primary support provider. |
Event 10033
Severity: |
Error |
Symbolic Name: |
SINK_ENTITY_UNSUPPORTED_MSG_FROM_TRAN_ENGINE |
Message: |
|
Text: |
An unsupported message (%1) was received from the Transaction Engine at Terminal %2. |
Parameter %1: |
The message type |
Parameter %2: |
The terminal ID |
Description: |
The eSocket.POS Sink Entity received an unsupported message from the eSocket.POS Transaction Engine. |
Action: |
Contact your primary support provider. |
Event 10034
Severity: |
Error |
Symbolic Name: |
SOURCE_ENTITY_UNSUPPORTED_MSG_FROM_EPOS |
Message: |
|
Text: |
An unsupported message (%1) was received from the EPOS system. Terminal ID %2. |
Parameter %1: |
The message type |
Parameter %2: |
The terminal ID |
Description: |
The eSocket.POS Source Entity received an unsupported message from the EPOS system. |
Action: |
Contact your primary support provider. |
Event 10035
Severity: |
Error |
Symbolic Name: |
TLV_EXTRACT_ERROR |
Message: |
|
Text: |
An EMV formatted message could not be unpacked. This usually refers to incorrectly formatted TLV data or PDOL data received from an EMV smartcard. The data was as follows: %1. |
Parameter %1: |
Contents of the message |
Description: |
An error occurred while unpacking an EMV formatted message. |
Action: |
Contact your primary support provider. |
Event 10036
Severity: |
Error |
Symbolic Name: |
UNABLE_TO_CONSTRUCT_REJECT_RSP |
Message: |
|
Text: |
eSocket.POS attempted to reject a message from the EPOS system but was unable to construct the reject response. |
Description: |
eSocket.POS attempted to reject a message from the EPOS system but was unable to construct the reject response. |
Action: |
Contact your primary support provider. |
Event 10037
Severity: |
Error |
Symbolic Name: |
UNABLE_TO_SAVE_MSG |
Message: |
|
Text: |
eSocket.POS (Terminal %1) was unable to save a message using the information server. |
Parameter %1: |
Terminal ID |
Description: |
eSocket.POS was unable to save a message. |
Action: |
Check that the message was properly formatted and the information server was properly configured. |
Event 10038
Severity: |
Error |
Symbolic Name: |
UNSUPPORTED_MSG_TYPE |
Message: |
|
Text: |
eSocket.POS received a message with an unsupported message type %1. |
Parameter %1: |
The unsupported message type received |
Description: |
eSocket.POS received a message with an unsupported message type. |
Action: |
Contact your primary support provider. |
Event 10039
Severity: |
Warning |
Symbolic Name: |
CLASS_NOT_FOUND |
Message: |
|
Text: |
The information server for terminal %1 could not find the class %2. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The requested data which is not contained in the store |
Description: |
The information server could not find the requested class. |
Action: |
Check that the class name is correctly configured and that the class is present in the correct location. |
Event 10040
Severity: |
Warning |
Symbolic Name: |
COMPONENT_DECLINED_TRAN |
Message: |
|
Text: |
The %1 component on Terminal %3 has declined a transaction it received. The reason returned was: %2. |
Parameter %1: |
Component name |
Parameter %2: |
Description of why the transaction was declined |
Parameter %3: |
Terminal ID |
Description: |
This event is logged when an eSocket.POS component declines a transaction. The event includes the name of the component that declined the transaction and a description of why the transaction was declined |
Action: |
Contact your primary support provider. |
Event 10041
Severity: |
Warning |
Symbolic Name: |
CONFIG_AGENT_ROLLBACK_FAILED |
Message: |
|
Text: |
The Configuration Agent was unable to completely rollback an aborted upload. The next event logged contains related technical information. |
Description: |
The Configuration Agent failed to rollback an aborted upload. This is not a critical failure as the data that could not be rolled back will not have marked active and will not be used by eSocket.POS |
Action: |
Contact your primary support provider. |
Event 10042
Severity: |
Warning |
Symbolic Name: |
COMPONENT_WRN_EXCEPTION |
Message: |
|
Text: |
The %1 component on Terminal %3 has logged the following warning: %2. |
Parameter %1: |
Component name |
Parameter %2: |
Description of the exception condition |
Parameter %3: |
Terminal ID |
Description: |
This event is logged when a component wished to report an exception condition that, while not serious enough to stop processing, may require technical attention. |
Action: |
Contact your primary support provider. |
Event 10043
Severity: |
Warning |
Symbolic Name: |
FAILED_TO_RETRIEVE_DATA |
Message: |
|
Text: |
The information server for terminal %1 failed to retrieve %2. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The data which could not be retrieved |
Description: |
The information server failed to retrieve the requested data. |
Action: |
Contact your primary support provider. |
Event 10044
Severity: |
Warning |
Symbolic Name: |
FAILED_TO_DELETE_DATA |
Message: |
|
Text: |
The information server for terminal %1 failed to delete data: %2. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The data which could not be deleted |
Description: |
The information server failed to delete the requested data. |
Action: |
Contact your primary support provider. |
Event 10045
Severity: |
Warning |
Symbolic Name: |
FAILED_TO_STORE_REQUEST |
Message: |
|
Text: |
The information server for terminal %1 failed to save a transaction request. |
Parameter %1: |
The terminal ID |
Description: |
The information server failed to save a transaction request. |
Action: |
Contact your primary support provider. |
Event 10046
Severity: |
Warning |
Symbolic Name: |
FAILED_TO_STORE_RESPONSE |
Message: |
|
Text: |
The information server for terminal %1 failed to save a transaction response. |
Parameter %1: |
The terminal ID |
Description: |
The information server failed to save a transaction response. |
Action: |
Contact your primary support provider. |
Event 10047
Severity: |
Warning |
Symbolic Name: |
FAILED_TO_UPDATE_DATA |
Message: |
|
Text: |
The information server for terminal %1 failed to update %2. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The data which could not be updated |
Description: |
The information server failed to update the requested data. |
Action: |
Contact your primary support provider. |
Event 10048
Severity: |
Warning |
Symbolic Name: |
FAILED_TO_RETRIEVE_FROM_STORE |
Message: |
|
Text: |
The information server for terminal %1 failed to retrieve information from the store. |
Parameter %1: |
The terminal ID |
Description: |
The information server failed to retrieve information from the store. |
Action: |
Contact your primary support provider. |
Event 10049
Severity: |
Warning |
Symbolic Name: |
FAILED_TO_RETRIEVE_MERCHANDISE_FROM_STORE |
Message: |
|
Text: |
The information server for terminal %1 failed to retrieve merchandise information with transaction number %2 from the store. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The transaction ID (Systems Trace Audit Number) |
Description: |
The information server failed to retrieve merchandise information from the store. |
Action: |
Contact your primary support provider. |
Event 10050
Severity: |
Warning |
Symbolic Name: |
FAILED_TO_RETRIEVE_TRAN_FROM_STORE |
Message: |
|
Text: |
The information server for terminal %1 failed to retrieve a transaction list for the System Trace Audit Number %2 from the store. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The transaction ID (Systems Trace Audit Number) |
Description: |
The information server failed to retrieve a transaction from the store. |
Action: |
Contact your primary support provider. |
Event 10051
Severity: |
Warning |
Symbolic Name: |
FAILED_TO_UPDATE_MERCHANDISE_IN_STORE |
Message: |
|
Text: |
The information server for terminal %1 failed to update merchandise information with transaction number %2 in the store. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The transaction ID (Systems Trace Audit Number) |
Description: |
The information server failed to update merchandise information in the store. |
Action: |
Contact your primary support provider. |
Event 10052
Severity: |
Warning |
Symbolic Name: |
KEYCHANGE_DISCONNECTED |
Message: |
|
Text: |
A PIN key change could not be performed because eSocket.POS is disconnected for terminal %1. |
Parameter %1: |
The terminal ID |
Description: |
The key change could not be performed because eSocket.POS is disconnected. The key change will be retried at regular intervals until eSocket.POS is connected. |
Action: |
Identify why eSocket.POS is disconnected. |
Event 10053
Severity: |
Warning |
Symbolic Name: |
NOT_FOUND_IN_INFO_STORE |
Message: |
|
Text: |
The information server for terminal %1 does not contain the requested data: %2. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The requested data which is not contained in the store |
Description: |
The information server does not contain the requested data. |
Action: |
Identify why the requested data is missing. |
Event 10054
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_CONFIG_LOAD_COMPLETED_SUCCESSFULLY |
Message: |
|
Text: |
The Configuration Agent has successfully applied a new %1 configuration |
Parameter %1: |
The configuration type |
Description: |
The Config Agent successfully applied a new set of configuration files to the eSocket.POS database. |
Action: |
None. |
Event 10055
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_CONFIG_LOAD_COMPLETED_UNSUCCESSFULLY |
Message: |
|
Text: |
The Configuration Agent has not successfully applied a new %1 configuration |
Parameter %1: |
The configuration type |
Description: |
An error occurred while applying a set of configuration files. |
Action: |
Contact your primary support provider. |
Event 10056
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_HOTCARD_LOAD_COMPLETE |
Message: |
|
Text: |
The Configuration Agent has successfully loaded new hotcard information |
Description: |
The Config Agent successfully applied a new set of hotcard data to the eSocket.POS database. |
Action: |
None. |
Event 10057
Severity: |
Warning |
Symbolic Name: |
CONFIG_AGENT_HTTP_DOWNLOAD_FAILED |
Message: |
|
Text: |
The Configuration Agent failed to download new configuration files via HTTP. Reason: %1 |
Parameter %1: |
The reason given for the failure |
Description: |
An error occurred while attempting to download new configuration files via http. Configuration file download failures and Hotcard configuration file download failures are logged separately. |
Action: |
Contact your primary support provider. |
Event 10058
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_HTTP_DOWNLOAD_COMPLETE |
Message: |
|
Text: |
The Configuration Agent has successfully downloaded new configuration files via HTTP |
Description: |
New configuration files were successfully downloaded via HTTP. |
Action: |
None. |
Event 10059
Severity: |
Warning |
Symbolic Name: |
CONFIG_AGENT_CANT_CREATE_DOWNLOAD_DIR |
Message: |
|
Text: |
The Configuration Agent was unable to create a directory in which to store downloaded configuration files |
Description: |
The configuration agent was unable to create a directory in which to store downloaded configuration files |
Action: |
Contact your primary support provider. |
Event 10060
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_STARTED |
Message: |
|
Text: |
The Configuration Agent has been successfully started |
Description: |
The Config Agent has started successfully. |
Action: |
None. |
Event 10061
Severity: |
Informational |
Symbolic Name: |
KEYCHANGE_SUCCESS |
Message: |
|
Text: |
The PIN key was successfully exchanged for terminal %1. |
Parameter %1: |
The terminal ID |
Description: |
The key change succeeded. |
Action: |
None. |
Event 10062
Severity: |
Informational |
Symbolic Name: |
DEVICE_STATUS_EVENT |
Message: |
|
Text: |
A status event was returned from device. Device Reason Code = %1. |
Parameter %1: |
Device reason/status code. |
Description: |
Declined status event returned from device. |
Action: |
Contact your primary support provider. |
Event 10063
Severity: |
Error |
Symbolic Name: |
XML_VALUE_VALIDATION_ERROR |
Message: |
|
Text: |
The value specified in a xml element or attribute does not conform to the required format. Element/Attribute name: %1. Specified value: %2. Description: %3. |
Parameter %1: |
Field name |
Parameter %2: |
Value specified |
Parameter %3: |
Description |
Description: |
This event is logged if the value specified in a xml element or attribute does not conform to the required format. |
Action: |
Contact your primary support provider. |
Event 10064
Severity: |
Error |
Symbolic Name: |
DEVICE_CONFIG_LOAD_FAILED |
Message: |
|
Text: |
The device configuration load for terminal %1 failed due to the following reason: %2 |
Parameter %1: |
Terminal name |
Parameter %2: |
Description |
Description: |
This event is logged if device configuration loading failed. |
Action: |
Contact your primary support provider. |
Event 10065
Severity: |
Error |
Symbolic Name: |
ESP_PROPERTY_VALUE_ERROR |
Message: |
|
Text: |
A property value for terminal %1 was incorrectly specified. Description: %2 |
Parameter %1: |
The Terminal ID |
Parameter %2: |
A description of the error |
Description: |
This event is logged when a property found in the eSocket.POS properties file is incorrectly specified / formatted |
Action: |
Check the eSocket.POS configuration. |
Event 10066
Severity: |
Error |
Symbolic Name: |
DEVICE_COMMS_ERROR |
Message: |
|
Text: |
A communication error occurred: %1 |
Parameter %1: |
A description of the error |
Description: |
This event is logged if a problem occurs during serial or TCP/IP communication with a device |
Action: |
Check the communication configuration for the device. |
Event 10067
Severity: |
Informational |
Symbolic Name: |
CHECK_READ_MICR_UNPACK_FAIL |
Message: |
|
Text: |
The checkreader at Terminal %3 was unable to unpack data %1 because %2. |
Parameter %1: |
The micr data line |
Parameter %2: |
Unpack fail reason |
Parameter %3: |
Terminal ID |
Description: |
This event is logged if the Check Read Component is unable to unpack the micr line |
Action: |
Contact your primary support provider. |
Event 10068
Severity: |
Error |
Symbolic Name: |
SMARTCARD_READER_ERROR |
Message: |
|
Text: |
The smartcard reader encountered the following error: %1 |
Parameter %1: |
The error encountered |
Description: |
This event is logged if the card reader encountered an error. |
Action: |
Contact your primary support provider. |
Event 10069
Severity: |
Error |
Symbolic Name: |
ATTEMPT_TO_SET_NULL_TLV_VALUE |
Message: |
|
Text: |
A tlv field could not be set as the value provided for that field was null. The field tag was: %1 |
Parameter %1: |
The tlv tag that was being set with a null value |
Description: |
This event is logged if a tlv field was set with a null value |
Action: |
Contact your primary support provider. |
Event 10070
Severity: |
Error |
Symbolic Name: |
DEVICE_TIMED_OUT |
Message: |
|
Text: |
Timed out while waiting for a response from a %1 device. |
Parameter %1: |
Name of the entity which timed out |
Description: |
This event is logged if a time out was encountered while waiting for a response from a device. |
Action: |
Contact your primary support provider. |
Event 10071
Severity: |
Error |
Symbolic Name: |
MONITORING_MSG_NOT_SENT |
Message: |
|
Text: |
A monitoring message could not be sent. At the time of this attempt the state of the eSocket.POS system was %1. |
Parameter %1: |
The system state when this error was logged. |
Description: |
This event is logged if the Monitoring component cannot send an 0800 Monitoring message because eSocket.POS is not connected. |
Action: |
Contact your primary support provider if necessary. |
Event 10072
Severity: |
Error |
Symbolic Name: |
DEVICE_UPDATE_FAILED |
Message: |
|
Text: |
Update failed for the %1 device. The error reported was: %2. |
Parameter %1: |
The device name |
Parameter %2: |
The error message |
Description: |
This event is logged if a device firmware update fails. |
Action: |
Contact your primary support provider. |
Event 10073
Severity: |
Informational |
Symbolic Name: |
DEVICE_UPDATE_SUCCESS |
Message: |
|
Text: |
Firmware update completed successfully for the %1 device. |
Parameter %1: |
The device name |
Description: |
This event is logged if a device firmware update completes successfully. |
Action: |
None. |
Event 10074
Severity: |
Error |
Symbolic Name: |
CLASS_VERSION_MISMATCH |
Message: |
|
Text: |
The current class version does not match the required one. A possible VM restart may be required to load a patched class. If problems are encountered after the restart, please contact your primary support provider to obtain the updated device integration code. |
Description: |
This event is logged after a device firmware update completes successfully but the class version validation fails. |
Action: |
Restart the VM. Contact your primary support provider if the problem persists. |
Event 10075
Severity: |
Informational |
Symbolic Name: |
SOFTWARE_UPDATE_COMPLETED |
Message: |
|
Text: |
The Configuration agent has successfully applied a new software update |
Description: |
This event is logged after a software update completes successfully |
Action: |
None. |
Event 10076
Severity: |
Error |
Symbolic Name: |
SOFTWARE_UPDATE_FAILED |
Message: |
|
Text: |
The Configuration agent failed to apply the new software update |
Description: |
This event is logged if a software update failed to complete |
Action: |
Contact your primary support provider. |
Event 10077
Severity: |
Informational |
Symbolic Name: |
SOFTWARE_UPDATE_ROLLBACK_COMPLETED |
Message: |
|
Text: |
The Configuration agent has successfully rolled back the failed software update |
Description: |
This event is logged after a software update has been rolled back |
Action: |
None. |
Event 10078
Severity: |
Informational |
Symbolic Name: |
SOFTWARE_UPDATE_CONFIGURATION_NOT_APPLIED |
Message: |
|
Text: |
The Configuration agent has not applied the set of configuration files due to a failed software update |
Description: |
This event is logged after a software update has failed, therefore the associated configuration was not applied |
Action: |
Contact your primary support provider. |
Event 10079
Severity: |
Error |
Symbolic Name: |
FATAL_PRINTER_ERROR |
Message: |
|
Text: |
A fatal printer error has occurred. The receipt printing has been aborted. |
Description: |
This event is logged when a fatal printer error occurs and a receipt could not be printed. |
Action: |
Contact your primary support provider. |
Event 10080
Severity: |
Error |
Symbolic Name: |
RECEIPT_PARSE_FAILURE |
Message: |
|
Text: |
A receipt of type %1 could not be constructed. The receipt printing has been aborted. The following error has been reported: %2 |
Parameter %1: |
The receipt type that could not be parsed. |
Parameter %2: |
A description of the exact problem that has occurred. |
Description: |
This event is logged if a raw receipt definition could not be parsed. |
Action: |
Contact your primary support provider. |
Event 10081
Severity: |
Error |
Symbolic Name: |
REMOTE_SINK_DISCARDED_ADVICE |
Message: |
|
Text: |
The RemoteSink discarded an advice message after %1 attempts to send it. |
Parameter %1: |
The number of attempts to send the message after which it was discarded. |
Description: |
The Postilion Interface (RemoteSink) discarded an advice message after exceeding the maximum number of retry attempts. |
Action: |
Investigate why eSocket.POS did not receive a response to this advice. This transaction may be resubmitted. |
Event 10082
Severity: |
Informational |
Symbolic Name: |
SQL_DATA_UPDATE_COMPLETED |
Message: |
|
Text: |
The Configuration agent has successfully applied a new SQL data update |
Description: |
This event is logged after a SQL data update completes successfully |
Action: |
None. |
Event 10083
Severity: |
Error |
Symbolic Name: |
SQL_DATA_UPDATE_FAILED |
Message: |
|
Text: |
The Configuration agent failed to apply the new SQL data update |
Description: |
This event is logged if a SQL data update failed to complete |
Action: |
Contact your primary support provider. |
Event 10084
Severity: |
Informational |
Symbolic Name: |
SQL_DATA_UPDATE_ROLLBACK_COMPLETED |
Message: |
|
Text: |
The Configuration agent has successfully rolled back the failed SQL data update |
Description: |
This event is logged after a SQL data update has been rolled back |
Action: |
None. |
Event 10085
Severity: |
Informational |
Symbolic Name: |
SOFTWARE_UPGRADE_PENDING |
Message: |
|
Text: |
Upgrade(s) pending: %1. Configuration changes will not be applied until all upgrades are complete. |
Parameter %1: |
The names of the pending software upgrades. |
Description: |
This event is logged when Configuration changes are not loaded yet because there are upgrades pending. |
Action: |
None. |
Event 10086
Severity: |
Warning |
Symbolic Name: |
CONFIG_AGENT_HTTP_UPLOAD_FAILED |
Message: |
|
Text: |
The Configuration Agent failed to upload files via http. Reason: %1 |
Parameter %1: |
The reason given for the failure |
Description: |
An error occurred while attempting to upload files via http |
Action: |
Contact your primary support provider. |
Event 10087
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_HTTP_UPLOAD_COMPLETE |
Message: |
|
Text: |
The Configuration Agent has successfully uploaded files via HTTP |
Description: |
New files were successfully uploaded via HTTP. |
Action: |
None. |
Event 10088
Severity: |
Error |
Symbolic Name: |
LOG_DRIVER_FAILURE |
Message: |
|
Text: |
The Log Driver %1 threw the following exception: %2 |
Parameter %1: |
The name of the log driver |
Parameter %2: |
The exception that was thrown |
Description: |
A log driver threw an exception while attempting to log an event. |
Action: |
Contact your primary support provider. |
Event 10089
Severity: |
Error |
Symbolic Name: |
CHAINED_TRAN_RESOLVE_FAILURE |
Message: |
|
Text: |
PosConnectSinkDriver could not resolve the system trace number %1 to a previous transaction. |
Parameter %1: |
The invalid System Trace Audit Number |
Description: |
This event is logged when PosConnectSinkDriver fails to resolve a chained transaction id to a previous transaction. |
Action: |
Contact your primary support provider. |
Event 10090
Severity: |
Error |
Symbolic Name: |
FAIL_TO_RENAME_FILE |
Message: |
|
Text: |
Config Agent could not rename the file %1. |
Parameter %1: |
The name of the file |
Description: |
This event is logged when Config Agent fails to rename an upload file. |
Action: |
Contact your primary support provider. |
Event 10091
Severity: |
Error |
Symbolic Name: |
RANK_NOT_INTEGER |
Message: |
|
Text: |
The rank for the %1 pipeline component must be an integer. %2 is not a valid rank value. |
Parameter %1: |
The pipeline component tag |
Parameter %2: |
The pipeline component rank |
Description: |
This event is logged if the value configured for the rank of a pipeline component is not an integer. |
Action: |
Contact your primary support provider. |
Event 10092
Severity: |
Error |
Symbolic Name: |
ESP_GLOBAL_PROPERTY_VALUE_ERROR |
Message: |
|
Text: |
The value for property, %1, is invalid. Description: %2 |
Parameter %1: |
The name of the property |
Parameter %2: |
A description of the error |
Description: |
This event is logged when a property found in the eSocket.POS properties file is incorrectly specified / formatted |
Action: |
Check the eSocket.POS properties file configuration. |
Event 10093
Severity: |
Error |
Symbolic Name: |
PAN_ENCRYPTION_KEY_MISSING |
Message: |
|
Text: |
The RSA Public Key required for PAN encryption is not available. |
Description: |
This event is logged when a PAN cannot be encrypted because there is no RSA Public Key available to use for encryption. |
Action: |
Contact your primary support provider. |
Event 10094
Severity: |
Informational |
Symbolic Name: |
CERTIFICATE_CHANGE_SUCCESS |
Message: |
|
Text: |
The RSA Certificate with alias, %1, was successfully retrieved and stored. |
Parameter %1: |
The alias of the certificate. |
Description: |
The RSA certificate change succeeded. |
Action: |
None. |
Event 10095
Severity: |
Error |
Symbolic Name: |
CERTIFICATE_CHANGE_INVALID_RESPONSE |
Message: |
|
Text: |
The RSA Certificate change cannot be processed: %1. |
Parameter %1: |
The reason for the failure. |
Description: |
The RSA certificate change 0810 response message is invalid or the request was declined. |
Action: |
Identify the reason that the certificate change failed. |
Event 10096
Severity: |
Error |
Symbolic Name: |
CERTIFICATE_CHANGE_EXCEPTION |
Message: |
|
Text: |
The RSA Certificate change cannot be processed by terminal, %1, because of an unexpected exception. |
Parameter %1: |
The terminal ID that attempted to process the request |
Description: |
The RSA Certificate change cannot be processed because of an unexpected exception. |
Action: |
Identify the reason that the certificate change failed. |
Event 10097
Severity: |
Warning |
Symbolic Name: |
CERTIFICATE_CHANGE_DISCONNECTED |
Message: |
|
Text: |
An RSA Certificate change could not be performed because eSocket.POS is disconnected for terminal %1. |
Parameter %1: |
The terminal ID |
Description: |
The certificate change could not be performed because eSocket.POS is disconnected. The certificate change will be retried at regular intervals until eSocket.POS is connected. |
Action: |
Identify why eSocket.POS is disconnected. |
Event 10098
Severity: |
Informational |
Symbolic Name: |
RSA_CERTIFICATE_UPDATE_COMPLETED |
Message: |
|
Text: |
The Configuration agent has successfully updated an RSA certificate. |
Description: |
This event is logged after an RSA certificate update completes successfully |
Action: |
None. |
Event 10099
Severity: |
Error |
Symbolic Name: |
RSA_CERTIFICATE_UPDATE_FAILED |
Message: |
|
Text: |
The Configuration agent failed to update an RSA certificate. |
Description: |
This event is logged if an RSA certificate update failed to complete |
Action: |
Contact your primary support provider. |
Event 10100
Severity: |
Error |
Symbolic Name: |
SSL_SERVER_AUTHENTICATION_FAILURE |
Message: |
|
Text: |
The SSL certificate provided by the server is not trusted. Server details: %1. Serial number: %2. |
Parameter %1: |
The server certificate details. |
Parameter %2: |
The server certificate serial number. |
Description: |
This event is logged if the server certificate provided by the server during the SSL handshake is not trusted. |
Action: |
Check the SSL configuration. |
Event 10101
Severity: |
Informational |
Symbolic Name: |
SSL_KEYSTORE_INITIALIZATION |
Message: |
|
Text: |
An SSL connection has been established for the first time. The following server certificate will be trusted in the future: %1. Serial number: %2. |
Parameter %1: |
The server certificate details. |
Parameter %2: |
The server certificate serial number. |
Description: |
This event is logged when eSocket.POS or Config Agent connect to the server for the first time and receive a certificate that they will trust in the future. |
Action: |
Check the SSL configuration. |
Event 10102
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_HTTP_DISCONNECT_FAILED |
Message: |
|
Text: |
The Configuration Agent failed to disconnect from the HTTP server. |
Description: |
An error occurred while attempting to disconnect from the HTTP server |
Action: |
Contact your primary support provider. |
Event 10103
Severity: |
Informational |
Symbolic Name: |
ESOCKETPOS_STOPPED |
Message: |
|
Text: |
eSocket.POS has been closed for terminal %1. |
Parameter %1: |
The terminal ID of the terminal that was closed. |
Description: |
This event is logged when eSocket.POS is shut down for a terminal |
Action: |
Event 10104
Severity: |
Warning |
Symbolic Name: |
CONFIG_AGENT_UNABLE_TO_GET_INSTALLED_APPS |
Message: |
|
Text: |
The Configuration Agent failed to determine the installed applications. |
Description: |
The list of installed applications could not be determined. |
Action: |
Contact your primary support provider. |
Event 10105
Severity: |
Error |
Symbolic Name: |
REMOTE_SINK_DISCARDED_ADVICE_AFTER_MAX_TIME_LIMIT |
Message: |
|
Text: |
The RemoteSink discarded an advice message (transaction number %1) after approximately %2 minutes, due to a software or database error. |
Parameter %1: |
The approximate maximum time limit in minutes to retry sending the message. |
Description: |
The Postilion Interface (RemoteSink) discarded an advice message after approximately the maximum retry time limit, due to a software or database error. |
Action: |
Investigate why eSocket.POS could not send this message. |
Event 10106
Severity: |
Warning |
Symbolic Name: |
SINK_DRIVER_RESPONSE_PROCESSING_ERROR |
Message: |
|
Text: |
The Sink Driver encountered an error when attempting to process a response received from the upstream entity. See the previous event for more information. |
Description: |
The Sink Driver encountered an error when attempting to process a response received from the upstream entity. |
Action: |
Investigate why the sink driver encountered an error. |
Event 10107
Severity: |
Error |
Symbolic Name: |
FAILED_TO_RESTART |
Message: |
|
Text: |
eSocket.POS could not be restarted. The error reported is as follows: %1 Details of the error are as follows: %2 |
Parameter %1: |
Error reported. |
Parameter %2: |
The exception that caused the error. |
Description: |
This event is logged when eSocket.POS fails to restart properly. |
Action: |
Check the eSocket.POS configuration. |
Event 10108
Severity: |
Error |
Symbolic Name: |
FAILED_TO_RESYNC |
Message: |
|
Text: |
Could not resync eSocket.POS for terminal %1. The error reported is as follows: %2. |
Parameter %1: |
Terminal identifier. |
Parameter %2: |
Error reported. |
Description: |
This event is logged when eSocket.POS fails to resync a terminal. |
Action: |
Check the eSocket.POS configuration. |
Event 10109
Severity: |
Informational |
Symbolic Name: |
GLOBAL_RESTART |
Message: |
|
Text: |
Global restart initiated. |
Description: |
This event is logged before eSocket.POS attempts to restart. |
Action: |
None. |
Event 10110
Severity: |
Error |
Symbolic Name: |
TRANSACTION_FAIL_RESYNC_IN_PROGRESS |
Message: |
|
Text: |
Could not process transaction for terminal %1 because a resync is in progress. |
Parameter %1: |
Terminal identifier. |
Description: |
This event is logged when eSocket.POS fails to process a transaction because a resync is in progress. |
Action: |
Resend transaction after resync completed. |
Event 10111
Severity: |
Error |
Symbolic Name: |
TASK_HANDLER_TASK_FAIL |
Message: |
|
Text: |
A task failed due to the following error: %1 %2 |
Parameter %1: |
The exception that caused the error. |
Parameter %2: |
Stack trace |
Description: |
This event is logged when one of the task handler tasks fails due to a runtime exception. |
Action: |
Check the eSocket.POS configuration. |
Event 10112
Severity: |
Warning |
Symbolic Name: |
PROCESSING_TERMINATED_TERMINAL_INSTANCE_CLOSED |
Message: |
|
Text: |
The transaction cannot be processed: the eSocket.POS terminal instance has been closed. |
Description: |
This event is logged when an eSocket.POS instance is closed while a transaction is in flight. |
Action: |
No action is required. |
Event 10113
Severity: |
Informational |
Symbolic Name: |
CUSTOMER_CANCELLED |
Message: |
|
Text: |
Transaction cancelled by customer. |
Description: |
This event is logged when the customer cancelled the transaction. |
Action: |
No action is required. |
Event 10114
Severity: |
Warning |
Symbolic Name: |
CUSTOMER_TIMEOUT |
Message: |
|
Text: |
Timeout while waiting for customer response. |
Description: |
This event is logged when a timeout occurs while awaiting customer information. |
Action: |
No action is required. |
Event 10115
Severity: |
Error |
Symbolic Name: |
CARD_READ_RETRIES_EXCEEDED |
Message: |
|
Text: |
The number of card read retries is exceeded. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when the number of card read retries is exceeded. |
Action: |
No action is required. |
Event 10116
Severity: |
Error |
Symbolic Name: |
NO_SUPPORTED_APPLICATIONS |
Message: |
|
Text: |
No supported applications were found. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when there are no supported applications. |
Action: |
No action is required. |
Event 10117
Severity: |
Error |
Symbolic Name: |
CARDHOLDER_VERIFICATION_FAILURE |
Message: |
|
Text: |
Cardholder verification has failed. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when cardholder verification fails. |
Action: |
No action is required. |
Event 10118
Severity: |
Warning |
Symbolic Name: |
ICC_BLOCKED |
Message: |
|
Text: |
ICC data is blocked. |
Description: |
This event is logged when ICC data is blocked. |
Action: |
No action is required. |
Event 10119
Severity: |
Error |
Symbolic Name: |
ICC_TRANSACTION_FAILED |
Message: |
|
Text: |
An ICC transaction has failed. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when an ICC transaction fails. |
Action: |
No action is required. |
Event 10120
Severity: |
Error |
Symbolic Name: |
DEVICE_FAILURE |
Message: |
|
Text: |
A device failure occurred. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when the device fails. |
Action: |
No action is required. |
Event 10121
Severity: |
Error |
Symbolic Name: |
FAILURE_TO_COMPLETE_ONLINE_TRANSACTION |
Message: |
|
Text: |
Failure to complete online transaction. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when an online transaction was not completed. |
Action: |
No action is required. |
Event 10122
Severity: |
Warning |
Symbolic Name: |
CARD_STILL_IN_SLOT |
Message: |
|
Text: |
The card is still in the slot. |
Description: |
This event is logged when the card is still in the slot. |
Action: |
No action is required. |
Event 10123
Severity: |
Error |
Symbolic Name: |
CARD_INSERT_RETRIES_EXCEEDED |
Message: |
|
Text: |
The card insert retries have been exceeded. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when the card insert retries have been exceeded. |
Action: |
No action is required. |
Event 10124
Severity: |
Informational |
Symbolic Name: |
OPERATOR_CANCELLED |
Message: |
|
Text: |
The operator has cancelled an operation. |
Description: |
This event is logged when the operator cancels a transaction. |
Action: |
No action is required. |
Event 10125
Severity: |
Error |
Symbolic Name: |
FAILED_TO_START_ENTITY |
Message: |
|
Text: |
eSocket.POS could not be started for terminal %1, entity %2 The error reported is as follows: %3 |
Parameter %1: |
The Terminal ID |
Parameter %2: |
The entity name |
Parameter %3: |
Error reported, or name of the entity which could not be instantiated |
Description: |
This event is logged when eSocket.POS fails to start properly. |
Action: |
Check the eSocket.POS configuration. |
Event 10126
Severity: |
Error |
Symbolic Name: |
FAILED_TO_START_MESSAGE |
Message: |
|
Text: |
eSocket.POS could not be started. The error reported is as follows: %1. |
Parameter %1: |
Error reported, due to nature of the error, no further information is available. |
Description: |
This event is logged when eSocket.POS fails to start properly. |
Action: |
Check the eSocket.POS configuration. |
Event 10127
Severity: |
Error |
Symbolic Name: |
ESOCKETPOS_MISCONFIGURED |
Message: |
|
Text: |
eSocket.POS is not configured correctly. The error reported is as follows: %1 |
Parameter %1: |
Error reported. |
Description: |
This event is logged when eSocket.POS is not configured correctly. |
Action: |
Check the eSocket.POS configuration. |
Event 10128
Severity: |
Error |
Symbolic Name: |
DEVICE_CONNECT_FAILURE |
Message: |
|
Text: |
A device connection failed for terminal ID %1 (SAP address %2, SetupData %3). |
Parameter %1: |
The terminal ID |
Parameter %2: |
The SAP address |
Parameter %3: |
The setup data |
Description: |
A device connection failed. |
Action: |
Contact your primary support provider. |
Event 10129
Severity: |
Error |
Symbolic Name: |
FAILED_TO_MASK_SENSITIVE_DATA |
Message: |
|
Text: |
eSocket.POS failed to mask %1 because %2. |
Parameter %1: |
The name of the sensitive data field |
Parameter %2: |
The error reported |
Description: |
Failed to mask sensitive data. |
Action: |
Contact your primary support provider. |
Event 10130
Severity: |
Warning |
Symbolic Name: |
NOT_PCI_COMPLIANT |
Message: |
|
Text: |
%1 may have been started in a non-PCI compliant manner. The configuration causing concern is: %2 |
Parameter %1: |
The eSocket.POS specific application, ie. eSocket.POS or Config Agent. |
Parameter %2: |
The configuration that may cause eSocket.POS to not be PCI compliant |
Description: |
eSocket.POS may have been started in a non-PCI compliant manner. |
Action: |
Consult the eSocket.POS documentation and check the configuration. |
Event 10131
Severity: |
Error |
Symbolic Name: |
ESP_SAP_INVALID_CONFIG |
Message: |
|
Text: |
The SAP configuration is not valid. The error reported is as follows: %1 |
Parameter %1: |
Error reported. |
Description: |
This event is logged when a SAP is incorrectly configured. |
Action: |
Verify that the SAP configuration is correct. |
Event 10132
Severity: |
Warning |
Symbolic Name: |
SSL_LOCAL_CERT_OLD |
Message: |
|
Text: |
The current date and time is close to the expiry date given in a certificate that was used to authenticate eSocket.POS to a remote entity. The certificate with alias %1 is valid until %2. Certificate Details: %3. Serial number: %4. |
Parameter %1: |
The alias used to retrieve the certificate from the SSL keystore. |
Parameter %2: |
The not after date of the validity period taken from the certificate. |
Parameter %3: |
The subject distinguished name from the certificate. |
Parameter %4: |
The serial number from the certificate. |
Description: |
This is event is logged if the current date and time is close to the expiry date given in a certificate that was used to authenticate eSocket.POS to a remote entity. |
Action: |
Update the local certificate before it expires. |
Event 10133
Severity: |
Warning |
Symbolic Name: |
SSL_LOCAL_CERT_NOT_VALID |
Message: |
|
Text: |
The current date and time is not within the validity period given in a certificate that was selected for authenticating eSocket.POS to the remote entity. The certificate with alias %1 is valid from %2 until %3. Certificate Details: %4. Serial Number: %5. |
Parameter %1: |
The alias used to retrieve the certificate from the SSL keystore. |
Parameter %2: |
The not before date of the validity period taken from the certificate. |
Parameter %3: |
The not after date of the validity period taken from the certificate. |
Parameter %4: |
The subject distinguished name from the certificate. |
Parameter %5: |
The serial number from the certificate. |
Description: |
This event is logged when the current date and time is not within the validity period given in a certificate that was selected for authenticating eSocket.POS to a remote entity. eSocket.POS will not drop the SSL connection, but it is likely that the remote entity will. |
Action: |
If the connection fails then the local certificate should be updated, or the configuration should be updated to use a different local certificate. |
Event 10134
Severity: |
Error |
Symbolic Name: |
SSL_CLIENT_AUTHENTICATION_FAILURE |
Message: |
|
Text: |
The SSL certificate provided by the client is not trusted. Client details: %1. Serial number: %2. |
Parameter %1: |
The client certificate details. |
Parameter %2: |
The client certificate serial number. |
Description: |
This event is logged if the certificate provided by the remote client during the SSL handshake is not trusted. |
Action: |
Check the SSL configuration. |
Event 10135
Severity: |
Error |
Symbolic Name: |
SSL_NO_SERVER_CERTIFICATE |
Message: |
|
Text: |
The remote server did not provide a SSL certificate, the connection will be dropped. |
Description: |
This event is logged if the server does not provide a certificate and eSocket.POS is required to authenticate the server. |
Action: |
Check the SSL configuration on eSocket.POS and on the remote server. |
Event 10136
Severity: |
Error |
Symbolic Name: |
MESSAGE_ENCRYPTION_KEY_MISSING |
Message: |
|
Text: |
The RSA Public Key required for MESSAGE encryption is not available. |
Description: |
This event is logged when a message cannot be encrypted because there is no RSA Public Key available to use for encryption. |
Action: |
Contact your primary support provider. |
Event 10137
Severity: |
Error |
Symbolic Name: |
MSG_DECRYPTION_ERROR |
Message: |
|
Text: |
The endpointfilter could not decrypt a message and the message will be ignored. |
Description: |
This event is logged when a general error occurred while decrypting a message in the EndpointFilterEncrypt class. |
Action: |
Contact your primary support provider. |
Event 10138
Severity: |
Error |
Symbolic Name: |
MSG_ENCRYPTION_ERROR |
Message: |
|
Text: |
The endpoint filter could not encrypt a message and the message will be ignored. |
Description: |
This event is logged when a general error occurred while encrypting a message in the EndpointFilterEncrypt class. |
Action: |
Contact your primary support provider. |
Event 10139
Severity: |
Error |
Symbolic Name: |
CIPHER_KEY_GENERATION_ERROR |
Message: |
|
Text: |
A new cipher key could not be generated. |
Description: |
This event is logged when an error occurred when a new cipher key was generated for message encryption. |
Action: |
Contact your primary support provider. |
Event 10140
Severity: |
Warning |
Symbolic Name: |
SECURE_DIRECTORY_CREATED |
Message: |
|
Text: |
Config Agent created the secure config directory at: %1. Ensure that the security permissions to this directory is configured such that only the Config Agent and Upgrade Manager processes has write privileges to it. |
Parameter %1: |
The name of the secure incoming directory. |
Description: |
This event is logged when Config Agent creates the secure config directory. This directory is used internally by the application and it should be configured such that only the Config Agent and Upgrade Manager processes has write privileges to it. |
Action: |
Configure the security permissions such that only the Config Agent and Upgrade Manager processes has write access to this directory. |
Event 10141
Severity: |
Warning |
Symbolic Name: |
SIGNING_CERTIFICATE_INITIALIZATION |
Message: |
|
Text: |
A signing certificate is being loaded for the first time and it will be trusted in future. Please inspect the following certificate and ensure that it is trusted: %1 |
Parameter %1: |
The certificate details. |
Description: |
This event is logged the first time that Config Agent receives a signer certificate as part of a PKI Data Update. The certificate will be trusted in the future. |
Action: |
Inspect the installed certificate and ensure that it belongs to a trusted source. |
Event 10142
Severity: |
Error |
Symbolic Name: |
JAR_AUTHENTICATION_FAILURE |
Message: |
|
Text: |
The Configuration Agent was unable to authenticate the file "%1". The following reason was reported: %2 %3 |
Parameter %1: |
The name of the file that failed authentication |
Parameter %2: |
The reason that authentication failed |
Parameter %3: |
Additional Data associated with the error |
Description: |
This event is logged when authentication of a JAR file fails. |
Action: |
Ensure that the Configuration Server is correctly configured to distribute signed files and that the correct certificates are loaded into the eSocket.POS Trusted Certificate Store. |
Event 10143
Severity: |
Informational |
Symbolic Name: |
PKI_DATA_UPDATE_COMPLETED |
Message: |
|
Text: |
The Configuration agent has successfully applied a PKI Data Update. |
Description: |
This event is logged after successfully applying a PKI data update. |
Action: |
None. |
Event 10144
Severity: |
Error |
Symbolic Name: |
PKI_DATA_UPDATE_FAILED |
Message: |
|
Text: |
The Configuration agent failed to apply a PKI Data Update. |
Description: |
This event is logged if a PKI data update failed. |
Action: |
Contact your primary support provider. |
Event 10145
Severity: |
Error |
Symbolic Name: |
JVM_VERSION_NOT_SUPPORTED |
Message: |
|
Text: |
An attempt was made to use functionality that is not supported on the version of the Java Virtual Machine that is currently running. The description of the functionality is as follows: %1 |
Parameter %1: |
A description of the functionality that is not supported on this JVM. |
Description: |
Some functionality is only supported on specific versions of the Java Virtual Machine. This error is logged when an attempt is made to use functionality that is not supported on the current Java Virtual Machine. |
Action: |
Install a later version of the Java Virtual Machine or disable the feature that is not supported on the current version. |
Event 10146
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_FILE_PARSE_FAILED |
Message: |
|
Text: |
The Configuration Agent was unable to parse an upload file successfully: "%1". The exception reported is as follows: %2 |
Parameter %1: |
an error message providing additional information about the error. |
Parameter %2: |
the report of the last exception recorded during the parsing of the load file. |
Description: |
An error occurred while parsing and loading the contents of an upload file |
Action: |
Contact your primary support provider. |
Event 10147
Severity: |
Warning |
Symbolic Name: |
SECURITY_PROVIDER_LOAD_FAILED |
Message: |
|
Text: |
The security provider class that is required for PCI SSF compliancy could not be loaded: %1 |
Parameter %1: |
The fully qualified name of the security provider class that could not be loaded. |
Description: |
This warning is logged when eSocket.POS fails to load the security provider class. This is not an error condition but it indicates that eSocket.POS cannot be configured for PCI SSF compliancy and an attempt to make use of the PCI SSF features may result in an error. |
Action: |
No action required. See the eSocket.POS user guide for more information on PCI Software Security Framework. |
Event 10148
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_HTTP_RETRYING_FAILED_DOWNLOAD |
Message: |
|
Text: |
The Configuration Agent failed to download new configuration files via HTTP. Reason: %1. The download will be retried in %2 seconds. If the download fails again, it will be retried %3 more time(s). |
Parameter %1: |
The reason given for the failure |
Parameter %2: |
The number of seconds before the download is going to be retried |
Parameter %3: |
The number of times the download will be retried if it fails again |
Description: |
An error occurred while attempting to download new configuration files via HTTP and the download is going to be retried. |
Action: |
None. |
Event 10149
Severity: |
Informational |
Symbolic Name: |
ESOCKETPOS_PRE_INITIALISED |
Message: |
|
Text: |
The application %1 was pre-initialized with parameters %2. |
Parameter %1: |
the application |
Parameter %2: |
startup parameters |
Description: |
The application has started pre-initialised |
Action: |
None. |
Event 10150
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_INCOMPLETE_DOWNLOAD |
Message: |
|
Text: |
The Configuration Agent downloaded an incomplete set of configuration files. These files have not been applied as this could lead to an inconsistent configuration. |
Description: |
Configuration Agent did not download all the configuration file types. |
Action: |
Check the status of the Configuration Server to determine why not all file types were retrieved. |
Event 10151
Severity: |
Informational |
Symbolic Name: |
ESOCKETPOS_SECURITY_REGISTER_PRIVILEGED |
Message: |
|
Text: |
The privileged software module with class name %1 has registered itself with the eSocket.POS access controller. This privileged module will be allowed to access sensitive data. |
Parameter %1: |
the name of the privileged module class |
Description: |
A privileged software module has registered itself with the eSocket.POS access controller. This privileged module will be allowed to access sensitive data. |
Action: |
None. |
Event 10152
Severity: |
Informational |
Symbolic Name: |
ESOCKETPOS_SECURITY_REGISTER_PRIVILEGED_LIST |
Message: |
|
Text: |
The following privileged software modules have registered themselves with the eSocket.POS access controller: %1. These privileged modules will be allowed to access sensitive data. |
Parameter %1: |
the names of the privileged module classes |
Description: |
This event records a list of all privileged software modules that have registered themselves with the eSocket.POS access controller. These privileged modules will be allowed to access sensitive data. |
Action: |
None. |
Event 10153
Severity: |
Informational |
Symbolic Name: |
STORE_CLEANER_COMPLETED |
Message: |
|
Text: |
The Store Cleaner has completed. |
Description: |
This event is logged when the Store Cleaner has completed. |
Action: |
None. |
Event 10154
Severity: |
Warning |
Symbolic Name: |
DEVICE_SERIAL_NR_VALIDATION_FAILED |
Message: |
|
Text: |
Serial Number Validation has failed and the %1 device has moved to a DENIED state. Access to the device is now denied for processing financial data. The %3 application has denied the %2 serial number because %4. %5 |
Parameter %1: |
the device for which the serial number validation failed. |
Parameter %2: |
the serial number of the connected device, if known. |
Parameter %3: |
the authorizing entity: the POS or eSocket.POS |
Parameter %4: |
a description of why serial number validation failed. |
Parameter %5: |
additional information e.g. is serial nr configured in database? |
Description: |
This event is logged when the device moves from an UNKNOWN or ALLOWED state into a DECLINED state following Serial Number Validation failure. |
Action: |
Investigate why validation has failed for the connected device. |
Event 10155
Severity: |
Informational |
Symbolic Name: |
DEVICE_SERIAL_NR_VALIDATED |
Message: |
|
Text: |
Serial Number Validation has succeeded and the %1 device has moved to an ALLOWED state. The device can now therefore be accessed for processing financial data. The %3 application has validated the %2 serial number because %4. %5 |
Parameter %1: |
the device for which the serial number validation succeeded. |
Parameter %2: |
the serial number of the connected device, if known. |
Parameter %3: |
the authorizing entity: POS or eSocket.POS. |
Parameter %4: |
a description of why serial number validation succeeded. |
Parameter %5: |
additional information e.g. is serial nr configured in database? |
Description: |
This event is logged when the device moves from an UNKNOWN or DENIED state into an ALLOWED state following Serial Number Validation success. |
Action: |
None. |
Event 10156
Severity: |
Informational |
Symbolic Name: |
DEVICE_SERIAL_NR_CHANGED |
Message: |
|
Text: |
The serial number of the %1 device has changed. The last serial number to be retrieved was %2. The current serial number is %3. %4 |
Parameter %1: |
the device for which the serial number has changed. |
Parameter %2: |
the serial number of the last connected device (if applicable). |
Parameter %3: |
the serial number of the connected device (if applicable). |
Parameter %4: |
additional info: e.g. is serial nr configured in database? is device disconnected? |
Description: |
This event is logged when a change is detected in the device serial number during Serial Number Validation. The change may relate to a new device, a replaced device or a disconnected device. |
Action: |
Action to be determined by merchant. |
Event 10157
Severity: |
Error |
Symbolic Name: |
EVENT_DATA_INVALID |
Message: |
|
Text: |
The %1 event or callback received by %2 has the following invalid event data: %3 The specific error(s) are: %4. As a result %5. %6 |
Parameter %1: |
the event or callback with invalid data. |
Parameter %2: |
a description of the event listener. |
Parameter %3: |
the invalid event data. |
Parameter %4: |
specific error(s). |
Parameter %5: |
the resulting behavior. |
Parameter %6: |
additional information. |
Description: |
This event is logged when an event or callback has invalid data. |
Action: |
Investigate the root cause. |
Event 10158
Severity: |
Warning |
Symbolic Name: |
EVENT_DISCARDED |
Message: |
|
Text: |
The %1 event or callback received by %2 has been discarded. The event data is: %3 The reason(s) are: %4. %5 |
Parameter %1: |
the discarded event or callback. |
Parameter %2: |
a description of the event listener. |
Parameter %3: |
the event data. |
Parameter %4: |
specific reason(s). |
Parameter %5: |
additional information. |
Description: |
This event is logged when an event or callback is discarded. |
Action: |
Investigate the root cause. |
Event 10159
Severity: |
Error |
Symbolic Name: |
CALLBACK_TIMED_OUT |
Message: |
|
Text: |
The %1 callback has timed out. The entity listening for the event is: %2. As a result %3. |
Parameter %1: |
the callback name. |
Parameter %2: |
a description for the event listener. |
Parameter %3: |
the resulting behavior. |
Description: |
This event is logged when a callback response is expected but is not recieved. |
Action: |
Investigate the root cause. |
Event 10160
Severity: |
Informational |
Symbolic Name: |
PERIPHERAL_DEVICE_CONNECTED |
Message: |
|
Text: |
The %1 device has been connected or come online. %2 |
Parameter %1: |
the device name. |
Parameter %2: |
additional information e.g. context or resulting behavior. |
Description: |
A peripheral device has been connected. |
Action: |
None or merchant specific. |
Event 10161
Severity: |
Informational |
Symbolic Name: |
PERIPHERAL_DEVICE_DISCONNECTED |
Message: |
|
Text: |
The %1 device has been disconnected or is unresponsive due to a device error. %2 |
Parameter %1: |
the device name. |
Parameter %2: |
additional information e.g. context or resulting behavior. |
Description: |
A peripheral device has been disconnected. |
Action: |
Check the device connectivity and validity. |
Event 10162
Severity: |
Error |
Symbolic Name: |
INCONSISTENT_INCREMENTAL_HOTCARD_LOAD |
Message: |
|
Text: |
The configuration agent attempted to apply an invalid incremental hotcard update. A hashing algorithm different from the one currently active was specified in the file. The update has been aborted. |
Description: |
This event is logged when the algorithm indicator in an incremental hotcard update file differs from the one recorded in the database. |
Action: |
Ensure that the hashing algorithm used by Config Server is consistent with that used by the latest hotcards in the eSocket.POS database. |
Event 10163
Severity: |
Error |
Symbolic Name: |
INVALID_SALT_FORMAT |
Message: |
|
Text: |
The configuration agent attempted to load an invalidly formatted hotcard salt. The salt was not a 24-byte hexadecimal string. A message will be sent to inform Config Server. |
Description: |
This event is logged when the hotcard salt retrieved by the configuration agent is not a 24-byte hexadecimal string. |
Action: |
Ensure that the salt supplied by Config Server is a 24-byte hexadecimal string. |
Event 10164
Severity: |
Informational |
Symbolic Name: |
HOTCARD_SALT_LOADED_SUCCESSFULLY |
Message: |
|
Text: |
The configuration agent has successfully loaded new hotcard salt data into the keystore. |
Description: |
This event is logged when the Config Agent successfully loads new hotcard salt data into the keystore. |
Action: |
None. |
Event 10165
Severity: |
Error |
Symbolic Name: |
NO_CONFIG_SERVER_SALT |
Message: |
|
Text: |
The configuration agent attempted to apply a full hotcard update that uses the SHA-2 hashing algorithm. Currently, no salt data for this algorithm has been loaded into the keystore. The update has been aborted. |
Description: |
This event is logged when a full SHA-2 hotcard update is attempted before salt has been loaded into the keystore. |
Action: |
Ensure that the hotcard file(s) you are attempting to load are accompanied by a file containing salt data. |
Event 10166
Severity: |
Informational |
Symbolic Name: |
ESOCKETPOS_SECURITY_PERMISSIONS_REQUESTED |
Message: |
|
Text: |
The secure software module with class name %1 has requested the following permission(s) from the eSocket.POS access controller: %2 |
Parameter %1: |
the name of the secure module class |
Parameter %2: |
the names of the requested permissions |
Description: |
This event is logged when a secure module requests permissions to access sensitive data from the access controller. |
Action: |
None. |
Event 10167
Severity: |
Informational |
Symbolic Name: |
RKD_SUCCESSFUL_FOR_DEVICE |
Message: |
|
Text: |
A key exchange was succesfully applied for the RKD device %1. |
Parameter %1: |
the name of the RKD device |
Description: |
This event is logged after a successful Remote Key Distribution for a particular device. |
Action: |
None. |
Event 10168
Severity: |
Warning |
Symbolic Name: |
RKD_RETRY_FOR_DEVICE |
Message: |
|
Text: |
A key exchange was unsuccessful for the RKD device %1. The process will be retried in %2 seconds. |
Parameter %1: |
the name of the RKD device |
Parameter %2: |
the delay until the retry attempt |
Description: |
This event is logged when a key exchange fails for an RKD device, and a retry will be attempted. |
Action: |
None. |
Event 10169
Severity: |
Error |
Symbolic Name: |
RKD_FAILED_FOR_DEVICE |
Message: |
|
Text: |
A key exchange for the RKD device %1 has failed after the %2 retries configured. No more attempts will be made. |
Parameter %1: |
the name of the RKD device |
Parameter %2: |
the configured number of retries |
Description: |
This event is logged when a key exchange fails for an RKD device, and no more retries remain. |
Action: |
None. |
Event 10170
Severity: |
Informational |
Symbolic Name: |
MESSAGE_ENCRYPTION_ON_SAP |
Message: |
|
Text: |
The SAP Factory %1 has message encryption enabled |
Parameter %1: |
SAP class name |
Description: |
Message encryption enabled on SAP |
Action: |
Event 10171
Severity: |
Warning |
Symbolic Name: |
ADDITIONAL_SAP_CONFIGURED |
Message: |
|
Text: |
An additional custom SAP has been configured. The configuration for SAP %1 will not be used |
Parameter %1: |
Class name of additional SAP |
Description: |
More than 1 custom SAP Factory configured |
Action: |
Event 10172
Severity: |
Informational |
Symbolic Name: |
RKD_DECLINED_FOR_DEVICE |
Message: |
|
Text: |
A key exchange was declined for the RKD device %1 because its key is still valid |
Parameter %1: |
the name of the RKD device |
Description: |
This event is logged when a RKD request is declined because the device’s current key is still valid and hasn’t expired. |
Action: |
None. |
Event 10173
Severity: |
Informational |
Symbolic Name: |
RKD_COMPROMISED |
Message: |
|
Text: |
Terminal %1 has been informed of a RKD key compromise from the upstream entity. Initiating RKD requests for all RKD devices associated with this terminal that require a new key. |
Parameter %1: |
. |
Description: |
This event is logged when the terminal has been informed of a RKD key compromise from the upstream entity. All devices associated with the terminal will generate a new RKD request. |
Action: |
None. |
Event 10174
Severity: |
Warning |
Symbolic Name: |
SUPPORT_EVENT_AGGREGATION_MOVE_INTO_HIGH_VOLUME |
Message: |
|
Text: |
The eSocket.POS Event ID %1 was logged %2 times during the last %3 second(s). The first %4 occurrence(s) of it was recorded to the Central Event Log. The first occurrence was recorded around %5. Please refer to the eSocket.POS User Guide for a description of this event. |
Parameter %1: |
The eSocket.POS event ID of the high volume of events. |
Parameter %2: |
The number of times the event was logged to the Central Event Log. |
Parameter %3: |
The time period during which the events were aggregated. |
Parameter %4: |
The number of events that were actually recorded to the Central Event Log. |
Parameter %5: |
The time at which the first event was logged and recorded. |
Description: |
This event is logged at the start of a potentially prolonged period of a high volume of eSocket.POS events (of a specific ID) being logged to the Central Event Log. Please refer to the eSocket.POS User Guide for a description of this event. |
Action: |
None. |
Event 10175
Severity: |
Warning |
Symbolic Name: |
SUPPORT_EVENT_AGGREGATION_MOVE_INTO_HIGH_VOLUME_PER_TERMINAL |
Message: |
|
Text: |
eSocket.POS Event ID %1 was logged by terminal %2 %3 times during the last %4 second(s). The first %5 occurrence(s) of it was recorded to the Central Event Log. The first occurrence was recorded around %6. Please refer to the eSocket.POS User Guide for a description of this event. |
Parameter %1: |
The eSocket.POS event ID of the high volume of events. |
Parameter %2: |
The terminal ID against which the events were logged. |
Parameter %3: |
The number of times the event was logged to the Central Event Log. |
Parameter %4: |
The time period during which the events were aggregated. |
Parameter %5: |
The number of events that were actually recorded to the Central Event Log. |
Parameter %6: |
The time at which the first event was logged and recorded. |
Description: |
This event is logged at the start of a potentially prolonged period of a high volume of eSocket.POS events (of a specific ID) being logged (against a specific terminal ID) to the Central Event Log. Please refer to the eSocket.POS User Guide for a description of this event. |
Action: |
None. |
Event 10176
Severity: |
Warning |
Symbolic Name: |
SUPPORT_EVENT_AGGREGATION_HIGH_VOLUME |
Message: |
|
Text: |
eSocket.POS Event ID %1 logged around %2, was repeated %3 times during the last %4 second(s). Please refer to the eSocket.POS User Guide for a description of these events. |
Parameter %1: |
The eSocket.POS event ID of the high volume of events. |
Parameter %2: |
The time at which the first event was logged and recorded. |
Parameter %3: |
The number of times the event was logged to the Central Event Log. |
Parameter %4: |
The time period during which the events were aggregated. |
Description: |
This event is logged during a prolonged period of a high volume of eSocket.POS events (of a specific ID) being logged to the Central Event Log. Please refer to the eSocket.POS User Guide for a description of these events. |
Action: |
None. |
Event 10177
Severity: |
Warning |
Symbolic Name: |
SUPPORT_EVENT_AGGREGATION_HIGH_VOLUME_PER_TERMINAL |
Message: |
|
Text: |
eSocket.POS Event ID %1, logged against terminal %2, logged around %3, was repeated %4 times during the last %5 second(s). Please refer to the eSocket.POS User Guide for a description of these events. |
Parameter %1: |
The event ID of the high volume of events. |
Parameter %2: |
The terminal ID against which the events were logged. |
Parameter %3: |
The time at which the first event was logged and recorded. |
Parameter %4: |
The number of times the event was logged to the Central Event Log. |
Parameter %5: |
The time period during which the events were aggregated. |
Description: |
This event is logged during a prolonged period of a high volume of eSocket.POS events (of a specific ID) being logged (against a specific terminal ID) to the Central Event Log. Please refer to the eSocket.POS User Guide for a description of these events. |
Action: |
None. |
Event 10178
Severity: |
Informational |
Symbolic Name: |
CUSTOM_APP_PLUGIN_STARTING |
Message: |
|
Text: |
eSocket.POS is starting a Custom Application plugin. The Java class name is [%1]. |
Parameter %1: |
The custom application class name |
Description: |
This event is logged during eSocket.POS startup, and names any custom applications started. |
Action: |
None. |
Event 10179
Severity: |
Warning |
Symbolic Name: |
DOWNLOAD_PROCESSING_DATA_PROPERTY |
Message: |
|
Text: |
The Processing Data files are in the normalized format. The postilion.esocketpos.DownloadProcessingData property is not applied for the normalized structure. This property is only applied for the legacy single Processing Data file. The Processing Data files are loaded. |
Parameter %1: |
|
Description: |
The postilion.esocketpos.DownloadProcessingData property is ignored because the normalized file structure is used. |
Action: |
None. |
Event 10180
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_RETRYING_FAILED_FILE_DOWNLOAD |
Message: |
|
Text: |
The Configuration Agent failed to download the file %1. Reason: %2 The download will be retried in 30 seconds. If the download fails again, it will be retried %3 more time(s). |
Parameter %1: |
The name of the file in question |
Parameter %2: |
The reason given for the failure |
Parameter %3: |
The number of times the download will be retried if it fails again |
Description: |
An error occurred while attempting to download a particular file via HTTP and the download is going to be retried. |
Action: |
None. |
Event 10181
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_FILE_DOWNLOAD_FAILED |
Message: |
|
Text: |
The Configuration Agent failed to download the file %1. Reason: %2 |
Parameter %1: |
The name of the file in question |
Parameter %2: |
The reason given for the failure |
Description: |
Repeated attempts to download a particular file via http have failed. All retry attempts have been exhausted. |
Action: |
None. |
Event 10182
Severity: |
Warning |
Symbolic Name: |
REMOTE_PROPERTY_HOMEDIR_NOT_SET |
Message: |
|
Text: |
Remote properties exist in the database with the active timestamp, but the postilion.esocketpos.install.HomeDir property is not set in the properties file. The remote properties will not be used |
Description: |
Remote properties exist in the database with the active timestamp, but the postilion.esocketpos.install.HomeDir property is not set in the properties file. The remote properties will not be used |
Action: |
In order to use remote properties, configure the postilion.esocketpos.install.HomeDir property in the properties file. |
Event 10183
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_COMMAND_PORT_OPENED |
Message: |
|
Text: |
The Configuration Agent is now listening for new commands at: %1:%2. Connections will be accepted from these trusted ip addresses: '%3' |
Parameter %1: |
IP address |
Parameter %2: |
Port |
Parameter %3: |
Trusted hosts |
Description: |
The command port has been successfully opened for the Configuration Agent |
Action: |
None. |
Event 10184
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_COMMAND_RECEIVED_FROM_REMOTE |
Message: |
|
Text: |
The Configuration Agent has received the command: '%1' from %2 and sent back the response '%3' |
Parameter %1: |
Command received from client |
Parameter %2: |
Remote address of client |
Parameter %3: |
Response sent back to the client |
Description: |
The Configuration Agent received a command from a client and sent back a response |
Action: |
None. |
Event 10185
Severity: |
Error |
Symbolic Name: |
INVALID_P2PE_HOTCARD_FILE |
Message: |
|
Text: |
The P2PE Hotcard file that is being loaded is invalid. A P2PE hotcard file that contains a tokenization key check value can only have a hash algorithm indicator of 1 - SHA-2 Salted Hashing. The hotcard loading has been aborted. |
Description: |
This event is logged when the algorithm indicator in a P2PE hotcard update file is not 1 - SHA2 |
Action: |
Ensure that the hashing algorithm used in all the records in a P2PE Hotcard file is 1 - SHA2 |
Event 10186
Severity: |
Error |
Symbolic Name: |
INVALID_CHECK_VALUE_INCR_LOAD |
Message: |
|
Text: |
The P2PE Hotcard file that is being loaded is invalid. The key check value supplied in the incremental file in line "%1" is different than the one supplied in a previous full load file. Hence the incremental load will not be applied. If any keys used to perform PAN tokenization have changed, a full hotcard load should be performed to update all the tokenized hotcard PANs. |
Parameter %1: |
the invalid record from the file |
Description: |
This event is logged when the key check value supplied in the incremental file is different than the one supplied in a previous full load file |
Action: |
Ensure that a full hotcard load is performed after changing any keys used to perform PAN tokenization. |
Event 10187
Severity: |
Warning |
Symbolic Name: |
P2PE_HOTCARD_CHECKING_CANNOT_PROCEED |
Message: |
|
Text: |
Terminal %1 encountered the following problem while attempting to perform hotcard checking: The PIN entry device in use supports P2PE hotcard checking, but the keys used to perform PAN tokenization do not match those that were used by ConfigServer during hotcard file generation. The key check value received from the PED is %2, while the key check value received from ConfigServer is %3. P2PE hotcard checking can therefore not be performed. |
Parameter %1: |
The terminal ID |
Parameter %2: |
The key check value received from the PED |
Parameter %3: |
The key check value received from ConfigServer |
Description: |
This event is logged when the PAN tokenization keys used by the PED do not match those that were used by ConfigServer during hotcard file generation. |
Action: |
Ensure that P2PE hotcard checking is enabled for the configuration set corresponding to this eSocket.POS instance. Also ensure that the keys used by the PED to perform PAN tokenization are identical to those used by ConfigServer during hotcard file generation. |
Event 10188
Severity: |
Error |
Symbolic Name: |
FAILED_TO_DISPLAY_LINE_ITEM |
Message: |
|
Text: |
eSocket.POS could not display the line items. The error reported is as follows: %1. |
Parameter %1: |
Error reported, due to nature of the error, no further information is available. |
Description: |
This event is logged when eSocket.POS fails to process the line item properly. |
Action: |
Check the message and do the needful. |
Event 10189
Severity: |
Error |
Symbolic Name: |
FAILED_TO_CONVERT_SIG_IMAGE |
Message: |
|
Text: |
eSocket.POS could not convert the captured signature image. The error reported is as follows: %1. |
Parameter %1: |
Error reported, due to nature of the error, no further information is available. |
Description: |
This event is logged when eSocket.POS fails to convert the format of the captured signature image. |
Action: |
Ensure that the image from the signature capture device is in the correct format |
Event 10190
Severity: |
Error |
Symbolic Name: |
DEVICE_NOT_CONNECTED |
Message: |
|
Text: |
The device is not connected. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when eSocket.POS attemps to communicate with a device that is not connected. |
Action: |
Check device connection and ensure device is configured correctly. |
Event 10191
Severity: |
Error |
Symbolic Name: |
DEVICE_CURRENTLY_BUSY |
Message: |
|
Text: |
The device is currently busy. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when eSocket.POS attemps to communicate with a device that is currently busy. |
Action: |
Wait until device is finished processing. |
Event 10192
Severity: |
Informational |
Symbolic Name: |
ESOCKETPOS_AUTO_SIGNON |
Message: |
|
Text: |
The application %1 has successfully auto signed-on terminal with Terminal ID: %2. |
Parameter %1: |
the application |
Parameter %2: |
sign on parameters |
Description: |
Automatic sign-on of terminals has completed. |
Action: |
None. |
Event 10193
Severity: |
Error |
Symbolic Name: |
REMOTE_SINK_DISCARDED_TRAN_ADVICE |
Message: |
|
Text: |
The RemoteSink discarded a transaction advice message after %1 attempts to reverse it. |
Parameter %1: |
The number of attempts to reverse the message after which it was discarded. |
Description: |
The Postilion Interface (RemoteSink) discarded a transaction advice message after exceeding the maximum number of reversal attempts. |
Action: |
nvestigate why eSocket.POS did not receive a response to the reversal for this advice. This transaction may be resubmitted. |
Event 10194
Severity: |
Warning |
Symbolic Name: |
REMOTE_SINK_DISCONNECTED |
Message: |
|
Text: |
%1. |
Parameter %1: |
Details |
Description: |
The Postilion Interface (RemoteSink) was disconnected. |
Action: |
o action required. |
Event 10195
Severity: |
Warning |
Symbolic Name: |
REMOTE_SINK_CONNECTED |
Message: |
|
Text: |
%1. |
Parameter %1: |
Details |
Description: |
The Postilion Interface (RemoteSink) was connected. |
Action: |
o action required. |
Event 10196
Severity: |
Error |
Symbolic Name: |
EMV_CONFIG_ERROR |
Message: |
|
Text: |
%1. |
Parameter %1: |
Details |
Description: |
The EmvConfig Pipeline Component encountered an error. |
Action: |
o action required. |
Event 10197
Severity: |
Warning |
Symbolic Name: |
DEVICE_SAP_CONFIG_INVALID |
Message: |
|
Text: |
The device connection SAP configuration '%1' has been configured incorrectly. %2 |
Parameter %1: |
The configuration item’s name. |
Parameter %2: |
Additional information. |
Description: |
Device connection configuration for the SAP is invalid. |
Action: |
Please ensure it is set correctly for the SAP. |
Event 10198
Severity: |
Error |
Symbolic Name: |
SLIP_UNEXPECTED_TOKEN |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: Expected a label, but found token '%3' instead. |
Parameter %1: |
name of the receipt definition. |
Parameter %2: |
position in the receipt. |
Parameter %3: |
token in the receipt. |
Description: |
This event is logged when an unexpected token is found in the SRSL. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10199
Severity: |
Error |
Symbolic Name: |
SLIP_UNEXPECTED |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: A '%3' was expected, but a '%4' was found |
Parameter %1: |
name of the receipt definition. |
Parameter %2: |
position in the receipt. |
Parameter %3: |
expected token. |
Parameter %4: |
found token. |
Description: |
This event is logged when an incorrect token is found. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10200
Severity: |
Error |
Symbolic Name: |
SLIP_UNEXPECTED_ETX |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: End of definition reached while still expecting more characters. |
Parameter %1: |
name of the receipt definition. |
Parameter %2: |
position in the receipt. |
Description: |
This event is logged when the end of the slip is reached but more data is expected in the slip. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10201
Severity: |
Error |
Symbolic Name: |
SLIP_AMOUNT_TOO_LARGE |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: The amount '%3' is not in a valid range. It must be greater than 0 and less than 1000. |
Parameter %1: |
name of the receipt definition. |
Parameter %2: |
the position in the receipt. |
Parameter %3: |
the amount. |
Description: |
This event is logged when the amount value is not in the range of 0…1000. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10202
Severity: |
Error |
Symbolic Name: |
SLIP_DUPLICATE |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: The duplicate statement '\&%3' is not valid. |
Parameter %1: |
the name of the receipt definition. |
Parameter %2: |
the position in the receipt. |
Parameter %3: |
The duplicate token that was encountered. |
Description: |
This event is logged when a duplicate was encountered in the SRSL. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10203
Severity: |
Error |
Symbolic Name: |
SLIP_TEXT_NOT_CLOSE |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: A closing \" character is missing. Text may not extend over more than one line. |
Parameter %1: |
the name of the receipt definition. |
Parameter %2: |
the position in the receipt. |
Description: |
This event is logged when a closing delimiter was not found. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10204
Severity: |
Error |
Symbolic Name: |
SLIP_CTRL_CHAR |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: The control character '%3' does not exist. |
Parameter %1: |
the name of the receipt definition. |
Parameter %2: |
the position in the receipt. |
Parameter %3: |
control character found. |
Description: |
This event is logged when an invalid control character was encountered while parsing the slip. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10205
Severity: |
Error |
Symbolic Name: |
SLIP_ALIGN |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: The alignment statement '[ … ]%3' is not valid. |
Parameter %1: |
the name of the receipt definition. |
Parameter %2: |
the position in the receipt. |
Parameter %3: |
The alignment parameter. |
Description: |
This event is logged when an invalid alignment statement is encountered. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10206
Severity: |
Error |
Symbolic Name: |
SLIP_DOWN |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: The parameter for the command 'down(%3)' is not a valid number. |
Parameter %1: |
the name of the receipt definition. |
Parameter %2: |
the position in the receipt. |
Parameter %3: |
parameter to the down command. |
Description: |
This event is logged when an invalid parameter is passed to the down command in SRSL. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10207
Severity: |
Error |
Symbolic Name: |
SLIP_BLOCK_SIZE |
Message: |
|
Text: |
SRSL Syntax Error in %1, position %2: The first parameter for the command 'block(%3, …)' is not a number. |
Parameter %1: |
the name of the receipt definition. |
Parameter %2: |
the position in the receipt. |
Parameter %3: |
first parameter to the block command. |
Description: |
This event is logged when the first parameter for the command block is not a number. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10208
Severity: |
Error |
Symbolic Name: |
SLIP_ERROR |
Message: |
|
Text: |
An SRSL error occurred in the definition of slip '%1' at position %2 . %3 |
Parameter %1: |
the name of the receipt definition. |
Parameter %2: |
the position in the receipt. |
Parameter %3: |
message containing more information. |
Description: |
This event is logged when a SRSL error occurs in a slip. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10209
Severity: |
Error |
Symbolic Name: |
SLIP_NAME |
Message: |
|
Text: |
SRSL Error: The name '%1' is not defined here. |
Parameter %1: |
the undefined name in receipt. |
Description: |
This event is logged when an undefined name is used in the slip. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10210
Severity: |
Error |
Symbolic Name: |
SLIP_VALUE_NOT_STRING |
Message: |
|
Text: |
SRSL Error: The value '%1' is not a string and thus cannot be used as a #value. |
Parameter %1: |
the value found. |
Description: |
This event is logged when a value found is not of type string. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10211
Severity: |
Error |
Symbolic Name: |
SLIP_NOT_FORMATTING |
Message: |
|
Text: |
SRSL Error: A formatting statement (%format) '%1' may not be used here. |
Parameter %1: |
the format found. |
Description: |
This event is logged when the format statement is used incorrectly. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10212
Severity: |
Error |
Symbolic Name: |
SLIP_FORMAT |
Message: |
|
Text: |
SRSL Error: The format '%1' does not exist at this position. |
Parameter %1: |
the format found. |
Description: |
This event is logged when the format does not exist at this position. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10213
Severity: |
Error |
Symbolic Name: |
SLIP_FORMAT_USE |
Message: |
|
Text: |
SRSL Error: Invalid format usage (parameter %1). |
Parameter %1: |
the format value used. |
Description: |
This event is logged when the format statement is used incorrectly. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10214
Severity: |
Error |
Symbolic Name: |
SLIP_FORMAT_NOT_STRING |
Message: |
|
Text: |
SRSL Error: The format '%1' is not a string and thus cannot be used as \%value. |
Parameter %1: |
the format found. |
Description: |
This event is logged when the format is not a string. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10215
Severity: |
Error |
Symbolic Name: |
SLIP_LOOKUP_INVALID |
Message: |
|
Text: |
SRSL Error: Invalid lookup usage of item "%1". |
Parameter %1: |
the lookup item. |
Description: |
This event is logged when an invalid lookup is performed. |
Action: |
Consult the SRSL syntax in the eSocket.POS User Guide. |
Event 10216
Severity: |
Warning |
Symbolic Name: |
SLIP_FORBIDDEN_EMV_TAG |
Message: |
|
Text: |
The value of EMV tag %1 is not allowed to be printed on the receipt. Please remove this tag from the receipt profile definition to prevent this warning from being logged. The current receipt will be printed as if this EMV tag is not present in the message. |
Parameter %1: |
The forbidden EMV tag. |
Description: |
This event is logged to report an attempt to print a forbidden EMV tag value. |
Action: |
Consult the forbidden EMV tag list in the eSocket.POS user guide. These forbidden EMV tag values are not allowed to print on the receipt to avoid exposing sensitive or cryptographic data. |
Event 10217
Severity: |
Warning |
Symbolic Name: |
INSECURE_ENCRYPTION_PROTOCOL_ENABLED_ON_CLIENT_SAP |
Message: |
|
Text: |
The Client Service Access Point (SAP) with name '%1' has the following insecure encryption protocol and/or version enabled: '%2'. Please upgrade to a secure version. |
Parameter %1: |
The name of the SAP. |
Parameter %2: |
The name and version of the protocol. |
Description: |
This event is logged when a client SAP has an insecure encryption protocol enabled. |
Action: |
No action is required. |
Event 10218
Severity: |
Error |
Symbolic Name: |
TRAN_DECLINED_TERM_BLOCKED |
Message: |
|
Text: |
The Terminal '%1' has been blocked |
Parameter %1: |
the terminal ID |
Description: |
This event is logged when the terminal has been blocked |
Action: |
No action is required. |
Event 10219
Severity: |
Informational |
Symbolic Name: |
TERM_UNBLOCKED |
Message: |
|
Text: |
The Terminal '%1' has been unblocked |
Parameter %1: |
the terminal ID |
Description: |
This event is logged when the terminal has been unblocked |
Action: |
No action is required. |
Event 10220
Severity: |
Error |
Symbolic Name: |
P2PE_DEVICE_BLOCK |
Message: |
|
Text: |
Transaction has failed because of a blocked device. The stack trace is as follows: %1 |
Parameter %1: |
The stack trace |
Description: |
This event is logged when a transaction fails due to a blocked device. |
Action: |
No action is required. |
Event 10221
Severity: |
Informational |
Symbolic Name: |
UPGRADE_MANAGER_STATUS |
Message: |
|
Text: |
UpgradeManager: %1 |
Parameter %1: |
The UpgradeManager status description |
Description: |
This event is logged by UpgradeManager to report status. |
Action: |
No action is required. |
Event 10222
Severity: |
Warning |
Symbolic Name: |
CARD_REMOVED_PREMATURELY |
Message: |
|
Text: |
The card was removed prematurely. |
Description: |
This event is logged when the card was removed prematurely. |
Action: |
No action is required. |
Event 10223
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_PROGRESS_STATUS_ERROR |
Message: |
|
Text: |
The Configuration Agent progress status is set to %1. |
Parameter %1: |
The status on the Configuration Agent file download process. |
Description: |
ConfigAgent progress status error event. |
Action: |
No action is required. This is provided for debugging purposes. |
Event 10224
Severity: |
Informational |
Symbolic Name: |
CONFIG_AGENT_PROGRESS_STATUS_INFO |
Message: |
|
Text: |
The Configuration Agent progress status is set to %1. |
Parameter %1: |
The status on the Configuration Agent file download process. |
Description: |
ConfigAgent progress status info event. |
Action: |
No action is required. |
Event 10225
Severity: |
Informational |
Symbolic Name: |
DEVICE_UPDATE_NOT_PERFORMED |
Message: |
|
Text: |
The %1 device driver could not perform a file update for the device connected to terminal %3. Reason: %2. |
Parameter %1: |
Device Driver |
Parameter %2: |
Reason why the update was not performed |
Parameter %3: |
Terminal ID |
Description: |
This event is logged when a requested update operation, on a given terminal, was not performed. |
Action: |
No action is required. |
Event 10226
Severity: |
Informational |
Symbolic Name: |
FILE_UPDATE_SUCCESS |
Message: |
|
Text: |
The file %2 of type %3 has been successfully uploaded for the %1 device. |
Parameter %1: |
the active device |
Parameter %2: |
the file name |
Parameter %3: |
the file type(whitelist, firmware) |
Description: |
This event is logged when a file is successful uploaded |
Action: |
No action is required. |
Event 10227
Severity: |
Error |
Symbolic Name: |
TERMINAL_BLOCKED |
Message: |
|
Text: |
Terminal %1 is blocked because %2 |
Parameter %1: |
Terminal ID |
Parameter %2: |
Reason why the terminal is blocked |
Description: |
This event is logged when a terminal has been blocked. |
Action: |
No action is required. |
Event 10228
Severity: |
Informational |
Symbolic Name: |
ESOCKETPOS_INFO_EVENT |
Message: |
|
Text: |
Info Description = %1 |
Parameter %1: |
Description of the event. |
Description: |
Generic info event returned by eSocket.POS. |
Action: |
No action is required. |
Event 10229
Severity: |
Error |
Symbolic Name: |
CHECK_READ_FAILED |
Message: |
|
Text: |
An error occurred while attempting to read a check |
Description: |
This ReasonCode is returned if an attempt to read check data failed. |
Action: |
No action is required. |
Event 10230
Severity: |
Error |
Symbolic Name: |
SQL_EXCEPTION_OCCURRED |
Message: |
|
Text: |
%1 failed to perform a SQL operation. The following error was reported: %2. |
Parameter %1: |
Application Name |
Parameter %2: |
The error to be reported. |
Description: |
This event is logged if a SQL operation failed to complete |
Action: |
Contact your primary support provider. |
Event 10231
Severity: |
Error |
Symbolic Name: |
TERMINAL_ACTIVATION_CSR_GENERATION_FAILED |
Message: |
|
Text: |
Generating a certificate signing request to be used for TLS connections failed for terminal %1. Reason: %2. |
Parameter %1: |
Terminal ID |
Parameter %2: |
Exception associated with the CSR generation failure |
Description: |
This event is logged when there is a failure during the process of creating a Certificate Signing Request (CSR) for the public key of a TLS key pair. |
Action: |
Investigate the reason for the CSR creation failing by reviewing the reported exception. Contact your primary support provider should additional assistance be required. |
Event 10232
Severity: |
Error |
Symbolic Name: |
TERMINAL_ACTIVATION_MAC_CALC_FAILED |
Message: |
|
Text: |
Calculating the MAC for a terminal activation request message failed for terminal %1. Reason: %2. |
Parameter %1: |
Terminal ID |
Parameter %2: |
Exception associated with the MAC calculation failing |
Description: |
This event is logged when MAC calculation for a terminal activation request message fails. |
Action: |
Investigate the reason for the MAC calculation failing by reviewing the reported exception. Contact your primary support provider should additional assistance be required. |
Event 10233
Severity: |
Error |
Symbolic Name: |
TERMINAL_ACTIVATION_CERT_UPDATE_FAILED |
Message: |
|
Text: |
Updating the public key certificate to be used for TLS connections failed for terminal %1. Reason: %2. |
Parameter %1: |
Terminal ID |
Parameter %2: |
Exception associated with the certificate update failing |
Description: |
This event is logged when updating the signed public key certificate for an TLS key pair alias fails. |
Action: |
Investigate the reason for the certificate update failing by reviewing the reported exception. Contact your primary support provider should additional assistance be required. |
Event 10234
Severity: |
Error |
Symbolic Name: |
TERMINAL_ACTIVATION_FAILED |
Message: |
|
Text: |
Activating terminal %1 for internet connectivity failed for terminal %1. Reason: %2. |
Parameter %1: |
Terminal ID |
Parameter %2: |
Exception associated with the failed activation attempt |
Description: |
This event is logged when an exception occurs while attempting to activate a terminal for internet connectivity. It indicates that terminal activation failed. |
Action: |
Investigate the reason for terminal activation failing by reviewing the reported exception. Terminal activation can fail due to errors occurring in eSocket.POS in which case the error will be reported by eSocket.POS or it can fail during validation on the switch in which case the error will be reported by the switch. Contact your primary support provider should additional assistance be required. |
Event 10235
Severity: |
Error |
Symbolic Name: |
TERMINAL_ACTIVATION_REQUEST_DECLINED |
Message: |
|
Text: |
A terminal activation request for internet connectivity for terminal %1 was declined by %2. |
Parameter %1: |
Terminal ID |
Parameter %2: |
Whether the request was declined by eSocket.POS or the switch |
Description: |
This event is logged when a terminal activation message is declined by either eSocket.POS or the switch. If declined by eSocket.POS it will be preceded by an event that indicates why the activation message was declined. If declined by the switch, the switch logs will contain information regarding the reasons for the decline. |
Action: |
Investigate the reason for terminal activation request being declined in the relevant logs. Contact your primary support provider should additional assistance be required. |
Event 10236
Severity: |
Warning |
Symbolic Name: |
INVALID_TPR |
Message: |
|
Text: |
Transaction Processing Result value %1 not found in %2. |
Description: |
This event is logged when a transaction processing request value cannot be found. |
Action: |
No action is required. |
Event 10237
Severity: |
Error |
Symbolic Name: |
CONFIG_MODULE_PROCESSOR_UPDATE_FAILED |
Message: |
|
Text: |
Config Agent Config Module Processor update failed. Reason: %1. |
Parameter %1: |
The reasons for the failure |
Description: |
This event is logged when a module processor update fails. |
Action: |
No action is required. |
Event 10238
Severity: |
Error |
Symbolic Name: |
UNKNOWN_COMMAND |
Message: |
|
Text: |
Unknown command received from the acquirer %1. |
Parameter %1: |
The command received |
Description: |
This event is logged when an unknown command is received from the acquirer. |
Action: |
No action is required. |
Event 10239
Severity: |
Warning |
Symbolic Name: |
SEC_RISK_SQL_PASSWORD_EMPTY |
Message: |
|
Text: |
Security Risk: Empty JDBC password configured. |
Description: |
This event is logged when the JDBC password is configured as empty. |
Action: |
No action is required. |
Event 10240
Severity: |
Warning |
Symbolic Name: |
REMOTE_SINK_TERM_ACT_PORT_NOT_SPECIFIED |
Message: |
|
Text: |
The RemoteSink entity configured for terminal ID %1 has a terminal activation host specified but not a terminal activation port number. If the intended behaviour is to make use of automated terminal activation, add the port number for the terminal activation destination. If the intended behaviour is not to make use of automated terminal activation, remove the terminal activation host. |
Parameter %1: |
Terminal ID |
Description: |
This event is logged when the RemoteSink configuration has a terminal activation host configured but not a terminal activation port number. |
Action: |
If the intended behaviour is to make use of automated terminal activation, add the port number for the terminal activation destination. If the intended behaviour is not to make use of automated terminal activation, remove the terminal activation host. |
Event 10241
Severity: |
Warning |
Symbolic Name: |
REMOTE_SINK_TERM_ACT_HOST_NOT_SPECIFIED |
Message: |
|
Text: |
The RemoteSink entity configured for terminal ID %1 has a terminal activation port number specified but not a terminal activation host. If the intended behaviour is to make use of automated terminal activation, add the host for terminal activation. If the intended behaviour is not to make use of automated terminal activation, remove the terminal activation port number. |
Parameter %1: |
Terminal ID |
Description: |
This event is logged when the RemoteSink configuration has a terminal activation port number configured but not a terminal activation host. |
Action: |
If the intended behaviour is to make use of automated terminal activation, add the host for terminal activation. If the intended behaviour is not to make use of automated terminal activation, remove the terminal activation port number. |
Event 10242
Severity: |
Error |
Symbolic Name: |
TLS_KEY_STORE_FILE_DOES_NOT_EXIST |
Message: |
|
Text: |
The TLS key store is not configured in the eSocket.POS properties file (property postilion.esocketpos.ssl.KeyStorePath), the key store file does not exist or it cannot be accessed. The key store was not loaded. |
Description: |
This event is logged when the TLS key store is not configured in the properties file or the key store file does not exist. |
Action: |
Validate that the TLS key store property is configured in the properties file (postilion.esocketpos.ssl.KeyStorePath), ensure the key store file exists and that the user under which the eSocket.POS process runs can access it. |
Event 10243
Severity: |
Error |
Symbolic Name: |
TLS_TRUST_STORE_FILE_DOES_NOT_EXIST |
Message: |
|
Text: |
The TLS trust store is not configured in the eSocket.POS properties file (postilion.esocketpos.ssl.TrustStorePath), the trust store file does not exist or it cannot be accessed. The trust store was not loaded. |
Description: |
This event is logged when the TLS trust store is not configured in the properties file or the trust store file does not exist. |
Action: |
Validate that the TLS trust store property is configured in the properties file (postilion.esocketpos.ssl.TrustStorePath), ensure the trust store file exists and that the user under which the eSocket.POS process runs can access it. |
Event 10244
Severity: |
Error |
Symbolic Name: |
TLS_KEY_STORE_PASSWORD_INCORRECT |
Message: |
|
Text: |
The TLS key store password is not configured in the eSocket.POS properties file (property postilion.esocketpos.ssl.KeyStorePassword) or it is incorrect. |
Description: |
This event is logged when the password for the TLS key store is not configured in the eSocket.POS properties file or is incorrect. |
Action: |
Validate that the TLS key store password is configured in the properties file (property postilion.esocketpos.ssl.KeyStorePassword) and that it is correct. |
Event 10245
Severity: |
Error |
Symbolic Name: |
TLS_TRUST_STORE_PASSWORD_INCORRECT |
Message: |
|
Text: |
The TLS trust store password is not configured in the eSocket.POS properties file (property postilion.esocketpos.ssl.TrustStorePassword) or it is incorrect. |
Description: |
This event is logged when the password for the TLS trust store is not configured in the eSocket.POS properties file or is incorrect. |
Action: |
Validate that the TLS trust store password is configured in the properties file (postilion.esocketpos.ssl.TrustStorePassword) and that it is correct. |
Event 10246
Severity: |
Error |
Symbolic Name: |
FIELD_ENCRYPTION_KEY_MISSING |
Message: |
|
Text: |
The RSA Public Key required for FIELDS encryption is not available. |
Description: |
This event is logged when the key required to encrypt sesitive fields such as PAN, TRACK2, ACCOUNT_ID_1, ACCOUNT_ID_2, PAYER_ACCOUNT_ID is not available in the eSocket.POS keystore. |
Action: |
Check the eSocket.POS configuration. |
Event 10247
Severity: |
Warning |
Symbolic Name: |
ORPHANED_MESSAGE_RECEIVED |
Message: |
|
Text: |
eSocket.POS has received an orphaned message from remote address %2. eSocket.POS does not recognize the terminal ID determined from the message: %1. This typically occurs if the remote entity (e.g. the upstream host) does not populate the terminal ID field(s) in a response message correctly. No further processing will be performed on this message, including tracing (if enabled). Message content: %3 |
Parameter %1: |
terminal ID as determined from orphaned message |
Parameter %2: |
the remote address |
Parameter %3: |
the orphaned message’s content |
Description: |
Orphaned message received by eSocket.POS |
Action: |
o action required. |
Event 10248
Severity: |
Warning |
Symbolic Name: |
SEC_RISK_PROPERTY_BLANK |
Message: |
|
Text: |
Security Risk: The following sensitive property %1 is configured as blank and hence it will not be encrypted. |
Parameter %1: |
sensitive property that is configured as blank. |
Description: |
This event is logged when a sensitive property that has to be encrypted is blank. |
Action: |
No action is required. |
Event 10249
Severity: |
Warning |
Symbolic Name: |
CONFIG_AGENT_INTERNET_CONNECTIVITY_CONFIG_NOT_VERIFIED |
Message: |
|
Text: |
ConfigAgent is configured to connect over the public internet (postilion.esocketpos.ConfigAgentConnectOverInternet is set) but it is not configured to verify signed files from ConfigServer (postilion.esocketpos.VerifyDistributionFiles is not set). It is a best practice to use signed configuration files when connecting to ConfigServer over the public internet. Set up ConfigServer and ConfigAgent to sign and verify files. |
Description: |
This event is logged when ConfigAgent is configured to connect over the public internet, but it is not configured to expect signed configuration files and verify those files. In other words configuration property postilion.esocketpos.VerifyDistributionFiles is not set. |
Action: |
When connecting to ConfigServer over the public internet, it is a best practice to only accept signed configuration files to mitigate risk. Set up ConfigServer and ConfigAgent to sign and verify files. |
Event 10250
Severity: |
Warning |
Symbolic Name: |
CONFIG_AGENT_INTERNET_CONNECTIVITY_NO_CLIENT_CERT |
Message: |
|
Text: |
ConfigAgent is configured to connect over the public internet (postilion.esocketpos.ConfigAgentConnectOverInternet is set) but there are no client TLS certificates to present to ConfigServer during TLS negotiation. It is a best practice to use mutual TLS authentication when connecting to ConfigServer over the public internet. Configure a default TLS key pair and certificate to be used for initial configuration retrieval. Once eSocket.POS has at least one activated terminal or an activated ConfigAgent client certificate (specified using the postilion.esocketpos.ConfigAgentClientCertAlias property) is present in the TLS key store, the activated TLS certificate will be used to connect to ConfigServer. |
Description: |
This event is logged when ConfigAgent is configured to connect over the public internet, but no client TLS certificate is available to present to ConfigServer during TLS negotiation. This means that there are no terminals configured on eSocket.POS which have been activated, or there is no activated ConfigAgent client TLS certificate (specified using the postilion.esocketpos.ConfigAgentClientCertAlias property) is present in the TLS key store. There is also no default certificate configured (using configuration property postilion.esocketpos.UnactivatedClientCertAlias), or that default certificate is not present or valid in the TLS key store. |
Action: |
When connecting to ConfigServer over the public internet, it is a best practice to always use mutual TLS authentication when retrieving configuration. Set up a default TLS key pair and certificate in the key store that will be used for initial configuration retrieval. Once there is at least one activated terminal on eSocket.POS, or an activated ConfigAgent client TLS certificate (specified using the postilion.esocketpos.ConfigAgentClientCertAlias property) is present in the TLS key store, the activated TLS certificate will be used to connect to ConfigServer. |
Event 10251
Severity: |
Warning |
Symbolic Name: |
OPC_RETRY_EXCEEDED |
Message: |
|
Text: |
The user selected a payment option (OPC) that is not allowed for the transaction amount. The transaction has been declined after %1 attempts. |
Parameter %1: |
the configured OPC retry limit. |
Description: |
This event is logged when an OPC re-selection attempt exceeds the configured retries allowed. |
Action: |
No action is required. |
Event 10252
Severity: |
Warning |
Symbolic Name: |
OPC_RETRY_FILTER_EXHAUSTED |
Message: |
|
Text: |
The user selected a payment option (OPC) that is not allowed for the transaction amount. Transaction declined as retry filtering removed all available OPCs to display. |
Description: |
This event is logged when the OPC re-selection filter removed all available OPC’s for display. |
Action: |
No action is required. |
Event 10253
Severity: |
Warning |
Symbolic Name: |
INCORRECT_USER_PARAM |
Message: |
|
Text: |
Parameter %1 is incorrectly configured. Consult the User Guide for the list of valid values for this parameter. |
Parameter %1: |
Parameter Name |
Description: |
This event is logged when user param is not configured correctly. |
Action: |
Consult the User Guide for the list of valid values for this parameter. |
Event 10254
Severity: |
Warning |
Symbolic Name: |
TRUSTED_CERT_UPDATE_FAILED_IN_TLS_TRUSTSTORE |
Message: |
|
Text: |
ConfigAgent attempted to add a trusted certificate in the TLS trust store but the key store manager being used does not support automated updates. The alias that was used to attempt storing the certificate is %1. |
Parameter %1: |
the alias that ConfigAgent attempted to add |
Description: |
This event is logged when ConfigAgent attempts to add a new trusted certificate to the TLS trust store, but the trust store manager implementation does not support automated updates. |
Action: |
Investigate the reason for the trust store manager implementation reporting this error and rectify it. A possibility is that all JAR files required are not configured on the class path. Refer to the eSocket.POS user guide for guidance on setting the eSocket.POS class path. It is possible to manually add the trusted certificate to the trust store, but preferably the certificate should be sent again as part of a configuration update to be updated in the trust store. |
Event 10255
Severity: |
Warning |
Symbolic Name: |
HTTP_CLIENT_SAP_UPDATE_FAILED_OPEN_CONNECTIONS |
Message: |
|
Text: |
ConfigAgent attempted to update it’s HTTP client’s SAP factory and SAP factory parameters but failed due to the current SAP still having open connections to the server. The attempted SAP factory is %1, the attempted SAP factory parameters are %2 and the attempted server port is %3. ConfigAgent will try to update the SAP again with the next scheduled configuration retrieval attempt. The current number of open connections for the existing SAP is %4. |
Parameter %1: |
SAP factory |
Parameter %2: |
SAP factory parameters |
Parameter %3: |
Server port to connect to |
Parameter %4: |
Current number of open connections. |
Description: |
This event is logged when ConfigAgent attempts to update its client SAP used for configuration downloads while the current SAP still has open connections. |
Action: |
No action is required. The next configuration load will attempt to update the SAP again. If the SAP details are no longer valid (e.g. the client certificate in use has expired), then the upstream entity (i.e. ConfigServer) will decline new connections and updated configuration will not be available until the SAP details have been updated. Restarting ConfigAgent could assist in clearing existing connections, but will also halt all downloads in progress. |
Event 10256
Severity: |
Error |
Symbolic Name: |
HTTP_CLIENT_SAP_UPDATE_ERROR |
Message: |
|
Text: |
ConfigAgent attempted to update it’s HTTP client’s SAP factory and SAP factory parameters but failed. The details of the failure are listed in the provided exception stack trace. The attempted SAP factory is %1, the attempted SAP factory parameters are %2 and the attempted server port is %3. ConfigAgent will try to update the SAP again with the next scheduled configuration retrieval attempt. Exception: %4 |
Parameter %1: |
SAP factory |
Parameter %2: |
SAP factory parameters |
Parameter %3: |
Server port to connect to |
Parameter %4: |
Exception stack trace |
Description: |
This event is logged when ConfigAgent attempts to update its client SAP used for configuration downloads and an error occurs. |
Action: |
Investigate the reason for the failure and apply corrective measures as necessary. The next configuration load will attempt to update the SAP again. If the SAP details are no longer valid (e.g. the client certificate in use has expired), then the upstream entity (i.e. ConfigServer) will decline new connections and updated configuration will not be available until the SAP details have been updated. |
Event 10257
Severity: |
Informational |
Symbolic Name: |
ADDITIONAL_TCP_CONNECTION_RECEIVED |
Message: |
|
Text: |
An entity has received an additional TCP connection from the host. Entity %1 has received a new connection from: %2 eSocket.POS will now disconnect from the old connection: %3 |
Parameter %1: |
Entity receiving the new connection |
Parameter %2: |
Details of new connection (IP/Port) |
Parameter %3: |
Details of old connection (IP/Port) |
Description: |
This event is logged when an entity receives an additional connection. |
Action: |
one |
Event 10258
Severity: |
Informational |
Symbolic Name: |
TRANSACTION_PROCESSING_SUSPENDED |
Message: |
|
Text: |
Transaction processing has been suspended for terminal %1 for the following reason: %2 |
Parameter %1: |
terminal id |
Parameter %2: |
suspended Reason |
Description: |
This event is logged when a transaction processing is suspended |
Action: |
one |
Event 10259
Severity: |
Warning |
Symbolic Name: |
OPC_CONFIG_RETRY_REACHED |
Message: |
|
Text: |
The OPC configuration update retry limit %1 has been reached, a new configuration request will not be generated for the current session - Card Acceptor ID %2 and terminal ID %3. |
Parameter %1: |
the OPC configuration retry limit |
Parameter %2: |
Card Acceptor ID |
Parameter %3: |
terminal ID |
Description: |
This event is logged when the OPC configuration update retry limit has been exceeded. |
Action: |
No action is required. |
Event 10260
Severity: |
Informational |
Symbolic Name: |
OPC_CONFIGURATION_APPLIED |
Message: |
|
Text: |
The terminal has successfully applied the new OPC configuration with version %1 for Card Acceptor code %2. |
Parameter %1: |
OPC configuration applied |
Parameter %2: |
Card Acceptor ID |
Description: |
This event is logged to notify that OPC configuration has successfully been applied. |
Action: |
one |
Event 10261
Severity: |
Warning |
Symbolic Name: |
OPC_CONFIG_UNEXPECTED_RESPONSE |
Message: |
|
Text: |
Unexpected OPC Configuration response encountered, this message has been discarded for Card Acceptor ID %1 and terminal ID %2. |
Parameter %1: |
Card Acceptor ID |
Parameter %2: |
terminal ID |
Description: |
This event is logged when an OPC configuration update retry request is unexpected. Either is does not have the correct message type or the incorrect field 70. |
Action: |
No action is required. |
Event 10262
Severity: |
Warning |
Symbolic Name: |
CAPK_CONFIG_LOAD_FAILED |
Message: |
|
Text: |
The CA public key configuration load for terminal %1 failed due to the following reason: %2 |
Parameter %1: |
Terminal name |
Parameter %2: |
Description |
Description: |
This event is logged when CA public key configuration was not loaded due to the corresponding AID configuration being absent. |
Action: |
No action is required. |
Event 10263
Severity: |
Informational |
Symbolic Name: |
OPC_CONFIG_UNABLE_TO_LOCATE_TIMER |
Message: |
|
Text: |
Unable to locate counter for timer: %1 for Card Acceptor ID %2 and terminal ID %3. |
Parameter %1: |
trigger name |
Parameter %2: |
Card Acceptor ID |
Parameter %3: |
terminal ID |
Description: |
|
Action: |
one |
Event 10264
Severity: |
Informational |
Symbolic Name: |
OPC_CONFIG_SAME_VERSION |
Message: |
|
Text: |
Unable to load new OPC configuration with version %1, for Card Acceptor ID %2 and terminal ID %3. Version %1 is already in the database. |
Parameter %1: |
version |
Parameter %2: |
Card Acceptor ID |
Parameter %3: |
terminal ID |
Description: |
This event is logged when the terminal attempts to apply the same OPC configuration version. |
Action: |
one |
Event 10265
Severity: |
Error |
Symbolic Name: |
OPC_CONFIGURATION_NOT_APPLIED |
Message: |
|
Text: |
The terminal has not successfully applied the new OPC configuration with version %1 for Card Acceptor ID code %2 due to an error: %3. |
Parameter %1: |
OPC configuration version |
Parameter %2: |
Card Acceptor ID |
Parameter %3: |
Exception |
Description: |
This event is logged to notify that OPC configuration has not successfully been applied due to an error. |
Action: |
No action is required. |
Event 10266
Severity: |
Warning |
Symbolic Name: |
OPC_CONFIGURATION_NOT_CLEARED |
Message: |
|
Text: |
The terminal has not successfully cleared the old OPC configuration for the %1 table with version %2 for Card Acceptor code %3 due to an error: %4. |
Parameter %1: |
Online Table |
Parameter %2: |
OPC configuration version |
Parameter %3: |
Card Acceptor ID |
Parameter %4: |
Exception |
Description: |
This event is logged to notify that the previous OPC configuration has not successfully been cleared for a specific table. |
Action: |
No action is required. |
Event 10267
Severity: |
Informational |
Symbolic Name: |
RETRY_ABORT |
Message: |
|
Text: |
A Retry Abort has been received for Card Acceptor ID %1 and Terminal ID %2. No retries shall occur. |
Parameter %1: |
Card Acceptor ID |
Parameter %2: |
terminal ID |
Description: |
This event is logged to notify that an 'Abort Retry' has been received. |
Action: |
No action is required. |
Event 10268
Severity: |
Warning |
Symbolic Name: |
OPC_CONFIG_ERROR |
Message: |
|
Text: |
An error has occurred during an OPC configuration download for Card Acceptor ID %1 and Terminal ID %2 with a Response Code %3. |
Parameter %1: |
Card Acceptor ID |
Parameter %2: |
terminal ID |
Parameter %3: |
response code |
Description: |
This event is logged for generic errors that occur during OPC configuration downloads. |
Action: |
No action is required. |
Event 10269
Severity: |
Warning |
Symbolic Name: |
NO_MAPPING_FOR_ACQUIRER_NAME |
Message: |
|
Text: |
No card acceptor mapping was found for acquirer name %2 for terminal %1. The acquirer name parameter will be ignored. |
Parameter %1: |
terminal ID |
Parameter %2: |
acquirer name |
Description: |
This event is logged when an acquirer name is configured for Pipeline Component OpcConfig but no card acceptor mapping is found. |
Action: |
Ensure parameter ACQUIRER_NAME is correctly configured and that the relevant configuration exists in the esp_acq_ca_map table. |
Event 10270
Severity: |
Warning |
Symbolic Name: |
ESP_PROPERTY_VALUE_ERROR_CORRECTED |
Message: |
|
Text: |
The value of property %2 for terminal %1 was incorrectly specified, and has been corrected to %3. Description: %4 |
Parameter %1: |
The terminal ID |
Parameter %2: |
The property name |
Parameter %3: |
The corrected value used for the property |
Parameter %4: |
Description of the incorrect value |
Description: |
This event is logged when a property found in the eSocket.POS properties file is incorrectly specified / formatted, and has been corrected |
Action: |
Check the eSocket.POS configuration. |
Event 10271
Severity: |
Error |
Symbolic Name: |
SAFQ_NOT_CLEARING |
Message: |
|
Text: |
The eSocket.POS monitoring system detected a delay in the delivery of %1 transactions (excluding the last dequeued transaction that is being delivered upstream) from the store and forward queue (SAFQ) of terminal %3. eSocket.POS has not been able to deliver any transactions from the SAFQ for %2 minutes. This could be due to the terminal not being signed on, the host being under load, the host sending an invalid response, or another reason. Please review the eSocket.POS event log and traces for any errors or warnings. Restart eSocket.POS if this message is logged multiple times. Contact your primary support provider if after a restart this message is still being logged. |
Parameter %1: |
the size of the SAFQ (excluding the last dequeued transaction that is being delivered upstream, if any) |
Parameter %2: |
the approximate time in minutes a transaction was last dequeued from the SAFQ in order to be sent upstream |
Parameter %3: |
terminal ID |
Description: |
The eSocket.POS monitoring system detected a delay in the delivery of transactions from the store and forward queue (SAFQ) of the specified terminal. This could be due to the terminal not being signed on, the host being under load, the host sending an invalid response, or another reason. |
Action: |
Please review the eSocket.POS event log and traces for any errors or warnings. Restart eSocket.POS if this message is logged multiple times. Contact your primary support provider if after a restart this message is still being logged. |
Event 10272
Severity: |
Informational |
Symbolic Name: |
SAFQ_CLEARING_AGAIN |
Message: |
|
Text: |
The eSocket.POS monitoring system detected that transactions from the store and forward queue (SAFQ) of terminal %1 are being delivered again, after it has been delayed. |
Parameter %1: |
terminal ID |
Description: |
The eSocket.POS monitoring system detected that transactions from the store and forward queue (SAFQ) of the specified terminal are being delivered again, after it has been delayed. |
Action: |
None. |
Event 10273
Severity: |
Error |
Symbolic Name: |
INVALID_BARCODE_REQUEST_MSG |
Message: |
|
Text: |
A message could not be sent to the %1 device because it was invalid. |
Parameter %1: |
The device name |
Description: |
An attempt was made to send an invalid barcode display request to a device. |
Action: |
Contact your primary support provider. |
Event 10274
Severity: |
Informational |
Symbolic Name: |
MONITORING_INTERVAL_PARAM_VALUE |
Message: |
|
Text: |
The value of the 1st parameter(Monitoring Interval) in PipelineComponentMonitor is set to %1s after adding a stagger time of %2s to the originally configured value of %3s. This means, eSocket.POS will send the terminal monitoring message to the upstream entity at an interval of %1 second(s), when no transactional activity from the POS was received during that interval and there was a change in the status of the terminal. |
Parameter %1: |
The new monitoring interval in seconds |
Parameter %2: |
The jitter time in seconds |
Parameter %3: |
The originaly configured monitoring interval in seconds |
Description: |
The value of the 1st parameter(Monitoring Interval) in PipelineComponentMonitor |
Action: |
None. |
Event 10275
Severity: |
Informational |
Symbolic Name: |
UPDATE_MSG_INTERVAL_PARAM_VALUE |
Message: |
|
Text: |
The value of the parameter UPDATE_MSG_TIMER(Update message timer) in PipelineComponentMonitor is set to %1s after adding a stagger time of %2s to the originally configured value of %3s. This means, eSocket.POS will send the terminal monitoring message to the upstream entity at an interval of %1 second(s), when no response from the upstream entity was received during that interval. |
Parameter %1: |
The new update message interval in seconds |
Parameter %2: |
The jitter time in seconds |
Parameter %3: |
The originaly configured update message interval in seconds |
Description: |
The value of the parameter UPDATE_MSG_TIMER(Update message timer) in PipelineComponentMonitor |
Action: |
None. |
Event 10276
Severity: |
Error |
Symbolic Name: |
RKD_FAILED_HOST_MALFUNCTION |
Message: |
|
Text: |
A key exchange for the RKD device %1 has failed due to a system malfunction at the host level. Please investigate at the host level. |
Parameter %1: |
the name of the RKD device |
Description: |
This event is logged when a key exchange fails due to a system malfunction at the host level. |
Action: |
None. |
Event 10277
Severity: |
Warning |
Symbolic Name: |
JDBC_SECURITY_WARNING |
Message: |
|
Text: |
For security purposes, you should only specify the server name and driver in the URL. For username and password values, use their corresponding configuration properties. |
Parameter %1: |
|
Description: |
This event is logged when a the JDBC username and/or the JDBC password are configured as part of the JDBC URL. This affects the security of the system and requires technical attention. |
Action: |
None. |
Event 10278
Severity: |
Informational |
Symbolic Name: |
HSQLDB_SERVER_LOG_MESSAGE |
Message: |
|
Text: |
HSQLDB Message: %1 |
Parameter %1: |
The message logged by the HSQLDB server |
Description: |
This event encapsulates HSQLDB server log messages that it would normally log to the console i.e. the stdout stream. This event will only be logged when eSocket.POS is started with an embedded HSQDB server instance i.e. when eSocket.POS launches the HSQLDB server and not when HSQLDB is run as a standalone server. |
Action: |
No action is required. |
Event 10279
Severity: |
Error |
Symbolic Name: |
HSQLDB_SERVER_LOG_ERROR_MESSAGE |
Message: |
|
Text: |
HSQLDB Error Message: %1 |
Parameter %1: |
The HSQLDB error message |
Description: |
Logged when an HSQLDB-related error occurs. |
Action: |
Review the error message logged to determine the corrective action to take. |
Event 10280
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_CLASS_FILES_MISSING |
Message: |
|
Text: |
Ensure that all dependencies are installed before applying the package. Missing dependency: %1 |
Parameter %1: |
The dependency which is not installed. |
Description: |
ConfigAgent dependency is not installed for Terminal data configuration. |
Action: |
Install the required dependency |
Event 10281
Severity: |
Error |
Symbolic Name: |
HTTP_SERVER_ERROR |
Message: |
|
Text: |
Http Server Error details: %1 |
Parameter %1: |
Details on the error received from the server. |
Description: |
This event encapsulates HTTP server error messages that it would normally log to the console i.e. the stderr stream. This event will only be logged when an HTTP server responds with an error to a request sent from eSocket.POS |
Action: |
Review the error message logged to determine the action to take to rectify |
Event 10282
Severity: |
Error |
Symbolic Name: |
HTTP_CLIENT_ERROR |
Message: |
|
Text: |
Http Client Error details: %1 |
Parameter %1: |
Details on the error received that occurred while building the HTTP Request. |
Description: |
This event encapsulates HTTP client error messages that it would normally log to the console i.e. the stderr stream. This event will only be logged when eSocket.POS is not able to build a valid HTTP request from the message received. |
Action: |
Review the error message logged to determine the action to take to rectify |
Event 10283
Severity: |
Informational |
Symbolic Name: |
SAFQ_LIMITS_STATE_CHANGE |
Message: |
|
Text: |
The eSocket.POS monitoring system detected a SAFQ limits state change of the store and forward queue (SAFQ) of terminal %1. The new state is: %2. |
Parameter %1: |
terminal ID |
Parameter %2: |
new safq limits state |
Description: |
A SAFQ limits state change was detected. |
Action: |
None. |
Event 10284
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_HTTP_REQUEST_UNSUCCESSFUL |
Message: |
|
Text: |
An HTTP request attempted by ConfigAgent was unsuccessful. Method: %1 URI: %2 Error details: %3 |
Parameter %1: |
The HTTP method |
Parameter %2: |
The URI to which the request was attempted. |
Parameter %3: |
The error details. |
Description: |
An HTTP request attempted by ConfigAgent failed to complete successfully. |
Action: |
Review the error message logged to determine the action to take. |
Event 10285
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_RETRYING_FAILED_CERTIFICATE_RENEWAL |
Message: |
|
Text: |
The Configuration Agent failed while attempting the TLS client certificate renewal. Reason: %1. The certificate renewal will be retried in %2 second(s). If the renewal fails again, it will be retried %3 more time(s). |
Parameter %1: |
The reason given for the failure |
Parameter %2: |
The number of seconds before the certificate renewal is going to be retried |
Parameter %3: |
The number of times the certificate renewal will be retried if it fails again |
Description: |
An error occurred while attempting the certificate renewal and the certificate renewal is going to be retried. |
Action: |
None. |
Event 10286
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_RETRYING_FAILED_CERTIFICATE_RENEWAL_ATTEMPTS_EXHAUSTED |
Message: |
|
Text: |
The Configuration Agent failed while attempting the TLS client certificate renewal. Reason: %1. The certificate renewal will be retried in %2 minute(s). |
Parameter %1: |
The reason given for the failure |
Parameter %2: |
The number of minutes before the certificate renewal is going to be retried |
Description: |
An error occurred while attempting the certificate renewal and the certificate renewal is going to be retried. |
Action: |
None. |
Event 10287
Severity: |
Error |
Symbolic Name: |
CONFIG_AGENT_CLIENT_CERTIFICATE_RENEWAL_FAILURE |
Message: |
|
Text: |
The renewal of TLS client certificate failed. Reason: %1. |
Parameter %1: |
Exception associated with the TLS client certificate renewal failing |
Description: |
This event is logged when TLS client certificate renewal fails. |
Action: |
Investigate the reason for the TLS certificate renewal failing by reviewing the reported exception. Contact your primary support provider should additional assistance be required. |
Event 10288
Severity: |
Warning |
Symbolic Name: |
INVALID_USER_PARAM |
Message: |
|
Text: |
%1. Consult the User Guide for the list of valid values for this parameter. |
Parameter %1: |
Message with valid parameter values |
Description: |
This event is logged when user param is not configured correctly. |
Action: |
Consult the User Guide for the list of valid values for this parameter. |
Event 10289
Severity: |
Warning |
Symbolic Name: |
MANDATE_VIOLATION_WARNING |
Message: |
|
Text: |
The current configuration for the parameter %1 is violating a %2 mandate. Please consult the User Guide or contact your primary support provider for assistance. |
Parameter %1: |
Parameter Name |
Parameter %2: |
Mandate Name |
Description: |
This event is logged when user parameter configuration violates an existing. |
Action: |
Consult the User Guide for more information |
Event 10290
Severity: |
Error |
Symbolic Name: |
MANDATE_VIOLATION_ERROR |
Message: |
|
Text: |
The current configuration for the parameter %1 is violating a %2 mandate. Please consult the User Guide or contact your primary support provider for assistance. |
Parameter %1: |
Parameter Name |
Parameter %2: |
Mandate Name |
Description: |
This event is logged when user parameter configuration violates an existing. |
Action: |
Consult the User Guide for more information |
Event 10291
Severity: |
Warning |
Symbolic Name: |
REMOTE_SINK_CONNECTION_ATTEMPT |
Message: |
|
Text: |
%1. |
Parameter %1: |
Details |
Description: |
This event is logged when the Postilion Interface (RemoteSink) attempts to connect to the remote host. |
Action: |
o action required. |
Event 10292
Severity: |
Informational |
Symbolic Name: |
DATABASE_CONNECTION_STATUS |
Message: |
|
Text: |
Database connection status update: %1. |
Parameter %1: |
Status message indicating the current state of the database connection. |
Description: |
This event is logged when the database connection is lost and will be reattempted or when it has recovered. |
Action: |
None. |
Event 10293
Severity: |
Informational |
Symbolic Name: |
LOG_CLEANER_COMPLETED |
Message: |
|
Text: |
The Service Log Cleaner has completed. |
Description: |
This event is logged when the Service Log Cleaner has completed. |
Action: |
None. |
7. Copyright
© Copyright ACI Worldwide 2021
All information contained in this documentation, as well as the software described in it, is confidential and proprietary to ACI Worldwide, Inc., or one of its subsidiaries, is subject to a license agreement, and may be used or copied only in accordance with the terms of such license. Except as permitted by such license, no part of this documentation may be reproduced, stored in a retrieval system, or transmitted in any form or by electronic, mechanical, recording, or any other means, without the prior written permission of ACI Worldwide, Inc., or one of its subsidiaries.
ACI, ACI Worldwide, and the ACI product names used in this documentation are trademarks or registered trademarks of ACI Worldwide, Inc., or one of its subsidiaries.
Other companies' trademarks, service marks, or registered trademarks and service marks are trademarks, service marks, or registered trademarks and service marks of their respective companies.