ACI Logo

eSocket.POS User Guide

Postilion ®
ACI Worldwide, Inc
2021-04-26
Version: v3.0.00.787120-r4.3

 

© 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 Payment Systems, the ACI logo, ACI Universal Payments, UP, the UP logo, ReD, and all ACI product names are trademarks or registered trademarks of ACI Worldwide, Inc., or one of its subsidiaries, in the United States, other countries or both. Other parties' trademarks referenced are the property of their respective owners.

1. About this publication

1.1. Purpose of this document

The eSocket.POS User Guide is the primary implementation and operations manual for the eSocket.POS application.

1.2. Intended audience

This document is intended for integrators, operators, and other IT personnel involved in the implementation and operation of POS applications that incorporate eSocket.POS.

Additional information for eSocket.POS developers is in the eSocket.POS Developer Guide.

1.3. Organization of this document

This document is organized into the following sections:

  • Introduction

  • Installation and upgrades

  • Configuration

  • eSocket.POS components

  • Operation

The following international standards publications might 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 (1993): 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

1.5. Contacts

Contact your primary support provider for further information or feedback.

1.6. What’s new in this release?

1.6.1. eSocket.POS v3.0 release information

eSocket.POS v3.0 is released to work with ConfigServer v2.5. ConfigServer 2.5 has been released with a patch to add support for Packaged software delivery which is required for eSocket.POS 3. Please refer to the patch release notes for more information about this.

1.6.2. New features and functions

An improved, system independent JAR installer

eSocket.POS installer has been completely rebuilt to make installing eSocket.POS as easy as possible. The new installation JAR does everything the old installer was doing, and more. See the new eSocket.POS installation JAR topic for details.

Java 8+ Support

eSocket.POS requires a minimum of Java 8 JRE.

Remote deployable upgrades

An existing eSocket.POS 2.8 installation can be updated remotely (from ConfigServer) to eSocket.POS 3.0 as a side-by-side installation.

Additional Serial communication library support for devices

The jSerialComm serial library has been provided as a serial communication library supported on both 32-bit/64-bit Windows and Linux operating systems.

1.7. Third-party licenses

The Apache License version 1.1 applies to:

  • XML4J (An XML Parser for Java) version 2.0.11 in esocket-tools.jar

License
/* ====================================================================
 * The Apache Software License, Version 1.1
 *
 * Copyright (c) 2000 The Apache Software Foundation.  All rights
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Apache" and "Apache Software Foundation" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache",
 *    nor may "Apache" appear in their name, without prior written
 *    permission of the Apache Software Foundation.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 * Portions of this software are based upon public domain software
 * originally written at the National Center for Supercomputing Applications,
 * University of Illinois, Urbana-Champaign.
 */

The Apache License version 2.0 applies to:

  • Apache Commons Daemon 1.2.3

  • Apache Log4j version 1.2.12 in esocket-tools.jar

  • Apache Xerces Java XML Parser 2.12.0 in xercesImpl.jar and the related Java XML API in xml-apis.jar

License
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

The Bouncy Castle License applies to:

  • bcprov-jdk15.jar

  • bcpkix-jdk15.jar

License
Please note this should be read in the same way as the MIT license.

Please also note this licensing model is made possible through funding from donations
and the sale of support contracts.

LICENSE
Copyright (c) 2000 - 2018 The Legion of the Bouncy Castle Inc. (http://www.bouncycastle.org)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without restriction,
 including without limitation the rights to use, copy, modify, merge, publish, distribute,
 sublicense, and/or sell copies of the Software, and to permit persons to whom the Software
 is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The Oracle License applies to:

  • Sun Java Platform Standard Edition (JDK) (J2SDK)

License
Oracle Binary Code License Agreement for the Java SE Platform Products and JavaFX

ORACLE AMERICA, INC. ("ORACLE"), FOR AND ON BEHALF OF ITSELF AND ITS SUBSIDIARIES AND AFFILIATES UNDER COMMON CONTROL, IS WILLING TO LICENSE THE SOFTWARE TO YOU ONLY UPON THE CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS BINARY CODE LICENSE AGREEMENT AND SUPPLEMENTAL LICENSE TERMS (COLLECTIVELY "AGREEMENT"). PLEASE READ THE AGREEMENT CAREFULLY. BY SELECTING THE "ACCEPT LICENSE AGREEMENT" (OR THE EQUIVALENT) BUTTON AND/OR BY USING THE SOFTWARE YOU ACKNOWLEDGE THAT YOU HAVE READ THE TERMS AND AGREE TO THEM. IF YOU ARE AGREEING TO THESE TERMS ON BEHALF OF A COMPANY OR OTHER LEGAL ENTITY, YOU REPRESENT THAT YOU HAVE THE LEGAL AUTHORITY TO BIND THE LEGAL ENTITY TO THESE TERMS. IF YOU DO NOT HAVE SUCH AUTHORITY, OR IF YOU DO NOT WISH TO BE BOUND BY THE TERMS, THEN SELECT THE "DECLINE LICENSE AGREEMENT" (OR THE EQUIVALENT) BUTTON AND YOU MUST NOT USE THE SOFTWARE ON THIS SITE OR ANY OTHER MEDIA ON WHICH THE SOFTWARE IS CONTAINED.

1. DEFINITIONS. "Software" means the software identified above in binary form that you selected for download, install or use (in the version You selected for download, install or use) from Oracle or its authorized licensees, any other machine readable materials (including, but not limited to, libraries, source files, header files, and data files), any updates or error corrections provided by Oracle, and any user manuals, programming guides and other documentation provided to you by Oracle under this Agreement. "General Purpose Desktop Computers and Servers" means computers, including desktop and laptop computers, or servers, used for general computing functions under end user control (such as but not specifically limited to email, general purpose Internet browsing, and office suite productivity tools). The use of Software in systems and solutions that provide dedicated functionality (other than as mentioned above) or designed for use in embedded or function-specific software applications, for example but not limited to: Software embedded in or bundled with industrial control systems, wireless mobile telephones, wireless handheld devices, kiosks, TV/STB, Blu-ray Disc devices, telematics and network control switching equipment, printers and storage management systems, and other related systems are excluded from this definition and not licensed under this Agreement. "Programs" means (a) Java technology applets and applications intended to run on the Java Platform, Standard Edition platform on Java-enabled General Purpose Desktop Computers and Servers; and (b) JavaFX technology applications intended to run on the JavaFX Runtime on JavaFX-enabled General Purpose Desktop Computers and Servers. 'Commercial Features' means those features identified in Table 1-1 (Commercial Features In Java SE Product Editions) of the Java SE documentation accessible at http://www.oracle.com/technetwork/java/javase/documentation/index.html. 'README File' means the README file for the Software accessible at http://www.oracle.com/technetwork/java/javase/documentation/index.html.

2. LICENSE TO USE. Subject to the terms and conditions of this Agreement including, but not limited to, the Java Technology Restrictions of the Supplemental License Terms, Oracle grants you a non-exclusive, non-transferable, limited license without license fees to reproduce and use internally the Software complete and unmodified for the sole purpose of running Programs. THE LICENSE SET FORTH IN THIS SECTION 2 DOES NOT EXTEND TO THE COMMERCIAL FEATURES. YOUR RIGHTS AND OBLIGATIONS RELATED TO THE COMMERCIAL FEATURES ARE AS SET FORTH IN THE SUPPLEMENTAL TERMS ALONG WITH ADDITIONAL LICENSES FOR DEVELOPERS AND PUBLISHERS.

3. RESTRICTIONS. Software is copyrighted. Title to Software and all associated intellectual property rights is retained by Oracle and/or its licensors. Unless enforcement is prohibited by applicable law, you may not modify, decompile, or reverse engineer Software. You acknowledge that the Software is developed for general use in a variety of information management applications; it is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use the Software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle disclaims any express or implied warranty of fitness for such uses. No right, title or interest in or to any trademark, service mark, logo or trade name of Oracle or its licensors is granted under this Agreement. Additional restrictions for developers and/or publishers licenses are set forth in the Supplemental License Terms.

4. DISCLAIMER OF WARRANTY. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ORACLE FURTHER DISCLAIMS ALL WARRANTIES, EXPRESS AND IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT.

5. LIMITATION OF LIABILITY. IN NO EVENT SHALL ORACLE BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, PUNITIVE OR CONSEQUENTIAL DAMAGES, OR DAMAGES FOR LOSS OF PROFITS, REVENUE, DATA OR DATA USE, INCURRED BY YOU OR ANY THIRD PARTY, WHETHER IN AN ACTION IN CONTRACT OR TORT, EVEN IF ORACLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. ORACLE'S ENTIRE LIABILITY FOR DAMAGES HEREUNDER SHALL IN NO EVENT EXCEED ONE THOUSAND DOLLARS (U.S. $1,000).

6. TERMINATION. This Agreement is effective until terminated. You may terminate this Agreement at any time by destroying all copies of Software. This Agreement will terminate immediately without notice from Oracle if you fail to comply with any provision of this Agreement. Either party may terminate this Agreement immediately should any Software become, or in either party's opinion be likely to become, the subject of a claim of infringement of any intellectual property right. Upon termination, you must destroy all copies of Software.

7. EXPORT REGULATIONS. You agree that U.S. export control laws and other applicable export and import laws govern your use of the Software, including technical data; additional information can be found on Oracle's Global Trade Compliance web site (http://www.oracle.com/products/export). You agree that neither the Software nor any direct product thereof will be exported, directly, or indirectly, in violation of these laws, or will be used for any purpose prohibited by these laws including, without limitation, nuclear, chemical, or biological weapons proliferation.

8. TRADEMARKS AND LOGOS. You acknowledge and agree as between you
and Oracle that Oracle owns the ORACLE and JAVA trademarks and all ORACLE- and JAVA-related trademarks, service marks, logos and other brand
designations ("Oracle Marks"), and you agree to comply with the Third
Party Usage Guidelines for Oracle Trademarks currently located at
http://www.oracle.com/us/legal/third-party-trademarks/index.html . Any use you make of the Oracle Marks inures to Oracle's benefit.

9. U.S. GOVERNMENT LICENSE RIGHTS. If Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in Software and accompanying documentation shall be only those set forth in this Agreement.

10. GOVERNING LAW. This agreement is governed by the substantive and procedural laws of California. You and Oracle agree to submit to the exclusive jurisdiction of, and venue in, the courts of San Francisco, or Santa Clara counties in California in any dispute arising out of or relating to this agreement.

11. SEVERABILITY. If any provision of this Agreement is held to be unenforceable, this Agreement will remain in effect with the provision omitted, unless omission would frustrate the intent of the parties, in which case this Agreement will immediately terminate.

12. INTEGRATION. This Agreement is the entire agreement between you and Oracle relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification of this Agreement will be binding, unless in writing and signed by an authorized representative of each party.

SUPPLEMENTAL LICENSE TERMS

These Supplemental License Terms add to or modify the terms of the Binary Code License Agreement. Capitalized terms not defined in these Supplemental Terms shall have the same meanings ascribed to them in the Binary Code License Agreement. These Supplemental Terms shall supersede any inconsistent or conflicting terms in the Binary Code License Agreement, or in any license contained within the Software.

A. COMMERCIAL FEATURES. You may not use the Commercial Features for running Programs, Java applets or applications in your internal business operations or for any commercial or production purpose, or for any purpose other than as set forth in Sections B, C, D and E of these Supplemental Terms. If You want to use the Commercial Features for any purpose other than as permitted in this Agreement, You must obtain a separate license from Oracle.

B. SOFTWARE INTERNAL USE FOR DEVELOPMENT LICENSE GRANT. Subject to the terms and conditions of this Agreement and restrictions and exceptions set forth in the README File incorporated herein by reference, including, but not limited to the Java Technology Restrictions of these Supplemental Terms, Oracle grants you a non-exclusive, non-transferable, limited license without fees to reproduce internally and use internally the Software complete and unmodified for the purpose of designing, developing, and testing your Programs.

C. LICENSE TO DISTRIBUTE SOFTWARE. Subject to the terms and conditions of this Agreement and restrictions and exceptions set forth in the README File, including, but not limited to the Java Technology Restrictions and Limitations on Redistribution of these Supplemental Terms, Oracle grants you a non-exclusive, non-transferable, limited license without fees to reproduce and distribute the Software, provided that (i) you distribute the Software complete and unmodified and only bundled as part of, and for the sole purpose of running, your Programs, (ii) the Programs add significant and primary functionality to the Software, (iii) you do not distribute additional software intended to replace any component(s) of the Software, (iv) you do not remove or alter any proprietary legends or notices contained in the Software, (v) you only distribute the Software subject to a license agreement that: (a) is a complete, unmodified reproduction of this Agreement; or (b) protects Oracle's interests consistent with the terms contained in this Agreement and that includes the notice set forth in Section H, and (vi) you agree to defend and indemnify Oracle and its licensors from and against any damages, costs, liabilities, settlement amounts and/or expenses (including attorneys' fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results from the use or distribution of any and all Programs and/or Software. The license set forth in this Section C does not extend to the Software identified in Section G.

D. LICENSE TO DISTRIBUTE REDISTRIBUTABLES. Subject to the terms and conditions of this Agreement and restrictions and exceptions set forth in the README File, including but not limited to the Java Technology Restrictions and Limitations on Redistribution of these Supplemental Terms, Oracle grants you a non-exclusive, non-transferable, limited license without fees to reproduce and distribute those files specifically identified as redistributable in the README File ("Redistributables") provided that: (i) you distribute the Redistributables complete and unmodified, and only bundled as part of Programs, (ii) the Programs add significant and primary functionality to the Redistributables, (iii) you do not distribute additional software intended to supersede any component(s) of the Redistributables (unless otherwise specified in the applicable README File), (iv) you do not remove or alter any proprietary legends or notices contained in or on the Redistributables, (v) you only distribute the Redistributables pursuant to a license agreement that: (a) is a complete, unmodified reproduction of this Agreement; or (b) protects Oracle's interests consistent with the terms contained in the Agreement and includes the notice set forth in Section H, (vi) you agree to defend and indemnify Oracle and its licensors from and against any damages, costs, liabilities, settlement amounts and/or expenses (including attorneys' fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results from the use or distribution of any and all Programs and/or Software. The license set forth in this Section D does not extend to the Software identified in Section G.

E. DISTRIBUTION BY PUBLISHERS. This section pertains to your distribution of the JavaTM SE Development Kit Software ('JDK') with your printed book or magazine (as those terms are commonly used in the industry) relating to Java technology ("Publication"). Subject to and conditioned upon your compliance with the restrictions and obligations contained in the Agreement, Oracle hereby grants to you a non-exclusive, nontransferable limited right to reproduce complete and unmodified copies of the JDK on electronic media (the "Media") for the sole purpose of inclusion and distribution with your Publication(s), subject to the following terms: (i) You may not distribute the JDK on a stand-alone basis; it must be distributed with your Publication(s); (ii) You are responsible for downloading the JDK from the applicable Oracle web site; (iii) You must refer to the JDK as JavaTM SE Development Kit; (iv) The JDK must be reproduced in its entirety and without any modification whatsoever (including with respect to all proprietary notices) and distributed with your Publication subject to a license agreement that is a complete, unmodified reproduction of this Agreement; (v) The Media label shall include the following information: 'Copyright [YEAR], Oracle America, Inc. All rights reserved. Use is subject to license terms. ORACLE and JAVA trademarks and all ORACLE- and JAVA-related trademarks, service marks, logos and other brand designations are trademarks or registered trademarks of Oracle in the U.S. and other countries.' [YEAR] is the year of Oracle's release of the Software; the year information can typically be found in the Software's 'About' box or screen. This information must be placed on the Media label in such a manner as to only apply to the JDK; (vi) You must clearly identify the JDK as Oracle's product on the Media holder or Media label, and you may not state or imply that Oracle is responsible for any third-party software contained on the Media; (vii) You may not include any third party software on the Media which is intended to be a replacement or substitute for the JDK; (viii) You agree to defend and indemnify Oracle and its licensors from and against any damages, costs, liabilities, settlement amounts and/or expenses (including attorneys' fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results from the use or distribution of the JDK and/or the Publication; ; and (ix) You shall provide Oracle with a written notice for each Publication; such notice shall include the following information: (1) title of Publication, (2) author(s), (3) date of Publication, and (4) ISBN or ISSN numbers. Such notice shall be sent to Oracle America, Inc., 500 Oracle Parkway, Redwood Shores, California 94065 U.S.A , Attention: General Counsel.

F. JAVA TECHNOLOGY RESTRICTIONS. You may not create, modify, or change the behavior of, or authorize your licensees to create, modify, or change the behavior of, classes, interfaces, or subpackages that are in any way identified as "java", "javax", "sun", 'oracle' or similar convention as specified by Oracle in any naming convention designation.

G. LIMITATIONS ON REDISTRIBUTION. You may not redistribute or otherwise transfer patches, bug fixes or updates made available by Oracle through Oracle Premier Support, including those made available under Oracle's Java SE Support program.

H. COMMERCIAL FEATURES NOTICE. For purpose of complying with Supplemental Term Section C.(v)(b) and D.(v)(b), your license agreement shall include the following notice, where the notice is displayed in a manner that anyone using the Software will see the notice:

Use of the Commercial Features for any commercial or production purpose requires a separate license from Oracle. 'Commercial Features' means those features identified Table 1-1 (Commercial Features In Java SE Product Editions) of the Java SE documentation accessible at http://www.oracle.com/technetwork/java/javase/documentation/index.html



I. SOURCE CODE. Software may contain source code that, unless expressly licensed for other purposes, is provided solely for reference purposes pursuant to the terms of this Agreement. Source code may not be redistributed unless expressly provided for in this Agreement.

J. THIRD PARTY CODE. Additional copyright notices and license terms applicable to portions of the Software are set forth in the THIRDPARTYLICENSEREADME file accessible at http://www.oracle.com/technetwork/java/javase/documentation/index.html. In addition to any terms and conditions of any third party opensource/freeware license identified in the THIRDPARTYLICENSEREADME file, the disclaimer of warranty and limitation of liability provisions in paragraphs 4 and 5 of the Binary Code License Agreement shall apply to all Software in this distribution.

K. TERMINATION FOR INFRINGEMENT. Either party may terminate this Agreement immediately should any Software become, or in either party's opinion be likely to become, the subject of a claim of infringement of any intellectual property right.

L. INSTALLATION AND AUTO-UPDATE. The Software's installation and auto-update processes transmit a limited amount of data to Oracle (or its service provider) about those specific processes to help Oracle understand and optimize them. Oracle does not associate the data with personally identifiable information. You can find more information about the data Oracle collects as a result of your Software download at http://www.oracle.com/technetwork/java/javase/documentation/index.html.

For inquiries please contact: Oracle America, Inc., 500 Oracle Parkway,

Redwood Shores, California 94065, USA.

Last updated 02 April 2013

The Microsoft Java SDK License applies to:

  • Microsoft Java SDK

License
END-USER LICENSE AGREEMENT FOR MICROSOFT SOFTWARE

IMPORTANT-READ CAREFULLY: This Microsoft End-User License
Agreement ("EULA") is a legal agreement between you (either
an individual or a single entity) and Microsoft Corporation
("Microsoft") for the Microsoft software product identified
above, which includes computer software and may include
associated media, printed materials, and "online" or
electronic documentation ("SOFTWARE PRODUCT"). By installing,
copying, or otherwise using the SOFTWARE PRODUCT, you agree
to be bound by the terms of this EULA. If you do not agree to
the terms of this EULA, do not install or use the SOFTWARE
PRODUCT.

Microsoft SOFTWARE DEVELOPMENT KIT FOR JAVA VERSION 4.0

The SOFTWARE PRODUCT is protected by copyright laws and
international copyright treaties, as well as other
intellectual property laws and treaties. The SOFTWARE PRODUCT
is licensed, not sold.

1. GRANT OF LICENSE. This EULA grants you the following rights
a. Software Product. Microsoft grants to you as an
individual, a personal, nonexclusive license to make and use
copies of the SOFTWARE PRODUCT for the sole purposes of
designing, developing, and testing your software product(s).
You may install copies of the SOFTWARE PRODUCT on an
unlimited number of computers provided that you are the only
individual using the SOFTWARE PRODUCT. If you are an entity,
Microsoft grants you the right to designate one individual
within your organization to have the right to use the
SOFTWARE PRODUCT in the manner provided above.
b. Electronic Documents. Solely with respect to electronic
documents included with the SOFTWARE PRODUCT, you may make an
unlimited number of copies (either in hardcopy or electronic
form), provided that such copies shall be used only for
internal purposes and are not republished or distributed to
any third party.
c. Storage/Network Use. You may also store or install a copy
of the SOFTWARE PRODUCT on a storage device, such as a
network server, used only to install or run the SOFTWARE
PRODUCT on your other computers over an internal network;
however, you must acquire and dedicate a license for each
separate computer on which the SOFTWARE PRODUCT is installed
or run from the storage device. A license for the SOFTWARE
PRODUCT may not be shared or used concurrently on different
computers.
d. Sample Code. In addition to the rights granted in Section
1(a), Microsoft grants you a non-exclusive, royalty-free
right to modify the source code version of those portions of
the SOFTWARE PRODUCT that are identified as sample code in
the REDIST.HTM file in the SOFTWARE PRODUCT ("SAMPLE CODE"),
for the sole purposes of designing, developing, and testing
your software product(s), provided that you comply with
Section 1(f), below.
e. Redistributable Files. In addition to the rights granted
in Section 1(a), Microsoft grants you a nonexclusive,
royalty-free right to reproduce and distribute in object code
form only the SAMPLE CODE and all the other files identified
in the REDIST.HTM file located in the SOFTWARE PRODUCT (the
"REDISTRIBUTABLES"), provided that you comply with Section
1(f), below.
f. Redistribution Requirements. If you wish to distribute the
REDISTRIBUTABLES, you agree to: (i) distribute the
REDISTRIBUTABLES in object code only in conjunction with and
as a part of a software product developed by you that adds
significant and primary functionality to the REDISTRIBUTABLES
("Licensed Product"); (ii) not use Microsoft's name, logo, or
trademarks to market your Licensed Product; (iii) include a
valid copyright notice on your Licensed Product; (iv)
indemnify, hold harmless, and defend Microsoft from and
against any claims or lawsuits, including attorney's fees,
that arise or result from the use or distribution of your
Licensed Product; (v) distribute all of the files listed
under each of the headings in the REDIST.HTM file (for
example, "Tool Files"); (vi) not permit further distribution
of the REDISTRIBUTABLES.
The following exceptions apply to subsection (f)(vi), above:
(A) you may permit further redistribution of the
REDISTRIBUTABLES by your distributors to your end-user
customers if your distributors only distribute the
REDISTRIBUTABLES in conjunction with, and as part of, your
Licensed Product and you and your distributors comply with
all other terms of this EULA;
(B) you may permit your end users to reproduce and distribute
the object code version of the files listed below ("Limited-
Use Redistributable Files") for use in development of an
application created by your end user ("End User
Application"), provided that your end user agrees to: (i)
distribute the Limited-Use Redistributable Files in object
code only in conjunction with and as a part of a software
application product developed by them that adds significant
and primary functionality to the Limited-Use Redistributable
Files ("End User Application"); (ii) not use Microsoft's
name, logo, or trademarks to market the End User Application;
(iii) include a valid copyright notice on the End User
Application; (iv) indemnify, hold harmless, and defend
Microsoft from and against any claims or lawsuits, including
attorney's fees, that arise or result from the use or
distribution of the End User Application; (v) not distribute
less than all of the files listed under each of the headings
in the REDIST. HTM file if your end user distributes any one
or more of such files in an End User Application; and (vi)
not permit further distribution of the Limited-Use
Redistributable Files by the user of the End User
Application. Limited-Use Redistributable Files: the Limited-
Use Redistributable Files are all of the files listed in the
REDIST.HTM file of the SOFTWARE PRODUCT, except those in
Section 3.

2. UPGRADES. If the SOFTWARE PRODUCT is labeled as an
upgrade, you must be properly licensed to use a product
identified by Microsoft as being eligible for the upgrade in
order to use the SOFTWARE PRODUCT. A SOFTWARE PRODUCT labeled
as an upgrade replaces and/or supplements the product that
formed the basis for your eligibility for the upgrade. You
may use the resulting upgraded product only in accordance
with the terms of this EULA. If the SOFTWARE PRODUCT is an
upgrade of a component of a package of software programs that
you licensed as a single product, the SOFTWARE PRODUCT may be
used and transferred only as part of that single product
package and may not be separated for use on more than one
computer.

3. COPYRIGHT. All title and copyrights in and to the SOFTWARE
PRODUCT (including but not limited to any images,
photographs, animations, video, audio, music, text, and
"applets" incorporated into the SOFTWARE PRODUCT), the
accompanying printed materials, and any copies of the
SOFTWARE PRODUCT are owned by Microsoft or its suppliers. The
SOFTWARE PRODUCT is protected by copyright laws and
international treaty provisions. Therefore, you must treat
the SOFTWARE PRODUCT like any other copyrighted material
except that you may install the SOFTWARE PRODUCT on a single
computer provided you keep the original solely for backup or
archival purposes. You may not copy the printed materials
accompanying the SOFTWARE PRODUCT.

4. PRERELEASE CODE. The SOFTWARE PRODUCT may contain
PRERELEASE CODE that is not at the level of performance and
compatibility of the final, generally available, product
offering. These portions of the SOFTWARE PRODUCT may not
operate correctly and may be substantially modified prior to
first commercial shipment. Microsoft is not obligated to make
this or any later version of the SOFTWARE PRODUCT
commercially available. Microsoft grants you the right to
distribute test versions of your Licensed Product created
using the PRERELEASE CODE provided you comply with the
license terms described in Section 1 and the following
additional provisions: (a) you must mark the test version of
your Licensed Product "BETA" and (b) you are solely
responsible for updating your customers with versions of your
Licensed Product that operate satisfactorily with the final
commercial release of the PRERELEASE CODE. In order to
determine what constitutes PRERELEASE CODE, consult the
REDIST.HTM file located in the SOFTWARE PRODUCT.

5. DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS
a. Limitations on Reverse Engineering, Decompilation, and
Disassembly. You may not reverse engineer, decompile, or
disassemble the SOFTWARE PRODUCT, except and only to the
extent that such activity is expressly permitted by
applicable law notwithstanding this limitation.
b. Separation of Components. The SOFTWARE PRODUCT is licensed
as a single product. Its component parts may not be separated
for use on more than one computer.
c. Rental. You may not rent, lease, or lend the SOFTWARE
PRODUCT.
d. Support Services. Microsoft may provide you with support
services related to the SOFTWARE PRODUCT ("Support
Services"). Use of Support Services is governed by the
Microsoft policies and programs described in the user manual,
"online" documentation, and/or other Microsoft-provided
materials. Any supplemental software code provided to you as
part of the Support Services shall be considered part of the
SOFTWARE PRODUCT and subject to the terms and conditions of
this EULA. With respect to technical information you provide
to Microsoft as part of the Support Services, Microsoft may
use such information for its business purposes, including for
product support and development. Microsoft will not utilize
such technical information in a form that personally
identifies you.
e. Software Transfer. You may permanently transfer all of
your rights under this EULA, provided you retain no copies,
you transfer all of the SOFTWARE PRODUCT (including all
component parts, the media and printed materials, any
upgrades, this EULA, and, if applicable, the Certificate of
Authenticity), and the recipient agrees to the terms of this
EULA. If the SOFTWARE PRODUCT is an upgrade, any transfer
must include all prior versions of the SOFTWARE PRODUCT.
f. Termination. Without prejudice to any other rights,
Microsoft may terminate this EULA if you fail to comply with
the terms and conditions of this EULA. In such event, you
must destroy all copies of the SOFTWARE PRODUCT and all of
its component parts.

6. U.S. GOVERNMENT RESTRICTED RIGHTS. The SOFTWARE PRODUCT
and documentation are provided with RESTRICTED RIGHTS. Use,
duplication, or disclosure by the Government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of the
Rights in Technical Data and Computer Software clause at
DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the
Commercial Computer Software-Restricted Rights at 48 CFR
52.227-19, as applicable. Manufacturer is Microsoft
Corporation/One Microsoft Way/Redmond, WA 98052-6399.

7. EXPORT RESTRICTIONS. You agree that neither you nor your
customers intend to or will, directly or indirectly, export
or transmit (i) the SOFTWARE or related documentation and
technical data or (ii) your software product as described in
Section 1(f) of this License (or any part thereof), or
process, or service that is the direct product of the
SOFTWARE, to any country to which such export or transmission
is restricted by any applicable U.S. regulation or statute,
without the prior written consent, if required, of the Bureau
of Export Administration of the U.S. Department of Commerce,
or such other governmental entity as may have jurisdiction
over such export or transmission.

8. NOTE ON JAVA SUPPORT. THE SOFTWARE PRODUCT CONTAINS
SUPPORT FOR PROGRAMS WRITTEN IN JAVA. JAVA TECHNOLOGY IS NOT
FAULT TOLERANT AND IS NOT DESIGNED, MANUFACTURED OR INTENDED
FOR USE OR RESALE AS ONLINE CONTROL EQUIPMENT IN HAZARDOUS
ENVIRONMENTS REQUIRING FAIL-SAFE PERFORMANCE, SUCH AS IN THE
OPERATION OF NUCLEAR FACILITIES, AIRCRAFT NAVIGATION OR
COMMUNICATIONS SYSTEMS, AIR TRAFFIC CONTROL, DIRECT LIFE
SUPPORT MACHINES, OR WEAPONS SYSTEMS, IN WHICH THE FAILURE OF
JAVA TECHNOLOGY COULD LEAD DIRECTLY TO DEATH, PERSONAL
INJURY, OR SEVERE PHYSICAL OR ENVIRONMENTAL DAMAGE. Sun
Microsystems, Inc. has contractually obligated Microsoft to
make this disclaimer.

MISCELLANEOUS

If you acquired this product in the United States, this EULA
is governed by the laws of the State of Washington.
If you acquired this product in Canada, this EULA is governed
by the laws of the Province of Ontario, Canada. Each of the
parties hereto irrevocably attorns to the jurisdiction of the
courts of the Province of Ontario and further agrees to
commence any litigation which may arise hereunder in the
courts located in the Judicial District of York, Province of
Ontario.

If this product was acquired outside the United States, then
local law may apply.

Should you have any questions concerning this EULA, or if you
desire to contact Microsoft for any reason, please contact
the Microsoft subsidiary serving your country, or write:
Microsoft Sales Information Center/One Microsoft Way/Redmond,
WA 98052-6399.

If you have a specific question regarding the licensing of
redistributables, you may call the Microsoft Technical Sales
Information Team at (800) 426-9400 (United States only) or
send inquiries via fax to Microsoft SDK for Java Licensing
Administrator, (206) 936-7329 (United States only).

LIMITED WARRANTY

LIMITED WARRANTY. To the maximum extent permitted by
applicable law, Microsoft and its suppliers disclaim all
other warranties, either express or implied, including, but
not limited to, implied warranties of merchantability AND
fitness for a particular purpose, with regard to the SOFTWARE
PRODUCT, and any accompanying hardware. This limited warranty
gives you specific legal rights. You may have others, which
vary from state/jurisdiction to state/jurisdiction.

NOTWITHSTANDING THE FOREGOING, MICROSOFT WARRANTS THAT IT HAS
ALL THIRD PARTY LICENSE RIGHTS THAT ARE NECESSARY TO GRANT
THE LICENSE RIGHTS SET FORTH HEREIN.

LIMITATION OF LIABILITY. EXCEPT WITH RESPECT TO THE WARRANTY
SET FORTH IN THE LAST SENTENCE OF THE "LIMITED WARRANTY"
SECTION ABOVE, MICROSOFT'S ENTIRE LIABILITY AND YOUR
EXCLUSIVE REMEDY UNDER THIS EULA SHALL NOT EXCEED ONE HUNDRED
DOLLARS (US $100.00).

NO LIABILITY FOR CONSEQUENTIAL DAMAGES. To the maximum extent
permitted by applicable law, in no event shall Microsoft or
its suppliers be liable for any special, incidental,
indirect, or consequential damages whatsoever (including,
without limitation, damages for loss of business profits,
business interruption, loss of business information, or any
other pecuniary loss) arising out of the use of or inability
to use the software product, even if Microsoft has been
advised of the possibility of such damages. Because some
states and jurisdictions do not allow the exclusion or
limitation of liability for consequential or incidental
damages, the above limitation may not apply to you.

The Microsoft JDBC Driver 8.2 license applies to:

  • sqljdbc.jar

License
MICROSOFT SOFTWARE LICENSE TERMS
MICROSOFT JDBC DRIVER 8.2 FOR SQL SERVER

These license terms are an agreement between you and Microsoft Corporation (or one of its affiliates). They apply to the software named above and any Microsoft services or software updates (except to the extent such services or updates are accompanied by new or additional terms, in which case those different terms apply prospectively and do not alter your or Microsoft’s rights relating to pre-updated software or services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW.  BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS.

1. INSTALLATION AND USE RIGHTS.
	a) General. You may install and use any number of copies of the software to develop and test your applications.
	b) Third Party Software. The software may include third party applications that Microsoft, not the third party, licenses to you under this agreement. Any included notices for third party applications are for your information only.

2. DISTRIBUTABLE CODE. The software may contain code you are permitted to distribute (i.e. make available for third parties) in applications you develop, as described in this Section.
	a) Distribution Rights. The code and test files described below are distributable if included with the software.
		i. REDIST.TXT Files. You may copy and distribute the object code form of code listed on the REDIST list in the software, if any, or listed at REDIST;
		ii. Image Library. You may copy and distribute images, graphics, and animations in the Image Library as described in the software documentation;
		iii. Sample Code, Templates, and Styles. You may copy, modify, and distribute the source and object code form of code marked as “sample”, “template”, “simple styles”, and “sketch styles”; and
		iv. Third Party Distribution. You may permit distributors of your applications to copy and distribute any of this distributable code you elect to distribute with your applications.
	b) Distribution Requirements. For any code you distribute, you must:
		i. add significant primary functionality to it in your applications;
		ii. require distributors and external end users to agree to terms that protect it and Microsoft at least as much as this agreement; and
		iii. indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of your applications, except to the extent that any claim is based solely on the unmodified distributable code.
	c) Distribution Restrictions. You may not:
		i. use Microsoft’s trademarks or trade dress in your application in any way that suggests your application comes from or is endorsed by Microsoft; or
		ii. modify or distribute the source code of any distributable code so that any part of it becomes subject to any license that requires that the distributable code, any other part of the software, or any of Microsoft’s other intellectual property be disclosed or distributed in source code form, or that others have the right to modify it.

3. DATA COLLECTION. The software may collect information about you and your use of the software and send that to Microsoft. Microsoft may use this information to provide services and improve Microsoft’s products and services. Your opt-out rights, if any, are described in the product documentation. Some features in the software may enable collection of data from users of your applications that access or use the software. If you use these features to enable data collection in your applications, you must comply with applicable law, including getting any required user consent, and maintain a prominent privacy policy that accurately informs users about how you use, collect, and share their data. You can learn more about Microsoft’s data collection and use in the product documentation and the Microsoft Privacy Statement at [https://go.microsoft.com/fwlink/?LinkId=521839]. You agree to comply with all applicable provisions of the Microsoft Privacy Statement.

4. SCOPE OF LICENSE. The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to):
	a) work around any technical limitations in the software that only allow you to use it in certain ways;
	b) reverse engineer, decompile or disassemble the software;
	c) remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software;
	d) use the software in any way that is against the law or to create or propagate malware; or
	e) share, publish, distribute, or lend the software (except for any distributable code, subject to the terms above), provide the software as a stand-alone hosted solution for others to use, or transfer the software or this agreement to any third party.

5. EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit http://aka.ms/exporting.

6. SUPPORT SERVICES. Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind.

7. UPDATES. The software may periodically check for updates, and download and install them for you. You may obtain updates only from Microsoft or authorized sources. Microsoft may need to update your system to provide you with updates. You agree to receive these automatic updates without any additional notice. Updates may not include or support all existing software features, services, or peripheral devices.

8. ENTIRE AGREEMENT. This agreement, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software.

9. APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES. If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles. If you acquired the software in any other country, its laws apply. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court. If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court.

10. CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you:
	a) Australia. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights.
	b) Canada. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software.
	c) Germany and Austria.
		i.	Warranty. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software.
		ii.	Limitation of Liability. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law.
		Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence.

11. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

12. LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT, OR INCIDENTAL DAMAGES.
This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, warranty, guarantee, or condition; strict liability, negligence, or other tort; or any other claim; in each case to the extent permitted by applicable law.
It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your state, province, or country may not allow the exclusion or limitation of incidental, consequential, or other damages.

Please note: As this software is distributed in Canada, some of the clauses in this agreement are provided below in French.
Remarque: Ce logiciel étant distribué au Canada, certaines des clauses dans ce contrat sont fournies ci-dessous en français.
EXONÉRATION DE GARANTIE. Le logiciel visé par une licence est offert « tel quel ». Toute utilisation de ce logiciel est à votre seule risque et péril. Microsoft n’accorde aucune autre garantie expresse. Vous pouvez bénéficier de droits additionnels en vertu du droit local sur la protection des consommateurs, que ce contrat ne peut modifier. La ou elles sont permises par le droit locale, les garanties implicites de qualité marchande, d’adéquation à un usage particulier et d’absence de contrefaçon sont exclues.
LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES DOMMAGES. Vous pouvez obtenir de Microsoft et de ses fournisseurs une indemnisation en cas de dommages directs uniquement à hauteur de 5,00 $ US. Vous ne pouvez prétendre à aucune indemnisation pour les autres dommages, y compris les dommages spéciaux, indirects ou accessoires et pertes de bénéfices.
Cette limitation concerne:
•	tout ce qui est relié au logiciel, aux services ou au contenu (y compris le code) figurant sur des sites Internet tiers ou dans des programmes tiers; et
•	les réclamations au titre de violation de contrat ou de garantie, ou au titre de responsabilité stricte, de négligence ou d’une autre faute dans la limite autorisée par la loi en vigueur.
Elle s’applique également, même si Microsoft connaissait ou devrait connaître l’éventualité d’un tel dommage. Si votre pays n’autorise pas l’exclusion ou la limitation de responsabilité pour les dommages indirects, accessoires ou de quelque nature que ce soit, il se peut que la limitation ou l’exclusion ci-dessus ne s’appliquera pas à votre égard.
EFFET JURIDIQUE. Le présent contrat décrit certains droits juridiques. Vous pourriez avoir d’autres droits prévus par les lois de votre pays. Le présent contrat ne modifie pas les droits que vous confèrent les lois de votre pays si celles-ci ne le permettent pas.

The HSQL 2.3.4 license applies to:

  • hsqldb-2.3.4.jar

License
/* Copyright (c) 2001-2016, The HSQL Development Group
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice, this
 * list of conditions and the following disclaimer.
 *
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * Neither the name of the HSQL Development Group nor the names of its
 * contributors may be used to endorse or promote products derived from this
 * software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

The JAI License applies to:

  • jai_codec.jar

  • jai_core.jar

License
Sun Microsystems, Inc.
Binary Code License Agreement

JAVA ADVANCED IMAGING API, VERSION 1.1.3

READ THE TERMS OF THIS AGREEMENT AND ANY PROVIDED SUPPLEMENTAL LICENSE TERMS (COLLECTIVELY "AGREEMENT") CAREFULLY BEFORE OPENING THE SOFTWARE MEDIA PACKAGE. BY OPENING THE SOFTWARE MEDIA PACKAGE, YOU AGREE TO THE TERMS OF THIS AGREEMENT. IF YOU ARE ACCESSING THE SOFTWARE ELECTRONICALLY, INDICATE YOUR ACCEPTANCE OF THESE TERMS BY SELECTING THE "ACCEPT" BUTTON AT THE END OF THIS AGREEMENT. IF YOU DO NOT AGREE TO ALL THESE TERMS, PROMPTLY RETURN THE UNUSED SOFTWARE TO YOUR PLACE OF PURCHASE FOR A REFUND OR, IF THE SOFTWARE IS ACCESSED ELECTRONICALLY, SELECT THE "DECLINE" BUTTON AT THE END OF THIS AGREEMENT.

1. LICENSE TO USE. Sun grants you a non-exclusive and non-transferable license for the internal use only of the accompanying software and documentation and any error corrections provided by Sun (collectively "Software"), by the number of users and the class of computer hardware for which the corresponding fee has been paid.

2. RESTRICTIONS. Software is confidential and copyrighted. Title to Software and all associated intellectual property rights is retained by Sun and/or its licensors. Except as specifically authorized in any Supplemental License Terms, you may not make copies of Software, other than a single copy of Software for archival purposes. Unless enforcement is prohibited by applicable law, you may not modify, decompile, or reverse engineer Software. Licensee acknowledges that Software is not designed or intended for use in the design, construction, operation or maintenance of any nuclear facility. Sun Microsystems, Inc. disclaims any express or implied warranty of fitness for such uses.  No right, title or interest in or to any trademark, service mark, logo or trade name of Sun or its licensors is granted under this Agreement.

3.  LIMITED WARRANTY. Sun warrants to you that for a period of ninety (90) days from the date of purchase, as evidenced by a copy of the receipt, the media on which Software is furnished (if any) will be free of defects in materials and workmanship under normal use. Except for the foregoing, Software is provided "AS IS". Your exclusive remedy and Sun's entire liability under this limited warranty will be at Sun's option to replace Software media or refund the fee paid for Software.

4. DISCLAIMER OF WARRANTY. UNLESS SPECIFIED IN THIS AGREEMENT, ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

5. LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event will Sun's liability to you, whether in contract, tort (including negligence), or otherwise, exceed the amount paid by you for Software under this Agreement. The foregoing limitations will apply even if the above stated warranty fails of its essential purpose.

6. Termination. This Agreement is effective until terminated. You may terminate this Agreement at any time by destroying all copies of Software. This Agreement will terminate immediately without notice from Sun if you fail to comply with any provision of this Agreement. Upon Termination, you must destroy all copies of Software.

7.  Export Regulations. All Software and technical data delivered under this Agreement are subject to US export control laws and may be subject to export or import regulations in other countries. You agree to comply strictly with all such laws and regulations and acknowledge that you have the responsibility to obtain such licenses to export, re-export, or import as may be required after delivery to you.

8. U.S. Government Restricted Rights. If Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in Software and accompanying documentation will be only as set forth in this Agreement; this is in accordance with 48 CFR 227.7201 through 227.7202-4 (for Department of Defense (DOD) acquisitions) and with 48 CFR 2.101 and 12.212 (for non-DOD acquisitions).

9. Governing Law. Any action related to this Agreement will be governed by California law and controlling U.S. federal law. No choice of law rules of any jurisdiction will apply.

10. Severability. If any provision of this Agreement is held to be unenforceable, this Agreement will remain in effect with the provision omitted, unless omission would frustrate the intent of the parties, in which case this Agreement will immediately terminate.

11. Integration. This Agreement is the entire agreement between you and Sun relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification of this Agreement will be binding, unless in writing and signed by an authorized representative of each party.


                    JAVA ADVANCED IMAGING, VERSION 1.1.3

                         SUPPLEMENTAL LICENSE TERMS

These supplemental license terms ("Supplemental Terms") add to or modify the terms of the Binary Code License Agreement (collectively, the "Agreement"). Capitalized terms not defined in these Supplemental Terms shall have the same meanings ascribed to them in the Agreement. These Supplemental Terms shall supersede any inconsistent or conflicting terms in the Agreement, or in any license contained within the Software.

1. Software Internal Use and Development License Grant. Subject to the terms and conditions of this Agreement, including, but not limited to Section 3 (Java Technology Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive, non-transferable, limited license to reproduce internally and use internally the binary form of the Software, complete and unmodified, for the sole purpose of designing, developing and testing your Java applets and applications ("Programs").

2. License to Distribute Software. In addition to the license granted in Section 1 (Software Internal Use and Development License Grant) of these Supplemental Terms, subject to the terms and conditions of this Agreement, including but not limited to, Section 3 (Java Technology Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive, non-transferable, limited license to reproduce and distribute the Software in binary code form only, provided that you (i) distribute the Software complete and unmodified and only bundled as part of your Programs, (ii) do not distribute additional software intended to replace any component(s) of the Software, (iii) do not remove or alter any proprietary legends or notices contained in the Software, (iv) only distribute the Software subject to a license agreement that protects Sun's interests consistent with the terms contained in this Agreement, and (v) agree to defend and indemnify Sun and its licensors from and against any damages, costs, liabilities, settlement amounts and/or expenses (including attorneys' fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results from the use or distribution of any and all Programs and/or Software.

3. Java Technology Restrictions. You may not modify the Java Platform Interface ("JPI", identified as classes contained within the "java" package or any subpackages of the "java" package), by creating additional classes within the JPI or otherwise causing the addition to or modification of the classes in the JPI. In the event that you create an additional class and associated API(s) which (i) extends the functionality of the Java platform, and (ii) is exposed to third party software developers for the purpose of developing additional software which invokes such additional API, you must promptly publish broadly an accurate specification for such API for free use by all developers. You may not create, or authorize your licensees to create additional classes, interfaces, or subpackages that are in any way identified as "java", "javax", "sun" or similar convention as specified by Sun in any naming convention designation.

4.  Java Runtime Availability.  Refer to the appropriate version of the Java Runtime Environment binary code license (currently located at http://www.java.sun.com/jdk/index.html) for the availability of runtime code which may be distributed with Java applets and applications.

5. Trademarks and Logos. You acknowledge and agree as between you and Sun that Sun owns the SUN, SOLARIS, JAVA, JINI, FORTE, and iPLANET trademarks and all SUN, SOLARIS, JAVA, JINI, FORTE, and iPLANET-related trademarks, service marks, logos and other brand designations ("Sun Marks"), and you agree to comply with the Sun Trademark and Logo Usage Requirements currently located at http://www.sun.com/policies/trademarks. Any use you make of the Sun Marks inures to Sun's benefit.

6. Source Code. Software may contain source code that is provided solely for reference purposes pursuant to the terms of this Agreement. Source code may not be redistributed unless expressly provided for in this Agreement.

7. Termination for Infringement. Either party may terminate this Agreement immediately should any Software become, or in either party's opinion be likely to become, the subject of a claim of infringement of any intellectual property right.

8. Third Party Code. Additional copyright notices and license terms applicable to portions of the Software are set forth in the THIRDPARTYLICENSEREADME. In addition to any terms and conditions of any third party open source/freeware license identified in the THIRDPARTYLICENSEREADME, the disclaimer of warranty and limitation of liability provisions in paragraphs 5 and 6 of the Binary Code License Agreement shall apply to all Software in this distribution.

For inquiries please contact: Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A

(LFI#143342/Form ID#011801)

The Microsoft Windows NT Resource Kit Support Tools License applies to:

  • msvcr71.dll

  • msvcr100

  • sc.exe

License
Microsoft NT Resource Kit License
MICROSOFT WINDOWS NT RESOURCE KIT SUPPORT TOOLS
END-USER LICENSE AGREEMENT FOR MICROSOFT SOFTWARE

IMPORTANT-READ CAREFULLY: This Microsoft End-User License Agreement ("EULA") is a legal agreement between you (either an individual or a single entity) and Microsoft Corporation for the Microsoft software identified above, which includes computer software and may include associated media, printed materials, and "online" or electronic documentation ("SOFTWARE"). The SOFTWARE also includes any updates and supplements to the original SOFTWARE provided to you by Microsoft. Any software provided along with the SOFTWARE that is associated with a separate end-user license agreement is licensed to you under the terms of that license agreement. By installing, copying, or otherwise using the SOFTWARE, you agree to be bound by the terms of this EULA. If you do not agree to the terms of this EULA, do not install or use the SOFTWARE.

SOFTWARE LICENSE: The SOFTWARE is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The SOFTWARE is licensed, not sold.

1. GRANT OF LICENSE. This EULA grants you the following rights:

*Installation and Use. Except as otherwise provided herein, you, as an individual may install and use copies of the SOFTWARE on an unlimited number of computers, including workstations, terminals or other electronic devices ("Computer(s)") provided that you are the only individual using the SOFTWARE. If you are an entity, you may designate one individual within your organization to have the right to use the SOFTWARE in the manner provided above. The SOFTWARE is in "use" on a Computer when it is loaded into temporary memory (i.e., RAM) or installed into permanent memory (e.g., hard disk, CD-ROM, or other storage device) of that Computer.

*Client/Server Software. The SOFTWARE may contain one or more components which consist of both the following types of software: "Server Software" that is installed and provides services on a computer acting as a server ("Server"); and "Client Software" that allows a Computer to access or utilize the services provided by the Server Software. If the component of the SOFTWARE consists of both Server Software and Client Software which are used together, you may also install and use copies of such Client Software on Computers within your organization and which are connected to your internal network. Such Computers running this Client Software may be used by more than one individual.

2. DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS.

*Limitations on Reverse Engineering, Decompilation, and Disassembly. You may not reverse engineer, decompile, or disassemble the SOFTWARE, except and only to the extent that such activity is expressly permitted by applicable law notwithstanding this limitation.

*Rental. You may not rent, lease or lend the SOFTWARE.

*Support Services. Microsoft may provide you with support services related to the SOFTWARE ("Support Services").  Use of Support Services is governed by the Microsoft polices and programs described in the user manual, in "on line" documentation and/or other Microsoft-provided materials.  Any supplemental software code provided to you as part of the Support Services shall be considered part of the SOFTWARE and subject to the terms and conditions of this EULA. With respect to technical information you provide to Microsoft as part of the Support Services, Microsoft may use such information for its business purposes, including for product support and development. Microsoft will not utilize such technical information in a form that personally identifies you.

*Termination. Without prejudice to any other rights, Microsoft may terminate this EULA if you fail to comply with the terms and conditions of this EULA. In such event, you must destroy all copies of the SOFTWARE and all of its component parts.

3. COPYRIGHT. All title and intellectual property rights in and to the SOFTWARE (including but not limited to any images, photographs, animations, video, audio, music, text, and "applets" incorporated into the SOFTWARE), the accompanying printed materials, and any copies of the SOFTWARE are owned by Microsoft or its suppliers. All title and intellectual property rights in and to the content which may be accessed through use of the SOFTWARE is the property of the respective content owner and may be protected by applicable copyright or other intellectual property laws and treaties. This EULA grants you no rights to use such content. All rights not expressly granted are reserved by Microsoft.

4. BACKUP COPY. After installation of one copy of the SOFTWARE pursuant to this EULA, you may keep the original media on which the SOFTWARE was provided by Microsoft solely for backup or archival purposes. If the original media is required to use the SOFTWARE on the Computer, you may make one copy of the SOFTWARE solely for backup or archival purposes. Except as expressly provided in this EULA, you may not otherwise make copies of the SOFTWARE or the printed materials accompanying the SOFTWARE.

5. U.S. GOVERNMENT RESTRICTED RIGHTS. The SOFTWARE and documentation are provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software-Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is Microsoft Corporation/One Microsoft Way/Redmond, WA 98052-6399.

6. EXPORT RESTRICTIONS. You agree that you will not export or re-export the SOFTWARE, any part thereof, or any process or service that is the direct product of the SOFTWARE (the foregoing collectively referred to as the "Restricted Components"), to any country, person or entity subject to U.S. export restrictions. You specifically agree not to export or re-export any of the Restricted Components (i) to any country to which the U.S. has embargoed or restricted the export of goods or services, which currently include, but are not necessarily limited to Cuba, Iran, Iraq, Libya, North Korea, Sudan and Syria, or to any national of any such country, wherever located, who intends to transmit or transport the Restricted Components back to such country; (ii) to any entity who you know or have reason to know will utilize the Restricted Components in the design, development or production of nuclear, chemical or biological weapons; or (iii) to any entity who you know or have reason to know has been prohibited from partcipating in U.S. export transactions by any federal agency of the U.S. government. You warrant and represent that neither the BXA nor any other U.S. federal agency has suspended, revoked or denied your export privileges.

7. NOTE ON JAVA SUPPORT. THE SOFTWARE MAY CONTAIN SUPPORT FOR PROGRAMS WRITTEN IN JAVA. JAVA TECHNOLOGY IS NOT FAULT TOLERANT AND IS NOT DESIGNED, MANUFACTURED, OR INTENDED FOR USE OR RESALE AS ON-LINE CONTROL EQUIPMENT IN HAZARDOUS ENVIRONMENTS REQUIRING FAIL-SAFE PERFORMANCE, SUCH AS IN THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT NAVIGATION OR COMMUNICATION SYSTEMS, AIR TRAFFIC CONTROL, DIRECT LIFE SUPPORT MACHINES, OR WEAPONS SYSTEMS, IN WHICH THE FAILURE OF JAVA TECHNOLOGY COULD LEAD DIRECTLY TO DEATH, PERSONAL INJURY, OR SEVERE PHYSICAL OR ENVIRONMENTAL DAMAGE.

MISCELLANEOUS
*If you acquired this SOFTWARE in the United States, this EULA is governed by the laws of the State of Washington. *If you acquired this SOFTWARE in Canada, this EULA is governed by the laws of the Province of Ontario, Canada. In such case, each of the parties hereto irrevocably attorns to the jurisdiction of the courts of the Province of Ontario and further agrees to commence any litigation which may arise hereunder in the courts located in the Judicial District of York, Province of Ontario.

*If this SOFTWARE was acquired outside the United States, then local law may apply.

*Should you have any questions concerning this EULA, or if you desire to contact Microsoft for any reason, please contact the Microsoft subsidiary serving your country, or write: Microsoft Sales Information Center/One Microsoft Way/Redmond, WA 98052-6399.

NO WARRANTIES. MICROSOFT EXPRESSLY DISCLAIMS ANY WARRANTY FOR THE SOFTWARE. THE SOFTWARE AND ANY RELATED DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. THE ENTIRE RISK ARISING OUT OF USE OR PERFORMANCE OF THE SOFTWARE REMAINS WITH YOU.

LIMITATION OF LIABILITY. To the maximum extent permitted by applicable law, in no event shall Microsoft or its suppliers be liable for any special, incidental, indirect, or consequential damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss) arising out of the use of or inability to use the SOFTWARE or the provision of or failure to provide Support Services, even if Microsoft has been advised of the possibility of such damages. In any case, Microsoft's entire liability under any provision of this EULA shall be limited to the greater of the amount actually paid by you for the SOFTWARE or US$5.00; provided however, if you have entered into a Microsoft Support Services agreement, Microsoft's entire liability regarding Support Services shall be governed by the terms of that agreement. Because some states and jurisdictions do not allow the exclusion or limitation of liability, the above limitation may not apply to you.

The Custom OSS by James Clarke License applies to:

  • XP XML Parser in esocket-tools.jar

License
Copyright (c) 1997, 1998 James Clark

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
``Software''), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL JAMES CLARK BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of James Clark shall
not be used in advertising or otherwise to promote the sale, use or
other dealings in this Software without prior written authorization
from James Clark.

The Eclipse Distribution License - v1.0 applies to:

  • istack-commons-runtime-3.0.8.jar

  • jakarta.activation-api-1.2.1.jar

  • jakarta.xml.bind-api-2.3.2.jar

  • jaxb-runtime-2.3.2.jar

License
Copyright (c) 2007, Eclipse Foundation, Inc. and its licensors.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Eclipse Foundation, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

1.8. Third-party notices

The Apache Commons Daemon 1.2.3 library is shipped with the following notice file:

Notice
Apache Commons Daemon
Copyright 1999-2020 The Apache Software Foundation

This product includes software developed by
The Apache Software Foundation (http://www.apache.org/).

The Apache Xerces Java XML Parser 2.12.0 library is shipped with the following notice file:

Notice
   =========================================================================
   ==  NOTICE file corresponding to section 4(d) of the Apache License,   ==
   ==  Version 2.0, in this case for the Apache Xerces Java distribution. ==
   =========================================================================

   Apache Xerces Java
   Copyright 1999-2010 The Apache Software Foundation

   This product includes software developed at
   The Apache Software Foundation (http://www.apache.org/).

   Portions of this software were originally based on the following:
     - software copyright (c) 1999, IBM Corporation., http://www.ibm.com.
     - software copyright (c) 1999, Sun Microsystems., http://www.sun.com.
     - voluntary contributions made by Paul Eng on behalf of the
       Apache Software Foundation that were originally developed at iClick, Inc.,
       software copyright (c) 1999.

The Apache Log4j API 2.13.3 library is shipped with the following notice file:

Notice
Apache Log4j API
Copyright 1999-2020 The Apache Software Foundation

This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).

The Apache Log4j Core 2.13.3 library is shipped with the following notice file:

Notice
Apache Log4j Core
Copyright 1999-2012 Apache Software Foundation

This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).

ResolverUtil.java
Copyright 2005-2006 Tim Fennell

The Microsoft JDBC Driver 8.2 library is shipped with the following notice file:

Notice
THIRD-PARTY SOFTWARE NOTICES AND INFORMATION FOR MICROSOFT JDBC DRIVER FOR SQL
SERVER

concurrentlinkedhashmap 1.4.2
cityhash

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   Copyright 2020 ACI Worldwide

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

The jSerialComm 2.6.2 library is shipped with the following notice file:

Notice
Fazecast jSerialComm
Copyright (C) 2012-2020 Fazecast, Inc.

This product includes software developed at Fazecast, Inc: you can
redistribute it and/or modify it under the terms of either the Apache
Software License, version 2, or the GNU Lesser General Public License
as published by the Free Software Foundation, version 3 or above.

jSerialComm is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of both the GNU Lesser General Public
License and the Apache Software License along with jSerialComm. If not,
see <http://www.gnu.org/licenses/> and <http://www.apache.org/licenses/>.

2. Introduction

2.1. Product overview

2.1.1. eSocket.POS

eSocket.POS enables rapid application development to provide electronic funds transfer (EFT) functionality to a point-of-sale (POS) system. An application programming interface (API) or a message-based interface provides this functionality which can be used by the POS developer.

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

2.1.2. Realtime

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

2.2. Support

See the License, Implementation, and Support Agreement for details about the support infrastructure offered for our payments product range.

2.3. Supported features

eSocket.POS supports a rich set of transaction processing features, including the following:

2.3.1. Interface between the POS application and Realtime

  • Provides an application program interface (API) or a message-based interface to the POS program.

  • Allows a transaction with the necessary data elements to be created.

  • Establishes and maintains a TCP/IP connection to Realtime via a PosConnect source node.

  • Translates transactions into messages to send to PosConnect.

  • Receives response messages from PosConnect and presents them to the local application as responses.

2.3.2. Peripheral device support

  • Interfaces with peripheral devices at the point of sale including:

    • Card reader

    • Display

    • Keypad

    • PIN pad

    • Smartcard reader

    • Barcode reader

    • Check reader

    • Signature capture device

  • Manages key changes on the PIN pad.

  • Manages interactions with an EMV smartcard.

  • Manages upgrades of firmware on peripheral devices.

  • Supports validation of peripheral devices based on the serial number.

2.3.3. Validation and authorization services

2.3.4. Central management

  • Retrieves configuration information and software updates from a central configuration server.

  • Reports terminal status information to the Terminal Monitor.

2.3.5. SSL

  • Supports mutual SSL authentication for connections to PosConnect, ConfigServer, the PIN Entry Device (PED), and the POS.

  • Supports the legacy server-only SSL authentication to PosConnect and ConfigServer which used to be offered by the eSocket.POS SSL Extension (for those customers who prefer to use it).

2.4. Supported transactions

eSocket.POS currently supports the following transaction types:

2.4.1. Financial transactions

  • Purchase

  • Purchase with cashback

  • Authorization request

  • Transaction advice

  • Referral

  • Deposit

  • Refund

  • Reversal

  • Purchasing card (level 2/level 3 data)

  • Debit adjustment

  • Credit adjustment

  • Reconciliation

2.4.2. Inquiries

  • Balance inquiry

  • Available funds inquiry

  • Mini-statement inquiry

  • Credit Admin Account Look-up General inquiry

  • Credit Admin Status Application General inquiry

  • Driver’s License Account Lookup General inquiry

  • Current transaction’s status inquiry

  • Card Verification inquiry

2.4.3. Check processing

  • Check verification

  • Check guarantee

2.4.4. Prepaid merchandise

  • Prepaid merchandise request

  • Prepaid merchandise confirm/advice

  • Prepaid merchandise procure

  • Prepaid merchandise reverse

2.4.5. Gift card transactions

  • Gift card activation

  • Gift card activation with deposit

  • Gift card load (deposit)

  • Gift card deactivation

  • Gift card deactivation with cashback

  • Gift card activation with refund

  • Gift card unload (account remains active)

Note
Gift card transaction processing requires the use of PosConnect v2.0 with Patch 2 (or higher) applied.

2.4.6. Other

  • Administration advice and request

  • Credit Admin Express Application transaction

  • Network management request

  • Device administration request

  • Driver’s License Instant Credit transaction

2.5. eSocket.POS deployment

The eSocket.POS client is designed to reside on a till or a retail outlet’s store server. There, it provides EFT capability to the Electronic Point-of-Sale (EPOS) tills. The till or store server is able to talk upstream to Realtime for transaction authorization or use sophisticated local authorization capability using eSocket.POS.

2.5.1. eSocket.POS at the till with central Realtime

eSocket.POS can be implemented on each till with a connection to a single central Realtime system.

Here, eSocket.POS processing functionality occurs on the till, with online authorization capability available to the central Realtime system. In this architecture, there is no need for an EFT component, Realtime or otherwise, to reside on the store server.

In this architecture eSocket.POS uses a database residing on the till.

Deployment overview of eSocket.POS at the till

2.5.2. eSocket.POS at the store server with central Realtime

eSocket.POS can be implemented on each store server with a connection to a centrally located Realtime system.

In this architecture, eSocket.POS processing functionality resides on the store server with online authorization capability available upstream to a central Realtime system.

Deployment overview of eSocket.POS at the store server

2.6. Limitations

eSocket.POS has the following limitations:

  • eSocket.POS no longer supports the Microsoft JVM or the Sub JdbcOdbcDriver.

  • eSocket.POS is supported on the Java 1.8 and later virtual machines*, with the exception of AdoptOpenJDK 11 32-bit that is not supported.

  • eSocket.POS only supports linking transactions from different terminals when it is installed in a store-server environment.

  • eSocket.POS using HSQL in server mode is not supported on Java 11. The alternative is to use the Java 8 JRE.

The following limitations apply when eSocket.POS is configured to encrypt properties in the properties file:

  • The upgrade installer that is shipped with upgrades built on versions of eSocket.POS prior to v2.4 is not able to decrypt properties.

  • To install upgrades built on older versions from the command line, the JDBC username and JDBC user password must be specified as system properties on the command line, for example:

    java.exe -Dpostilion.esocketpos.JdbcUser= esp_user -Dpostilion.esocketpos.JdbcUserPassword= user_password -jar setup_VeriFoneSC5000_v1.0_build12345_r2.0.jar -p c:\postilion\eSocket.POS\properties.txt

The following limitations apply to contactless transactions:

  • Contactless preswipe/preread is not supported as the final transaction amount is required before the card is tapped.

The following limitation applies to connecting to the Oracle Payment Interface system:

2.7. Data security standards

The PCI Security Standards Council (PCI SSC) has defined a set of best practices, called the Payment Application Data Security Standard (PA-DSS), which are aimed at assisting software vendors to create secure payment applications. For a complete listing of ACI Worldwide components and versions that are PA-DSS validated, see the PCI web site: https://www.pcisecuritystandards.org/

The following statement from the Payment Card Industry PA-DSS Vendor Release Agreement between the PCI SSC and ACI Worldwide applies only to those licensed products listed on the PCI web site as being approved:

"Legal Terms and Conditions

Acceptance of a given payment application by the PCI Security Standards Council, LLC (PCI SSC) only applies to the specific version of that payment application that was reviewed by a PA-QSA and subsequently accepted by PCI SSC (the "Accepted Version"). If any aspect of a payment application or version thereof is different from that which was reviewed by the PA-QSA and accepted by PCI SSC - even if the different payment application or version (the "Alternate Version") conforms to the basic product description of the Accepted Version - then the Alternate Version should not be considered accepted by PCI SSC, nor promoted as accepted by PCI SSC.

No vendor or other third party may refer to a payment application as "PCI Approved" or "PCI SSC Approved", and no vendor or other third party may otherwise state or imply that PCI SSC has, in whole or part, accepted or approved any aspect of a vendor or its services or payment applications, except to the extent and subject to the terms and restrictions expressly set forth in a written agreement with PCI SSC, or in a PA-DSS letter of acceptance provided by PCI SSC. All other references to PCI SSC’s approval or acceptance of a payment application or version thereof are strictly and actively prohibited by PCI SSC.

When granted, PCI SSC acceptance is provided to ensure certain security and operational characteristics important to the achievement of PCI SSC’s goals, but such acceptance does not under any circumstances include or imply any endorsement or warranty regarding the payment application vendor or the functionality, quality, or performance of the payment application or any other product or service. PCI SSC does not warrant any products or services provided by third parties. PCI SSC acceptance does not, under any circumstances, include or imply any product warranties from PCI SSC, including, without limitation, any implied warranties of merchantability, fitness for purpose or non-infringement, all of which are expressly disclaimed by PCI SSC. All rights and remedies regarding products and services that have received acceptance from PCI SSC, shall be provided by the party providing such products or services, and not by PCI SSC or any payment brands."

3. Installation and upgrades

3.1. Installation and upgrades

eSocket.POS can be installed on a number of different hardware platforms, operating systems, and databases.

The new installer can be used on Windows and Linux operating systems. By default, the installer assumes that the HSQL database will be used for the standalone mode. The installation is driven by the install.properties file, which allows you to specify many parameters that control how eSocket.POS should be installed, such as:

  • Database Server Name

  • Database Device

  • Database Device Filename

  • Log Device

  • Log Device Filename

During the installation, the user must specify a Java virtual machine, database driver, and associated parameters. The use of a database management system other than HSQL standalone mode can therefore be determined by the choice of database driver.

Remote upgrades are enabled by configuring and running the Upgrade Manager during the POS or Store Server’s boot process. See the Upgrade Manager page for a detailed description and for configuration instructions.

Separate notes are provided for a Realtime installation.

3.2. Supported platforms

3.2.1. Databases

eSocket.POS supports the following databases:

Automated installation:

  • Microsoft SQL Server 2019, 2017, 2016

  • Microsoft SQL Server Express 2019, 2017, 2016

  • HSQL Database Engine (HSQLDB) 2.3.4

Manual installation:

  • IBM DB2 Express-C 9.5

Note
  • eSocket.POS can support any other database platform with a JDBC driver supporting ANSI SQL. Contact your primary support provider to determine what is required to support your preferred platform.

  • Use of the MySQL/MariaDB database platform requires that the NO_BACKSLASH_ESCAPES SQL_MODE be enabled. See the "SQL_MODE" section of the MySQL/MariaDB documentation for instructions and additional information.

3.2.2. Operating systems

eSocket.POS supports the following operating systems:

  • Windows Server 2019

  • Windows Server 2016

  • Windows Server 2012

  • Windows 10

  • Linux

Note
eSocket.POS can support other Windows versions and other Linux-like operating systems. Contact your primary support provider to determine what is required to support your preferred platform.

3.3. Using eSocket.POS Installer utility

3.3.1. The new eSocket.POS installation JAR

eSocket.POS is now distributed using an executable JAR file installer. This new JAR can be installed by running the install command on the terminal. Alternatively, Upgrade Manager can do the install in the case of an upgrade.

Verifying an installation package

For security purposes, steps must be taken to ensure that the installation package files (which can consist of plugins and patches) have not been altered or tampered with prior to installation. Two files enable this:

  • A text file, <jar_installer_name>.md5.txt.
    This file contains a checksum value, supplied with the release of every payments software package.

  • A verify_hash utility.
    This utility performs the actual verification and is supplied with the Realtime Framework installer package.

The files are distributed separately. If you do not have a hash value file or the utility, contact your primary support provider.

To verify the installation package:

  1. Ensure that the text file is in the same folder as the installation package; an error message will display if the text file cannot be located.

  2. Start a command line session (in Windows you would do this by clicking Start > Run, typing cmd, and then clicking OK).

  3. Type verify_hash <release_file_name> at the prompt and press Enter.

For example, suppose you have received the following files from ACI and have placed them all in the same folder:

  • setup_eSocket.POS_vX.X_buildXXXXXX_r4.3_install.jar

  • setup_eSocket.POS_vX.X_buildXXXXXX_r4.3_install.jar.md5.txt

To perform the verification process:

  1. Open a command line session and type the following:

    verify_hash "setup_eSocket.POS_vX.X_buildXXXXXX_r4.3_install.jar"

  2. Press Enter.

If the verification is successful, the following text displays on the screen:

Read precalculated file digest...
Calculating release file digest...
MD5 Hash values match.

If this message does not display, or a different message displays, consult your primary support provider.

Content of the JAR installer

The new JAR installer contains everything required to install eSocket.POS successfully on Windows and Linux systems. The following elements are expected :

  • install.properties:
    This is the manifest file that drives eSocket.POS installation. All properties required for the installation must be defined here.

  • hsql_database.zip:
    eSocket.POS is shipped with an empty, ready-to-use HSQL database.

  • esp.jar:
    This contains all the eSocket.POS classes and libraries that are copied during the installation.

  • installs directory:
    If the JAR packages eSocket.POS with plugins or device drivers, those plugins and device drivers installation JARs must be in an installs directory inside the installation JAR.

  • patches directory:
    If any patch must be installed with eSocket.POS, those patch installation JAR files must be location inside the patches directory.

  • META-INF directory:
    This directory contains various manifest files used mainly during the upgrade.

eSocket.POS packages

eSocket.POS releases are now packaged by default to match how plugins are used in various regions. The following packages are available :

  • Verifone US package:
    eSocket.POS is packaged with the following :

    • Verifone XPI 1.0 and its latest patches

    • Verifone XPI 2.0 and its latest patches

    • VerifoneFormAgent 1.0 and its latest patches

    • eSocket.POS ITK 1.0 and its latest patches

  • Ingenico EU package:
    eSocket.POS is packaged with the following :

    • Ingenico EMV 5.1 and its latest patches

  • Verifone EU package:
    eSocket.POS is packaged with :

    • Dione 5.0 and its latest patches

    • eSocket.POS OSCar 1.0 and its latest patches

  • Ingenico US package:
    IeSocket.POS is delivered with :

    • Ingenico RBA 1.2 and its latest patches

    • Ingenico UPP 1.0 and its latest patches

    • eSocket.POS ITK 1.0 and its latest patches

Note
  • The packages listed here does not mean eSocket.POS only supports the provided combinations. Customers are free to use any plugin/customization compatible with eSocket.POS

  • Customers don’t have to install everything provided in the package. For the Verifone US package, for example, it is not expected that the customer will use all 3 drivers provided. The installation JAR can be customized to match the customer’s environment.

Customize the JAR content

The new eSocket.POS installation JAR can be customized to add/remove various elements to prepare it for the installation.

Adding plugins/extensions

As stated before, any plugin, extension, and customization can be installed with eSocket.POS by copying it to the installs directory inside the JAR.

This directory must only contains JAR installers for the plugins. It must not contain any patches.

The plugins in the installs directory will only be installed if the postilion.esocketpos.install.InstallPlugins property is set to true in the install.properties file.

Adding patches

Any eSocket.POS or plugin patches that should be installed at the same time with eSocket.POS must be part of the patches directory in the installation JAR. Those patches will be installed after the contents of the installs folder is installed.

If a patch requires a plugin that’s inside the installs directory, that plugin will already be installed on the system by the time the patch installation starts during the eSocket.POS installation.

The patches in the patches directory will only be installed if the postilion.esocketpos.install.InstallPatches property is set to true in the install.properties file.

Adding keystore/truststore

On clean installs or upgrades, it is possible to update the installation package to contain a keystore and truststore file to be installed on the terminal.

Prerequisite: On the environment where the eSocket.POS installation package is created, ensure that a JDK is installed and configured on the system path environment variable as the jar utility shipped with a JDK is required for this operation.

Run the setup JAR with the -a or --add-file flag, followed by the file type you want to put in the JAR.

The following files can be added to the package:

  • Trust store files: Put the trust store files in a truststore folder and run the --add-file command.

  • Key store files: Put the key store files in a keystore folder and run the --add-file command.

For example:

java -jar setup_eSocket.POS_v3.0_buildXXXXXX_r4.3_install.jar -a keystore

Note
The above command does not complete immediately and should not be used in an automated script.

An alternative, to update the keystore/truststore in the JAR file, is to run the following commands manually:

  • jar uf setup_eSocket.POS_v3.0_buildXXXXXX_r4.3_install.jar keystore

  • jar uf setup_eSocket.POS_v3.0_buildXXXXXX_r4.3_install.jar truststore

3.3.2. Before you begin your eSocket.POS installation

The eSocket.POS Java installation utility handles the entire installation process and performs all required steps to get eSocket.POS running with device drivers and front-ends provided in the installation package.

Before starting eSocket.POS installation, ensure the following pre-installation steps are already taken:

  • ACI recommends that you run the installation JAR from an account with elevated privileges, preferably an administrator account.

  • eSocket.POS installation packages are available in the same directory

  • Ensure that Java Runtime 1.8 or later is installed in the system.

  • Environment variables called JAVA_HOME and JRE_HOME needs to be set, that indicates the Java Runtime Environment(JRE) folder location, must be specified. The JRE folder contains the bin folder containing the JRE executable (for example, java.exe on Windows).

  • The required database management system (DBMS) is installed and configured.

  • Ensure the JDBC driver for the database in use is available on the system and is part of the classpath. This step can be skipped for SQL Server on Windows and HSQL databases as eSocket.POS ensures the required JDBC drivers are available on the system.

  • Configure a system variable for the Postilion directory in environment variable POSTILIONDIR. For example, configuration of the variable POSTILIONDIR on Windows, to a value of, c:\Program Files\Postilion, results in eSocket.POS being installed to the c:\Program Files\Postilion\eSocket.POS directory. Likewise, for Linux, a value of /opt/Postilion can be configured.

  • Ensure the installation user has the required permissions to read and write files/directories in the target eSocket.POS installation directory.

  • Update the installation manifest file to configure attributes for the installation.

  • On Windows, the sc.exe utility is used to manage eSocket.POS services. Ensure that this utility is installed on your system before starting the installation.

The eSocket.POS installation utility ensures all pre-installation steps are taken and the installation will fail earlier if the system is not ready to perform the installation.

3.3.3. The installation manifest file

The installation utility requires minimal input to ensure that the eSocket.POS installation is performed successfully. The required input is provided to the utility through a manifest file. Each line of the file is a key=value pair. eSocket.POS loads those properties before starting the installation.

The eSocket.POS installation JAR ships with a default install.properties file. The file contains a minimum set of properties that can be used.

To extract this file from the installation JAR, run one of the following commands:

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar -e

or

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar --extract

where XXXXXX is the eSocket.POS build number.

This command extracts install.properties from the installation JAR into the installation directory (where the installation JAR is located).

After the install.properties file has been updated, a new installation JAR file can be created including this new install.properties by running the command:

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar -c

or

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar --compress

where XXXXXX is the eSocket.POS build number.

The new installation JAR location will be output in the console.

The manifest file name cannot be changed; it must be called install.properties during the installation and must always be at the same location as the eSocket.POS installation JAR or at the root of the eSocket.POS installation JAR.

The following table describes the properties that can be configured in a manifest file. The properties are case-insensitive.

Note
In addition to the properties described here, that are used during the installation, any other property supported by eSocket.POS that is configured in the install.properties file will be copied to the default properties file generated during eSocket.POS installation.
Property Mandatory Description

postilion.esocketpos.JdbcDriver

Yes

Specifies the JDBC driver class.

Not required if using HSQL. eSocket.POS installation defaults to the HSQL driver.

postilion.esocketpos.JdbcUrl

No

Specifies the URL for the JDBC connection. If using HSQL, and the JDBC URL is not configured, the eSocket.POS database will be installed inside the eSocket.POS directory during the installation.

Note
  • If either of postilion.esocketpos.JdbcServerName or postilion.esocketpos.JdbcServerPort properties are used, the server name and port must be omitted from the URL.

  • For security purposes, do not configure the JDBC username or the JDBC password as part of this property. Use their respective configuration properties instead.

postilion.esocketpos.JdbcUser

No

Specifies the JDBC username. If using HSQL, and the JDBC User is not provided, the HSQL default user SA will be used.

Note
If Windows Authentication is used to connect to Microsoft SQL Server, then this property must be specified with an empty string value.

postilion.esocketpos.JdbcUserPassword

Yes

Specifies the password for the JDBC user.

If using HSQL, and no password is provided, no password will be used.

Note
If the password is not required for authentication (for example when using Windows Authentication to connect to Microsoft SQL Server), then this property must be specified with an empty string value.

postilion.esocketpos.JdbcServerName

No

Specifies the JDBC server name.

postilion.esocketpos.JdbcServerPort

No

Specifies the JDBC server port.

Note
This property is used in conjunction with postilion.esocketpos.JdbcServerName. If this property is not specified, it will use the properties provided in the postilion.esocketpos.JdbcUrl, or default to the driver specific defaults.

postilion.esocketpos.JdbcJarLocation

No

Location of the JDBC driver library. If using HSQL DB or Microsoft SQL Server, this field is not required as eSocket.POS already provides the library.

postilion.esocketpos.database.DataFileLocation

No

This property allows setting the location where the database log and data file needs to be installed. It is not required to specify this property for the supported SQL Server versions and is only made available if a custom location must be configured, for example: postilion.esocketpos.database.DataFileLocation=C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\MSSQL.

Note
This property is only supported for SQLServer.

postilion.esocketpos.hsqldb_params

No

These values are used as the command line arguments to run the org.hsqldb.Server class, and further options are contained in the HSQLDB documentation. This is required if eSocket.POS uses HSqlDB in server-mode as an eSocket.POS Windows Service.

postilion.esocketpos.hsqldb_params = -database <db_filename>

postilion.esocketpos.install.ClassDir

No

The java classes directory on the system.

The directory where eSocket.POS classes will be copied to during the installation.

postilion.esocketpos.ConfigId

No

The terminal’s Config ID used to connect and request configuration from Config Server. This is the combination of the Retailer ID and the Config Set ID used by the terminal.

postilion.esocketpos.ConfigHttpServer

No

Specifies whether the Config Server is the TCP/IP address or hostname.

postilion.esocketpos.ConfigServerPort

No

The port used to connect to Config Server.

postilion.esocketpos.ScriptName

No

The location and name of the script file to use when contacting the HTTP server.

postilion.esocketpos.service.EspRun.StartupType

No

The startup type for the eSocket.POS service. Select from delayed, auto, or manual. It defaults to auto.

postilion.esocketpos.service.EspRun.LogLevel

No

The verbosity of events raised by the eSocket.POS service framework for the eSocket.POS service. It can be either Error, Info, Warn, or Debug. It defaults to Debug.

postilion.esocketpos.service.EspRun.LogPrefix

No

The log file name prefix. It defaults to EspRun-Service-Log.

postilion.esocketpos.service.EspRun.JvmMs

No

Initial memory pool size in MB used by the eSocket.POS service. The default configuration is set to 64 MB.

postilion.esocketpos.service.EspRun.JvmMx

No

Maximum memory pool size, in MB, used by the eSocket.POS service. The default configuration is set to 128 MB.

postilion.esocketpos.service.EspRun.JvmPath

No

The path to the JVM DLL which eSocket.POS must use. If a specific JVM must be configured, it can be set as per the following example:

%JAVA_HOME%\bin\client\jvm.dll

(This requires the JAVA_HOME to be specified on the system environment variables). It defaults to auto which will automatically locate an installed JVM on the system path.

postilion.esocketpos.service.EspRun.JvmMs

No

Initial memory pool size, in MB, used by the eSocket.POS service. The default configuration is set to 64 MB.

Front End
Property Mandatory Description

postilion.esocketpos.service.EspRun.Frontend

No

Specifies the message interface that will be used to transact in eSocket.POS. If configured, eSocket.POS will include all properties required to get started quickly. These properties are not case-sensitive. Possible values include:

Note
Skip this property if any other interface or eSocket.POS extensions will be used as a front end.

postilion.esocketpos.service.<service_name>.Parameters

No

<service_name> can be EspRun, EspConfigAgent , or EspUpgrManager.

Specifies the respective service parameters. This represents the set of arguments that the service will run with. It replaces the parameters previously set in the service configuration and should now be set in the properties file. See the eSocket.POS service configuration page for details on configuring this parameter for all 3 services.

If this parameter is not configured, the necessary configuration to run the XML interface will be used (as in the example that follows).

postilion.esocketpos.service.EspRun.Parameters=-p C:\\postilion\\esocketpos\\properties.txt -xml

Service configuration

This section describes the service configuration for Windows and Linux.

Windows
Property Mandatory Description

postilion.esocketpos.service.UpgradeManager.StartupType

No

The startup type for the eSocket.POS Upgrade Manager service. It can be delayed, auto, or manual. The default is auto.

postilion.esocketpos.service.UpgradeManager.LogLevel

No

The verbosity of events raised by the eSocket.POS service framework for the eSocket.POS Upgrade Manager service. It can be Error, Info, Warn, or Debug. The default is Debug.

postilion.esocketpos.service.UpgradeManager.LogPrefix

No

The log file name prefix. It defaults to UpgradeManager-Service-Log.

postilion.esocketpos.service.UpgradeManager.JvmMs

No

Initial memory pool size, in MB, used by the eSocket.POS Upgrade Manager service. The default configuration is set to 64 MB.

postilion.esocketpos.service.UpgradeManager.JvmMx

No

Maximum memory pool size, in MB, used by the eSocket.POS Upgrade Manager service. The default configuration is set to 128 MB.

postilion.esocketpos.service.UpgradeManager.JvmPath

No

The path to the JVM DLL which eSocket.POS must use. If a specific JVM must be configured, it can be set as per the following example:
%JAVA_HOME%\bin\client\jvm.dll

(This requires the JAVA_HOME to be specified on the system environment variables). It defaults to auto, which will automatically locate an installed JVM on the system path.

postilion.esocketpos.service.ConfigAgent.StartupType

No

The startup type for the eSocket.POS Config Agent service. It can be delayed, auto, or manual. The default is auto.

postilion.esocketpos.service.ConfigAgent.LogLevel

No

The verbosity of events raised by the eSocket.POS service framework for the eSocket.POS Config Agent service. It can be Error, Info, Warn, or Debug. It defaults to Debug.

postilion.esocketpos.service.ConfigAgent.LogPrefix

No

The log file name prefix. It defaults to ConfigAgent-Service-Log.

postilion.esocketpos.service.ConfigAgent.JvmMs

No

Initial memory pool size, in MB, used by the eSocket.POS Config Agent service. The default configuration is set to 64 MB.

postilion.esocketpos.service.ConfigAgent.JvmMx

No

Maximum memory pool size, in MB, used by the eSocket.POS Config Agent service. The default configuration is set to 128 MB.

postilion.esocketpos.service.ConfigAgent.JvmPath

No

The path to the JVM DLL which eSocket.POS Config Agent must use. If a specific JVM must be configured, it can be set as per the following example:

%JAVA_HOME%\bin\client\jvm.dll

(This requires the JAVA_HOME to be specified on the system environment variables). It defaults to auto, which will automatically locate an installed JVM on the system path.

Linux
Property Mandatory Description

postilion.esocketpos.service.JsvcPath

No

Specifies the location of the jsvc application used by the eSocket.POS services on Linux. If not set, it will use the /usr/bin/jsvc location. If the path must be set to a value other than the default, it must be set to the absolute location of the application. For example, /usr/bin//jsvc.

postilion.esocketpos.service.EspRun.Debug

No

Specifies whether debugging must be enabled for the eSocket.POS service. It is disabled by default. To disable this property, set it to true.

postilion.esocketpos.service.EspRun.JvmMs

No

Initial memory pool size, in MB, used by the eSocket.POS service. The default configuration is set to 64 MB.

postilion.esocketpos.service.EspRun.JvmMx

No

Maximum memory pool size, in MB, used by the eSocket.POS service. The default configuration is set to 128 MB.

postilion.esocketpos.service.EspRun.JvmPath

No

The path to the JVM DLL which eSocket.POS must use. If a specific JVM must be configured, it can be set as per the following example:

/usr/java/jdk1.8.0_201

If not set, it will default to the configured JAVA_HOME specified on the system environment variables.

postilion.esocketpos.service.UpgradeManager.Debug

No

Specifies whether debugging must be enabled for the eSocket.POS Upgrade Manager service. It is disabled by default. To enable this property, set it to true.

postilion.esocketpos.service.UpgradeManager.JvmMs

No

Initial memory pool size, in MB, used by the eSocket.POS Upgrade Manager service. The default configuration is set to 64 MB.

postilion.esocketpos.service.UpgradeManager.JvmMx

No

Maximum memory pool size, in MB, used by the eSocket.POS Upgrade Manager service. The default configuration is set to 128 MB.

postilion.esocketpos.service.UpgradeManager.JvmPath

No

The path to the JVM DLL which eSocket.POS must use. If a specific JVM must be configured, it can be set as per the following example:

/usr/java/jdk1.8.0_201

If not set, it will default to the configured JAVA_HOME specified on the system environment variables.

postilion.esocketpos.service.ConfigAgent.Debug

No

Specifies whether debugging must be enabled for the eSocket.POS ConfigAgent service. It is disabled by default. To disable this property, set it to true.

postilion.esocketpos.service.ConfigAgent.JvmMs

No

Initial memory pool size, in MB, used by the eSocket.POS Config Agent service. The default configuration is set to 64 MB.

postilion.esocketpos.service.ConfigAgent.JvmMx

No

Maximum memory pool size, in MB, used by the eSocket.POS Config Agent service. The default configuration is set to 128 MB.

postilion.esocketpos.service.ConfigAgent.JvmPath

No

The path to the JVM DLL which eSocket.POS Config Agent must use. If a specific JVM must be configured, it can be set as per the following example:

/usr/java/jdk1.8.0_201

If not set, it will default to the configured JAVA_HOME specified on the system environment variables.

postilion.esocketpos.install.InstallPlugins

No

This Boolean value indicates whether the base extensions for eSocket.POS that are placed in the jars folder of the installation JAR must be applied after the installation of eSocket.POS. By default, this setting is enabled for installs and can be turned off by setting it to false.

postilion.esocketpos.install.FailPluginFailInstall

No

This Boolean value indicates whether the entire installation is stopped and rolled back if the installation of one of the JAR-base extensions fails. This only applies when other extensions or plugins are being installed together with eSocket.POS. That is, postilion.esocketpos.install.InstallPlugins is set to true in the install.properties file. This setting is disabled by default, meaning that base extension failures do not stop the eSocket.POS installation. It can be turned on by setting this property to the value of true.

postilion.esocketpos.install.InstallPatches

No

This Boolean value indicates whether patches that are placed in the patches folder of the installation JAR must be applied after the installation of eSocket.POS. By default, this setting is enabled for installs and can be turned off setting by it to false.

postilion.esocketpos.install.FailPatchFailInstall

No

This Boolean value indicates whether the entire installation is stopped and rolled back if the installation of one of the JAR-base extensions fails. This only applies when other extensions or plugins are being installed together with eSocket.POS. That is, postilion.esocketpos.install.InstallPlugins is set to true in the install.properties file. This setting is disabled by default, meaning that base extension failures do not stop the eSocket.POS installation. It can be turned on by setting this property to the value of true.

postilion.esocketpos.install.StartEspService

No

This setting indicates whether the eSocket.POS service must be started after the installation. By default, this setting is enabled for installs and can be turned off by setting it to false.

postilion.esocketpos.install.UpgradeMgrMaxWaitTime

No

This property allows configuring the maximum waiting time (in minutes) that the installation must wait while Upgrade Manager applies patches from the incoming directory. If not configured, by default it is set to '3' which will result in a 3-minute wait period.

Support is provided for Microsoft SQL Server installations of eSocket.POS using a JDBC data source configured for Windows authentication or SQL authentication.

3.3.4. eSocket.POS installation

The following steps are required to install eSocket.POS in an environment:

  • Ensure the system requirements are met and all the pre-installation checks are performed.

  • Extract the default manifest file from the installation JAR by running the command:

    java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar -e

    More details can be found on the manifest page.

  • Update the extracted install.properties file in the current working directory with any configuration updates if required. The installation will use the updated configuration when the next step is performed.

  • Update the installation package with keystore/truststore files, if necessary. See the Adding keystore/trustore to installation package section.

  • Once ready, eSocket.POS can be installed on the system by running this command:

    java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar

    where XXXXXX is the build number of the eSocket.POS version being installed.

If the install.properties file inside the jar has already been updated with values to be used for the installation, there is no need to extract it again. It can be used for the installation by adding the option -d in the command:

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar -d

or

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar --default

where XXXXXX is the build number of the eSocket.POS version being installed.

Installation Process

By default, eSocket.POS will attempt to install the database during the installation. Run the install command with -s option or --skip-database to skip the database step and install it manually using the database installer afterwards.

This command will ensure eSocket.POS is installed in the environment and will configure what is needed to run eSocket.POS:

  • The installer performs pre-installation checks ensure that the system is ready and is meeting the requirements for eSocket.POS to be installed.

  • All necessary directories for eSocket.POS are created.

  • The eSocket.POS database is created, along with all the tables, if using HSQL standalone mode or Microsoft SQL Server.

  • Libraries and other third-party software that eSocket.POS ships are copied to the environment.

  • DTD files required for XML definitions are copied to the environment.

  • All the OS-specific steps will be taken by the installer during the installation. Registry entries and services will be created during the installation.

If something goes wrong during the installation, installation will be rolled back and an installation log file will provide more verbose details and the installation utility will exit.

Installation sequence

The following installation steps are performed to complete the installation:

  1. Installation of Java classes and a Java classpath file

  2. Copying of third-party libraries and dependencies shipped with the package

  3. Installation of certain DTD files required for XML fields, messages, and file formats.

  4. Installation of the database. The eSocket.POS database can only be installed automatically when using Microsoft SQL Server and/or HSQL Database standalone mode. For a clean install, the database created is esocketpos. For a side-by-side upgrade, to avoid collision with the existing database, the default database name used is esocketpos3.

  5. Creation of the database tables required for eSocket.POS. No data is inserted into these tables during the installation.

  6. Installation of the eSocket.POS service. Only the main eSocket.POS service is installed automatically during the installation. It has been improved to include features previously relayed to other services. Scripts are generated to manage the services.

  7. Installation of a default properties file based on the installation values.

  8. Creation of eSocket.POS uninstall scripts. The system dependent script generated here can be used to uninstall eSocket.POS.

  9. Copying of keystore and/or trust stores from the installation package (if provided in the package).

  10. Installation of extensions and plugins, which are distributed as part of the packaged JAR installation.

  11. Installation of patches, which are distributed as part of the packaged JAR installation.

  12. Downloading of configuration from the Terminal Management System if configured to do so during the installation.

  13. Providing the application’s Version utility

  14. Starting the eSocket.POS service if enabled, putting the terminal in a state ready to be initialized.

3.3.5. eSocket.POS installation utility - Upgrade

eSocket.POS can be upgraded from version 2.8 to 3.0. Because of the major differences between the two versions, an in-place upgrade is not supported. eSocket.POS offers a side-by-side upgrade from the previous version to ensure the old version is left unmodified when eSocket.POS 3 is installed.

To install eSocket.POS 3 side-by-side with an older version, the properties listed in the table below must be updated to ensure there is no collision between the existing eSocket.POS installation with the new eSocket.POS installation, such as specifying the existing eSocket.POS install location and service names of the eSocket.POS 3 services.

After eSocket.POS 3 is upgraded, the transactional tables and state data will be migrated when the terminal initializes for the first time. This process will occur per terminal, and will fail the terminal initialization if the data migration could not be completed. This is to ensure that the eSocket.POS 3 terminal can only perform transactions when the data was successfuly migrated, and if decided to rollback to eSocket.POS 2, there will be no transactions present in eSocket.POS 3 avoiding maintaining two different sets of transactions in the database.

The table describes the properties that can be configured in the install manifest file (install.properties). Those properties are case-insensitive. Configure the new eSocket.POS installation for the relevant stores and terminals in ConfigServer and deliver the configuration to the eSocket.POS terminal/server using the new eSocket.POS Config Agent.

Property Mandatory Description

postilion.esocketpos.upgrade.CurrentEspLocation

No

Specifies the location of the existing eSocket.POS installation. If not configured, eSocket.POS will attempt to locate the current installation based on the value of the POSTILIONDIR variable.

postilion.esocketpos.service.EspRun.ServiceName

No

Specifies the name for the eSocket.POS service on Windows. If this property is not configured, eSocket.POS service will be called EspRunv3 to prevent collision with EspRun used in the previous version.

postilion.esocketpos.service.EspRun.ServiceDisplayName

No

Specifies the name displayed for the eSocket.POS service on Windows. If this property is not configured, eSocket.POS service name displayed will be eSocket.POS v3 to prevent collision with eSocket.POS used in the previous version.

postilion.esocketpos.service.UpgradeManager.ServiceName

No

Specifies the name for the eSocket.POS Upgrade Manager service on Windows. If this property is not configured, eSocket.POS Upgrade Manager service will be called EspUpgrManagerv3 to prevent collision with EspUpgrManager used in the previous version.

postilion.esocketpos.service.UpgradeManager.ServiceDisplayName

No

Specifies the name displayed for the eSocket.POS Upgrade Manager service on Windows. If this property is not configured, eSocket.POS Upgrade Manager service displayed name will be eSocket.POS Upgrade Manager v3 to prevent collision with eSocket.POS Upgrade Manager used in the previous version.

postilion.esocketpos.service.ConfigAgent.ServiceName

No

Specifies the name for the eSocket.POS Config Agent service on Windows. If this property is not configured, eSocket.POS Config Agent service will be called EspConfigAgentv3 to prevent collision with EspConfigAgent used in the previous version.

postilion.esocketpos.service.ConfigAgent.ServiceDisplayName

No

Specifies the name displayed for the eSocket.POS Config Agent service on Windows. If this property is not configured, eSocket.POS Config Agent service displayed name will be eSocket.POS Config Agent v3 to prevent collision with eSocket.POS Config Agent used in the previous version.

postilion.esocketpos.database.name

Yes

Specifies the name that should be used for the eSocket.POS database to prevent collision with the previous eSocket.POS installation. This must be set for upgrades.

The upgrade command

To upgrade eSocket.POS directly in the terminal using the command line utility, run the following command:

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar --upgrade

or

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar -up

where XXXXXX is the eSocket.POS build number.

Once installed, configure the new eSocket.POS installation for the relevant stores and terminals in ConfigServer and deliver the configuration to the eSocket.POS terminal/server using the new eSocket.POS Config Agent.

For information on using the ConfigServer remote software deployment mechanism, refer to the eSocket.POS Configuration Server User Guide. For information on the eSocket.POS Upgrade Manager, refer to the Upgrade Manager - overview topic in this guide.

Using existing SSL config

The new eSocket.POS installation JAR can automatically copy the keystore and truststore, together with their properties, from the working eSocket.POS installation to the newly installed eSocket.POS instance.

To achieve this, the following options must be used in the command running the JAR:

  • -cks or --copy-keystore - to copy the keystore and all its properties from the existing eSocket.POS installation

  • -cts or --copy-truststore - to copy the SSL truststore and all its properties from the existing eSocket.POS installation.

For example:

java -jar setup_eSocket.POS_v3.0_buildXXXXXX_r4_3_install.jar -up -cks -cts

or

java -jar setup_eSocket.POS_v3.0_buildXXXXXX_r4_3_install.jar --upgrade --copy-keystore --copy-truststore

Note
This does not apply to auxiliary keystore entries. If auxiliary keystores are used, they should be copied over manually. Their properties file entries should be added in the install.properties and their files copied inside the installation JAR.
Using the same Config ID

This is used to specify the Configuration ID that the terminal will use. The value populated here will be used to download configuration from the Terminal Management System or Config Server, and then be populated in the default properties file generated after the installation for the property postilion.esocketpos.ConfigId.

Example:

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar -up -d --config-id Retailer_00000000

During a side-by-side upgrade, the value of this parameter can be copied from the current eSocket.POS properties by specifying the property key in a variable form. That is, ${property_key}. Note that the config-id value must be explicitly specified when upgrading from the command-line and not through a remote deployment using the legacy eSocket.POS Upgrade Manager.

Example:

'java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar -up -d --config-id ${postilion.esocketpos.ConfigId}`
Path to the current Properties file

This is to specify the location of the current properties file. It can be used during an upgrade to specify the location of the current installation properties file, or during the uninstallation to specify the location of the installation properties file.

In both cases, the properties file is used to locate an existing eSocket.POS installation. It does not drive the new installation. That is done by the install.properties file.

Example:

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar -up -d --properties-file C:\Postilion\eSocket.POS\properties.txt

During a side-by-side upgrade, the value of this parameter can be copied from the current eSocket.POS properties by specifying the property key in a variable form. That is, ${property_key}. Note that the properties-file value must be explicitly specified when upgrading from the command-line and not through a remote deployment using the legacy eSocket.POS Upgrade Manager.

Example:

java -jar setup_eSocket.POS_v3.0_build_XXXXXX_r4.3_install.jar -up -d --properties-file ${postilion.esocketpos.PropertiesFilePath}

Remote upgrades

For remote upgrades, the upgrade command is sent down to the terminal as an Upgrade Action and will be run by the existing eSocket.POS Upgrade Manager.

Upgrade Actions

Upgrade actions are a set of key = values properties defined in the manifest file, located at META-INF\esp_manifest.txt, inside the new eSocket.POS installation JAR.

Those actions are run by the existing eSocket.POS Upgrade Manager to facilitate a remote side-by-side upgrade of eSocket.POS. Upgrade actions are run in order by the number appended to it in the manifest.

A few upgrade actions can be defined in the same manifest file and numbered from 1…​ to n. The below entries forms part of the esp_manifest and represent the main action that initiates a side-by-side upgrade in the terminal. The following properties must be defined for each action to be valid:

install.majorupgrade.action.type.{i}

This is the type of action that must be run. The following types of actions are supported:

  • OsCommand: Here, a command will be run on the operating system. The command must be specified as part of the install.majorupgrade.action.command property.

install.majorupgrade.action.command.{i}

The command that must be run on the terminal operating system.

install.majorupgrade.action.failure_action.{i}

This is the action that must be taken should the command fail. The following values are supported:

  • FAIL: The upgrade will stop and be considered as failed.

  • IGNORE: The failure will be ignored, and the next action will be run.

install.majorupgrade.action.description.{i}

The description of the action being run.

An example of the default upgrade action defined inside META-INF\esp_manifest.txt follows:

install.majorupgrade.action.type.1 = OsCommand
install.majorupgrade.action.command.1 = java -jar setup_eSocket.POS_v3.0_buildXXXXXX_r4.3_install.jar -up -d --config-id ${postilion.esocketpos.ConfigId} --properties-file ${postilion.esocketpos.PropertiesFilePath}
install.majorupgrade.action.failure_action.1 = FAIL
install.majorupgrade.action.description.1 = eSocket.POS Major Upgrade
Remote upgrade steps

To upgrade eSocket.POS remotely:

Prerequisites

For Windows environments, ensure that User Account Control(UAC) is turned off for Windows 10 machines before performing the upgrade remotely.

  1. Customize the installation to match your environment, by updating the installation JAR with the required applications and configuration.

    1. Ensure all required plugins and patches are copied inside the JAR.

    2. Update the install.properties file to match the desired configuration.

    3. Update the esp_manifest.txt file to ensure the upgrade command includes all the expected options.

  2. Deliver the new eSocket.POS setup JAR package to the existing eSocket.POS Config Agent incoming directory. To do this, use the ConfigServer remote software deployment mechanism, or a third-party file delivery tool. The incoming directory is the path specified for the postilion.esocketpos.IncomingConfigPath property in the eSocket.POS properties file.

    After the setup JAR file is delivered, the existing eSocket.POS Upgrade Manager automatically installs the new eSocket.POS at a separate directory the next time it is run. This typically happens when the eSocket.POS terminal or server starts.

  3. Configure the new eSocket.POS installation for the relevant stores and terminals in ConfigServer and deliver the configuration to the eSocket.POS terminal/server using the new eSocket.POS Config Agent.

Remote uninstallation of thr eSocket.POS old version

After a side-by-side upgrade of eSocket.POS, both eSocket.POS 2.8 and 3.0 are installed on the system. When eSocket.POS 3.0 is installed and running successfully, eSocket.POS 2.8 must be removed.

To remove eSocket.POS 2.8, you can configure the postilion.esocketpos.legacy.Action property remotely to disable or uninstall the previous version of eSocket.POS. Only do this when eSocket.POS 3.0 is working as expected, because once eSocket.POS 2.8 is uninstalled there is no way to return to it.

Note
After the upgrade, the outcome of the action taken on the previous version will be stored in the log files.

3.3.6. Side by Side eSocket.POS upgrade - Best practices

Having 2 eSocket.POS versions installed on the same system can create challenges, and if the transition is not managed properly, can lead to confusion and chaos.

To ensure a smooth upgrade from eSocket.POS 2 to eSocket.POS 3 without negatively impacting the use of eSocket.POS, consider the following best practices:

  • Prepare your infrastructure: The new eSocket.POS version requires a more recent Java version (1.8 or later) and more recent database platforms (it does not work with older SQL server), to highlight a few examples. You must ensure that your current setup meets the system requirements for the eSocket.POS version you’re upgrading to.

  • Make an upgrade plan: Extensions or customization applications used with the current eSocket.POS version must also be updated for use with the new eSocket.POS version. You must assess if they will work as is, or if configuration changes are required on the extensions or customization applications that work with eSocket.POS.

  • Things to keep the same: The Configuration ID for the terminal and port numbers used for eSocket.POS must be the same across eSocket.POS versions to limit the changes on extensions or customization applications.

  • Leverage the new installation JAR: All eSocket.POS plug-ins, extensions, and customizations can be installed with eSocket.POS. You do not have to install any of those individually; all compatible applications should be part of the JAR which, makes it easier to install.

  • Use different directories: Although the new eSocket.POS is installed by default in a separate directory, it still allows you to configure where the classes will be copied to. Either leave this unchanged so that they are copied inside the new installation directory or ensure the classes' destination configured does not conflict with the existing eSocket.POS directory.

  • Undertake configuration:

    1. Carefully read through the newly added properties, especially the ones used during the installation, to ensure the new eSocket.POS is configured correctly.

    2. Carefully configure services parameters that are now part of the properties file.

    3. Avoid configuring parameters, that are different between terminals, in install.properties to avoid sending a different installation JAR per terminal.

  • Run a trial upgrade: The best way to determine if any issues will appear during the upgrade is to run a trial in a test environment similar to your production environment. This will help detect any conflict or collision that might occur if the upgrade is performed. Allow a considerable time for this step and engage with your primary support provider should any issues arise.

  • Upgrade a staging site: Once the trial upgrade is successful and all potential issues resolved, a single or small set of terminals can be upgraded first, followed by a gradual upgrade of more terminals.

  • When to rollback: If you cannot transact after upgrading to the new version, ACI recommends that you collect the traces/logs for investigation and then immediately roll back to the previous version.

  • Too late to rollback: If issues arise after the terminal has already been transacting successfully with the new eSocket.POS version, avoid rolling back to the previous version. Rather contact your primary support provider to have it resolved.

3.3.7. Uninstalling eSocket.POS

The following steps are required to uninstall eSocket.POS in an environment:

  1. Use an Operating System user that has the correct permissions to modify the eSocket.POS installation folder and run the uninstall.cmd (on Windows) or uninstall.sh (on Linux) from the eSocket.POS\uninstall directory of the installation.

  2. Delete the eSocket.POS\uninstall folder manually after the uninstall completes.

Note
If eSocket.POS was upgraded from a previous version, and the previous version is still available in the system, it should not be uninstalled using the command above. It should instead be rolled back using the rollback JAR that ships with eSocket.POS.

3.3.8. eSocket.POS installation utility - Rollback

eSocket.POS can be rolled back to the previous version after a major side-by-side upgrade. This is achieved by the rollback JAR that ships with eSocket.POS. The rollback is only possible when eSocket.POS was upgraded using Upgrade Manager. If eSocket.POS was installed or upgraded manually, rolling back using this rollback JAR will not be allowed.

The rollback JAR

The eSocket.POS 3.0 major side-by-side rollback JAR is lightweight and has the following content:

  • META-INF directory:
    This directory contains various manifest files used mainly during the rollback.

  • postilion directory:
    This directory contains the classes that will drive the rollback on the new eSocket.POS side.

  • bootstrap.zip file:
    This is a zip file with all classes needed by the Upgrade Manager to achieve the rollback.

The rollback command

The roll back is processed by Upgrade Manager as an Upgrade Action. The action command is defined in the manifest inside the META-INF\esp_manifest.txt JAR, which is inside the rollback JAR.

The command used to roll back to the previous eSocket.POS version is of the form :

java -jar rollback_eSocket.POS_v3.0_build_XXXXXX_r4.3.jar --rollback

or

java -jar rollback_eSocket.POS_v3.0_build_XXXXXX_r4.3.jar -r

where XXXXXX is the eSocket.POS build number.

Remote rollback

For remote rollback, the upgrade command is sent down to the terminal as an Upgrade Action and will be run by the previously installed eSocket.POS Upgrade Manager to remove eSocket.POS 3 and enable the previous version of eSocket.POS.

Remote rollback steps

To upgrade eSocket.POS remotely :

  1. Customize the rollback JAR command if needed. Confirm that the rollback command in the esp_manifest.txt manifest file includes all the expected options.

  2. Deliver the rollback JAR to the existing eSocket.POS incoming directory.

  3. The next time eSocket.POS is run, it will automatically uninstall the current eSocket.POS and restore the previous major version that was backed up during the side-by-side upgrade.

  4. The configuration will be in the same state it was before the major upgrade. If any changes were made in the configuration while using the newer version, the configuration should be downloaded to the terminal (that is now rolled back) as soon as the older version of eSocket.POS is restored.

Note

To get eSocket.POS to automatically process the rollback JAR, the postilion.esocketpos.upgrade.AllowRollbackAsUpgrade property is set to true. If this property is set remotely, it will take effect the next time the service is started.

Remote rollback processing

During a remote rollback, both the previous version (the version being rolled back to) and the current version (the version being rolled back from) will perform some part of the processing.

The current version will perform a few checks to ensure that it can be rolled back to the previous version. After rolling back the upgrade, the previous version of eSocket.POS is re-enabled.

When activating the previous eSocket.POS services in Windows, the startup mode used by the eSocket.POS 2 services will be updated to match the configured startup types for the services which were configured in the properties file for eSocket.POS 3, for example, if the postilion.esocketpos.service.<servicename>.StartupType property was set to auto, then the eSocket.POS 2 service will be configured for auto start when Windows starts-up.

Once the rollback is triggered, the previous version will uninstall the current version completely and update the registry to reset the active eSocket.POS version.

Note

The postilion.esocketpos.upgrade.AllowRollbackAsUpgrade property mentioned earlier must be set to true in both the previous and the current version of eSocket.POS for the rollback to apply successfully.

3.4. Manual install or upgrade

3.4.1. Manual installation - Java classes

Overview

If the eSocket.POS applications must be run as Windows services, create the required services, if they do not already exist. Prior to an upgrade, it might be necessary to upgrade the Java virtual machine (JVM) in use. If so, then after upgrading eSocket.POS, update pre-existing services to specify the path to the DLL of the new JVM.

Java classes and jar files

After the .tgz file is extracted, the eSocket.POS classes and jar files are found in the eSocket.POS/classes directory. All eSocket.POS classes fall in the postilion.esocketpos package and are therefore contained in the eSocket.POS/classes/postilion/esocketpos directory.

The following jar files are also included in the eSocket.POS/classes directory.

  • esocket-tools.jar

  • bcprov-jdk15.jar and bcpkix-jdk15.jar

  • xercesImpl.jar and xml-apis.jar in the endorsed subdirectory

  • sqljdbc.jar

The classes and jar files must be specified in the classpath for the Java VM when running the eSocket.POS application. The jar files must appear after the location of the eSocket.POS Java class files in the classpath.

Other files

Certain DTD files required for XML fields, messages, and file formats are also included in the .tgz file, and are extracted to the eSocket.POS/xml directory.

3.4.2. Manual installation - database

Note
  • The installation of the database program itself, and creation of an eSocket.POS database (if the database program supports multiple databases), is beyond the scope of this user guide. Contact your primary support provider for more information.

  • When installing or upgrading the database, use the DatabaseInstaller Java classes for the new eSocket.POS installation, by specifying the eSocket.POS 3.0 classes on the classpath and not that of the previous eSocket.POS version.

Installation

An eSocket.POS database installer script is provided to create the tables required by eSocket.POS. After the database is created, the database installer must be run as follows:

<java> <classpath> postilion.esocketpos.util.DatabaseInstaller<jdbc_driver> <jdbc_url> <db_user> <user_password> <log_filename> <text_datatype> <db_option> <log_mode> [named parameters]

Where:

  • <java> = Command to run the Java VM

  • <classpath> = Classpath including eSocket.POS classes and jar files

  • <jdbc_driver> = Fully qualified JDBC driver name

  • <jdbc_url> = URL of JDBC data source

  • <db_user> = Name of database user login

  • <password> = Password for user login

  • <log_filename> = Path and filename for log file

  • <text_datatype> = TEXT or equivalent data type

  • <db_option> = CREATE or DROP

  • <log_mode> = Optional parameter set to V for verbose logging

  • [named parameters] = Zero or more named parameters

    The named parameters must be listed in the following form:

    <parameter one name>:<parameter one value> <parameter two name>:<parameter two value>

    The following named parameters are supported:

    • -jdbc_server_name = Optional parameter to set the JDBC server name

    • -jdbc_server_port = Optional parameter to set the JDBC server port

    Example:

    • -jdbc_server_name:MyServerName' (sets the JDBC server name to MyServerName)

    • -jdbc_server_name:NewServerName -jdbc_server_port:12345' (sets the JDBC server name to 'NewServerName' and the JDBC server port to '12345')

Upgrade

The same database installer script described in the "Installation" section is used to upgrade the eSocket.POS database. It must be run the same, but with the following option set:

<db_option> = Path and filename of the upgrade script to apply. For example, esocket_upgrade_minor.sql

This upgrades the database table and field definitions to match those of the new version of eSocket.POS, and maintains the existing data in the database.

For a major upgrade, the major upgrade script must be run first, followed by the minor upgrade script.

3.4.3. Manual installation - documentation

The following documentation forms part of the eSocket.POS application:

  • eSocket.POS User Guide

  • eSocket.POS Developer Guide

  • eSocket.POS Developer Guide - Java API Reference Guide

  • eSocket.POS Release Notes

  • README.TXT

Documentation is contained in the .tgz file. After extracting this file, documentation is found in the eSocket.POS/doc directory. Except the README.TXT file, these are installed in the form of HTML files and can be read on any platform using a web browser.

3.5. Remote upgrades

3.5.1. Remote upgrades

Remote upgrades are enabled by configuring and running the Upgrade Manager during the POS or Store Server’s boot process.

3.6. Installation - Realtime

The installation of an upstream Realtime system and related applications, such as the PosConnect interface, is beyond the scope of this document. See the relevant Realtime documentation.

Note
Realtime is not usually installed on the same machine as eSocket.POS, although it is possible to do this. Typically, eSocket.POS is installed on a POS terminal or store server, independent of the installation of the remote Realtime system.

4. Configuration

4.1. Configuration Overview

eSocket.POS receives configuration information from multiple sources, described below. eSocket.POS can verify the integrity and authenticity of distribution files that it receives packaged in signed JARs.

4.1.1. eSocket.POS properties

eSocket.POS properties are the first source of configuration information accessed by eSocket.POS when it starts. These properties include initial configuration such as startup information, runtime parameters, and remotely-configured properties.

Most eSocket.POS properties can be configured remotely, typically using the Configuration Server, after which they are loaded by means of the terminal configuration file.

4.1.2. Message Front-end parameters

Several runtime parameters are also passed to the eSocket.POS Message Front-end.

4.1.3. SQL database

Most eSocket.POS configuration information is stored in a database supporting ANSI SQL queries via JDBC. The layout of tables and columns in the eSocket.POS database is described in detail in the Table Definitions section. Details on configuring Application classes are given in this user guide, as are specific devices and Pipeline Components. Card information and other parameters are also stored in the database.

4.1.4. Configuration Agent

Configuration information is transferred - as full or partial loads - into the eSocket.POS database by means of the Configuration Agent. These files are typically generated by the ConfigServer (though can be generated manually), and then either downloaded by the Configuration Agent via HTTP, or transferred via a third-party mechanism into a directory where the Configuration Agent polls for incoming files. This behavior depends on the values set in the Configuration Agent properties.

Note
Refer to eSocket.POS Configuration Server User Guide for details of this application.

4.1.5. Upgrade Manager

Remote upgrades are enabled by configuring and running the Upgrade Manager during the POS or Store Server’s boot process. See the Upgrade Manager - overview topic for a detailed description and for configuration instructions.

4.1.6. PosConnect and the payments system

eSocket.POS connects to PosConnect and the payments system. Some details on the configuration of PosConnect and the payments system are given here, but most are beyond the scope of this document. See the relevant payments system documentation for details.

4.2. eSocket.POS properties

At startup, eSocket.POS reads eSocket.POS properties before accessing a much larger set of eSocket.POS configuration information (including the names of other classes and parameters) from the eSocket.POS database.

4.2.1. Remotely-configured properties

eSocket.POS properties that are configured remotely, typically via the Configuration Server, are stored in a table in the eSocket.POS database. eSocket.POS gives preference to these over the properties in the eSocket.POS properties file. Furthermore, if eSocket.POS should find a blank value for a particular property in this table, it will ignore that property, regardless of how it is configured in the eSocket.POS properties file.

Not all eSocket.POS properties are remotely configurable. Refer to the tables below.

Note
For the remotely-configured properties functionality to work correctly, the home directory property (postilion.esocketpos.install.HomeDir) must be configured for all services. Refer to the sample configuration below. The user must also ensure that eSocket.POS has write access to the home directory.

4.2.2. eSocket.POS properties file

The eSocket.POS properties file is a plain-text file containing initial configuration information for a specific instance of eSocket.POS.

The properties are read from the file at startup. The file consists of property/value pairs in the following format:

<property_name1> = <value1>

4.2.3. eSocket.POS properties placeholders

The user can configure eSocket.POS properties with placeholders. Placeholders allow the user to append a unique value specific to the service using the property, or to the physical machine running eSocket.POS, while using a common properties file across all services and machines. When the properties are loaded, eSocket.POS will replace the placeholders with the appropriate values.

eSocket.POS supports two placeholders:

Placeholder Description

${eSPHostName}

The name of the machine on which eSocket.POS is installed.

${eSPService}

A shortened name of the service that loaded the properties. These are listed as follows:

  • eSocket.POS - replaced with esocketpos

  • eSocket.POS Config Agent - replaced with esp_config_agent

  • eSocket.POS Upgrade Manager - replaced with esp_upgrade_manager

Examples

To illustrate the usage of placeholders, two properties are configured with the ${eSPService} placeholder.

  1. postilion.esocketpos.TracePath = C:\\postilion\\ ${eSPService} \\Trace

  2. log4j.appender.A1.File = C:\\postilion\\logfiles\\ ${eSPService} _output.log

The first property will write the trace output for each service into its own directory. The second property will write the log file output of each service to the same directory, but each to its own file. When these properties are loaded by each service, the resulting values for these properties will be as follows:

Service Property value

eSocket.POS

  1. postilion.esocketpos.TracePath = C:\\postilion\\ esocketpos \\Trace

  2. log4j.appender.A1.File = C:\\postilion\\logfiles\\ esocketpos _output.log

eSocket.POS Config Agent

  1. postilion.esocketpos.TracePath = C:\\postilion\\ esp_config_agent \\Trace

  2. log4j.appender.A1.File = C:\\postilion\\logfiles\\ esp_config_agent _output.log

eSocket.POS Upgrade Manager

  1. postilion.esocketpos.TracePath = C:\\postilion\\ esp_upgrade_manager \\Trace

  2. log4j.appender.A1.File = C:\\postilion\\logfiles\\ esp_upgrade_manager _output.log

4.2.4. eSocket.POS properties

A list of configurable properties for eSocket.POS is categorized and described below.

Note
Properties that are not remotely configurable are marked with an asterisk (*).
Tracing
Property Description

postilion.esocketpos.TracePath

Specifies the path where trace files are stored (not required for Configuration Agent properties).

postilion.esocketpos.Trace

Specifies the trace behavior at startup as follows:

  • ON or <entity> <entity>…​ <entity> ON turns tracing on (globally or for the specified entities) when eSocket.POS starts.

  • CLEAR or <entity> <entity>…​ <entity> CLEAR turns tracing on and clears the trace file.

See tracing settings for further details.

postilion.esocketpos.TraceStyle

Specifies the trace style at startup as follows:

  • NORMAL

  • CASCADE

If this property is not specified, then the default is CASCADE.

postilion.esocketpos.TraceNrLines

Specifies the maximum number of lines that the detailed trace file may contain.

If this property is not specified, the default is 100,000.

postilion.esocketpos.TraceNrFiles

Specifies the maximum number of eSocket.POS trace files that the trace viewer can contain.

If this property is not specified, then the default is 5.

postilion.esocketpos.DesensitizeXMLData

If set to false then sensitive field data (for example, PAN and Track 2) is unmasked in the XML Interface message traces. If set to true then sensitive fields are masked.

If this property is not specified, then the default is true.

Example: postilion.esocketpos.DesensitizeXMLData = false

postilion.esocketpos.TraceConnectionEvents

If set to true then eSocket.POS will trace the TCP/IP connectivity for the XML Interface to the Global eSocket.POS trace.

If this property is not specified, then the default is true .

Example: postilion.esocketpos.TraceConnectionEvents = false

Commands
Property Description

postilion.esocketpos.CommandPort

This is the port that eSocket.POS listens on for TCP\UDP commands.

Note
Not required for Configuration Agent properties.
Warning
Configuring this property will prohibit the PCI-DSS compliance of the system.
Database
Property Description

postilion.esocketpos.JdbcDriver

Specifies the JDBC driver class.

*This property cannot be configured remotely.

postilion.esocketpos.JdbcUrl

Specifies the URL for the JDBC connection.

Note
  • If either of postilion.esocketpos.JdbcServerName or postilion.esocketpos.JdbcServerPort properties are used, the server name and port should omitted from the URL.

  • For security purposes, do not configure the JDBC username or the JDBC password as part of this property, use their respective configuration properties instead.

*This property cannot be configured remotely.

postilion.esocketpos.JdbcUser

Specifies the JDBC username.

Note
If Windows Authentication is used to connect to Microsoft SQL Server, then this property must be specified with an empty string value.

*This property cannot be configured remotely.

postilion.esocketpos.JdbcServerName

(Optional) Specifies the JDBC server name.

Note
This property is used in conjunction with postilion.esocketpos.JdbcServerPort. If this property is not specified, it will use the properties provided in the postilion.esocketpos.JdbcUrl or default to the driver specific defaults.

postilion.esocketpos.JdbcServerPort

(Optional) Specifies the JDBC server port.

Note
This property is used in conjunction with postilion.esocketpos.JdbcServerName. If this property is not specified, it will use the properties provided in the postilion.esocketpos.JdbcUrl or default to the driver specific defaults.

postilion.esocketpos.JdbcUserPassword

Specifies the password for the JDBC user.

Note
If Windows Authentication is used to connect to Microsoft SQL Server, then this property must be specified with an empty string value.

*This property cannot be configured remotely.

postilion.esocketpos.JdbcMaxConnections

The maximum number of allowed simultaneous JDBC connections.

Note
If this property is used then it must be specified with the same value for all eSocket.POS terminals that run from within the same JVM.

*This property cannot be configured remotely.

postilion.esocketpos.JdbcRefreshInterval

The period (in milliseconds) for which a JDBC connection is allowed to idle before it expires. Setting this property to zero results in connections never expiring.

Note
If this property is used then it must be specified with the same value for all eSocket.POS terminals that run from within the same JVM.

*This property cannot be configured remotely.

Services
Property Description

postilion.esocketpos.restart.Services

Specifies a list of services that must be restarted when eSocket.POS receives a RESTART command on a Windows platform. The list is in the order in which services must be started. The names of the services must be given as specified in the service registry keys.

For example, to restart the default list of services this property must be specified as: EspUpgrManager EspConfigAgent EspRun

Note
This is different from the service display names.

postilion.esocketpos.service.<service_name>.Parameters

<service_name> can be EspRun, EspConfigAgent, or EspUpgrManager.

Specifies the respective service parameters. This represents the set of arguments with which the service will run. It replaces the parameters previously set in the service configuration; it should now be set in the properties file. See eSocket.POS service configuration page for more details on how to configure this parameter for all three services.

If this parameter is not configured, the necessary configuration to run the XML interface will be used (as in the example below).

Example: postilion.esocketpos.service.EspRun.Parameters=-p C:\\postilion\\esocketpos\\properties.txt -xml

postilion.esocketpos.restart.Custom

Specifies a custom restart script that must be used to restart eSocket.POS when receiving a RESTART command. This is used on non-Windows platforms.

Security
Property Description

postilion.esocketpos.SaveTrack2

Specifies whether track 2 data must be saved in the esp_trans table.

  • 1 - Track 2 data is saved in the esp_trans table.

Note
To comply with Visa Cardholder Information Security Program (CISP) requirements, by default Track 2 data is not saved.
Warning
Changing this property from default will prohibit the PCI-DSS compliance of the system.

postilion.esocketpos.StoreSensitiveDataAsEncrypted

Specifies whether sensitive data such as PAN, Track2 Data, Account Id1, Account Id2, and Payer Account Id must be saved in the esp_trans table in encrypted format.

  • TRUE - Sensitive data is saved in encrypted format in the esp_trans table.

Note
To comply with General Data Protection Regulation (GDPR) requirements, this property must be turned ON, in other words, set to TRUE. This property is turned OFF by default.

postilion.esocketpos.install.KeyStore

This is the path of the key store file used by the Certificate Manager component.

Note
The default is <eSocket.POS directory>\keystore\esp.ks.

*This property cannot be configured remotely.

postilion.esocketpos.JceKeyStoreType

This is the JCE key store type to use for the key store. The possible values supported are:

  • BKS - the Bouncy Castle Provider key store format (default)

  • IAIKKeyStore - The IAIK provider

*This property cannot be configured remotely.

postilion.esocketpos.JceProvider

The fully qualified class name of the JCE provider to use for RSA encryption.

  • The default is the Bouncy Castle Provider.

*This property cannot be configured remotely.

postilion.esocketpos.JceRsaAlgorithmSpecification

The JCEalgorithm specification to use for RSA encryption. The possible values supported are:

  • RSA/NONE/OAEPWithSHA1AndMGF1Padding - If an alternative is used, it must be an equivalent.

  • RSA/ECB/OAEPPadding - This is the equivalent algorithm specification for the IAIK provider.

postilion.esocketpos.ssl.WarnOldLocalCerts

The number of days prior to the expiration of a local SSL certificate for which eSocket.POS must consider the certificate as being old. Each time eSocket.POS is re-started, it logs a warning for each old certificate the first time that it selects the certificate for authenticating the local side of an SSL connection.

  • The default is 30 days.

postilion.esocketpos.MaxCertificateExchangeDays

The maximum number of days allowed between successful certificate exchanges. If this number is exceeded, eSocket.POS logs a warning whenever it restarts.

  • The default is 5 days.

  • If a value of 0 is specified, then the number of days since the last certificate exchange is never checked.

postilion.esocketpos.serialvalidation.PatternMatcher

Use the pattern matcher plugin during terminal ID and device serial number validation to determine a valid set of values.

  • "LIKE" (default) - values are defined as exact terminal ID / device serial numbers or defined using a pattern.

  • "RANGED_NUMERIC" - values are defined in ranges using the format of [start_range]-[end-range]. During validation, a value is deemed to be valid if it falls within the defined range. It should be noted that the defined range also includes the [start_range] and [end_range] values. If this configuration is used but the terminal ID / device serial number range configured does not contain a "-" range character, then the default "LIKE" pattern matcher is used for validation of that specific terminal ID / device serial number.

Event logging
Property Description

postilion.esocketpos.LogDriver

The driver class that must be used for logging events to a text file (postilion.esocketpos.util.Log4j).

appender.rolling.name

If Log4J is used for event logging, this parameter defining the Rolling File Appender name, can be set to one of the following:

  • RollingFile

appender.rolling.type

If Log4J is used for event logging, this can be set to one of the following:

  • RollingFile

Note
If the Rolling File Appender is used, there must be a separate properties file for Configuration Agent and eSocket.POS and a different log file must be configured for each.

Furthermore, for security purposes, the SMTP appender org.apache.log4j.net.SMTPAppender is not supported and must not be configured.

appender.rolling.fileName

If Log4J is used for event logging, this specifies the complete filename and path of the log file output.

This property is set to the following value by default:

c:\\postilion\\esocket.pos\\logs\\esp_logs.txt

Note
If the Rolling File Appender is used, a different log file must be configured for Configuration Agent and eSocket.POS.

appender.rolling.filePattern

If Log4J is used for event logging, this specifies the filename pattern used for the archived log file names.

This property is set to the following value by default:

c:\\postilion\\esocket.pos\\logs\\esp_logs-%i.txt

Note
If the Rolling File Appender is used, a different log file pattern must be configured for Configuration Agent and eSocket.POS.

appender.rolling.layout.type

If Log4J is used for event logging, set to the following:

  • PatternLayout

appender.rolling.layout.pattern

If Log4J is used for event logging, this property specifies the date format and can be set to the following:

%d [%t] %-5p %c - %m%n

appender.rolling.policies.type

If Log4J is used for event logging, specifies the rolling file appender policies type, set to the following:

  • Policies

appender.rolling.policies.size.type

If Log4J is used for event logging, specifies the rolling file appender size policies type, set to the following:

  • SizeBasedTriggeringPolicy

appender.rolling.policies.size.size

If Log4J is used for event logging, specifies the maximum size of each log file produced, for example 1MB.

Note
This is only applicable to the Rolling File Appender.

appender.rolling.strategy.type

If Log4J is used for event logging, specifies the strategy type for the rolling file appender and can be set to the following:

  • DefaultRolloverStrategy

appender.rolling.strategy.max

Specifies the maximum number of log files (excluding the current log file) to keep. This defaults to 10.

Note
This is only applicable to the Rolling File Appender.

logger.rolling.name

Specifies the logger packages and can be set to the following:

  • eSocket.POS

logger.rolling.level

Specifies the types of errors that are logged and can be set to the following:

  • INFO

logger.rolling.additivity

Specifies whether the additivity attribute must be enabled and can be set to the following:

  • false

logger.rolling.appenderRef.rolling.ref

Specifies the declared name to refer to the appender reference and can be set to the following:

  • RollingFile

rootLogger.level

Specifies the root logger debugging level and can be set to the following:

  • DEBUG

rootLogger.appenderRef.rolling.ref

Specifies the root logger declared name to refer to the appender reference and can be set to the following:

  • RollingFile

postilion.esocketpos.PropertiesFilePath

This specifies the complete filename and path of the eSocket.POS properties file and is required if Log4J is used or if the property postilion.esocketpos.MaxSafeLogFileSize is specified.

postilion.esocketpos.MaxSafeLogFileSize

This specifies the maximum size of the esp_stderr.log file in megabytes.

If the property is not configured, a default of 10 megabytes is used. A value of UNLIMITED indicates that the file size must not be limited.

The esp_stderr.log file is used to troubleshoot a failure in the log driver, and it is not intended for general purpose use. If the maximum file size is reached, eSocket.POS stops logging to the file until it is manually deleted.

postilion.esocketpos.InstallLogsPath

This property represents the directory where all installation log files are copied to.

Store server
Property Description

postilion.esocketpos.component.remotesink.NumberOfThreads

Specifies the number of threads that are utilized by the RemoteSink entity within an eSocket.POS Store Server deployment.

Note
The default value is 4, but it should be set to at least the number of terminals in-store to prevent transaction slow-down during peak periods.

postilion.esocketpos.component.storeandforwardqueue.NumberOfThreads

Specifies the number of threads that are utilized by the StoreAndForwardQueue entity within an eSocket.POS Store Server deployment.

Note
The default value is 4, but it should be set to at least the number of terminals in-store to prevent transaction slow-down during peak periods.

postilion.esocketpos.component.storeandforwardqueue.NumberOfMonitorThreads

Specifies the number of threads that are utilized to monitor each terminal’s StoreAndForwardQueue within an eSocket.POS Store Server deployment

Note
The default value is 4

postilion.esocketpos.component.dualsink.NumberOfThreads

Specifies the number of threads that are utilized by the DualSink entity within an eSocket.POS Store Server deployment.

Note
The default value is 4, but it should be set to at least the number of terminals in-store to prevent transaction slow-down during peak periods.

postilion.esocketpos.storeserver.CleanerTime

The time at which the transaction cleaner must be run every day, in the format HHmm. The default time is 01h00.

postilion.esocketpos.storeserver.TransactionRetentionPeriod

The number of hours (integer) for which transactions must be retained in the database.

Note
This property requires that postilion.esocketpos.storeserver.CleanerTime be configured for the store cleaner to run.

postilion.esocketpos.storeserver.PANRetentionPeriod

(Optional) The number of hours, specified as an integer, for which encrypted PANs must be retained in the database. This property cannot be larger than the TransactionRetentionPeriod property. A special value (which is also the default value) of 9999 means that encrypted PANs must not be removed. This property is only used when the PAN Component is set to perform point-to-point encryption.

Note
This property requires the postilion.esocketpos.storeserver.TransactionRetentionPeriod property to be setup.

postilion.esocketpos.storeserver.EventsUndeliveredRetentionPeriod

(Optional) The number of hours, specified as an integer, for which undelivered support events must be retained in the database.

postilion.esocketpos.storeserver.TransactionLinkingMethod

(Optional) Specifies the method used for linking transactions. The possible values supported are:

  • DEFAULT - Links via system trace audit number and terminal ID.

  • RETRIEVAL_REF_NR - Links via retrieval reference number.

Note
If unspecified, eSocket.POS will use DEFAULT.

postilion.esocketpos.storeserver.AutoInitTerminals

(Optional) Specifies how terminals should be pre-initialized at start-up.

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

postilion.esocketpos.storeserver.signon.RetryEnabled

(Optional) Specifies whether sign-on should be retried if it fails.

If this property is not set, the default value is false.

Example: postilion.esocketpos.storeserver.signon.RetryEnabled = true

postilion.esocketpos.storeserver.signon.RetryMaxAttempts

(Optional) Specifies the number of sign-in retry attempts. The total number of attempts will be one more than this value to take into account the initial sign-on attempt. For example, if configured with a value of 5, a total of six attempts will be made to sign on.

If this property is not set, the default value is 0.

Example: postilion.esocketpos.storeserver.signon.RetryMaxAttempts = 3

postilion.esocketpos.storeserver.signon.RetryInterval

(Optional) Specifies the interval, in milliseconds, that should be applied after sign-on fails and before the sign-on retry is enqueued for processing. This value may not be the same as the actual time difference between retries since the sign-on retry attempt may not be processed immediately.

If this property is not set, the default value is 0.

Example: postilion.esocketpos.storeserver.signon.RetryInterval = 5000

postilion.esocketpos.storeserver.signon.RetryWithTrace

(Optional) Specifies whether sign-on retry actions should be traced. This can be enabled when troubleshooting or debugging sign-in retries.

If this property is not set, the default value is false.

Example: postilion.esocketpos.storeserver.signon.RetryWithTrace = true

Event handler
Property Description

postilion.esocketpos.eventhandler.MaskSensitiveData

This property specifies if sensitive card information must be masked in unsolicited card read messages. It can be configured with one of the following values:

  • DefaultFalse - Mask sensitive card information based on the configuration for the card product and do not mask it if the card product is not configured.

  • DefaultTrue - Mask sensitive card information based on the configuration for the card product and mask it if the card product is not configured. This is the default behavior.

  • AlwaysTrue - Always mask sensitive card information.

  • AlwaysFalse - Never mask sensitive card information.

postilion.esocketpos.RaiseLegacyCardReadEvent

(Optional) The possible values supported are:

  • false - This will raise the PROMPT_PRESENT_CARD event when a card read is performed on a contactless-enabled device.

  • true - This will raise the PROMPT_INSERT_CARD legacy event instead of the newer PROMPT_PRESENT_CARD when a card read is performed on a contactless-enabled device.

Note
If unspecified, eSocket.POS will use false.

*This property cannot be configured remotely.

Device configuration
Property Description

postilion.esocketpos.mode

This property specifies the mode that eSocket.POS operates under when a terminal is assigned multiple device groups. The Devices page contains more information on device groups. Configure this property with one of the following values:

  • active-active - All device groups will be prompted simultaneously for the initial device interaction.

  • active-backup(default) - If a device group is specified in the transaction, then that device group will be used. If no device group is specified in the transaction or if the device group specified in the transaction is not connected, eSocket.POS will iterate through the device groups until a connected device group is found and interacted with.

Information server
Property Description

postilion.esocketpos.ApplyConfigurationOnResync

This property specifies whether new ProcessingData configuration must be applied immediately after Config Agent has marked it as active in the database (default behavior) or only after a terminal RESYNC or a restart of the eSocket.POS service. It can be set to the following value:

  • 1 - the ProcessingData configuration only takes effect after a terminal is resynced or if the eSocket.POS service is restarted.

If this property is not set, the default behavior is to apply updated ProcessingData configuration immediately.

postilion.esocketpos.ConfigDefaultTerminalId

If specified, this property is used as the default terminal ID at startup if eSocket.POS could not start using the terminal ID configured in the database.

Note
This requires corresponding data to be configured in the database for the default terminal ID. This property is used to retrieve the configuration only, and not to be used to override the terminal ID in transactions .

*This property cannot be configured remotely.

postilion.esocketpos.UseOnlineCaPublicKeys

This property specifies whether eSocket.POS must use the online CA public keys database table (esp_capks_online) for EMV file downloads when the EMV Config pipeline component is configured.

Note
This requires corresponding key data to be configured in the database for the default CA public key configuration. See the Pipeline component - EMV Config page for more information about the default keys that must be loaded prior to an EMV file download.

(Optional) The possible values supported are:

  • true - eSocket.POS must use the online CA public keys database table (esp_capks_online) for EMV file downloads.

  • false - eSocket.POS must use the default CA public keys database table (esp_ca_public_key) for EMV file downloads.

Note
If unspecified, eSocket.POS will use false.
Custom applications
Property Description

postilion.esocketpos.EspRun.CustomApp. CustomAppName .ClassName

Start a custom application where this value specifies the fully qualified class name. Custom classes must extend the base class postilion.esocketpos.util.ACustomApp.

CustomAppName should be set to the user-friendly name of this custom application.

Store-and-forward Queue
Property Description

postilion.esocketpos.safq.send_only_when_signed_on

This property specifies whether eSocket.POS only sends store-and-forward queue messages after the POS application has initialized the terminal. It can be set to the following value:

  • 1 - eSocket.POS only sends store-and-forward queue transactions when the POS application has initialized the terminal.

If this property is not set, the default behavior is that Store-And-Forward Queue messages will be sent regardless of whether the POS application has initialized the terminal.

postilion.esocketpos.safq.backoffstrategy_failure_threshold

This property is used to determine if the server appears to be under load (is not responding to requests timely). Failures greater than this value indicate that the server is under load. It can be set to any integer value.

This property is used along with MAX_BACKOFF_TIME for Remote Sink when sending Advice Repeats upon upstream entity disconnection.

If this property is not set, the default value is zero.

EMV
Property Description

postilion.esocketpos.emv.fallback. AID

This property specifies whether EMV fallback is allowed for a specific AID:

  • true - EMV fallback allowed

  • false - EMV fallback not allowed

If this property is not set, the default value is true.

Example: postilion.esocketpos.emv.fallback.A0000000031010 = false

postilion.esocketpos.DontSendReversalOnSinkEmvTimeout

This property allows eSocket.POS to switch between the handling of timeout reversals at the RemoteSink or the EMV pipeline component for contact chip transactions.

The possible values supported are:

  • false - eSocket.POS will generate timeout reversals at the RemoteSink for contact chip transactions.

  • true - eSocket.POS will generate timeout reversals at the EMV pipeline components for contact chip transactions.

Note
If this property is not set, the default value is false.

Example: postilion.esocketpos.DontSendReversalOnSinkEmvTimeout = false

Hotcard checking
Property Description

postilion.esocketpos.AllowNullCSNMatchingForConfiguredHotcards

This property allows the identification of hotcards for transactions containing a card sequence number when the card sequence number is not present for the card in the hotcard list.

  • true - Allow hotcard matching for a card sequence number with a value of NIL.

  • false - Only allow hotcard matching for an exact match of the card sequence number (default).

Example: postilion.esocketpos.AllowNullCSNMatchingForConfiguredHotcards = true

Note
This configuration only applies when using the Hotcard pipeline component.

*This property cannot be configured remotely.

Miscellaneous
Property Description

postilion.esocketpos.pipelinecomponentconfirm.ShouldDisplayNegativeAmountsForCreditTransactions

This property specifies whether PipelineComponentConfirm displays positive or negative amounts for credit transaction types (for example, refunds). Amounts for debit transaction types are unaffected:

  • 1 - Negative amounts are displayed for credit transaction types

  • 0 - Positive amounts are displayed for credit transaction types

If this property is not set, the default value is 0 (false).

Example: postilion.esocketpos.pipelinecomponentconfirm.ShouldDisplayNegativeAmountsForCreditTransactions = 1

postilion.esocketpos.BlockTransactionWhenTerminalBusy

This property specifies whether eSocket.POS will prevent new transactions from being processed while a transaction is in flight.

  • true - block new transactions with Response Code (ISO field 39) = P3 while transactions are in flight.

  • false - allow all transactions. The POS software is responsible for managing transactions.

If this property is not set, the default value is false.

Example: postilion.esocketpos.BlockTransactionWhenTerminalBusy = true

postilion.esocketpos.resync.RetryResync

(Optional) This property specifies whether eSocket.POS should retry to resync after a resync failure.

  • true - eSocket.POS will re-attempt a resync if a resync failure occurs.

  • false - eSocket.POS will not re-attempt a resync if a resync failure occurs.

If this property is not set, the default value is false.

Example: postilion.esocketpos.resync.RetryResync = true

postilion.esocketpos.resync.RetryMaxAttempts

(Optional) This property specifies the number of times eSocket.POS should retry to resync after a resync failure.

If this property is not set, the default value is 3.

Example: postilion.esocketpos.resync.RetryMaxAttempts = 3

Note
eSocket.POS will only retry if postilion.esocketpos.resync.RetryResync = true

postilion.esocketpos.resync.RetryInterval

(Optional) This property specifies the interval, in milliseconds, that should be applied after a resync fails and before the resync is re-attempted by eSocket.POS.

If this property is not set, the default value is 15000.

Example: postilion.esocketpos.resync.RetryInterval = 15000

Note
eSocket.POS will only retry if postilion.esocketpos.resync.RetryResync = true

postilion.esocketpos.monitoring.SafqNotClearingThreshold

(Optional) This property specifies the time period, in minutes, after which the store and forward queue (SAFQ) is considered to not be clearing if:

  • there is more than one transaction in the SAFQ, and

  • the transaction at the head of the SAFQ has not been successfully delivered upstream.

If this property is not set, the default value is 5.

Example: postilion.esocketpos.monitoring.SafqNotClearingThreshold = 5

NOTES:

  • If this threshold is exceeded, the terminal status is changed to critical, the SAFQ_NOT_CLEARING event is raised (see the eSocket.POS Developer Guide ), and the SAFQ_NOT_CLEARING support event is logged (and written to the trace file).

  • This property can also be set in hours by appending an h to the value. For example 12h indicates 12 hours in: postilion.esocketpos.monitoring.SafqNotClearingThreshold = 12h

  • The value of this property should be less than the time it would take to discard an advice message or swap to another Sink (in Active/Active environment).

postilion.esocketpos.monitoring.SafqMonitoringInterval

(Optional) This property specifies the interval, in seconds, the "SAFQ not clearing threshold" (see previous property) will be checked.

If this property is not set, the default value is 30.

Example: postilion.esocketpos.monitoring.SafqMonitoringInterval = 30

postilion.esocketpos.monitoring.SafqMonitoringDetailedTracing

(Optional) If this property is set to true while tracing is enabled for a terminal, details are written to the trace file regarding the periodic checks performed by the SAFQ monitoring.

If this property is not set, the default value is false.

Example: postilion.esocketpos.monitoring.SafqMonitoringDetailedTracing = false

Legacy
Property Description

postilion.esocketpos.SendLegacyLodgingDataStructuredData

This property specifies whether lodging data sent from the POS must be populated in the message to the upstream entity in the legacy structured data field LodgingData instead of Postilion:LodgingData:

  • false - Populate lodging data in the Postilion:LodgingData structured data field

  • true - Enables the legacy support for populating lodging data in the LodgingData structured data field

If this property is not set, the default value is false.

Example: postilion.esocketpos.SendLegacyLodgingDataStructuredData = true

postilion.esocketpos.legacy.Path

This property specifies the location on the file system where the previous eSocket.POS installation is installed.

postilion.esocketpos.legacy.Action

This property specifies which action should be taken on the legacy eSocket.POS installation when starting eSocket.POS. The following actions are supported:

  • IGNORE - No action is taken.
    eSocket.POS will run normally, ignoring legacy installations. Ensure that the previous eSocket.POS services are manually disabled when choosing this option

  • DISABLE (Default) - All eSocket.POS services prior to eSocket.POS version 3 will be disabled.
    This option is only available on Windows.

  • UNINSTALL - eSocket.POS will silently uninstall the previous eSocket.POS installation.
    This option is only available on Windows. The uninstall log will be copied to the current eSocket.POS log directory, and can be requested remotely using a file request.

Note
  • These values are case insensitive.

  • If this property is configured remotely, the action will take place at the next restart.

Additional properties are also described separately for the following functionality:

A sample configuration is:

###
#
# Install settings
#
##

postilion.esocketpos.install.HomeDir = c:\\postilion\\eSocket.POS
postilion.esocketpos.install.ClassPath = C:\\winnt\\java\\classes;c:\\postilion\\eSocket.POS\\bin\\esocket-tools.jar;c:\\postilion\\eSocket.POS\\bin\\bcprov-jdk11-130.jar;c:\\postilion\\eSocket.POS\\bin\\sqljdbc.jar


###
#
# XML Interface
#
##

postilion.esocketpos.xmlinterface.eSocketPosSchemaFile = C:\\Postilion\\eSocket.POS\\xml\\MessageInterface.dtd
postilion.esocketpos.xmlinterface.ListenPort                     = 55001

###
#
# Tracing settings
#
##

postilion.esocketpos.TracePath = c:\\postilion\\Trace\\eSocket.POS
postilion.esocketpos.TraceStyle = CASCADE

###
#
# Command Port: the global eSocket.POS command port for this installation
#
##

postilion.esocketpos.CommandPort = 12345

###
#
# Examples of JDBC drivers:
#
# Microsoft: com.microsoft.sqlserver.jdbc.SQLServerDriver
# HSQLDB: org.hsqldb.jdbcDriver
#
###

postilion.esocketpos.JdbcDriver = com.microsoft.sqlserver.jdbc.SQLServerDriver
postilion.esocketpos.JdbcUrl = jdbc:sqlserver://;databaseName=esocketpos;integratedSecurity=true;sendStringParametersAsUnicode=false
postilion.esocketpos.JdbcUser =
postilion.esocketpos.JdbcUserPassword =
postilion.esocketpos.JdbcServerName = localhost
postilion.esocketpos.JdbcServerPort = 1433

###
#
# properties required by eSocket.POS Configuration Agent
#
##

postilion.esocketpos.IncomingConfigPath = c:\\postilion\\esocket.pos\\incoming

postilion.esocketpos.ConfigPollStartTime = 0200
postilion.esocketpos.ConfigPollInterval = 1440
postilion.esocketpos.HotcardPollStartTime = 0200
postilion.esocketpos.HotcardPollInterval = 1440
postilion.esocketpos.ConfigHistorySize = 3

###
#
# ConfigServer connection
# Required if the Configuration Agent fetches files from the ConfigServer:
#
##

#postilion.esocketpos.ConfigId = TERM_GRP_3

###
#
# ConfigServer connection
# Additional properties required if the Configuration Agent fetches files
 from the ConfigServer
# using HTTP:
#
##

# postilion.esocketpos.ConfigHttpServer = 137.1.3.41
# postilion.esocketpos.ConfigServerPort = 58080
# postilion.esocketpos.ScriptName = configserver/fileserver

###
#
# LogDriver
#
##

postilion.esocketpos.LogDriver = postilion.esocketpos.util.Log4j

###
#
# Log4J properties used by eSocket.POS to provide logging functionality
# Required if LogDriver is postilion.esocketpos.util.Log4j
#
##

appender.rolling.type = RollingFile
appender.rolling.name = RollingFile
appender.rolling.fileName = c:\\postilion\\esocket.pos\\logs\\esp_logs.txt
appender.rolling.filePattern = c:\\postilion\\esocket.pos\\logs\\esp_logs-%i.txt
appender.rolling.layout.type = PatternLayout
appender.rolling.layout.pattern = %d [%t] %-5p %c - %m%n
appender.rolling.policies.type = Policies
appender.rolling.policies.size.type = SizeBasedTriggeringPolicy
appender.rolling.policies.size.size = 1MB
appender.rolling.strategy.type = DefaultRolloverStrategy
appender.rolling.strategy.max = 10

# Print all messages of priority INFO and above
logger.rolling.name = eSocket.POS
logger.rolling.level = INFO
logger.rolling.additivity = false
logger.rolling.appenderRef.rolling.ref = RollingFile

# Root logger
rootLogger.level = DEBUG
rootLogger.appenderRef.rolling.ref = RollingFile

###
#
# Integration Tool Kit Specific
# Required for eSocket.POS to start in -mfe mode with itk
#
###

#postilion.esocketpos.mfe.class.name = postilion.espitk.posinterface.ItkFrontEnd

#postilion.esocketpos.itk.fixed.SapFactory = postilion.espitk.ipc.ItkSapFactory
#postilion.esocketpos.itk.fixed.SapProtocol = 15
#postilion.esocketpos.itk.fixed.SapFactorySetupData = -fixed-length
#postilion.esocketpos.itk.fixed.nodePort = 30000

#postilion.esocketpos.itk.variable.SapFactory = postilion.espitk.ipc.ItkSapFactory
#postilion.esocketpos.itk.variable.SapProtocol = 15
#postilion.esocketpos.itk.variable.SapFactorySetupData = -variable-length
#postilion.esocketpos.itk.variable.nodePort = 50000

###
#
# Oracle Payment Interface (OPI) Specific
# Required for eSocket.POS to start in -mfe mode with OPI
#
###

#postilion.esocketpos.mfe.class.name = postilion.esocketpos.posinterface.opi.OPIFrontEnd

#postilion.esocketpos.opi.SapFactory = postilion.esocketpos.ipc.opi.EspOPITcpSapFactory
#postilion.esocketpos.opi.SapProtocol = 15
#postilion.esocketpos.opi.SapFactorySetupData = -ssl-type=jsse -ssl-remote-auth=false -ssl-protocols=TLSv1.2;SSLv2Hello
#postilion.esocketpos.opi.nodePort = 45000

4.3. Configure classes

Many of the classes in the eSocket.POS application can be configured to enable integration with different message protocols for the source and sink entities, different databases, different peripheral devices, and different logging mechanisms.

The class configuration is stored in the esp_classes database table. Each line of the table configures a single class.

Exactly one class must be configured for each of the following:

  • Source entity

  • Sink entity

  • Card reader

  • Display

  • Keypad

  • PIN pad

The following classes may optionally be configured (if not configured, NullDevice is used):

  • Smart card reader

  • Check reader

  • Signature capture

  • Operator display

  • Barcode reader

Zero or more classes can be configured for the following, using a rank to indicate the order in which the components are configured in the pipeline:

  • Request pipeline components

  • Response pipeline components

Zero or more classes can be configured for the following, using a rank to indicate the order in which the drivers are called when logging an event:

  • Log driver

Zero or one class can be configured for the following:

4.3.1. Source entity

The source entity row in the esp_classes table is as follows:

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

term_category

The terminal category

ans8

class_tag

SOURCE

ans..80

rank

0

INT

class_name

Fully qualified name of the source entity class

The standard implementation is postilion.esocketpos.posinterface.IsoPosInterface

ans..255

params

Dependent on the source entity class chosen

IsoPosInterface takes no parameters.

ans..255

4.3.2. Sink entity

The sink entity row in the esp_classes table is as follows:

Field Notes Format

timestamp

Timestamp in YYMMDDHHmmss format identifying the configuration set for this entry

n12

term_category

The terminal category

ans8

class_tag

SINK

ans..80

rank

0

INT

class_name

Fully qualified name of the sink entity class

The standard implementation is postilion.esocketpos.postilioninterface.RemoteSink

ans..255

params

Dependent on the sink entity class chosen

For RemoteSink parameters, refer to the RemoteSink page.

ans..255

4.3.3. Request pipeline component

Each request pipeline component uses a separate line in the esp_classes table as follows, using the rank column to indicate the position of the component in the pipeline.

Note
The rank must be sequential starting at 1. If there is a gap in the ranking, any component with a rank after the gap is ignored.
Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

term_category

The terminal category

ans8

class_tag

REQ_PIPELINE

ans..80

rank

The position of the component in the request pipeline

Sequential, starting at 1.

INT

class_name

Fully-qualified name of the pipeline component class

ans..255

params

Refer to the user guide for the pipeline component.

ans..255

4.3.4. Response pipeline component

Each response pipeline component uses a separate line in the esp_classes table as follows, using the rank column to indicate the position of the component in the pipeline.

Note
The rank has to be sequential starting at 1. If there is a gap in the ranking, any component with a rank after the gap is ignored.
Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

term_category

The terminal category

ans8

class_tag

RSP_PIPELINE

ans..80

rank

The position of the component in the response pipeline

Sequential, starting at 1

INT

class_name

Fully-qualified name of the pipeline component class

ans..255

params

Refer to the user guide for the pipeline component.

ans..255

4.3.5. Devices

The device classes (one for each of the logical devices required by eSocket.POS). Each class appears on a separate row into the esp_classes table as follows:

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

term_category

The terminal category

ans8

class_tag

CARDREADER , DISPLAY , KEYPAD , PINPAD, SMARTCARDREADER , CHECKREADER or SIGNATURECAPTURE

ans..80

rank

0

INT

class_name

Fully-qualified name of the Device class

ans..255

params

Refer to the user guide for the device.

ans..255

If the physical device consists of more than one logical device, such as a PIN pad with integrated display, card reader, or keypad functions, then the same device class can be used for more than one tag.

The following are mandatory:

  • CARDREADER

  • DISPLAY

  • KEYPAD

  • PINPAD

Even if the device is not present, a configured class must still be included and set to postilion.esocketpos.devicemanager.NullDevice. The remaining device classes are optional, and NullDevice is automatically used if they are omitted.

4.4. File verification

eSocket.POS can verify the integrity and authenticity of distribution files that it receives packaged in signed JARs. If this functionality is enabled, eSocket.POS is only able to read files from signed JARs, and only if it can authenticate these JARs.

4.4.1. Configuring file verification and authentication

To enable this functionality, the property postilion.esocketpos.VerifyDistributionFiles must be configured for the Configuration Agent.

In addition, the property postilion.esocketpos.SecuredConfigPath must be configured for both the Configuration Agent and the Upgrade Manager. After this property is configured, it points to a secured directory which is used internally by eSocket.POS to ensure that it only loads authenticated files. Only the Configuration Agent, Upgrade Manager, and other trusted processes must have write access to this directory.

Files from ConfigServer

ConfigServer can distribute files to eSocket.POS as signed JAR archives. File signing is disabled by default and must be enabled on ConfigServer prior to configuring eSocket.POS to verify file signatures. (See the ConfigServer User Guide for more information.)

Signed files from sources other than ConfigServer

Signed files can be distributed from sources other than ConfigServer, in which case the Java jarsigner utility can be used to create signatures. See https://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html.

Files to be authenticated follow the same naming convention as for unsigned files, except that an additional .jar extension is appended. The JAR archive contains a single entry that represents the original file along with the JAR manifest folder. Software Update files are the exception; for them, the .zip extension is replaced by a .jar extension and the JAR manifest folder is added to the existing ZIP archive. For example, an unsigned file named file.sql must have a signed equivalent of file.sql.jar and an unsigned software update file named file.zip must have a signed equivalent of file.jar.

The Upgrade Manager is unable to verify the signatures for software upgrades. The norm is for Configuration Agent to request files from ConfigServer via HTTP, verify the signatures and then extract the verified files to the secured directory. If ConfigServer is not used, the unsigned software upgrades must be delivered directly into the secured directory and the upgrade is applied without verifying it.

When signed files are created by sources other than ConfigServer, it is necessary to install a custom X.509 signing certificate that contains an RSA public key. If the certificate is loaded manually, the alias must be in the form CUSTOM_SIGNING_<timestamp>. If the certificate is sent down using ConfigServer, then the file transferred must have a name of the form CUSTOM_SIGNING_<timestamp>.cer, where <timestamp> is the timestamp at which the certificate was generated. The <timestamp> value must be unique across all signing certificates.

Initializing the keystore

When file verification and authentication are enabled for eSocket.POS, the keystore must be initialized with the signing certificate. This can be done in one of the following ways:

  • The certificate can be loaded automatically by trusting the first certificate received from ConfigServer.

  • Prior to configuring eSocket.POS to verify files, the ConfigServer File(s) for Transfer mechanism on the File Transfers tab may be used to install a certificate. After eSocket.POS is configured to verify files this method may also be used to install or update custom signing certificates.

  • The certificate can be loaded manually. Once this is done, Configuration Agent accepts JAR files signed by this certificate.

4.5. Loading certificates and private keys manually

4.5.1. Loading certificates and private keys manually

If certificates and private keys must be manually loaded into the eSocket.POS keystore, the following command-line utility can be used:

<java> <classpath> postilion.esocketpos.crypto.TrustedCertificateStore [<command>] <properties_file> <input_file> <alias> [<input_alias>]

where <java> <classpath> is the invocation of the Java virtual machine with classpath parameters.

The command-line parameters are described below:

Parameter Description

command

Specifies the command to run. The following commands are supported:

  • -importcert - Import a X.509 public key certificate chain from a PEM file.

  • -importpriv - Import a private key and certificate chain from a PKCS #12 (.p12) file. The PKCS #12 file must contain both the private key and its associated public key certificate chain. The private key cannot be imported on its own.

This parameter is optional. If not specified, the -importcert command will be run by default.

properties_file

The fully qualified path of the eSocket.POS properties file.

For example, c:\eSocket.POS\esp_properties.txt

input_file

The fully qualified path to the input certificate/key file.

When using the -importcert command, this must be a X.509 certificate PEM file. For the -importpriv command, this must be a PKCS #12 file containing both the private key and its associated public key certificate chain.

alias

The alias under which the certificate or private key should be stored in the eSocket.POS keystore.

For PosConnect RSA public key certificates, this must be the same as the alias used by the PosConnect Certificate Management Service (with naming convention POSCONNECT_PCIDSS_yymmdd).

input_alias

The alias of the private key and certificate chain in the PKCS #12 input file. If not specified, the value provided for the <alias> parameter will be used by default.

This parameter does not apply to X.509 certificate PEM input files.

4.5.2. Example usage

Example 1: Loading a PosConnect RSA public key certificate

Assume the PosConnect RSA public key certificate for alias POSCONNECT_PCIDSS_130417 was saved to a file called posconnect.pem using the Realtime Certificate Management Configuration console.

To load the certificate into the eSocket.POS keystore, run:

    java -cp C:\windows\java\classes;C:\postilion\eSocket.POS\bin\bcprov-jdk15.jar postilion.esocketpos.crypto.TrustedCertificateStore -importcert C:\postilion\eSocket.POS\properties.txt posconnect.pem POSCONNECT_PCIDSS_130417
Example 2: Loading a private key (e.g. for Apple Pay NFC VAS data decryption)

Assume OpenSSL is used to generate a private-public key pair and the private key has been outputted to a file private_key.pem. For Apple Pay NFC VAS (near field communication value added service), this would be an EC (elliptic curve) private-public key pair using curve X9.62 prime256v1.

First, create the PKCS #12 file:

  • Generate the public key certificate associated with the private key:

    openssl req -new -x509 -key private_key.pem -out cert.pem -days 1200
  • Generate the PKCS #12 file from the private key and certificate and store it in the file under key alias MyKeyAlias :

    openssl pkcs12 -export -inkey private_key.pem -in cert.pem -name MyKeyAlias -out key.p12

Now load the private key and certificate from the PKCS #12 file into the eSocket.POS keystore by executing:

java -cp C:\windows\java\classes;C:\postilion\eSocket.POS\bin\bcprov-jdk15.jar postilion.esocketpos.crypto.TrustedCertificateStore -importpriv C:\postilion\eSocket.POS\properties.txt key.p12 MyKeyAlias

Enter the PKCS #12 file password when prompted by the TrustedCertificateStore utility.

If private key and certificate needs to be stored under a different alias in the eSocket.POS keystore (e.g. under MyKeyAliasEsocket), run the following command instead:

java -cp C:\windows\java\classes;C:\postilion\eSocket.POS\bin\bcprov-jdk15.jar postilion.esocketpos.crypto.TrustedCertificateStore -importpriv C:\postilion\eSocket.POS\properties.txt key.p12 MyKeyAliasEsocket MyKeyAlias

4.6. Configuring strong data protection

The following standard eSocket.POS components must be configured as described below for eSocket.POS to operate in a manner compliant with strong data protection:

  • PAN encryption must be enabled in the PAN pipeline component. The PAN component must also be configured to mask sensitive data by default.

  • To perform PAN encryption, the Certificate Manager component must be configured.

  • The Transaction Store Cleaner component must be configured.

Properties in the property file must be set as follows:

  • The database username and password must not be specified in the clear. The following properties must therefore not be present: postilion.esocketpos.JdbcUser and postilion.esocketpos.JdbcUserPassword. The encryption tool can be run from the command line to encrypt the username and password.

  • Command port use must be restricted. The postilion.esocketpos.CommandPort property must not be configured and the command port in the Terminal Configuration must be set to '0'.

  • The postilion.esocketpos.SaveTrack2 property must not be configured to a value of '1' (Save Track 2 data to the database).

In order to support strong data protection eSocket.POS will automatically encrypt the following sensitive properties during startup, if they are not encrypted and not blank.

  • postilion.esocketpos.JdbcUser

  • postilion.esocketpos.JdbcUserPassword

  • postilion.esocketpos.ssl.KeyStorePassword

  • postilion.esocketpos.ssl.TrustStorePassword

  • postilion.esocketpos.keystore.<keystorename>.Password

eSocket.POS logs a warning if it detects that it is started up in a manner that is not configured for strong data protection.

4.6.1. SSL

The SSL functionality, previously found in the eSocket.POS SSL Extension, is now part of the eSocket.POS main product. In addition, the eSocket.POS implementation of SSL also supports mutually authenticated and anonymous SSL on all connection channels - that is, for connections to PosConnect, ConfigServer, the PIN Entry Device (PED), and the POS. For more information, see the SSL pages.

4.6.2. Encrypting sensitive properties in the properties file

It is a security risk to keep usernames and passwords in the clear in the eSocket.POS properties file. To this end, a utility is provided that encrypts the sensitive properties in the properties file and store them under new encrypted property names. This encryption is performed using Triple DES encryption, with a key that is generated during the encryption process and stored in the keystore. The utility can be run from a command line as follows:

<java> <classpath> postilion.esocketpos.util.security.SecurityUtils --insensitive < file_1>…​< file_n> --sensitive <sensitive_properties_file>

where <java> <classpath> is the invocation of the Java virtual machine with classpath parameters.

Note
To ensure the integrity of the eSocket.POS keystore file, all other eSocket.POS applications must be stopped before running the utility.
Use of the command line options

Note the following regarding use of the command line options:

  • --insensitive (mandatory)

    • This command line option takes a space-separated list of properties files.

    • If the sensitive option is not specified, then any existing encrypted properties in the list of insensitive properties files are re-encrypted under a new key.

  • --sensitive (not mandatory)

    • This command line option takes a single file (containing the unencrypted sensitive properties) as a parameter.

    • If this option is specified, the utility accepts the unencrypted sensitive properties from the file specified and encrypts them under a newly generated key.

After running this utility, each file specified in the list of files provided to the --insensitive command line option contains the newly encrypted properties, replacing the properties that are stored in the clear. After the properties are successfully encrypted, the file specified with the --sensitive command line option are deleted.

The following mapping of property names result from running this utility:

Property Sensitive property name Insensitive property name

User

postilion.esocketpos.JdbcUser

postilion.esocketpos.encrypted.JdbcUser

Password

postilion.esocketpos.JdbcUserPassword

postilion.esocketpos.encrypted.JdbcUserPassword

SSL Keystore Password

postilion.esocketpos.ssl.KeyStorePassword

postilion.esocketpos.ssl.encrypted.KeyStorePassword

SSL Truststore Password

postilion.esocketpos.ssl.TrustStorePassword

postilione.socketpos.ssl.encrypted.TrustStorePassword

Auxiliary Keystore Password

postilion.esocketpos.keystore.<keystorename>.Password

postilion.esocketpos.keystore.encrypted.<keystorename>.Password

4.7. Configuration Agent files

4.7.1. Configuration Agent files

The eSocket.POSConfiguration Agent supports loading of full or incremental configuration files in XML format.

Upload files are further separated into categories: these are processing data, terminal data, terminal configuration, and hotcards. The category is also indicated in the name of the upload file, and affects the processing performed by the Configuration Agent when it loads the file. The Configuration Agent supports the following upload file categories:

The Configuration Agent maintains separate poll timers for configuration and hotcard upload files. It is possible, for example, to configure the Configuration Agent to poll for new configuration files every 24 hours, and for new hotcard files every 60 minutes.

When more than one configuration file is available for loading, the Configuration Agent determines the smallest set of upload files that brings the database up to date. For example, if two unprocessed full upload files are detected, the Configuration Agent processes only the more recent of the two. Similarly, if a full upload file is present with more recent incremental upload files, then the full upload file and all subsequent incremental upload files are processed by the Configuration Agent in order.

Upload files and their types and categories are identified by means of an upload file naming convention.

4.7.2. File naming convention

For eSocket.POS Configuration Agent to correctly identify upload files, the following naming convention for an upload file must be adhered to:

<LABEL>_<SUB_LABEL>_<TIMESTAMP>_<TYPE>.<EXTENSION>

where:

LABEL is the category of upload file. The following labels are supported by the Configuration Agent:

esp_terminal_config

terminal configuration upload files - used to add, remove or update terminals

esp_terminal_data

terminal data upload files - used to add, remove or update the data associated with a category of terminal

esp_processing_data

processing data upload files - used to add, remove or update non-terminal specific data

esp_hotcard

hotcard files

ConfigServerHashSalt

salt files that accompany hotcard files when salted hashing is used

SUB_LABEL is used when the upload file is downloaded in more than one part. For example, if esp_processing_data is downloaded in three parts, the SUB_LABEL is used to indicate the details of each part. The format is as follows:

<PART>< number ><OF><total number><title>

where:

  • number indicates which part this is of the total parts making up the upload file.

  • total number is the total number of parts making up the upload file.

  • title is a custom name which indicates the type of data in this part of the upload file - use any string value, except an underscore.

The download will succeed if:

  • The SUB_LABEL is not in the filename and the upload file is downloaded in one part.

  • The SUB_LABEL is present and indicates how many parts the upload file is divided into, that is, the total number of parts.

  • All the files in the total number of parts are available and numbered in order. For example, if you have PART1OF3, PART1OF3 and PART3OF3, then PART2OF3 is missing, and the download will fail.

Note
SUB_LABEL is optional so can be absent from the file name.

TIMESTAMP is the timestamp of this upload file. Upload file timestamps are used by the Configuration Agent when inserting data sets into the eSocket.POS database. This timestamp must be of the form YYMMddHHmmss, where:

  • YY is the 2-digit year (for example, 04 to indicate 2004)

  • MM is the month (for example, 01 to indicate January)

  • dd is the day of the month (for example, 21)

  • HHmmss is the 24-hour time (for example, 123059)

TYPE is the type of the file, which can be set to full or incr.

Note
Salt files must always be of type full.

EXTENSION is the extension of the file. Configuration upload files must have the extension ".xml" and hotcard upload files must have the extension ".hc". If these files are signed they must have the extensions ".xml.jar" and ".hc.jar" respectively. Salt files can have any extension and is typically the name of the retailer.

4.7.3. Configuration uploads

In addition to the management of terminals, eSocket.POS configuration files are used to populate the database with both terminal specific and general processing information.

Terminal configuration files are used to manage the terminals that are serviced by eSocket.POS. This includes the addition of new terminals and the removal and updating of existing terminals. The data contained in this file is unique for each terminal. These configuration files are validated against the DTD terminal configuration file.

This file must start with the following XML:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE TerminalConfig SYSTEM "TerminalConfig.dtd">

where "TerminalConfig.dtd" is the absolute path to the DTD.

Terminal data files contain terminal information that is required by all terminals, but need not be unique across all terminals. An example of such data is the POS geographic data. The information in this file is loaded for terminals whose Terminal Category ID matches the ID in the file. The XML data in these files are validated against the DTD terminal data file. This file must start with the following XML:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE TerminalData SYSTEM "TerminalData.dtd">

where "TerminalData.dtd" is the absolute path to the DTD.

Processing data files contain the data that is required to process transactions. This includes card and account information. The XML data in these files is validated against the DTD processing data configuration file.

This file must start with the following XML:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ProcessingData SYSTEM "ProcessingData.dtd">

where "ProcessingData.dtd" is the absolute path to the DTD.

Configuration upload file processing

At user configurable intervals, the Configuration Agent either fetches new configuration upload files from an HTTP server or checks the specified upload directory for them, depending on the values of the eSocket.POS properties. These files must be named in accordance with the upload file naming convention.

If new files are present, then the following data validation and data loading steps are performed for each type of configuration file (terminal configuration, terminal data and processing data).

Data validation

During the validation phase, each new config upload file is validated to ensure that the XML is well formed and that it conforms to the DTD. Any errors in the file are logged. Although the Configuration Agent attempts to validate the entire file and to report as many errors as possible, some XML errors are considered fatal and will cause the Configuration Agent to abort the validation of the offending file.

If any errors are detected in a file, the Configuration Agent continues validating any remaining config upload files. Once all files are processed, however, it does not attempt to load data from any of the files.

Files that could not be validated are indicated by appending the tag "failed_<TIMESTAMP>", where <TIMESTAMP> is the time that processing was attempted on the file. Files that are successfully validated are renamed by appending the tag "processed_<TIMESTAMP>".

Data loading

If all files are successfully validated, then the Configuration Agent proceeds with the second phase and attempts to load the data. As with validation, any errors are logged. The Configuration Agent does not, however, attempt to continue processing files after an error is detected. Additionally, the Configuration Agent attempts to rollback any changes that are made to the database up to that point.

The Configuration Agent tags all files that are successfully processed by appending "processed_<TIMESTAMP>". If an error occurred during loading, the offending file is tagged by appending "failed_<TIMESTAMP>". All subsequent files are tagged with "ignored_<TIMESTAMP>".

After all files in the set are successfully loaded, the resulting dataset is marked as active. The previously active dataset (if one exists) is marked as old. A configurable number of old datasets are retained in the database. Once this is exceeded, the oldest datasets are deleted.

If the postilion.esocketpos.ApplyConfigurationOnResync property is not set the updated processing data is available to eSocket.POS immediately, otherwise, along with the updated terminal data and terminal configuration, it only comes into use when the terminal is resynced or re-initialized by the POS application, or the eSocket.POS service is restarted. Hotcard lists, however, are always applied immediately.

4.7.4. Processing data formats

Processing data can be represented in a de-normalized or normalized format in regard to BINs and Acquirer card-acceptor mappings.

The de-normalized format has been supported up to eSocket.POS version 2.6 and backwards compatibility has been provided for this format in eSocket.POS version 2.7. This format requires all BINs and Acquirer card-acceptor mappings to be de-normalized in the tables, esp_cards and esp_accounts. The tables, esp_bins and esp_acq_ca_map, are not used in this format.

The normalized format is supported from eSocket.POS version 2.7. This format requires all BINs and Acquirer card-acceptor mappings to be normalized into the tables, esp_bins and esp_acq_ca_map, which result in much smaller processing data files. eSocket.POS Configuration Server (ConfigServer) generates files in this format more efficiently than files in the de-normalized format.

4.7.5. Terminal configuration DTD

Hotcard uploads
Overview

Hotcard upload files contain records for cards that are marked "hot" due to them having been lost or stolen. This file is formatted as specified on the Hotcard format page.

At user configurable intervals, the Configuration Agent either downloads new hotcard upload files from an HTTP server, or checks the specified upload directory for them, depending on the values set for the eSocket.POS properties. These files must be named in accordance with the upload file naming convention. Hotcard upload files are expected to have a label of "esp_hotcard" and the extension ".hc" for unsigned files or extension ".hc.jar" for signed files. These files have names such as "esp_hotcard_030121150000_full.hc" or "esp_hotcard_030121150000_full.hc.jar".

Additionally, when the SHA-2 algorithm for salted hashing of hotcard PANs is used, hotcard upload files are sometimes accompanied by a salt value. This value is a 48-hexadecimal-digit string used to calculate the hashed PANs contained in these files. A salt value is supplied the first time hotcard updates using SHA-2 are to be applied, and thereafter on a periodic basis to "rotate" the salt. Whenever a salt rotation takes place, i.e. a new salt value is supplied, all hotcards have to be updated to use new hashed PANs, corresponding to the new salt value. As a result, a full hotcard update must then first take place before any incremental updates.

To supply the salt value when the specified upload directory is used, a salt file must also be placed there, containing this value. Salt files also use the upload file naming convention, with a label of "ConfigServerHashSalt" and always with the type "full". The hashed PANs corresponding to such a salt value are obtained by using the salt as a triple-DES key in an HMAC/SHA-256 hashing algorithm. This constitutes the SHA-2 algorithm.

Some hotcard files support point-to-point encryption (P2PE). A hotcard used in a P2PE environment contains a tokenization check value in the first line of the file, and the PANs are in a tokenized form. The tokenization check value is stored in the eSocket.POS keystore. eSocket.POS uses this check value during transaction processing to compare against the check value received from the PED. See Pipeline component - Hotcard for more details on hotcard checking.

NOTE

When used in a P2PE environment, a salt is referred to as a tokenization key and a hashed PAN as a tokenized PAN.

Data validation

During the validation phase, each hotcard file in the set of upload files is checked to ensure that they are correctly formatted according to their type (full/incremental). All files in the set are validated, and all errors reported to the log. If any file could not be successfully validated, the entire hotcard load is aborted.

Files that could not be validated are indicated by appending the tag "failed_<TIMESTAMP>", where <TIMESTAMP> is the time that processing was attempted on the file. Files that are successfully validated are renamed by appending "processed_<TIMESTAMP>".

In the case of salt files, when more than one is present in the upload directory, the one with the most recent timestamp is validated and used. A valid salt file contains only the salt value, as a 48-hexadecimal-digit string. Afterwards (regardless of whether validation succeeded or not), all discovered salt files are deleted for security purposes. If validation fails, an error is logged, the entire hotcard load is aborted and all hotcard files that would otherwise be processed are tagged by appending "failed_<TIMESTAMP>".

Data loading

If all hotcard files in the upload set are successfully validated, then the Configuration Agent attempts to load the data they contain into the eSocket.POS database. If an error occurs while attempting to load the data, the file that caused the error is tagged by appending "failed_<TIMESTAMP>". All remaining files are tagged by appending "ignored_<TIMESTAMP>". Files that are successfully processed are tagged with "processed_<TIMESTAMP>". Unlike the load of config files, the Configuration Agent does not attempt to roll back the changes effected by those files that have already been processed, should an error occur.

Therefore, should an error occur during a hotcard upload, it is recommended that a full upload be done to flush old records from the database and insert the required new entries.

Hotcards file layout

Financial institutions are requested to supply hotcards information in a file called Hotcards.txt.

There are two types of downloads that may be requested, each with a different file layout:

Note
  • Every line must be terminated by a carriage return (CR) and line-feed (LF) character combination.

  • Fields must be separated by a comma (,) and there must be no excess space buffering the fields.

  • There must not be any spaces at the end of the line.

  • If any of the files do not conform to these specifications, processing of all files is aborted.

  • If a hotcard file is used in a point-to-point encryption (P2PE) environment, it has a tokenization check value in the first line of the file. See P2PE check value layout for details.

  • See the Hotcard checking property for more configuration to hotcards.

Previous versions of eSocket.POS did not include the PAN hash value and PAN hash algorithm fields. To maintain backwards compatibility, the Hotcard loader is able to load files in the old format.

Full download - file layout
Field Key M/O Length Format Default Description

PAN

*

O, must be present if PAN Hash Value is not present.

< = 19

numeric

The PAN of the hotcard.

Response code

M

2

numeric

The error code that the Transaction Manager uses to decline a transaction with this hotcard.

Authorization response ID

M

6

alphanumeric and space

The response ID that the Transaction Manager uses to respond to transactions with this PAN.

Card sequence number

*

O

3

numeric

(null)

Used by the Transaction Manager to distinguish cards with the same PAN. Card sequence numbers with less than 3 characters must be padded with 0s in the front.

Telephone number

O

< = 25

ASCII

(null)

The telephone number used to contact a person associated with the card issuer.

In files generated by ConfigServer, this field may also have the hotcard category appended (following a '|' character), and this is an alternative supported format. If the hotcard category is present in this field, the phone number is restricted to 20 characters.

Entry date

O

8

numeric YYYYMMDD)

current date

Date on which hotcard files are provided by the card issuer.

PAN hash value

*

O, must be present if PAN is not present

< = 512

HEX

Hash value of the PAN as a hexadecimal string.

PAN hash algorithm

O

1

numeric

0

The algorithm used to create the hash of the PAN:

0 - SHA-256 (default)

1 - SHA-2

Hotcard category

O

< = 2

alphanumeric

(null)

The hotcard category is used to refine hotcard processing so that the risk associated with a particular card can be used to determine how the transaction is handled.

To use this field, the hotcard component must be configured to determine the treatment of the hotcard category. See the hotcard component category_treatment parameter for details.

Examples of valid entries (full)
5432109878376215,02,P12345,003,+27-21-123123213,20000503,,

5432145235255551,02,P12345,,,,,

5423567282549472,03,P93824,002,,20000502,,

5423574621000472,02,P93826,,+27-21-97674362,,,

,02,P12345,003,+27-21-123123213,20000503,1C263801D475670903283D1D101607A9A95492BE896FD95EB286F0EC44457AA9,0

,02,P12345,,,,1C263801D475670903283D1D101607A9A95492BE896FD95EB286F0EC44457AA9,,W
Incremental download - file layout
Field Key M/O Length Format Default Description

Command

M

1

alphanumeric

The value can be I (insert), D (delete), or U (update). It informs the Realtime application what operation to perform on the given record.

PAN

*

O, must be present if hashed_pan is not present.

< = 19

numeric

The PAN of the hotcard.

Response code

M

2

numeric

The error code that the Transaction Manager uses to respond to a transaction with this hotcard.

Authorization response ID

M

6

alphanumeric and space

The response ID that the Transaction Manager uses to respond to transactions with this PAN.

Card sequence number

*

O

3

numeric

(null)

Used by the Transaction Manager to distinguish cards with the same PAN. Card sequence numbers with less than 3 characters must be padded with 0s in the front.

Telephone number

O

< = 25

ASCII

(null)

The telephone number used to contact a person associated with the card issuer.

In files generated by ConfigServer, this field may also have the hotcard category appended (following a '|' character), and this is an alternative supported format. If the hotcard category is present in this field, the phone number is restricted to 20 characters.

Entry date

O

8

numeric (YYYYMMDD)

current date

Date on which hotcard files are provided by the card issuer.

PAN hash value

*

O, must be present if PAN is not present

< = 512

HEX

Hash value of the PAN as a hexadecimal string.

PAN hash algorithm

O

1

numeric

0

The algorithm used to create the hash of the PAN:

0 - SHA-256

1 - SHA-2

Hotcard Category

O

< = 2

alpha-numeric

No default.

The hotcard category is used to refine hotcard processing so that the risk associated with a particular card can be used to determine how the transaction is handled.

To use this field, the hotcard component must be configured to determine the treatment of the hotcard category. See the hotcard component category_treatment parameter for details.

Note
For records to be deleted during an incremental download where SHA-2 hashing is not used, only the fields marked by an asterisk in the Key column need to be specified. However, if any of these fields do not have a value, then it may also be an empty string.
Examples of valid entries (incremental)
I,5432109878376215,01,P12345,002,+27-21-123123213,20000503

I,5432109878376215,01,P12345,003,,

D,5432145235255551,,,003,,

U,5423574621000472,02,P93824,,+27-21-97674362,

I,,99,resp 6,002,,,1C263801D475670903283D1D101607A9A95492BE896FD95EB286F0EC44457AA9,

U,,04,resp 4,001,phone99,20020612,1C263801D475670903283D1D101607A9A95492BE896FD95EB286F0EC44457AA9,0

D,,05,resp 5,,,,1C263801D475670903283D1D101607A9A95492BE896FD95EB286F0EC44457AA9,0,H
P2PE check value layout

MetaData:KeyCheckValue= <check value>

where the <check value> is a 6-digit hexadecimal string.

Example of valid P2PE check value entry

MetaData:KeyCheckValue=FFFFFF

SQL data scripts

Custom eSocket.POS components, like custom pipeline components or device integrations, can install and manage their own database tables in the eSocket.POS database. Configuration Agent can process SQL data scripts that insert into or update the configuration data in these tables. SQL scripts that change the database schema must not be distributed using this mechanism: they must be packaged as an upgrade and processed by the Upgrade Manager.

Configuration Agent looks for files in the incoming directory that conform to the following naming convention: esp_sql_data_<timestamp>.sql (or esp_sql_data_<timestamp>.sql.jar for signed files) and apply them in timestamp order.

SQL script format

The Configuration Agent requires the SQL script to contain additional information contained in SQL comments. This is to do dependency checks before applying an update, and to support rollback: the statements in the script are not run as a single transaction because the amount of data may prohibit this. Instead, the SQL script contains additional statements that can be used to roll back any changes if an error occurs during the execution of the SQL script.

The following example illustrates the SQL comment markup required for each logical update in the SQL script. The description field is used for logging and error reporting. After the description, follows any number of conditions that must be true before this update is applied. There are a number of supported conditions described below. Multiple SQL statements must be separated by an --ENDSTATEMENT comment. The --ROLLBACK statement indicates the start of the rollback statements for this update. They are only run during rollback if the update . the conditions evaluated to true.

There can be more than one logical update (each with its own conditions and rollback statements). They are separated by empty lines in the SQL file.

--DESCRIPTION Insert new custom data

--NOTEXISTS SELECT * FROM my_custom_table
 WHERE my_key = 1 OR my_key = 2

INSERT INTO my_custom_table (my_key,
 my_value)

VALUES (1, 'one')

--ENDSTATEMENT

INSERT INTO my_custom_table (my_key,
 my_value)

VALUES (2, 'two')

--ROLLBACK

--EXISTS SELECT * FROM my_custom_table WHERE my_key
 = 1 OR my_key = 2

DELETE FROM my_custom_table WHERE my_key = 1

--ENDSTATEMENT

DELETE FROM my_custom_table WHERE my_key = 2
--DESCRIPTION
 Insert more custom data

--NOTEXISTS SELECT * FROM my_custom_table
 WHERE my_key = 3

INSERT
 INTO
 my_custom_table (my_key,
 my_value)

VALUES
 (3,
 'three')

--ROLLBACK

--EXISTS SELECT * FROM my_custom_table WHERE my_key
 = 3

DELETE
 FROM
 my_custom_table WHERE
 my_key =
 3
Supported conditions

The following conditions can be evaluated before applying an update statement:

  • --EXISTS <sql_query>: evaluates to true if the SQL query returns at least 1 row.

  • --NOTEXISTS <sql_query>: evaluates to true if the SQL query returns 0 rows.

  • --EXISTS <table_name>: evaluates to true if the table exists.

  • --NOTEXISTS <table_name>: evaluates to true if the table does not exists.

  • --HASCOLUMN <table_name>.<column_name>: evaluates to true if the column exists.

  • --NOCOLUMN <table_name>.<column_name>: evaluates to true if the column does not exist.

Software updates

The Configuration Agent software update mechanism is a deprecated mechanism for the distribution of patches and updates to the eSocket.POS application. All updates must now be distributed using the Upgrade Manager format. However, devices updates and other file downloads can still be distributed using this mechanism.

The eSocket.POS Configuration Agent polls for incoming software update zip files at the same time and in the same location that it polls for incoming XML configuration files. If the Configuration Agent is configured to connect to the ConfigServer, these files are first downloaded via HTTP. Software update files follow the naming convention esp_update<timestamp>.zip_ (or esp_update<timestamp>.jar_ for signed files).

Once the Configuration Agent has located a software update zip file, it unzips the contents of the zip, using the file root_dir.txt inside the zip to determine the root directory where the files must be unzipped to (e.g. c:\winnt\java\classes or /usr/eSocket.POS/classes). The file root_dir.txt is inserted into the zip file automatically by the ConfigServer, which allows the user to specify the location.

The mechanism for distributing software updates is as follows:

  • The retailer or ACI Worldwide prepares a ZIP file, which is unzipped into a particular location on the POS or store servers belonging to that retailer.

  • Using the central ConfigServer, the retailer associates the ZIP file with a particular terminal category and specifies the location where it is unpacked.

  • At some stage, the Configuration Agent on the POS or store server automatically contacts the ConfigServer. In response, the server sends the update ZIP files.

  • The Configuration Agent automatically unzips the ZIP file into the specified location.

  • Further processing may be applied if this is a device update ZIP file.

4.8. SSL

4.8.1. SSL - overview

eSocket.POS supports mutually authenticated SSL on all connection channels, i.e. for connections to PosConnect, ConfigServer, the PIN Entry Device (PED) and the POS. SSL to the PED is supported via a TCP/IP connection to the device. SSL to the POS is supported via the XML interface or the Message-Front-End.

eSocket.POS also provides the server-side legacy SSL authentication to PosConnect and ConfigServer which was previously offered by the eSocket.POS SSL Extension.

Since both of these SSL methodologies are supported, certain aspects of configuration are the same for both the current and the legacy SSL implementations and certain aspects of configuration differ. Configuration specific to the legacy implementation is documented in the Legacy SSL configuration section.

Key and certificate requirements for SSL authentication

For eSocket.POS to authenticate itself to a remote entity it requires an accessible private key and an identity associated with this key, in the form of an X.509 public key certificate.

When eSocket.POS authenticates a remote entity it requires access to trusted root certificates that are used to authenticate the certificate provided by the remote side of the connection.

The above mentioned keys and certificates must be made available on the POS, in the form of a Java keystore. Clients are required to create the keystore using a third party tool, and it must be distributed to eSocket.POS using a third party mechanism. ACI Worldwide recommends using the Sun Java Key and Certificate Management Tool to facilitate these operations. See https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html.

Note that eSocket.POS plays the role of the server when receiving connections from the POS application and it requires a private key to establish an authenticated SSL connection. This means that if eSocket.POS is required to authenticate the POS, it requires a private key, regardless of whether the remote entity needs to authenticate eSocket.POS

Certificate requirements for legacy SSL authentication

The legacy implementation uses a custom implementation for deciding if the server must be trusted. The certificate used by the server must be available on the POS itself. This certificate can be installed manually or delivered via ConfigServer or eSocket.POS stores (and trusts) the certificate it receives from the server during the SSL handshake, if it does not already have a certificate for that type of connection. The details of how this is done are explained in the Key store initialization topic.

4.8.2. SSL limitations

Use of SSL features requires:

  • The Java 1.4 or later virtual machine, which includes the Java Secure Socket Extension (JSSE).

  • The Bouncy Castle JCE security provider, which must be configured on the class path.

  • Only TLS v1.1 and TLS v1.2 can be used on Java 1.7 or Java 1.8.

  • SSL v3 and TLS v1 can only be used on Java 1.6 or earlier virtual machines.

  • Only legacy support is provided for SSL v2 on a version of the Java virtual machine that supports it.

While SSL can be implemented over any reliable connection orientated protocol, this implementation only supports SSL over TCP/IP based connections.

eSocket.POS does not support certificate revocation lists (CRLs). However, it does support validation of the common name from the issuer and subject distinguishable names in the X.509 certificate. This means that if the private key for any of the remote entities that are trusted by eSocket.POS becomes compromised, the eSocket.POS configuration has to be updated to not trust the common names from the certificate corresponding to the compromised key. The remote entity has to get a new certificate, either signed by another issuer, or with a different common name.

4.8.3. Managing keys and certificates

The SSL keystore and SSL truststore

In addition to the default eSocket.POS keystore used by the legacy SSL implementation, eSocket.POS requires up to two additional Java keystores:

  • eSocket.POS SSL truststore

    • This is a Java Keystore that contains trusted certificate entries which represent the trusted root certificates that can be used to authenticate remote entities.

    • Instructions for how to configure the SSL truststore can be found in the Configuring the SSL truststore topic.

  • eSocket.POS SSL keystore

  • This is a Java Keystore that contains key entries which represent the private keys, and the corresponding identities that can be used to authenticate the local side of the SSL connection.

  • Instructions for how to configure the SSL truststore can be found in the Configuring the SSL truststore topic.

ACI Worldwide recommends using the Sun Java Key and Certificate Management Tool to create the keystore and truststore and to manage these entities. See http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html. Some clients might also want to set up their own Certificate Authority for signing the certificates stored in the eSocket.POS SSL keystore; information on how to do this is beyond the scope of this document.

Warnings for old certificates

A certificate’s validity period is checked each time that it is selected for authenticating the local side of the SSL connection. A warning is logged if the certificate is invalid or if the certificate is valid, but the current date is close to the expiry date. This allows enough time to update the configuration, if it is required.

4.8.4. Configuration

Standard SSL configuration - overview

To enable standard SSL support in eSocket.POS, the following configuration must be done:

  • If eSocket.POS is required to authenticate the remote entity the SSL Trust Store must be configured.

  • If eSocket.POS is required to authenticate itself to the remote entity the SSL Key Store must be configured.

  • Configure SSL for TCP connections.

Configuring the SSL keystore

eSocket.POS requires access to the SSL keystore on the local machine to store key entries which represent the private keys and the corresponding identities that can be used to authenticate the local side of the SSL connection. The following eSocket.POS properties must be configured:

Property Description Default Required

postilion.esocketpos.ssl.KeyStorePath

The path to an SSL keystore. The file name must end with a .ks and it may not be located in the Configuration Agent incoming directory.

Not applicable

This property is required for eSocket.POS to authenticate itself to a remote entity during the establishment of an SSL connection.

postilion.esocketpos.ssl.KeyStoreType

The JCE keystore type. Possible values are

  • "BKS" - the Bouncy Castle Provider key store format.

  • "IAIKKeyStore" - The IAIK provider key store format.

  • "JKS" - Java key store format.

JKS

Not applicable

postilion.esocketpos.ssl.KeyStorePassword

The password to access the keystore. The same password must be used to protect the keystore and each of its entries.

Not applicable

Mandatory if postilion.esocketpos.ssl.KeyStorePath is configured.

Configuring the SSL truststore

eSocket.POS requires access to the SSL truststore on the local machine to store trusted certificate entries, which represent the trusted root certificates that can be used to authenticate remote entities. The following eSocket.POS properties must be configured:

Property Description Default Required

postilion.esocketpos.ssl.TrustStorePath

The path to the SSL truststore. The file name must end with a .ks and it may not be located in the Configuration Agent incoming directory.

Not applicable

This property is required if eSocket.POS authenticates remote entities using the default JSSE algorithm during the establishment of an SSL connection.

postilion.esocketpos.ssl.TrustStoreType

The JCE truststore type. Possible values are

  • "BKS" - the Bouncy Castle Provider key store format.

  • "IAIKKeyStore" - The IAIK provider key store format.

  • "JKS" - Java key store format.

JKS

Not applicable

postilion.esocketpos.ssl.TrustStorePassword

The password to access the truststore.

Not applicable

Mandatory if postilion.esocketpos.ssl.TrustStorePath is configured.

Configuring SSL on TCP connections

To enable SSL on TCP connections the EspTcpSapFactory must be configured as a custom SAP factory. The following named parameters are used in the setup data:

  • -ssl-type:

    • Required

    • This must be set to jsse.

  • -ssl-remote-auth:

    • Optional

    • The default is false for connections received by the XML Interface and the Message Front-end. It is true for other connections.

  • -ssl-iss-cn:

    • Optional

  • -ssl-sub-cn:

    • Optional

  • -ssl-local-cert:

  • Optional

This applies to configurations of:

Parameters in the SAP address for device connections

When using the ConfigServer configuration consoles, the setup data is associated with a 'Connection Type' as opposed to a specific connection. However, it is useful to specify different parameters for different devices, without adding a new connection type.

It has therefore been made possible to configure some of the parameters as part of the SAP address in the esp_device_config table. The format for the address is [host],[port] followed by any of the following named parameters:

  • -ssl-iss-cn

  • -ssl-sub-cn

  • -ssl-local-cert

4.8.5. Legacy SSL

Legacy SSL overview

eSocket.POS provides the legacy server-side SSL authentication to PosConnect and ConfigServer which used to be offered by the eSocket.POS SSL Extension. The eSocket.POS TCP SAP Factory can be configured for the RemoteSink and Configuration Agent to use for their outgoing connections. A Public Key Infrastructure (PKI) is also provided that allows trusted SSL server certificates to be distributed to the terminals through ConfigServer.

Legacy Configuration
Legacy SSL configuration - overview

To enable legacy SSL support in eSocket.POS, the following configuration must be done:

  • Configure the trusted Key Store - refer to the Security section of eSocket.POS properties page.

  • If eSocket.POS is required to authenticate itself to the remote entity the SSL Key Store must be configured.

  • Configure RemoteSink.

If Configuration Agent is configured for HTTP, and SSL is required over the connection, the following must also be configured.

Legacy SSL configuration - RemoteSink

To enable SSL on TCP connections to RemoteSink the EspTcpSapFactory must be configured as a custom SAP factory. The following named parameters are used in the setup data:

  • -ssl-type:

    • Required

    • This must be set to remotesink.

  • -ssl-remote-auth:

    • Optional

    • If set, this must be set to true.

  • -ssl-iss-cn:

    • Optional

  • -ssl-sub-cn:

    • Optional

  • -ssl-local-cert:

    • Optional

Legacy SSL configuration - Configuration Agent

To enable SSL on TCP connections to Configuration Agent the EspTcpSapFactory must be configured as a custom SAP factory. The following named parameters are used in the setup data:

  • -ssl-type:

    • Required

    • This must be set to configagent.

  • -ssl-remote-auth:

    • Optional

    • If set, this must be set to true.

-ssl-iss-cn: ** Optional

  • -ssl-sub-cn:

    • Optional

  • -ssl-local-cert:

    • Optional

Note
IIS uses different ports to service plain TCP and SSL. The default SSL port number is 443. The postilion.esocketpos.ConfigServerPort property must be configured accordingly.
Public key infrastructure
Public key infrastructure - overview

eSocket.POS provides a public key infrastructure (PKI): a strategy for delivering trusted server public key certificates to the eSocket.POS terminals. The terminals must have access to the certificates of the servers that they can trust, both for ConfigServer and for POSConnect. This involves two distinct operational activities:

Key store initialization

When an eSocket.POS terminal is configured for the first time, the trusted server certificates for the ConfigServer and PosConnect servers must be stored in the trusted key store. eSocket.POS provides support for both automatic and manual key store initialization.

Manual key store initialization

Before the trusted certificate can be stored at the terminal it must be retrieved from the Certificate Management console for PosConnect, or from IIS for ConfigServer, and stored in a certificate file that is named according to the following convention: <alias>.cer

Where the alias is described as follows:

  • For PosConnect certificates: POSCONNECT_SSL_yymmdd where yymmdd is date that the key pair was generated by the CMS.

  • For ConfigServer (IIS) certificates: CONFIGSERVER_SSL_yymmdd where yymmdd is date that the key pair was generated by the IIS.

At the eSocket.POS terminal, the certificate can be loaded manually.

Automatic key store initialization

If no trusted certificate is manually loaded for eSocket.POS or for Configuration Agent, the first connection made to each of the two servers are trusted. The certificate provided by the server during this first SSL handshake is stored in the key store and are trusted from then on. When this occurs, an informational event are logged with the credentials of the certificate so that they can be inspected manually.

This is slightly less secure than the manual initialization, because new terminals could be deceived if the first connection they make is to an attacker’s server (for example, in a man-in-the-middle attack). However, the risk of this kind of breach can be reduced significantly by inspecting the credentials that are logged.

Certificate renewal
Certificate renewal - overview

Before the ConfigServer or PosConnect SSL certificate expires, a new certificate must be acquired and delivered to every terminal. The following steps must be followed in both cases:

  1. Generate a new key pair and Certificate Signing Request (CSR).

  2. Send the CSR to a Certificate Authority to be signed.

  3. Update the server with the signed certificate but continue using the old certificate.

  4. Retrieve the new certificate from the server.

  5. Deliver the new certificate to the terminals using ConfigServer or update the certificate manually at the terminal.

  6. After a sufficient period, when all terminals are successfully updated, change to the new certificate. This can be determined using the eSocket.POS Configuration Server Query console.

The details of steps 1-5 and 6 are slightly different for PosConnect and for ConfigServer. However, step 5 is the same. Once the certificate file is retrieved, it must be stored in a file with the required naming convention, <alias>.cer , where the alias is described below:

  • For PosConnect certificates: POSCONNECT_SSL_yymmdd where yymmdd is the date that the key pair was generated by the CMS.

  • For ConfigServer (IIS) certificates: CONFIGSERVER_SSL_yymmdd where yymmdd is date that the key pair was generated by the IIS.

The certificate file can then be scheduled for delivery to each eSocket.POS instance by using the ConfigServer Store and Terminal console. The certificate file must be registered separately for each Terminal Profile.

  1. Log in to the ConfigServer Store and Terminal console (if not already logged in).

  2. Select the Profiles page.

  3. Select the Terminal-Profiles sub-page.

  4. Add the certificate file by clicking the Add File(s) for Transfer button.

  5. Select a Terminal Profile.

  6. Click OK when done.

If ConfigServer is not in use, the certificate can be manually updated at the terminal.

Certificate renewal - PosConnect

The first four steps are done through the Certificate Management console and are described in detail in the Realtime Framework User Guide. The alias chosen in the first step must be named according to the following convention:

POSCONNECT_SSL_yymmdd

Where: yymmdd is date that the key pair is generated by the CMS. The final step is done on the Terminal Applications tab of the Applications Configuration console.

  1. Generate a new key pair and Certificate Signing Request (CSR).

  2. Send the CSR to a Certificate Authority to be signed.

  3. Update the server with the signed certificate but continue using the old certificate. Do not update the SAP configuration yet.

  4. Retrieve the new certificate from the Certificate Management console.

  5. Deliver the new certificate to the terminals using ConfigServer - as described on the Certificate renewal - overview page.

  6. When all terminals have been updated, change to the new certificate: update the PosConnect application SAP, by selecting the new SSL certificate from the drop-down list of aliases.

Certificate renewal - ConfigServer

Before the ConfigServer or PosConnect SSL certificate expires, a new certificate must be acquired and delivered to every terminal. In both cases, following these steps:

  1. Generate a new key pair and Certificate Signing Request (CSR):

    1. Click the Start button and select Settings > Control Panel > Administrative Tools > Computer Management.

    2. Expand Services and Applications > Internet Information Services > Default Web Site.

    3. Right-click Default Web Site and select Properties and click the Directory Security tab.

    4. In the Secure Communications section, click the Server Certificate…​ button.

    5. Follow the Web Server Certificate Wizard to create a CSR:

      1. Select Renew the current certificate.

      2. The wizard can send the CSR online to a CA automatically, or it can generate a CSR file that can be sent to the CA later.

  2. Send the CSR to a Certificate Authority to be signed.

  3. Update the server with the signed certificate:

    1. Click the Start button and select Settings > Control Panel > Administrative Tools > Computer Management .

    2. Expand Services and Applications > Internet Information Services > Default Web Site.

    3. Right-click Default Web Site and select Properties. Click the Directory Security tab.

    4. In the Secure Communications section, click the Server Certificate…​ button.

    5. Follow the Web Server Certificate Wizard.

      1. Select Process the pending request and install the certificate.

      2. This updates and activates the server with the signed server certificate.

  4. Retrieve the new certificate from the server. This must be done before step 5 so that the new certificate is retrieved.

  5. Before restarting IIS, update it to continue using the old certificate:

    1. From the Start button, go to Settings > Control Panel > Administrative Tools > Computer Management.

    2. Expand Services and Applications > Internet Information Services > Default Web Site.

    3. Right-click Default Web Site and select Properties. Click the Directory Security tab.

    4. In the Secure Communications section, click the Server Certificate…​ button.

    5. Follow the Web Server Certificate Wizard:

      1. Select Replace the current certificate.

      2. Select the previous certificate from the list, identifying it by its expiry date.

    6. Restart IIS.

  6. Deliver the new certificate to the terminals using ConfigServer (as described in Certificate renewal - overview).

  7. When all terminals have been updated, change to the new certificate:

    1. From the Start button, go to Settings > Control Panel > Administrative Tools > Computer Management.

    2. Expand Services and Applications > Internet Information Services > Default Web Site.

    3. Right-click Default Web Site and select Properties. Click the Directory Security tab.

    4. In the Secure Communications section, click the Server Certificate…​ button.

    5. Follow the Web Server Certificate Wizard:

      1. Select Replace the current certificate.

      2. Select the new certificate from the list, identifying it by its expiry date.

    6. Restart IIS.

Certificate retrieval
Retrieving a local SSL certificate from the CMS

The Certificate Management console provides the ability to retrieve a public key certificate from the Certificate Manager Service (CMS) for distribution, as described below:

  1. Select Modify on the chosen certificate under the Local Certificates tab.

  2. Click the Retrieve Certificate tab of the Modify Local Certificate dialog box.

  3. Select the appropriate certificate name (alias) from the drop-down list in the Available Alias field.

  4. Click the Get Certificate For Alias button. The certificate contents are returned as a single certificate in a Base64 DER encoded format and shown in the text display area on this page.

  5. Click the Save Certificate button.

  6. Specify a name for the file and provide a location to which the file must be copied for storage. The file must be named using the required naming convention.

  7. Click the Close button once completed.

Retrieve a local SSL certificate from IIS

IIS provides the ability to retrieve a public key certificate for distribution:

  1. Click Start > Settings > Control Panel > Administrative Tools > Computer Management.

  2. Expand Services and Applications > Internet Information Services > Default Web Site.

  3. Right-click the Default Web Site , and select Properties > Directory Security tab.

  4. In the Secure Communications section, click the View Certificate…​ button.

  5. On the Details tab, click the Copy to File…​ button.

  6. Follow the Certificate Export Wizard using the following options:

    1. Do not export the private key.

    2. Use Base 64 Encoded X.509 (.CER)

    3. Name the file according to the required naming scheme.

Configuration - payments system
Payments system

With the exception of the requirement below, the configuration of the payments system is beyond the scope of this document. See the relevant payments system documentation for details.

On the Source Nodes page of the Transaction Manager Configuration console:

  • Make sure the source node is configured to reconcile per terminal, if reconciliation is required. In addition, if the POS does not initiate cutover, make sure the Auto Settle option is selected.

PosConnect

With the exception of the requirement below, the configuration of the PosConnect source node is beyond the scope of this document. See the PosConnect User Guide for details.

On the Terminal Applications page of the Realtime Applications Configuration console:

  • Set the SAP to match the port specified in the last parameter of RemoteSink in the params column of the esp_classes table.

4.9. Point-to-point encryption

4.9.1. Point-to-point encryption overview

Point-to-point encryption (P2PE) entails the PED using an encryption mechanism, DUKPT in this case, on sensitive cardholder data before sending the card details to eSocket.POS. eSocket.POS needs access to parts of the sensitive card holder data to perform basic validation and other processing. When P2PE is enabled, the PED sends track 1, track 2, and track 3 data to eSocket.POS with the minimal clear text that eSocket.POS requires. The rest of the text is obfuscated (replaced with zeroes). Decryption is performed at PosConnect using the configured P2PE scheme, with the help of the configured HSM.

Supported hardware requirements
  • P2PE is not supported by all device manufacturers. Check if your PED models support P2PE before attempting configuration.

  • Not all HSM models support the decryption commands required for P2PE. Check that the correct HSM manufacturer is used, and that the correct firmware is applied.

4.9.2. P2PE limitations

  • With point-to-point encryption enabled, eSocket.POS no longer has access to all of the discretionary track data. The following information is inaccessible, and consequently cannot be provided to the POS:

    • Card sequence number - This means that it will not be delivered in offline stand-in advice messages.

    • Cardholder name - Not available in responses to the POS for magnetic stripe transactions.

    • Effective date checking - Not possible for magnetic stripe transactions.

  • The implementation supports only the Thales RG8000 HSM with updated firmware that includes support for DUKPT BDKs in the Decrypt Data Block (M2) command. Contact your primary support provider for more information on this.

  • The implementation supports only a 3DES DUKPT-based solution.

4.9.3. Configuring eSocket.POS for P2PE

Configuring the Point-To-Point Encryption solution is a task that encompasses multiple servers. The configuration of the cryptographic keys required by PosConnect to perform the decryption falls outside the scope of this user guide.

As part of configuring point to point encryption, the following transaction engine pipeline components in eSocket.POS must be customized:

See the relevant pages for information about configuring these pipeline components.

NOTE

Some P2PE terminals require whitelist files. Refer to the PosConnect User Guide and Configuration Server User Guide for more information on how to load, sign, and distribute these files to eSocket.POS and the PED.

Ghosting of card holder data

For eSocket.POS to perform basic validation, it needs access to parts of the sensitive card holder data. When P2PE is enabled, the PED sends track 1, track 2, and track 3 data to eSocket.POS with the minimal clear text that eSocket.POS requires to perform basic validation. The rest of the text is ghosted (i.e. replaced with zeroes).

Whitelist files

Not all cards that are accepted at the POS require point-to-point encryption, for example gift cards. Whitelist files are files containing a list of BINs for which P2PE should not be performed.

  • Whitelist files are loaded and signed at PosConnect. See the PosConnect User Guide for details on configuring whitelist files.

  • If a whitelist file is in use, then the WhiteListFileName extended parameter in the PAN Component needs to be set to the correct name. This extended parameter links eSocket.POS to the whitelist file that was loaded and signed at PosConnect.

  • The whitelist file must be loaded onto the PED. The file can be distributed from ConfigServer to eSocket.POS via either the Named Parameters functionality, or with the Add Files for transfer mechanism in place.

4.10. End-to-end encryption

4.10.1. VeriShield encryption

VeriShield is an end-to-end encryption scheme that uses format-preserving encryption (FPE) when protecting sensitive cardholder data in authorization messages to processors. When VeriShield is enabled, the PED sends track data to eSocket.POS with the minimum clear text that eSocket.POS requires. The PED encrypts the remaining clear text and replaces it with the resulting cryptogram. The cryptogram is such that the format of the track data is preserved. Decryption is performed upstream at a processor that supports VeriShield encryption.

Note
  • VeriShield encryption is not supported by all device manufacturers.

  • Currently, eSocket.POS supports VeriShield encryption in a configuration using eSocket ITK, Verifone FormAgent devices that support VeriShield, and the eSocket.POS Verifone FormAgent Device Driver.

For VeriShield encryption on eSocket.POS, you must configure the following transaction engine pipeline components:

If the processor involved supports TransArmor along with VeriShield encryption, the Verishield TransArmor pipeline component also needs to be configured.

To configure the Verifone device driver or the eSocket ITK interface, see the relevant user guides provided with the software.

4.10.2. TransArmor non-format-preserving encryption

TransArmor end-to-end encryption uses non-format-preserving encryption (non-FPE) when protecting sensitive cardholder data in authorization messages to First Data. An example of TransArmor non-format-preserving encryption is the TransArmor RSA encryption scheme. When enabled, the PED sends obfuscated track data to eSocket.POS. Furthermore, the PED passes the full, encrypted track data upstream. Decryption is performed upstream by First Data.

Note
  • Currently, eSocket.POS only supports TransArmor non-format-preserving encryption when the POS drives the PED. As such, the onus is on the POS to supply obfuscated and encrypted track data.

  • TransArmor non-format-preserving encryption is currently only supported on the eSocket.POS XML interface or <<API.adoc#lnk_API,API>.

For TransArmor non-format-preserving encryption on eSocket.POS, you must configure the PAN pipeline component (see the "PAN Encryption" parameter).

4.11. Acquirer specific configuration

4.11.1. Acquirer specific configuration

Oney overview

This page provides an overview of all required configuration for processing Oney cards.

ConfigServer - File Transfer Loader

The File Transfer Loader needs to be configured on the ConfigServer Base Configuration console and needs to be configured to send Oney OPC files with a .oney extension.

The Delivery and Feedback Location should be configured to the directory where the .oney files are loaded.

The Delivery Extensions should be configured to include the .oney extension.

When running this utility from the command line, set the FileValidator as postilion.espconfigserver.loaders.OneyFileValidator to validate the .oney files.

Example command: csjava.exe postilion.espconfigserver.loaders.FileTransferLoader postilion.espconfigserver.loaders.OneyFileValidator

Configuring the system properties
  1. Log in to the Base Configuration console.

  2. Select the System Properties page.

  3. Modify the system properties by selecting the Modify edit option, or by clicking the Modify button.

Please see the eSocket.POS Configuration Server User Guide for more information on running the File Transfer Loader, as well as how the result files are generated after the transfer files are processed by the applicable terminals.

The recommended approach is loading the .oney file to all terminals by setting the terminal ID to the value ALL.

Example: OPC<retailer_id>_ALL.oney_

The .oney file contains fixed length comma-separated fields, shorter values should be padded with a space character, validated as per the definition below:

Field Notes Format Example

mid

Can contain digits or spaces.

ans..10

0065082900

extended_bin

Must contain digits and may be appended with question marks (?)

ns10

49715200??

code_support

-

an..5

CABAN

code_support_label

-

ans..32

CB AUCHAN

pin_code_flag

Can be any of the following: 0, 1, or 2

n1

1

allow_cancellations

A value of O (Oui/Yes) will be saved as 1, anything else will be saved as 0

a1

O

allow_refunds

A value of O (Oui/Yes) will be saved as 1, anything else will be saved as 0

a1

N

opc_code

-

an5

AH044

short_label

-

ans..10

EN 4X

long_label

-

ans..32

  • 4 X SANS FRAIS

opc_type

Can contain any of the following digits: 0, 1, 2, 3, 4, 6

n1

0

start_date

Date field which must be in the format DD/MM/CCYY

ns10

12/12/2017

end_date

Date field which must be in the format DD/MM/CCYY

ns10

31/12/2035

opc_display_order

Digits only. Values must be prepended with zeroes.

n2

03

standin_amount

Digits only. Values must be prepended with zeroes.

n10

0000000300

ConfigAgent - OneyConfigModuleProcessor

eSocket.POS should be configured with the Oney Config Module Processor that is used to load Oney configuration from the Acquirer into the eSocket.POS database in the Oney OPC table .

OneyConfigModuleProcessor must be configured in the eSocket.POS properties file using the following tag and value:

Property: postilion.esocketpos.ConfigAgentModuleProcessors

Value: postilion.esocketpos.oney.OneyConfigModuleProcessor

Example: postilion.esocketpos.ConfigAgentModuleProcessors = postilion.esocketpos.oney.OneyConfigModuleProcessor

The following properties may additionally configured in the eSocket.POS Properties file for OneyConfigModuleProcessor:

Property Description

postilion.esocketpos.oney.OneyConfigModuleProcessor.ConfigPollStartTime

The time at which the OneyConfigModuleProcessor must begin polling for incoming configuration files. This value is only used when the Configuration Agent starts up. Since all subsequent polls are performed relative to this first one, this start time provides some mechanism for effecting a poll at a specific time.

For example, configuring the OneyConfigModuleProcessor to start at 00:00 with a poll interval of 24 hours results in a poll once a day at midnight.

The value for this property must be a 4-digit 24-hour time.

Example:
1500 (3pm)

If not specified, the default value is 9999 and indicates that the action file must be processed at startup.

postilion.esocketpos.oney.OneyConfigModuleProcessor.ConfigPollOnStartUp

Indicates that OneyConfigModuleProcessor must process the action files immediately after the Configuration Agent starts.

Example: True

If not specified, the default value is FALSE, indicating that files should not be processed immediately on startup.

postilion.esocketpos.oney.OneyConfigModuleProcessor.ConfigPollInterval

The time (in minutes) that OneyConfigModuleProcessor must wait between polls for configuration files. If set to 0, the load is only attempted once.

If not specified, the default value is 0.

postilion.esocketpos.oney.OneyConfigModuleProcessor.RetryAttempts

The number times that OneyConfigModuleProcessor must retry to poll after a failed attempt at polling.

If not specified, the default value is 5.

postilion.esocketpos.oney.OneyConfigModuleProcessor.RetryInterval

The time (in seconds) that OneyConfigModuleProcessor must wait before retrying to poll after a failed attempt at polling.

If not specified, the default value is 30.

eSocket.POS - Transaction Engine

The following pipeline components need to be configured to support the processing rules:

These components all extend their non-Oney specific counterparts and will therefore replace them in the respective pipelines.

Pipeline component - Oney OPC

The Oney OPC pipeline component replaces and extends the base functionality in the OPC pipeline component. It first attempts to select the OPC information from the Oney-specific OPC table, and will fall back to the standard OPC data if no Oney-specific information is found. This component also requires the Card acceptor ID code pipeline component to be configured in order to set the card acceptor ID code (field 42) which is used when retrieving the Oney OPC information.

Note: The component includes the functionalities of the standard eSocket.POS OPC pipeline component.

Usage: If configured, must be present in both Request and Response Pipelines, optional.

If configured, do not configure the OPC pipeline component.

Rank: Must be configured after the PAN, Card acceptor ID code and Cashback components, but before the PIN component.

Class name: postilion.esocketpos.oney.PipelineComponentOneyOpc

Parameters: None

Pipeline component - Oney PIN

Description: The Oney PIN component replaces and extends the standard eSocket.POS PIN pipeline component. It is responsible for checking whether a PIN is required for the transaction being processed, based on the Oney OPC data set in this transaction.

Note: The component includes the functionalities of the standard eSocket.POS PIN pipeline component.

Note: The this component does not change the behavior of the standard eSocket.POS PIN pipeline component when processing EMV transactions.

Usage: Request and Response pipelines, optional. Must not be configured if there is no PIN pad configured.

The Request pipeline becomes mandatory, when the Response pipeline is required.

If configured, do not configure the PIN pipeline component.

Rank: Must be configured after the PAN , OPC , Account and EMV components, but before the Stand-in component.

Class name: postilion.esocketpos.oney.PipelineComponentOneyPin

Parameters: See the PIN pipeline component page for more information about configuring the PIN component.

Pipeline component - Oney Transaction Allowed

Description: The Oney Transaction Allowed component replaces and extends the base functionality in the Transaction Allowed pipeline component.

It checks if the transaction being processed is allowed, based on the Oney OPC data set in this transaction.

If the transaction is a refund transaction and the Oney OPC data has the Allow Refunds option selected, then the component will not decline the transaction.

If the transaction is a reversal transaction that was not generated by eSocket.POS and the Oney OPC data has the Allow Reversals option selected, then the component will not decline the transaction.

Note: The component includes the functionalities of the standard eSocket.POS Transaction Allowed pipeline component.

Usage: Request pipeline, optional.

If configured, do not configure the Transaction Allowed pipeline component.

Rank: Must be configured immediately after the Oney OPC component.

Class name: postilion.esocketpos.oney.PipelineComponentOneyTransactionAllowed

Parameters: The component does not have any configurable parameters.

Decline conditions:

Condition Response Code Message Reason Code

The transaction is a reversal transaction that is not generated by eSocket.POS, and the Oney OPC data does not allow reversal transactions.

57 - Transaction not permitted to cardholder

9756 - Not Valid for Transaction

The transaction is a refund transaction, and the Oney OPC data does not allow refund transactions.

57 - Transaction not permitted to cardholder

9756 - Not Valid for Transaction

4.12. Configure eSocket.POS to operate with the mPOS Bridge

The mPOS Bridge provides communication between eSocket.POS and the supported mobile device. To configure eSocket.POS to operate with the mPOS Bridge, configure the following config parameters:

See the relevant device driver user guide for the steps to configure the mposmetaimpl and the MOBILE_DEVICE parameters.

4.13. RFID processing

RFID processing occurs when an RFID tag is used for payment.

RFID processing is not supported by all device manufacturers. Currently eSocket.POS supports RFID processing when used with Verifone FormAgent devices that support RFID processing. These devices use either the eSocket.POS Verifone FormAgent Device Driver or the eSocket.POS Verifone XPI Device Driver.

For RFID processing on eSocket.POS, you must configure the following pipeline components:

To configure the Verifone device driver, see the relevant user guides provided with the software.

4.14. Quick Chip Processing

The Quick Chip solution allows for early removal of the chip card from the terminal, while relying on standard EMV processing between the card and terminal. It removes the need for EMV processing to wait for the final transaction amount, authorization response, and post-authorization processing (such as script processing and issuer authentication).

Traditionally, two factors associated with standard contact chip processing can make the transactions potentially slower than magnetic stripe transactions, while significantly increasing the perception that the transaction is slow:

  • The chip terminal waiting for the final amount before completing cardholder verification method processing and requesting data for online authorization from the card.

  • The card remaining in the reader until the authorization response is received from the issuer.

The Quick Chip solution overcomes both of these constraints.

Quick Chip:

  • Significantly reduces time of card in terminal as part of critical path, by eliminating dependencies, allowing for improved throughput

  • Provides the same EMV level of security for online authorizations, including the cryptogram

  • Improves consumer perceived throughput time (particularly important where the cardholder hands over their card to a clerk)

  • Lessens cardholder friction by reducing wait time for card removal, consequently also reducing the frequency of cardholders leaving their card behind in the terminal

  • Integrates with US Common Debit AID processing

  • Integrates with Visa Easy Payment Service (VEPS) that allows qualified merchants to process small value transactions without requiring a Cardholder Verification Method or issuing a transaction receipt (unless requested by the cardholder)

  • Supports all cardholder verification methods

    NOTE

    All Quick Chip transactions must be authorized online, and are suitable only for Online Only terminal configurations. The EMV Terminal Floor Limit must remain at zero for Quick Chip transactions. This in combination with the TAC-Online Transaction Exceeds Floor Limit (Byte 4, bit 8) = 1 will result in the EMV kernel requesting an Authorization Request Cryptogram (ARQC) from the chip card.

Quick Chip EMV Pre-swipe Processing:

eSocket.POS supports initiating an EMV interaction, retrieving the track2 equivalent data from an EMV card, and performing cryptogram generation during the pre-swipe phase of a transaction when the transaction amount is still unknown and Quick Chip is enabled. This is to support POS environments where the transaction amount or flows need to be adjusted based on the type of card (BIN) presented by the cardholder.

For eSocket.POS to support Quick Chip EMV Pre-swipe processing, the terminal parameter QUICK_CHIP_PREDETERMINED_AMOUNT needs to be configured. See the table below, which describes Quick Chip custom parameter configuration, for details.

Quick Chip EMV Pre-swipe Flow:

  • For EMV reads during pre-swipe with Quick Chip processing, Pipeline Component EMV uses the configured Quick Chip Predetermined Amount. It then performs all card interactions during the pre-swipe phase of the transaction and prompts for card removal. The data obtained from card interactions is picked up by the subsequent 0100 or 0200 transaction and sent upstream for authorization.

  • During the pre-swipe phase of the transaction, the customer may continue with account selection, PIN entry, and cashback entry, depending on the card and the eSocket.POS pipeline configuration.

  • Pipeline Component Confirm prompts for amount confirmation during the 0100 or 0200 transaction once the final amount is known.

    NOTE

    If Cashback is performed, the Amount, Authorized field (tag 9F02) is populated with the sum of the predetermined amount and the cash back amount. All other amount fields are populated as for a standard EMV cash back transaction.

Check the table below for detailed descriptions on the Quick Chip custom parameters.

Parameter Name Format Description Example Value

ENABLE_QUICK_CHIP

n1

The terminal parameter ENABLE_QUICK_CHIP provides a configuration option to configure a POS Terminal/PED to process Quick Chip transactions. The configuration is "1" (enable) or "0" (disable) for all transactions performed at a specific device/terminal.

1

ENABLE_CTLS_QUICK_CHIP

n1

The terminal parameter ENABLE_CTLS_QUICK_CHIP provides a configuration option to configure a POS Terminal/PED to process Quick Chip for contactless transactions. The configuration is "1" (enable) or "0" (disable) for all contactless transactions performed at a specific device/terminal.

NOTE

This parameter is dependent on ENABLE_QUICK_CHIP and can only be configured when ENABLE_QUICK_CHIP parameter is set to 1.

1

QUICK_CHIP_PREDETERMINED_AMOUNT

n..12

The terminal parameter QUICK_CHIP_PREDETERMINED_AMOUNT provides a configuration option to configure a POS Terminal/PED with Quick Chip Predetermined (Placeholder) Amount for processing Quick Chip transactions. The Quick Chip Predetermined Amount value must be a numeric value expressed in minor denomination and is used for both contact and contactless quick chip.

5000

4.14.1. Configure the terminal to enable Quick Chip:

For the required terminal profile, configure the ENABLE_QUICK_CHIP value as a custom parameter by completing the following two tasks.

Add a parameter definition:

  1. From the Software Components Configuration console, select the Parameter Definition tab, and click the Add New button. The New Custom Parameter window appears and prompts for information.

  2. Enter the Tag value as ENABLE_QUICK_CHIP.

  3. Enter the Name value as enable quick chip for EMV , or any other identifiable value.

  4. Select n from the Format drop-down list.

  5. Specify the Length as exactly 1.

  6. Click Save + Exit when done.

Add a new parameter:

  1. From the Store and Terminal Configuration console, select the Profiles > Components tabs.

  2. Select the required Terminal Profile from the drop-down list.

  3. From the Parameter Values tab, click the Add New button to add a new parameter.

  4. Search for the ENABLE_QUICK_CHIP tag created before, and then select it.

  5. Specify the desired value in the Value field. Set value to 1, to enable Quick Chip on the terminal. Default value is disabled (0).

  6. Click Save + Exit when done.

4.14.2. Configure the terminal to enable Contactless Quick Chip:

For the required terminal profile, configure the ENABLE_CTLS_QUICK_CHIP value as a custom parameter by completing the following two tasks.

Add a parameter definition:

  1. From the Software Components Configuration console, select the Parameter Definition tab, and click the Add New button. The New Custom Parameter window appears and prompts for information.

  2. Enter the Tag value as ENABLE_CTLS_QUICK_CHIP.

  3. Enter the Name value as enable quick chip for contactless EMV , or any other identifiable value.

  4. Select n from the Format drop-down list.

  5. Specify the Length as exactly 1.

  6. Click Save + Exit when done.

Add a new parameter:

  1. From the Store and Terminal Configuration console, select the Profiles > Components tabs.

  2. Select the required Terminal Profile from the drop-down list.

  3. From the Parameter Values tab, click the Add New button to add a new parameter.

  4. Search for the ENABLE_CTLS_QUICK_CHIP tag created before, and then select it.

  5. Specify the desired value in the Value field. Set value to 1, to enable Quick Chip on the terminal. Default value is disabled (0).

  6. Click Save + Exit when done.

4.14.3. Configure the Quick Chip Predetermined Amount:

For the required terminal profile, configure the QUICK_CHIP_PREDETERMINED_AMOUNT value as a custom parameter by completing the following two tasks.

Add a parameter definition:

  1. From the Software Components Configuration console, select the Parameter Definition tab, and click the Add New button. The New Custom Parameter window appears and prompts for information.

  2. Enter the Tag value as QUICK_CHIP_PREDETERMINED_AMOUNT.

  3. Enter the Name value as set quick chip predetermined amount for EMV , or any other identifiable value.

  4. Select n from the Format drop-down list.

  5. Specify the Length as upto 12.

  6. Click Save + Exit when done.

Add a new parameter:

  1. From the Store and Terminal Configuration console, select the Profiles > Components tabs.

  2. Select the required Terminal Profile from the drop-down list.

  3. From the Parameter Values tab, click the Add New button to add a new parameter.

  4. Search for the QUICK_CHIP_PREDETERMINED_AMOUNT tag created before, and then select it.

  5. Specify the desired value in the Value field. The desired value should be a numeric value expressed in minor denomination.

  6. Click Save + Exit when done.

4.15. Configure rapid payment service processing

For rapid payment service processing (RPS) to work on eSocket.POS, you must configure the RPS pipeline component. Then complete the following tasks to configure RPS for magnetic stripe and EMV cards.

4.15.1. Configure RPS for magnetic stripe cards (contact and contactless)

You must configure RPS for magnetic stripe cards on the ConfigServer Cards Configuration console as follows:

  1. Go to Account Profile > Limits and set the RPS Limit. Transactions whose values exceed this limit do not qualify for RPS.

  2. Go to Account Profile and select the RPS Mode:

    • If set to Yes but must be forced online , then stand-in is not allowed for an RPS transaction. If eSocket.POS is offline then no transaction is marked as a valid RPS transaction, and normal stand-in processing applies. The default behavior can be modified to allow offline stand-in for forced online RPS transactions. See the OFFLINE_AUTH_ALLOWED_PROGRAMS parameter of the RPS pipeline component for more information.

    • If set to Yes and can be offline , eSocket.POS always performs stand-in for RPS transactions, even if the RPS limit exceeds the normal stand-in limit.

  3. Go to Account Profile and set the RPS Program to MasterCard or Visa.

    • MasterCard RPS transactions do not require a signature (PIN requirements remain unchanged). Acceptable PAN entry modes are 02 (Magnetic Stripe), 90 (Magnetic stripe pure), and 91 (Contactless Magnetic Stripe). MasterCard RPS overrides the service restriction code.

    • Visa RPS transactions do not require a signature or PIN. Applicable PAN entry modes are 90 (Magnetic Stripe pure) and 91 (Contactless Magnetic Stripe). Fallback transactions do not qualify for Visa RPS. Visa RPS does not override the service restriction code.

      NOTE

      You can configure the RPS program(s) for which PIN entry may be bypassed with the RPS_PIN_BYPASS parameter on the PIN component.

4.15.2. Configure RPS for EMV contact cards (including Quick Chip)

NOTE

RPS for EMV contact cards is currently only supported for custom EMV RPS programs. See the CUSTOM_EMV_CONFIGURATION parameter of the RPS pipeline component.

You must then complete the following configuration on the ConfigServer Cards Configuration console:

  1. Go to Account Profile and set the RPS Mode to anything other than None.

  2. Go to Account Profile and set the RPS Program to anything other than None.

  3. Go to EMV Card Parameters > AID Parameters and set the RPS_CVM_CAPABILITY entry (1 byte in hexadecimal format) under Custom Data.

Applicable PAN entry modes are 05 (ICC) and 07 (Auto entry via contactless ICC). The device driver must support RPS for EMV contact transactions for this processing to occur.

4.16. Wallet Payments Processing

Wallet Payments are initiated by the POS with a wallet payment type and a barcode data. These transactions are not card based transactions and thus are routed using receiving institution ID code to the appropriate host.

A Wallet Payment transaction is initiated by the POS with the following mandatory fields:

  • WalletPaymentType (set to value Alipay)

  • BarcodeData

The POS might also set the following optional fields in the transaction:

  • Quantity

  • TransactionName

  • StoreId

  • Memo

eSocket XML interface maps these fields in the following Structured Data subfields:

  • Structured Data Tag WalletPaymentType

  • Structured Data Tag BarcodeData

  • Structured Data Tag Quantity

  • Structured Data Tag TransactionName

  • Structured Data Tag StoreId

  • Structured Data Tag Memo

When the transaction reaches the Alipay pipeline component, all these Structured Data tags are removed and formatted into the Structured Data tag WalletPayment which is further sent upstream.

For Wallet Payment support, you must configure the following transaction engine pipeline component:

Check the table below for detailed descriptions on the Wallet Payment custom parameters.

Parameter Name Format Description Example Value

WALLET_PAYMENT_DISPLAY

n1

The terminal parameter 'WALLET_PAYMENT_DISPLAY' provides a configuration option to configure a POS Terminal/PED to enable the device display for the wallet payment transactions. The configuration is "1" (enable) or "0" (disable) for all transactions performed at a specific device/terminal. Default value is "0" (disabled).

WALLET_PAYMENT_DISPLAY = 1

4.16.1. Configure the terminal to enable device display for the Wallet Payment Transactions:

For the required terminal profile, configure the WALLET_PAYMENT_DISPLAY value as a custom parameter by completing the following two tasks.

Add a parameter definition:

  1. From the Software Components Configuration console, select the Parameter Definition tab, and click the Add New button. The New Custom Parameter window appears and prompts for information.

  2. Enter the Tag value as WALLET_PAYMENT_DISPLAY.

  3. Enter the Name value as enable display for wallet payments , or any other identifiable value.

  4. Select n from the Format drop-down list.

  5. Specify the Length as exactly 1.

  6. Click Save + Exit when done.

Add a new parameter:

  1. From the Store and Terminal Configuration console, select the Profiles > Components tabs.

  2. Select the required Terminal Profile from the drop-down list.

  3. From the Parameter Values tab, click the Add New button to add a new parameter.

  4. Search for the WALLET_PAYMENT_DISPLAY tag created before, and then select it.

  5. Specify the desired value in the Value field. Set value to 1, to enable the display for the wallet payments on the terminal. Default value is disabled (0).

  6. Click Save + Exit when done.

4.17. OPC payments processing

OPCs define how transactions should be processed by the issuer. The OPC for a transaction combines both the transaction type, as well as possible customer benefits.

Transaction types may include 'sale', 'giftcard activation', and others.

Customers using retailer cards are extended a benefit by the retailer, through a choice of payment plans (OPCs). Some examples of payment plans are:

  • Pay in full with immediate debit.

  • Pay in full with deferred debit (at the end of the current month).

  • Pay in x monthly installments.

The list of OPCs that is displayed is dependent on what OPCs are configured. There are multiple ways to configure these. Please see the Oney Overview and OPC Configuration Pipeline Component pages for more information.

If there are no OPCs configured that match a card that is eligible for OPC processing then a default OPC may be used. This default OPC may be configured on the card profile or it may be configured as terminal parameters. A default OPC configured on the card will take preference over on configured as terminal parameters.

If the OPC Pipeline Component is configured, eSocket.POS will process OPC transactions.

To enable OPC processing for eligible cards in eSocket.POS, the following tasks should be completed:

Configure cards that are eligible for OPC processing.

You must configure OPC processing for cards on the ConfigServer Cards Configuration console as follows:

  1. Go to Card Profiles, select a card profile to edit, and check the OPC selection (mandatory).

  2. If required, provide a default OPC value for the card.

To process EMV cards, the parameter 'OPC_TAG' should also be configured. See the table below for more information.

Configure optional terminal parameters

The following extended parameters can be configured on a Terminal Profile for OPC processing.

Tag Format Description Example Value

OPC_TAG

ans…​40

` This parameter determines which EMV tag to use as the code support. The code support is used to link an EMV card to a list of OPCs that are selectable for that card. OPC processing will not occur for EMV cards if this is not configured. This parameters value is configured in the format: <EMV tag>:<Expected length of tag on the card>.

DF2F:5

DEFAULT_OPC_CODE

an..5

This parameter defines a default OPC value to be used if there are no matching OPCs for the card in the OPC configuration tables, and if the card does not have a default OPC configured. This value is populated in the message and will be sent upstream to the acquirer.

00001

DEFAULT_OPC_SHORT_LABEL

ans..40

This parameter defines a default OPC short label value to be used if there are no matching OPCs for the card in the OPC configuration tables, and if the card does not have a default OPC configured. If configured, this value is used for receipt printing.

CREDIT

DEFAULT_OPC_LONG_LABEL

ans..40

This parameter defines a default OPC long label value to be used if there are no matching OPCs for the card in the OPC configuration tables, and if the card does not have a default OPC configured. If configured, this value is used for receipt printing.

REVOLVING

DEFAULT_OPC_CODE_SUPPORT_LABEL

ans..40

This parameter defines a default OPC code support label value to be used if there are no matching OPCs for the card in the OPC configuration tables, and if the card does not have a default OPC configured. If configured, this value is used for receipt printing.

DEFAULTCARD

For a given Terminal Profile, configure the relevant tags as extended parameters, by completing the following steps.

NOTE

The OPC_TAG is used as an example. These steps should be followed for each required tag.

Firstly, add a parameter definition:

  1. Open the Software Components Configuration console.

  2. From the Parameter Definition tab, click the Add New button.

  3. In the New Custom Parameter window:

    1. Enter the Tag value as OPC_TAG.

    2. Enter the Name value as EMV OPC TAG

    3. Select ans from the Format drop-down list.

    4. Specify the Length as up to 40

  4. Click Save + Exit when done.

Secondly, add a new parameter:

  1. Open the Store and Terminal Configuration console.

  2. From the Profiles tab, select the Components tab.

  3. Select the required Terminal Profile from the drop-down list.

  4. From the Parameter Values tab, click the Add New button to add a new parameter.

  5. Use the Search button to search for the OPC_TAG tag created before, and then select it.

  6. Specify the desired value in the Value field.

  7. Click Save + Exit when done.

4.18. General Data Protection Regulation

To comply with the General Data Protection Regulation (GDPR), sensitive information such as PAN, Track 2 Data, Account ID1, Account ID2, and Payer Account ID should not be stored in the database in the clear. RSA algorithm is used to encrypt this information. Advices constructed by fetching information from the database will therefore always contain encrypted data.

Note
  • Do not enabled GDPR functionality when using in place or format preserving encryption as this feature will interfere with decryption.

  • GDPR functionality will only work correctly, if the property postilion.esocketpos.StoreSensitiveDataAsEncrypted is set to TRUE in the eSocket.POS properties file.

  • The existing transactions in the database may not be GDPR compliant until the Transaction Store Cleaner deleted the transactions older than the retention period.

4.18.1. RSA Key Exchange Configuration

For key exchange, the PipelineComponentCertificateManager should be configured with the relevant parameters. For more information on these parameters, see the "Pipeline Components" section of the eSocket.POS User Guide.

  • The PipelineComponentCertificateManager injects an 0800 message at the specified interval.

  • The host sends the public key certificate in the 0810 response message.

  • Upon receiving the key, the eSocket.POS keystore is updated with the certificate stored under POSCONNECT_PCIDSS_yymmdd alias.

  • Before sending the transactions, a key exchange should take place so that the keystore contains the key/certificate used for the encryption.

4.18.2. SHA-2 salted hashing configuration

In order to be compliant with the GDPR, the hotcard PANs need to be stored in the eSocket.POS database as salted hash values. SHA-2 salted hashing should be configured for the hotcard file format when performing the hotcard loads, using the Hotcard Loader. ConfigServer provides the mechanism for creating the salted hash for hotcard PANs.

  • Please refer to the Hotcard Loader and File Generator section of the eSocket.POS Configuration Server User Guide.

4.19. Configure SCA (Strong Customer Authentication) processing

For SCA processing to work on eSocket.POS, you must configure the SCA pipeline component. In addition, the optional configurations listed below can be carried out.

4.19.1. Configure the terminal to disable Single Tap and PIN Support

For the required terminal, configure the DISABLE_SINGLE_TAP_AND_PIN field under Custom Data by completing the following tasks:

  1. From the Store and Terminal Configuration console, select the Stores and Terminals page.

  2. Select the Terminals sub-page.

  3. Enter the Store to which a terminal belongs.

  4. Select the Terminals grid.

  5. Add/Edit a terminal by selecting the Add New or Modify options, or by clicking the Add New or Modify button.

  6. Enter the custom data field DISABLE_SINGLE_TAP_AND_PIN. The value entered must follow the format DISABLE_SINGLE_TAP_AND_PIN=1/0. 1 - True: Disable Single Tap and PIN. 0 - False: Enable Single Tap and PIN (default).

5. eSocket.POS components

5.1. eSocket.POS components

The eSocket.POS application consists of a large number of configurable components, as shown in the following diagram. The various entities in this diagram are listed below and described in more detail in this user guide.

eSocket.POS overview

  • POS interface - presents various ways to interface to the POS application

  • Upstream interfaces - to communicate with upstream entities such as Realtime

  • Pipelines - includes the transaction engine request and response pipelines, and an internal message format

  • Devices - access is coordinated by the eSocket.POS Device Manager

  • Database - accessed by the Information Server

  • Configuration Agent - used to upload configuration information to eSocket.POS

5.2. POS interface

5.2.1. POS Interface

eSocket.POS presents five methods of interfacing with the POS application. These are by application programming interface (API), XML interface, Message Front-end, the Multi-source Front-end and the OPI interface.

API

eSocket.POS provides a Java-based API, which can be used by the POS developer to integrate with eSocket.POS. The API is defined in the eSocket.POS Developer Guide.

XML interface

In cases where using the eSocket.POS API is not feasible, eSocket.POS presents a message-based interface through, which one or more POS terminals can communicate using TCP. Communication is based on a defined XML message format that closely mirrors the eSocket.POS API. Full details of the XML message format are provided in the eSocket.POS Developer Guide.

Message Front-end

Where neither the API nor the XML interface is feasible, for instance where the POS terminal already uses a legacy message format, eSocket.POS presents a Message Front-end which can be customized to support different message formats. Like the XML interface, the Message Front-end allows one or more POS terminals to communicate with eSocket.POS via TCP. Different message formats are supported by means of the eSocket.POS source entity, which translates between POS messages, and the format used internally by eSocket.POS. Custom development of the source entity is required in order for eSocket.POS to support different POS message formats.

Multi-source Front-end

When more than one POS interface needs to be configured for a single instance of eSocket.POS, for example, where multiple POS terminals communicate using two or more different message formats, eSocket.POS presents a Multi-source Front-end, which allows multiple source entities/interfaces to be defined, and several POS terminals to communicate using any one of the configured interfaces. Each source entity/interface defined will communicate using its own port, defined in the eSocket.POS properties file.

Oracle POS Interface(OPI)

eSocket.POS has a specific front-end that interfaces with Oracle POS applications: a ready-to-use custom source entity. Oracle Retail and Hospitality POS systems communicate with eSocket.POS via this front-end using TCP. All XML messages defined by the OPI specifications are supported.

5.2.2. Message reason code

In addition to the response code, a response message received at the POS contains a message reason code, which provides further details on why the transaction was approved or declined. This value is present in the API or XML interface response, and can be present in responses from the message front-end, depending on the message format.

The descriptions of the various pipeline components list the message reason codes that each component can return. Additional message reason codes that can be returned for other reasons are listed below. For a full list, see the eSocket.POS Developer Guide.

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

9645

Serial number validation failed

9646

Device not connected

9647

Device currently busy

9649

Check read failed

Rejections due to processing and network conditions:

8601

Abort and Retry

8602

Retry Abort

9650

Issuer disconnected

9651

Issuer timeout before response

9652

Configuration out of date

Other rejections:

9660

Signature did not match

9661

Pinpad failure

9662

Timeout during application selection

9663

Check decline notification

9665

Loyalty timeout

9666

Loyalty failed

9670

Batch totals not available

9680

Key change in progress

9681

Contactless card floor limit exceeded

9682

Max contactless floor limit exceeded

9683

Bad key card

9684

Bad application blocked

9685

Card blocked

Rejections due to missing data:

9700

Missing amount

9701

Missing PAN

9702

Missing expiry date

9703

Missing PIN data

9704

Missing processing code

9705

Missing from 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 data

9712

Missing signature data

9713

Missing EMV data

9714

Missing RFID PIN

9715

Missing barcode data

9716

Missing card acceptor ID

9717

Missing OPC data

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 track 2 data

9766

Invalid track 2 data

9767

Transaction value below minimum

9768

Null P2PE Luhn check

9769

Invalid CVV

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

9775

Payment interrupt failed

9776

Check data mismatch

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:

9790

Upstream response

9791

Administrative response

9792

Advice response

9793

Last send on suspect advice

9799

Unknown

9800 to 9999

Values reserved for use in customized components

5.2.3. API

API - overview

The eSocket.POS application programming interface (API) is designed to be used by the POS application to perform the following tasks:

  • Provide a Java-based interface between the POS application and the eSocket.POS application.

  • Allow a 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 present them to the local application as a new transaction with the response code and other properties set.

The local application need not concern itself with the construction of messages by eSocket.POS or Postilion. 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 are 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 API is defined in the eSocket.POS Developer Guide.

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 must consist of numeric values only, and be no greater than 19 characters. The eSocket.POS Developer Guide defines the data element format of each property.

Java

eSocket.POS is developed in Java (conforming to SUN Java v1.4). This means that local Java-based applications using 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 supports Windows, most distributions of Unix and Linux, Mac OS, and others.

Note that a small number of eSocket.POS components are only available for particular JVMs, operating systems, or database platforms. Where these restrictions apply, they are documented in the eSocket.POS User Guide.

5.2.4. XML interface

XML interface

The eSocket.POS XML interface provides remote access to the eSocket.POS API, using an XML message format. Full details of the XML message format are provided in the eSocket.POS Developer Guide.

Although the XML interface provides a message-based interface to eSocket.POS, it is conceptually different to the Message Front-end. The XML interface is based on a standard XML message format, which has a direct correspondence to the eSocket.POS API. By contrast, the Message Front-end provides an arbitrary message interface for use when the XML interface cannot be supported. This relies on the development of a custom source entity to unpack the message.

Running the XML interface
Running the XML interface as a Windows service

The XML interface can be run as part of the eSocket.POS Windows service. The XML interface can then be started and stopped from the Windows Services Manager.

By default, the eSocket.POS service is configured to run the XML interface (the -xml parameter is included when the service is installed).

Refer to the page on Running eSocket.POS as a Windows service for details on how to update the settings for the service.

Running the XML interface from the command line

The XML interface can be started using the following command line:

<java> <classpath> postilion.esocketpos.posinterface.xmlinterface.XmlInterface <command_line_parameters>

where <java> <classpath> is the invocation of the Java virtual machine with classpath parameters.

The <command_line_parameters> are discussed below.

Command line parameters
Field Notes Format

properties_file

The fully qualified path of the eSocket.POS properties file.

For example,
c:\eSocket.POS\esp_properties.txt

ans..255

Java System Properties

The following Java command line properties might be required:

Property Description

-Djava.awt.headless=true

Headless mode is a system configuration, where the operating system on which eSocket.POS runs does not support a display, keyboard or mouse. An example would be Linux running without a graphical display. This parameter is required when eSocket.POS needs to support signature capture functionality on a system which is running in headless mode. The reason for this is to ensure that eSocket.POS does not use the native graphical libraries during image conversion, as they are not available in headless mode.

eSocket.POS properties

The following eSocket.POS properties are required by the XML interface and must be configured:

  • postilion.esocketpos.xmlinterface.ListenPort: The port on which the XML Interface listens for incoming messages.

  • postilion.esocketpos.xmlinterface.eSocketPosSchemaFile: The full path and filename of the MessageInterface DTD.

The following eSocket.POS properties are optional:

  • postilion.esocketpos.xmlinterface.NumberOfProcessors: The number of threads servicing incoming messages from the XML interface. By default, this is 4, but this must be increased for store servers with a large number of terminals, particularly if each transaction takes some time for eSocket.POS to process, due to customer and device interactions or callbacks to the POS.

  • postilion.esocketpos.xmlinterface.CustomFilter: The fully qualified class name for a custom endpoint filter to pack and unpack TCP messages.

  • postilion.esocketpos.xmlinterface.CallbackTimeout: The number of seconds that eSocket.POS must allow when waiting for a callback response from the POS. A default of 60 seconds is used, if this value is not present. Can be omitted, if callback is not required.

  • postilion.esocketpos.xmlinterface.NumberOfConnections: The maximum number of POS Terminals allowed to establish a TCP connection to the XML Interface.

  • postilion.esocketpos.xmlinterface.SapFactory: The fully qualified Java class name of a custom Service Access Point (SAP) factory class that the XML Interface must use. This might be required in some cases to handle client specific network issues or new functionality.

  • postilion.esocketpos.xmlinterface.SapFactorySetupData: The setup data required by the SAP factory class, if one is configured. Refer to the documentation delivered with the SAP factory class.

  • postilion.esocketpos.xmlinterface.SapProtocol: The protocol associated with the Service Access Point (SAP) created by the custom SAP factory, if one is configured. Refer to the documentation delivered with the SAP factory class. The default value is 0 - TCP (Realtime).

  • postilion.esocketpos.CloseOldTerminalConnectionOnReconnect: This property specifies whether eSocket.POS should close the previous connection from the POS for a particular terminal when the POS establishes a new connection for that terminal.

    • true: eSocket.POS will close the previous connection from the POS for a particular a terminal. This option can be used in environments, where the POS experiences connection management issues, resulting in old connections remaining open indefinitely. This is the recommended option.

    • false: eSocket.POS will not close the previous connection from the POS for a particular a terminal. This option should be used in environments, where the POS uses a pool of connections shared among multiple terminals. As this option will not close connections properly, this is not recommended.

      If this property is not set, the default value is 'true'.

  • postilion.esocketpos.xmlinterface.xmlValidation: This property specifies whether eSocket.POS should validate incoming POS XML information or not.

    • true if XML validation should be performed on the XML message.

    • false if XML validation should not be performed.

      If this property is not set, the default value is 'true'.

5.2.5. Message Front-end

Message Front-end

The eSocket.POS Message Front-end provides an interface through which one or more POS devices can communicate with eSocket.POS using an arbitrary message format. It would typically be used when integrating to a POS system when use of the eSocket.POS API or XML interface is not possible. This integration requires development of a custom Source Entity, which maps the POS message protocol to the ISO 8583 message protocol used internally by eSocket.POS.

When a new POS system requires access to a standard message interface to eSocket.POS and is capable of packing and unpacking XML messages, the XML interface must be used rather than the Message Front-end. The XML interface provides a standard message-based interface to eSocket.POS, based on a defined XML message format, which has a direct correspondence to the eSocket.POS API and does not require any custom development.

Message Front-end
Running the Message Front-end as a Windows service

The Message Front-end can be run as part of the eSocket.POS Windows service. The Message Front-end can then be started and stopped, using the Windows Services Manager.

When the eSocket.POS service is installed, it is configured by default to run the XML interface rather than the Message Front-end. Before the Message Front-end is run for the first time, the settings for the service must be updated to include -mfe <params> in the service parameters, instead of -xml. The <params> for running the Message Front-end as a service are the same as described below, except the properties file is specified separately using the -p parameter for the service.

Refer to the page on Running eSocket.POS as a Windows service for details on how to update the settings for the service.

Running the Message Front-end from the command line

The Message Front-end can be started using the following command line: <java> <classpath> postilion.esocketpos.posinterface.MsgFrontEnd <params>

where <java> <classpath> is the invocation of the Java virtual machine with classpath parameters.

The <params> are discussed below.

Command line parameters
Field Notes Format

nr_threads

The number of threads, for example, 4.

n1

node_port

The TCP/IP port to listen on for incoming connections, for example, 1111.

n..5

setup_data

Reserved for future use. A value must be specified, but this is ignored. For example, 0

ans..

interface_class

Fully qualified name of the source entity class. The source entity class extending postilion.esocketpos.posinterface.APosInterface, for example, postilion.esocketpos.posinterface.IsoPosInterface

ans..255

properties_file

The fully qualified path of the eSocket.POS properties file. Only required when starting Message Front-end via command line. For example,
c:\eSocket.POS\esp_properties.txt

ans..255

keep_pos

A Boolean to specify, if the POS data must be maintained in memory after the POS has disconnected. Specify 1 to keep POS data, 0 otherwise. For example, 1.

n1

Running the Message Front-end with a different class

The Message Front-end can be run using a class other than the default class, when started as a Windows service. To start the Message Front-end with a different class, specify the postilion.esocketpos.mfe.class.name in the properties file, when starting the Message Front-end as a Windows service. Refer to eSocket.POS properties below for more details.

eSocket.POS properties

The following eSocket.POS properties are optional:

  • postilion.esocketpos.mfe.SapFactory: The fully qualified Java class name of a custom service access point (SAP) factory class that the Message Front-end must use. This might be required in some cases to handle client-specific network issues or new functionality.

  • postilion.esocketpos.mfe.SapFactorySetupData: The setup data required by the SAP factory class, if one is configured. Refer to the documentation delivered with the SAP factory class.

  • postilion.esocketpos.mfe.SapProtocol: The protocol associated with the service access point (SAP) created by the custom SAP factory, if one is configured. Refer to the documentation delivered with the SAP factory class. The default value is 0 - TCP (Realtime).

  • postilion.esocketpos.mfe.class.name: The class name with which to start eSocket.POS in -mfe mode. Refer to the documentation delivered with the specified class for information on further configuration.

  • postilion.esocketpos.CloseOldTerminalConnectionOnReconnect: This property specifies whether eSocket.POS should close the previous connection from the POS for a particular terminal when the POS establishes a new connection for that terminal.

    • true: eSocket.POS will close the previous connection from the POS for a particular terminal. This option can be used in environments where the POS experiences connection management issues resulting in old connections remaining open indefinitely. This is the recommended option.

    • false: eSocket.POS will not close the previous connection from the POS for a particular terminal. This option should be used in environments where the POS uses a pool of connections shared among multiple terminals. As this option will not close connections properly, this is not recommended.

      If this property is not set, the default value is true.

5.2.6. Multi-source Front-end

Multi-source Front-end

The eSocket.POS Multi-source Front-end allows several source entities/interfaces, each with their own arbitrary message format, to communicate with eSocket.POS from multiple POS devices.

It would typically be used when two or more message formats need to be supported in a single store-server instance of eSocket.POS. Each source entity communicates with eSocket.POS via its own port.

The Multi-source Front-end is able to support a single instance of the XML interface, which provides a standard message-based interface to eSocket.POS, and multiple instances of the Message Front-end, which rely on the development of a custom source entity to unpack messages. Only Message Front-end implementations of postilion.esocketpos.posinterface.MultiSourceMsgFrontEnd, making use of processors extending postilion.esocketpos.posinterface.MultiSourceMsgFrontEndProcessor, is currently supported.

Multi-source Front-end
Running the Multi-source Front-end as a Windows service

The Multi-source Front-end can be run as part of the eSocket.POS Windows service. The Multi-source Front-end can then be started and stopped, using the Windows Services Manager.

When the eSocket.POS service is installed, it is configured by default to run the XML interface rather than the Multi-source Front-end. Before the Multi-source Front-end is run for the first time, the settings for the service must be updated to include -msfe in the service parameters, instead of -xml. There are no other parameters needed to run the Multi-source Front-end, except the properties file, which is specified separately using the -p parameter in the service parameters.

Refer to the page on Running eSocket.POS as a Windows service for details on how to update the settings for the service.

Running the Multi-source Front-end from the command line

The Multi-source Front-end can be started using the following command line: <java> <classpath> postilion.esocketpos.posinterface.MultiSourceFrontEnd <params>

where <java> <classpath> is the invocation of the Java virtual machine with classpath parameters.

The <params> are discussed below.

Command line parameters
Field Notes Format

properties_file

The fully qualified path of the eSocket.POS properties file.

For example, c:\eSocket.POS\esp_properties.txt.

ans..255

The following eSocket.POS properties are required by the Multi-source Front-end and must be configured:

  • postilion.esocketpos.nr_src_interfaces: The number of source interfaces that need to be initialized.

The following eSocket.POS properties are required to instantiate a XML Interface:

  • postilion.esocketpos.src_int_<n>_interface.class.name: Fully qualified name of the XML source entity class. This should be the name of the standard XmlInterface that ships with eSocket.POS - postilion.esocketpos.posinterface.xmlinterface.XmlInterface.

The following eSocket.POS properties are required to instantiate a Message Front-end. These properties are the same as those specified as run parameters, when running only one the Message Front-end:

  • postilion.esocketpos.src_int_<n>_mfe.class.name: Fully qualified name of the custom Message Front-end class. Only Message Front-ends extending postilion.esocketpos.posinterface.MultiSourceMsgFrontEnd, and making use of processors extending postilion.esocketpos.posinterface.MultiSourceMsgFrontEndProcessor, are currently supported.

  • postilion.esocketpos.src_int_<n>_interface.class.name: Fully qualified name of the source entity class. The source entity class extending postilion.esocketpos.posinterface.APosInterface, for example, postilion.esocketpos.posinterface.IsoPosInterface

    Each custom developed source entity class extending the APosInterface class can only be defined once.

  • postilion.esocketpos.src_int_<n>_num_threads: The number of threads to use. For example, 4.

  • postilion.esocketpos.src_int_<n>_node_port: The TCP/IP port to listen on for incoming connections. For example, 1111.

    Please note that no two source entities should share port numbers - each source entity should have its own unique port number.

  • postilion.esocketpos.src_int_<n>_keep_pos: A Boolean to specify, if the POS data must be maintained in memory after the POS has disconnected. Specify 1 to keep the POS data, or leave at 0 otherwise.

    • <n> specifies the order in which source entities are initialized and is used to associate the correct properties with the correct source entity.

A sample configuration is:

###
 #
 # Multi-source Front-end Specific Properties
 # Required for eSocket.POS to start in -msfe mode with the standard
 # eSocket.POS IsoPosInterface and XML interface configured as source entities.
 #
 ###

# Number of source interfaces configured
postilion.esocketpos.nr_src_interfaces = 2

# Interface class name for source interface 1
postilion.esocketpos.src_int_1_interface.class.name = postilion.esocketpos.posinterface.xmlinterface.XmlInterface

# MFE class name for source interface 2
postilion.esocketpos.src_int_2_mfe.class.name = postilion.esocketpos.posinterface.MsgFrontEnd

# Source interface 2 class name
postilion.esocketpos.src_int_2_interface.class.name = postilion.esocketpos.posinterface.IsoPosInterface

# Number of threads for source interface 2
postilion.esocketpos.src_int_2_num_threads = 4

# Listening port for source interface 2
postilion.esocketpos.src_int_2_node_port = 12345

# Keep POS data parameter for source interface 2
postilion.esocketpos.src_int_2_keep_pos = 0

5.2.7. Oracle Payment Interface

Overview

This page provides a high-level overview of important information on enabling eSocket.POS to connect to Oracle point of sale (POS) systems.

Note
eSocket.POS can currently only connect to either the Oracle Retail POS (XStore) system or the Oracle Hospitality POS (Simphony) system, not both at the same time. See the Limitations page for details.
Configuration

To run eSocket.POS with the Oracle Payment Interface, complete all of the following, referring to the appropriate sections for details:

Receipt Printing

To enable receipt printing for OPI implementations, complete the following steps:

  1. Ensure the pipeline component receipt printer is properly configured.

  2. Provide an SRSL-compliant receipt definition. See the Receipt Structure Example for OPI Implementations for an example of how to customize your receipt structure for various transactions.

  3. (Optional) Customize any text displayed on the receipt using a resource bundle. See Example resource bundles SRSL for OPI Implementations.

  4. (Optional) Customize any additional information about currency symbols displayed on the receipt. See Example Currencies Symbols SRSL for OPI Implementations.

  5. Confirm that no printer device is configured on the eSocket.POS terminal profile. If a printer device is configured on eSocket.POS, it will not be able to relay the printing functionality to the Oracle Payment Interface.

OPI Messages Configuration

eSocket.POS OPI supports a mechanism for customizing various text displayed, such as the transaction outcome text displayed on the POS for each transaction, or line item display labels.

Although eSocket.POS provides default messages, text used can be customized by loading a resource bundle into the terminal configuration using Config Server.

IssuerId Mapping

To ensure that the IssuerId field is mapped for each transaction, the Issuer Id pipeline component must be configured. Each card profile must also be mapped to its Issuer ID, as required by the component.

General configuration
POS Interface

eSocket.POS communicates with the Oracle Payment Interface, using the eSocket.POS OPI interface source entity. The source entity is configured in the terminal configuration.

Configure a source entity

To configure a source entity, complete the following steps:

  1. Log into the Software Components Configuration console, if not already logged in.

  2. Select the Branch from the drop-down list.

  3. Select the Source/Sink page.

  4. Select the Source Entities grid.

  5. Select the Add New edit option, or click Add New, to add a new source entity.

  6. Type the following configuration information in the appropriate variable field.

    Variable Setting

    Name

    postilion.esocketpos.posinterface.opi.OPIInterface

    Class

    Enter the full Java class name of the source entity. See the command line parameters in the Message Front-end page of this guide for details on setting this value.

    Default parameters

    Enter the default parameters for this source entity. These values are used, unless overridden in the terminal profile configured with the ConfigServer Store and Terminal Configuration console. See the command line parameters in the Message Front-end page of this guide for details on setting this value.

  7. Click Save + Exit.

Assign a source entity to a terminal profile

The following steps outline the process for assigning a source entity to a terminal profile:

  1. Log into the Store and Terminal Configuration console, if not already logged in.

  2. Select the Branch from the drop-down list.

  3. Select the Profiles page.

  4. Select the Components sub-page.

  5. Select the Terminal Profile to which components are assigned.

  6. Select the Source/Sink sub-page of the Components sub-page.

  7. Select the Source Entity grid.

  8. Select the Add New edit option, or click Add New, to assign the newly created source entity.

  9. Select the OPI Interface source entity from the drop-down box.

  10. Click Save + Exit.

eSocket.POS properties file
Configure terminal auto-initialization

The OPI message protocol does not have a sign-on message flow. eSocket.POS must therefore be configured to initialize all terminals when the service is started. To enable this functionality, complete the following step:

  1. Specify the postilion.esocketpos.storeserver.AutoInitTerminals property in the properties file with either of the following values:

    • All

    • AllSignOn

      There is no difference in functionality when specifying either of the two options.

      For example,

postilion.esocketpos.storeserver.AutoInitTerminals = AllSignOn

Configure the eSocket.POS transaction linking method

To configure the linking method, complete the following step:

  1. Set the postilion.esocketpos.storeserver.TransactionLinkingMethod property to RETRIEVAL_REF_NR.

    For example,

    postilion.esocketpos.storeserver.TransactionLinkingMethod = RETRIEVAL_REF_NR

See the eSocket.POS properties section for more information.

Configure the eSocket.POS service

The eSocket.POS service must be updated to use the Message Front-end (-mfe) parameter.

  1. Update the eSocket.POS startup and runtime environment parameters, using the Windows Registry Editor, as follows:

    1. Expand the registry node at: HKEY_LOCAL_MACHINE > SYSTEM > CurrentControlSet > Services > EspRun > Parameters

    2. Set the Command Line value data to the following:

      postilion.esocketpos.util.EspRun -p <properties_file> -mfe <nr_threads> <node_port> <setup_data> postilion.esocketpos.posinterface.opi.OPIInterface <keep_pos>

      For example, postilion.esocketpos.util.EspRun -p "C:\postilion\eSocket.POS\properties.txt" -mfe 4 40500 0 postilion.esocketpos.posinterface.opi.OPIInterface 1

    3. Click OK to save the changes.

See the Message Front-end and eSocket.POS Windows services pages for more information.

Configure the OPI Interface connection

For eSocket.POS to connect with the Oracle Payment Interface (OPI), you must configure the SAP and endpoint filter. To do this, append the following to the eSocket.POS properties file:

  1. The eSocket.POS OPI interface property.

    Property Description

    postilion.esocketpos.mfe.class.name

    The fully qualified name of the class that is used when starting the eSocket.POS service with the OPI interface. Set this to postilion.esocketpos.posinterface.opi.OPIFrontEnd

  2. The configuration properties for the OPI SAP factory and endpoint

    Property Description

    postilion.esocketpos.mfe.nodePort

    The TCP/IP port for the service access point (SAP) that listens for the HTTP POST messages. For example, 45000.

    postilion.esocketpos.mfe.SapFactory

    The fully qualified Java class name of a custom SAP factory class that eSocket.POS must use for OPI. Set this to postilion.esocketpos.ipc.opi.EspOPITcpSapFactory

    postilion.esocketpos.mfe.SapFactorySetupData

    SSL is required on the TCP connection to the POS. See the SSL Configuration - Overview page for more information on SSL. See Configuring SSL on TCP connections for details on the TCP connection-specific configuration required. The following example shows the configuration with remote authentication disabled: -ssl-type=jsse -ssl-remote-auth=false -ssl-protocols=TLSv1.2;SSLv2Hello

    postilion.esocketpos.mfe.SapProtocol

    The protocol associated with the SAP. Set this to 15.


Terminal configuration
Configure the Workstation Number to Terminal ID mapping

To process transactions from an Oracle terminal, the 'WSNo' needs to be configured as a custom data parameter on the terminal configuration.

Use Config Server to configure the Workstation Number for the terminal. Each terminal is associated with a physical connection to a device. The Workstation Number is configured during terminal configuration.

To configure the Workstation Number to Terminal ID mapping:

  1. Open the ConfigServer Store and Terminal Console.

  2. Select the Store and Terminals tab.

  3. Select the Terminals tab.

  4. Enter the Store to which a terminal must be added or modified. Alternatively, click Search to search for a store.

  5. Add a new terminal by right-clicking on the Terminals grid and selecting Add New or edit an existing terminal by right-clicking on the terminal and selecting Modify.

  6. Complete or modify the fields as required. Type the following in the Custom Data text box:

    WSNo=n

    where n indicates the configured Workstation Number in the Oracle POS system.

    For example,

    WSNo=1

OPI Terminal parameters

The following table lists the terminal parameters that can be configured in any OPI-based POS implementation.

Parameter name Format Description Example value

GIFT_CARD_CASHOUT_MODE

n1

The terminal parameter GIFT_CARD_CASHOUT_MODE provides a configuration option to configure a POS Terminal to process Gift Card Cashout transactions.

The following configuration values can be set:

  • 1 - Cashout the remaining funds from the gift card account, but the account should remain active.

  • 2 - Deactivate the gift card account regardless of the funds available.

  • 3 - Cashout the remaining funds from the gift card account and close the account.

1

OPI_MODE

n1

The OPI_MODE terminal parameter provides an option for configuring which POS system the terminal uses.

The following configuration values can be set:

  • 1 - OPI Retail (Default) Set this to use XStore.

  • 2 - OPI Hospitality Set this to use Simphony.

1

Oracle Retail terminal parameters

The following terminal parameters are only applicable for an Oracle Retail POS implementation. That is, when OPI_MODE is set to 1.

Parameter name Format Description Example value

ALWAYS_ENABLE_PRESWIPE

n1

The terminal parameter ALWAYS_ENABLE_PRESWIPE provides a configuration option to configure a POS Terminal to always activate the card reader, while the POS operator is scanning the items.

The configuration values are as follows:

  • 1 - Always allow pre-swipe

  • 0 - Never allow pre-swipe (Default)

Note
Ensure that the pre-swipe configuration on the device driver in use is synchronized at the driver level with the Oracle Payment interface. Failure to do so can result in unexpected behavior and the pre-swipe functionality not working.

0

Oracle Hospitality terminal parameters

The following terminal parameters are only applicable for the Oracle Hospitality POS implementation. That is, when OPI_MODE is set to 2.

Parameter name Format Description Example value

SUPPRESS_CASHBACK

ans

The SUPPRESS_CASHBACK terminal parameter provides configuration for suppressing the cashback prompt for specific OPI transaction types, even if the card and account are eligible.

The value for this parameter should be a comma-separated (,) list of 2-digit OPI transaction types.

For example, if this parameter is set to 01,05, eSocket.POS will not prompt for cashback during sale (01) and authorization request (05) transactions.

01,05

Configure the Custom Parameters on a Terminal Profile

Configure the relevant tags as extended parameters for a given Terminal Profile by completing the following steps. You must repeat these steps for each required tag.

Note
OPI_MODE is used as an example. Replace OPI_MODE with the relevant tag.
  1. Add a parameter definition.

    1. Open the Software Components Configuration console.

    2. From the Parameter Definition tab, click Add New.

    3. In the New Custom Parameter window:

      1. Type OPI_MODE in the Tag value field.

      2. Type OPI MODE in the Name value field.

      3. Select n from the Format drop-down list.

      4. Specify the Length as up to 1.

    4. Click Save + Exit when done.

  2. Add a new parameter.

    1. Open the Store and Terminal Configuration console.

    2. Select the Components tab from the Profiles tab.

    3. Select the required Terminal Profile from the drop-down list.

    4. From the Parameter Values tab, click Add New to add a new parameter.

    5. Click Search to search for the OPI_MODE tag created before, and then select it.

    6. Type the desired value in the Value field.

    7. Click Save + Exit when done.


Oracle Payment Interface messages configuration

eSocket.POS OPI Interface supports a mechanism for customizing various messages displayed on the POS or the PED during the transaction.

Although eSocket.POS provides default messages for each one of the messages, they can be customized by loading a resource bundle into the terminal configuration using ConfigServer.

Customizable text

The following table provides more information about the properties used to customize messages:

Property Default value Description

pos_tran_outcome_approved

APPROVED

Displayed at the POS, when the transaction is approved.

pos_tran_outcome_declined

DECLINED

Displayed at the POS, when the transaction is declined.

pos_tran_outcome_customer_canceled

CANCELED BY CUSTOMER

Displayed at the POS, when the cardholder presses the cancel button on the PED.

pos_tran_outcome_operator_canceled

CANCELED BY OPERATOR

Displayed at the POS, when the operator canceled the transaction.

pos_tran_outcome_voice_auth

CALL THE BANK

Displayed at the POS, when manual authorization is required for the transaction.

pos_tran_outcome_customer_timeout

CUSTOMER TIMEOUT

Displayed at the POS, when the eSocket.POS timeouts waiting for a customer interaction.

pos_tran_outcome_switch_inoperative

SWITCH NOT REACHABLE

Displayed at the POS, when no response was received from the upstream entity.

pos_tran_outcome_terminal_busy

TERMINAL BUSY

Displayed at the POS, when eSocket.POS is not in a state to process a transaction.

pos_tran_outcome_general_error

AN ERROR OCCURRED

Displayed at the POS, when an unexpected error occurred while eSocket.POS was processing the message.

Note
Usually, a message in the event log provides more details on the error.

pos_tran_outcome<rsp_code>_

Not applicable

Displayed at the POS, when the response code specified is received.

pos_tran_outcome<rsp_code>_<msg_reason_code>_

Not applicable

Displayed at the POS, when the specified response code and message reason code are received.

amount_adjustment_label

DISCOUNT UPDATED

Displayed on the PED during line item, when a discount has been applied to one of the product purchased.

tax_changed_label

TAX UPDATED

Displayed on the PED during line item, when the tax amount for one of the items has been updated.

total_amount_currency

$

Currency symbol used for all total amounts displayed on the PED during line item display.

Note
Some device drivers have their own properties for the total currency that might override what is set here.

total_due_label

TOTAL DUE

Displayed after the payment, where only the partial amount was paid. Instead of displaying all the items again, eSocket.POS only displays the remaining total to pay using this label.

discount_amount_label

Discount Amount

Displayed on the PED during line item, under all the items to identify the total discount for the transaction.

tax_amount_label

Tax Amount

Displayed on the PED during line item, under all the items to identify the total tax for the transaction.

Configure displayed message texts with ConfigServer

To configure the response texts using ConfigServer, you must first configure a parameter definition under which the response texts can be configured:

  1. From the ConfigServer Software Components Console, add a new entry to the Parameter Definition.

  2. Set the tag to "OPIMessages_**", where ** is the two-character ISO-639-1/B language code, to configure the prompts message for the terminal prompt language configured. Example: If the prompt language is English, you should configure the tag as follows:

    OPIMessages_en
  3. Enter any descriptive Name. For example, "Custom OPI text messages".

  4. Set Format to "ans".

  5. Set Length to "up to" and enter "99999" in the text box.

To configure the messages under the parameter definition created, perform the following steps:

  1. From the ConfigServer Store and Terminal Console select the Profiles > Components tab.

  2. Select the relevant Terminal Profile from the drop-down list. If the terminal profile has not been created yet, it can be configured on the Profiles > Terminal Profiles tab.

  3. Select the Parameter_Values tab. Add an entry to the parameter definition created. Set the parameter value to a list of name=value pairs, specifying the message text properties, as described in the section above.

Pipeline Components
Pipeline component - Card Issuer Identification

Description: The card issuer identification component populates the IssuerId structured data tag (field 127.22). The IssuerId can be used by downstream entities to identify the card issuer for a given transaction. This issuer ID must be configured beforehand in the card profile custom data using the same IssuerId tag. See the Configuration Server User Guide for information on configuring card profile custom data.

Usage: Request pipeline, optional. Only required for eSocket.POS OPI implementations.

Rank: Must be configured after the PAN component, before the EMV component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentCardIssuerIdentification

Parameters: None.

Decline conditions:

Condition Response code Message reason code

The IssuerId configured is invalid and its length is bigger than 2.

05 - Do not honor

9779 - Invalid Issuer ID

No IssuerId is configured for the card used for the transaction.

05 - Do not honor

9718 - Missing Issuer ID

Pipeline component - OPI Manual Authorization

Description: The OPI Manual Authorization component enables eSocket.POS to support the Simphony-specific manual authorization transaction flow, where a second card read is required and only a completion message is sent upstream. If this component is configured, Simphony manual authorization transactions (Oracle transaction type 37) are authorized by eSocket.POS if the transactions already have an authorization code.

Usage: Request pipeline, optional. Only required for Oracle Hospitality implementations.

Rank: Must be configured after the EMV component at the end of the request leg.

Class name: postilion.esocketpos.transactionengine.PipelineComponentOPIManualAuthorization

Parameters: None.

Decline conditions: None.

Retail (XStore)
Oracle Retail Overview

This page provides a high-level overview of the Oracle Retail point of sale (POS).

Limitations
  • The following OPI message types are supported for Retail within eSocket.POS:

    • 01 - Sale/Purchase

    • 03 - Refund

    • 04 - Reversal

    • 07 - Sale Completion

    • 08 - Void

    • 20 - Transaction Inquiry

    • 27 - Balance Inquiry

    • 28 - Gift/SVC Reload (Top-Up)

    • 29 - Gift/SVC Activate/Issue

    • 30 - Gift/SVC Redeem (Purchase)

    • 31 - Gift/SVC Void

    • 32 - Gift/SVC Close Card

    • 37 - Manual Authorization

    • 39 - Void of Refund

    • 43 - Line Item Advice

    • 45 - Sale End

    • 50 - Read Non-PCI Card

    • 51 - Check Authorization

    • 52 - Void Check Authorization

    • 53 - Cancel Current Transaction

    • 60 - Get Customer Verification

    • 60 - Get Signature

    • 62 - Get Numeric Field

    • 63 - Get Alphanumeric Field

    • 64 - Get Date Field

    • 65 - Get Button Selection

    • 67 - Display Message

  • The eSocket.POS integrates with Oracle Payment Interface (OPI) Xstore version 18.0.1.

  • Signature Capture is only supported with device drivers capable of capturing the signature in 3-Byte Ascii format.

  • Timeout values impact performance. Ensure that sensible timeout values are configured for both eSocket.POS and the XStore POS.

  • Check Authorization Transaction:

    • The reading of the check details will be handled by the POS.

  • Card tokenization is currently not supported by XStore.

  • Generic prompts and display messages are not supported during line item.

  • Cancel Current Transaction:

    • eSocket.POS does not support processing the Cancel Current Transaction request when the transaction has been sent upstream. You must use the cancel button on the device pad.

Configuration

Configure the following to run eSocket.POS with the Retail Oracle Payment Interface.

  • Generic prompting

    See the OPI Generic Prompt Configuration page for details.

  • Oracle software

    See the OPI Oracle Software Configuration page for details.

Oracle Payment Interface configuration
Configure the Oracle software
EFTlink specific configuration
  • Update the following parameters in the EftlinkConfig.properties configuration file:

    • ServerChannel1 needs to be unset. This is required as this is the port that Xstore would use to communicate with the PED device. As eSocket.POS would be driving the PED, we need to disable this configuration setting.

    • TLSEnabled needs to be set to false.

  • Update the following parameters in the opiretail.properties configuration file:

    • EPSAddress and EPSPort needs to be set to the network address/port, where eSocket.POS will be accepting the messages from the source entity.

Note
Please refer to the Oracle EFTlink and Xstore documentation for configuring these values.

Generic prompt configuration
Overview

The following Oracle Payment Interface message types are mapped to eSocket.POS generic prompt requests:

  • 60 - Get Customer Verification

  • 62 - Get Numeric Field

  • 63 - Get Alphanumeric Field

  • 64 - Get Date Field

  • 65 - Get Button Selection

Mapping

The following table describes the mapping to the eSocket.POS Prompts XML Structure. The "Prompt use" column describes when default eSocket.POS prompt is used, and when the OPI-specified prompt overrides the default. The "Prompt-specific" column maps the OPI field to the corresponding eSocket.POS field.

OPI transaction type Data type Prompt ID Prompt use Prompt-specific fields

60 - Get Customer Verification

B (Boolean)

PromptBoolean

The prompt name defaults to "PromptBoolean".

AcceptLabel in the OPI request is mapped to the AcceptText field in eSocket.POS. DeclineLabel in the OPI request is mapped to the DeclineText field in eSocket.POS

62 - Get Numeric Field

N (Numeric)

PromptNumeric

The "DataName" field in the OPI request is used as the prompt name, if specified. If the "DataName" field is not specified in the request, the prompt name defaults to "PromptNumeric".

PromptText and GuidanceText mapped as per the table in the "Configure the Prompt Text mapping" section that follows

63 - Get Alphanumeric Field

A (Alphanumeric)

PromptAlphanumeric

The "DataName" field in the OPI request is used as the prompt name, if specified. If the "DataName" field is not specified in the request, the prompt name defaults to "PromptAlphanumeric".

PromptText and GuidanceText mapped as per the table in the "Configure the Prompt Text mapping" section that follows.

64 - Get Date Field

N (Numeric)

PromptNumeric

The "DataName" field in the OPI request is used as the prompt name, if specified. If the "DataName" field is not specified in the request, the prompt name defaults to "PromptNumeric".

PromptText and GuidanceText mapped as per the table in the "Configure the Prompt Text mapping" section that follows.

65 - Get Button Selection

O (Option)

PromptOption

The "SelectionName" field in the OPI request is used as the prompt name, if specified. If the "SelectionName" field is not specified in the request, the prompt name defaults to "PromptOption".

ButtonLabel1 to ButtonLabel10 are mapped as OptionTextLine objects.

See the appropriate device driver user guide for additional information on configuring other prompt properties.

Configure the Prompt Text mapping

The following table gives detailed descriptions on the Prompt Text Map Mode parameter. This is an optional parameter.

Parameter name Format Description Example value

PROMPT_TEXT_MAP_MODE

n1

The terminal parameter "PROMPT_TEXT_MAP_MODE" determines how the prompt text sent from the POS is mapped for the Get Numeric Field and the Get Alphanumeric Field requests from the POS.

The value used here depends on the device driver used. Some devices have limitations on displaying free-form text when prompting for numeric or alphanumeric input.

The configuration values are:

  • 0 - PromptText and GuidanceText are not mapped to the XML prompt data. Device driver-specific generic prompt configuration is required.

  • 1 - PromptText and GuidanceText are mapped to DisplayTextLine elements in the XML prompt data.

  • 2 - PromptText is mapped to CustomProperty elements with key "prompt_idx" in the XML for use with device drivers that expect prompt text (default).

Note
Ensure this property is set to override the default value when the device driver in use does not support the "prompt_idx" key.

0

Configure the PROMPT_TEXT_MAP_MODE value as a custom parameter for the required terminal profile by completing. To do so, add a parameter definition and a new parameter.

  1. Add a parameter definition:

    1. From the Software Components Configuration console, select the Parameter Definition tab, then click Add New. The New Custom Parameter window appears.

    2. Enter the Tag value as PROMPT_TEXT_MAP_MODE.

    3. Enter the Name value as Set the prompt text map mode, or any other identifiable value.

    4. Select n from the Format drop-down list.

    5. Specify the Length as 1.

    6. Click Save + Exit when done.

  2. Add a new parameter:

    1. From the Store and Terminal Configuration console, select the Profiles > Components tabs.

    2. Select the required Terminal Profile from the drop-down list.

    3. From the Parameter Values tab, click Add New to add a new parameter.

    4. Search for the PROMPT_TEXT_MAP_MODE tag created in step 1 and then select it.

    5. Specify the desired value in the Value field. The default value is 2.

    6. Click Save + Exit when done.

Hospitality (Food and Bev)
Oracle Hospitality Overview

This page provides a high-level overview of the Oracle Hospitality point of sale (POS).

Limitations
  • The following OPI message types are supported for Hospitality within eSocket.POS:

    • 01 - Sale/Purchase

    • 02 - Sale and Cashback

    • 03 - Refund

    • 04 - Reversal

    • 05 - Authorization Transaction

    • 06 - Incremental Authorization Transaction

    • 07 - Sale Completion

    • 08 - Void

    • 12 - Sale Adjustment

    • 16 - Authorization Release

    • 20 - Transaction Inquiry

    • 27 - Balance Inquiry

    • 28 - Gift/SVC Reload (Top-Up)

    • 29 - Gift/SVC Activate/Issue

    • 30 - Gift/SVC Redeem (Purchase)

    • 31 - Gift/SVC Void

    • 32 - Gift/SVC Close Card

    • 37 - Manual Authorization

    • 39 - Void of Refund

    • 41 - Is Online

    • 43 - Line Item Advice

    • 44 - Quick Chip Init

    • 45 - Sale End

    • 46 - Quick Chip Cancel

    • 53 - Cancel Current Transaction

  • eSocket.POS integrates with Oracle Payment Interface (OPI) Simphony version 18.2.0.0.

  • Timeout values impact performance. Ensure that sensible timeout values are configured for both eSocket.POS and the Oracle Hospitality POS.

  • Card tokenization is currently not supported by the Oracle Hospitality POS.

  • Gratuity (Tip) prompting is handled by the Oracle Hospitality POS. Ensure that the Gratuity pipeline component is not configured.

  • Cancel Current Transaction:

    • eSocket.POS does not support processing the Cancel Current Transaction request when the transaction has been sent upstream. You must use the cancel button on the device pad.

  • Quick chip transactions:

    • Oracle quick chip implementation relies extensively on the Pre-swipe pipeline component. Ensure pre-swipe is configured when using OPI Quick Chip transactions.

    • A pre-swipe enable event is raised by eSocket.POS when OPI initializes Quick Chip (OPI transaction type 44) to attempt the card read. A pre-swipe cancel event is raised when OPI cancels the Quick Chip Transaction (OPI transaction type 46) to clear card data. See the eSocket.POS Developer Guide for more information on various pre-swipe events.

    • eSocket.POS does not force a chip card read during quick chip transactions. A card swipe or tap is also allowed, depending on the pre-read modes enabled at the device driver configuration.

    • Oracle Quick Chip transactions work best when Quick chip is also enabled on both eSocket.POS and the device driver in use. See the Quick Chip Processing page for more information on enabling Quick Chip on eSocket.POS, and the relevant device driver user guide for more information on setting up pre-swipe/pre-read to work with Quick Chip.

  • Manual Authorization Transactions:

    • Hospitality Manual Authorization transactions (transaction type 37) require the OPI Manual Authorization pipeline component to be configured.

    • Unlike the retail implementation, Oracle Hospitality Manual Authorization transactions require a second card read. The request received by eSocket.POS is not linked to the original authorization that required manual authorization.

5.3. Upstream interfaces

5.3.1. Upstream interface

eSocket.POS uses a sink entity to communicate with an upstream entity, such as Realtime. The sink entity translates the internal message format to a format that the upstream entity supports.

eSocket.POS provides the following:

  • RemoteSink - a standard sink entity to communicate with Realtime. The eSocket.POS RemoteSink sends and receives messages from an upstream Realtime entity via a PosConnect source node. eSocket.POS establishes its own TCP connection to the upstream PosConnect source node. Upstream messages are formatted according to the PosConnect interface specification.

  • DualSink - a dual sink manages two RemoteSink entities connecting to two Realtime systems for redundancy purposes, for example, in an active/active deployment.

  • CallbackSink - a sink entity for when the POS controls the authorization channel.

  • MultiSink - a plug-point for extensions, to implement a multiple sink environment. In a multiple sink environment, the sink entities can communicate with more than one payment server and not just Realtime.

    NOTE

    For an extension to be implemented for a specific upstream entity, contact your ACI service provider.

5.3.2. RemoteSink

The eSocket.POS RemoteSink manages communication with an upstream Realtime.

In addition to managing communications at the network level, the RemoteSink entity also manages the integrity of the EFT message flow from eSocket.POS to Realtime.

If the Realtime connection is unavailable (no connection exists), then the RemoteSink does the following:

  • Declines requests with a Response Code of 91

  • Queues advices

If Realtime does not respond within the configured timeout period, then the RemoteSink does the following:

  • For a request, declines the request with a Response Code of _91 and generates a reversal advice (0420) to Realtime.

  • For an advice, repeats the advice, with retries grouped into window periods according to the configurable parameters, ADVICES_PER_SEND_WINDOW and MAX_NR_ADVICE_SEND_WINDOWS (described below). During each window, once the advice is sent ADVICES_PER_SEND_WINDOW or more times and at least one other upstream response (for example, 0110, 0210, 0610 or 0810 message) is received since the previous attempt, the upstream entity is considered still alive and processing messages. A new window period is started, provided that MAX_NR_ADVICE_SEND_WINDOWS is not reached. On the other hand, if, during the final window period, the upstream entity is deemed alive and ADVICES_PER_SEND_WINDOW is reached or exceeded, RemoteSink logs an error and discards the advice. Any advice that could potentially be the final one sent contains the Message Reason Code 9793, indicating a suspected format error.

Class name: postilion.esocketpos.postilioninterface.RemoteSink

Parameters: The RemoteSink must be configured with the following parameters, separated by spaces:

Param# Parameter Values

1

driver

Specifies the driver class used to map the message to a format understood by the upstream entity.

Set to postilion.esocketpos.postilioninterface.driver.PosConnectSinkDriver when connecting to PosConnect v1.1 or later.

Set to postilion.esocketpos.postilioninterface.driver.PostTermSinkDriver when connecting to PostTerm or PosConnect v1.0.

2

connection type

The type of connection to be used.

1 - permanent connection

2 - managed connection (for instance when two RemoteSinks are managed by a DualSink)

3

IP address

The host name or IP address to which an upstream TCP connection is made.

Typically set to the host name of the Realtime system where PosConnect is listening for TCP connections.

4

port

The port number to which an upstream TCP connection is made.

Typically set to the port on which the PosConnect is listening for TCP connections.

5

timeout

The number of seconds to wait for a response before returning a timeout response or sending a repeat.

RemoteSink can also be configured with the following named parameters:

Parameter Values

Reconnect interval

RECONNECT_INTERVAL=x, where x is the amount of seconds to wait before the next connect attempt. x must be a positive integer value. x is added to a random value between 0 (included) and 30 (excluded) to determine the total reconnect interval. For example, if RECONNECT_INTERVAL is set to 30, and RemoteSink gets disconnected from the upstream entity, then RemoteSink waits a minimum of 30 seconds and a maximum of 59 seconds before it attempts to reconnect to the upstream entity.

If this parameter is not specified, the reconnect interval is calculated as a random value between 0 (inclusive) and 30 (exclusive).

Maximum backoff time

MAX_BACKOFF_TIME=x, where x is the maximum time in seconds to wait between the transmission of advices when the server is under load.

If this parameter is not specified, a default time of 360 seconds (6 minutes) is used.

Maximum number of advice send windows

MAX_NR_ADVICE_SEND_WINDOWS=x, where x is the maximum number of window periods into which repeated advices must be grouped. A new window is started when the number of times the advice is re-sent has reached or exceeded the minimum specified for a window, and activity is detected on the connection with the upstream entity.

If this parameter is not specified, a default value of 3 windows is used.

Advices per send window

ADVICES_PER_SEND_WINDOW=x, where x is the minimum number of times an advice must be re-sent during a window period. If no other activity is detected on the connection, the advice is re-sent indefinitely.

If this parameter is not specified, a default value of 8 retry attempts is used.

Realtime systems connected in Active/Active Mode

This parameter can be configured to indicate if the Realtime system to which the sink entity is connected to, has been configured to operate in Active/Active mode with another Realtime system. It is specified as

SNK_AA=x , where x is one of:

  • 0 - Active/Backup mode.

  • 1 - Active/Active mode.

This parameter only has an effect if the Sink entity is managed by DualSink and if the SNK_AA parameter is also set for the DualSink. It will not have any effect otherwise. If it is specified as Active/Active, RemoteSink sends the advice back to DualSink and removes it from the store-and-forward queue when an advice has not been successfully sent after a configurable number of retries. DualSink then attempts to pass the advice to the secondary sink. In this mode the RemoteSink will make use of the ADV_PER_SINK_SWP parameter as a guide of how many times to allow a message to be resent before it is send back to the DualSink. The default is Active/Backup.

Advices per sink swap

This parameter only has an effect if the Sink entity is managed by DualSink and if the SNK_AA parameter is also set for the DualSink. It is specified as

ADV_PER_SINK_SWP=x, where x is the maximum number of times an advice will be re-sent before the advice is sent back to the DualSink.

If this parameter is not specified, a default value of 8 retry attempts is used.

Log connection Events

This parameter determines if the Remotesink logs connect and disconnect events to the event log in addition to the trace. It is specified as

LOG_CNNCT_EVNTS=x, where x is one of:

  • 0 - Trace Only.

  • 1 - Trace and Event Log.

If this parameter is not specified, connection events will only be logged to the Trace.

Discard exception advice time

This parameter determines for how many minutes we will attempt to resend an advice which causes an exception during send processing. For this period, the retry will happen every five seconds. This parameter is specified as

DISCARD_EXCP_ADV_TIME=x, where x is the number of minutes to retry.

If this parameter is not specified, a default value of 30 minutes will be used.

Activation host

This parameter specifies the IP address or host name of the machine where terminal activation requests are processed. The parameter is specified as

ACTIVATION_HOST=x, where x is the IP address or host name

This parameter is optional and should only be specified if terminal activation is being used. If it is specified, then Activation port (ACTIVATION_PORT) must also be specified.

Activation port

This parameter specifies the port number on the machine where terminal activation requests are processed. This parameter is specified as

ACTIVATION_PORT=x, where x is a valid port number.

This parameter is optional and should only be specified if terminal activation is being used. If it is specified, then Activation host (ACTIVATION_HOST) must also be specified.

Send advice for reversal not found

This parameter is optional. It specifies whether Remote Sink should send an advice when the reversal response from an upstream entity indicates that the original transaction was not found.

It can be specified as follows:

SEND_ADVICE_REVERSAL_NOT_FOUND=x, where x is one of:

  • 0 - Do not send advices (Default behavior).

  • 1 - Send advice.

Disable timeout reversals

This parameter specifies whether Remote Sink should send timeout reversals. If set to 0, when the response is not received within the configured timeout window, a timeout reversal is sent to the upstream entity. By default, the reversal is always sent.

DISABLE_TIMEOUT_REVERSALS=x, where x is one of:

  • 0 - Send reversals on timeout.

  • 1 - Do not send reversals on timeout.

Configuring a custom SAP factory

RemoteSink can be configured to use a custom Service Access Point (SAP) factory class which is needed for SSL or might be required in some cases to handle client-specific network issues. If a custom SAP factory must be used, it can be configured as a row in the esp_classes table as follows:

Field Format Values

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

term_category

The terminal category

ans8

class_tag

Set to SINK_SAP if this is a single sink entity with a permanent connection. If the connection is managed by a DualSink entity, the class_tag must be set to [sink_tag]_SAP, where [sink_tag] is the class_tag for this RemoteSink entity configured in DualSink.

ans..80

rank

0

INT

class_name

The fully qualified name of the SAP factory class to be used, for instance postilion.esocketpos.sapfactory.CustomSapFactory.

ans..255

params

_<protocol>

<sap setup data>_

Where:

  • <protocol> is the type of protocol to be used. This must typically be set to a Realtime SDK defined integer value, but is dependent on the implementation of SAP factory. Commonly used values are:

    0 - TCP

    1 - X25

    5 - Modem

    15 - Raw TCP

    18 - TCP Realtime (2 byte header)

  • <sap setup data> is the local setup data string required by the SAP factory class. The format of this string is implementation specific and is documented in the application providing the implementation.

Note that the parameters must contain two consecutive semi-colons.

See the documentation that is provided with the Custom SAP factory for more information.

ans..255

To maintain backwards compatibility with previous versions of the product, instead of adding an entry to the esp_classes table, the following additional parameters CAN be used to configure a custom SAP factory:

Param# Parameter Values

6

SAP Factory Class Name

The name of the SAP factory class to be used, for instance postilion.esocketpos.sapfactory.CustomSapFactory.

7

SAP Protocol

The type of protocol to be used. This must typically be set to a Realtime SDK defined integer value, but is dependent on the implementation of the Custom SAP factory. For instance,

0 - TCP

1 - X25

5 - Modem

15 - Raw TCP

18 - TCP Realtime (2 byte header)

See the documentation about the Custom SAP factory for more information on which Protocol settings to use.

8

SAP Setup Data

The setup data required by the SAP factory class. Note that this must be enclosed by double quotation marks ("). These values are dependent on the Custom SAP factory class used. See the documentation about the Custom SAP factory for more information.

Note
If a SAP factory is configured as both part of the RemoteSink parameters and as a class in the esp_classes table, then the SAP factory that is configured as part of the RemoteSink parameters are used, and the entry in the esp_classes table is ignored.

Please contact your primary support provider for further details about SAP factory classes.

5.3.3. DualSink

The DualSink model allows eSocket.POS to maintain a primary and a secondary connection to two different Realtime systems to provide redundancy in case one connection is not available. DualSink does not connect to Realtime itself, but instead creates and manages two RemoteSink entities.

At any one time, DualSink has only one active RemoteSink, either the primary or the secondary sink. DualSink sends transactions to the active sink, except where an advice is linked to a previous transaction (for instance, a request followed by a reversal advice). In this case the advice is sent to the same sink as the original request, unless the Sinks connected in Active/Active Mode parameter is set to Active/Active, in which case the advice is still sent to the active sink. Each sink maintains a separate store-and-forward queue.

DualSink determines which sink is active, depending on the connection status, and attempts to connect to the secondary sink if the primary is disconnected, or if a timeout occurs while waiting for a response from the primary. The secondary sink remains active for a configurable number of transactions, after which DualSink attempts to reconnect to the primary sink. If the primary sink is still not available, the secondary remains active for the same number of transactions, after which DualSink again attempts to connect to the primary, and so on. Connectivity is maintained or attempted on the inactive sink for the purposes of clearing store and forward transactions on its queue, even if new transaction attempts are being sent on the other active sink.

If a response is received from Transaction Manager indicating that the upstream entity is unavailable (indicated by a response code of 91 or 96), failover behavior is determined by the value of the Postilion:UpstreamUnavailableAction sub-value of the Postilion:ActiveActiveData structured data value in the response:

Postilion:UpstreamUnavailableAction Values

Behavior

Swap

Swap the connection to the alternate sink.

SwapAndRetry

Swap the connection to the alternate sink and attempt to retransmit the transaction to that sink.

NoSwap

Take no action.

If the Postilion:UpstreamUnavailableAction value is not set, or set to a different value than those listed above, default upstream unavailable behavior occurs. This means taking no action, unless the Upstream entity unavailable action indicates otherwise.

Configuration of SINK and remote sink entity tags:

DualSink must be configured in the esp_classes table, under the tag SINK, and two RemoteSinks must be configured, under the tags specified by the SINK_NAMES parameter (see below). If SINK_NAMES is not specified, DualSink will default to the tags SINK1 and SINK2 for loading the remote sink entities.

DualSink must have parameters as specified below, and the two RemoteSinks must have parameters including connection information for two different Realtime systems, and must have a connection type of 2 - Managed Connection.

Parameters: The DualSink must be configured with the following parameters, separated by spaces:

Parameter Values

1

connection timeout

The number of minutes, after which, if no transactions are received, the connection is dropped. This must be a large value, for instance, several hours.

Set to 0 to maintain the connection permanently.

2

retries on secondary

The number of transactions to send to the secondary connection before attempting to reconnect to the primary.

3

primary sink selection

0 - select sink1 as the primary at startup

1 - select the primary randomly at startup (either sink1 or sink2)

4

connection wait time

This is the time to wait in seconds for a connection to be established. This parameter is optional with a default value of 10 seconds.

In addition, DualSink can also be configured with the following named parameters:

Parameter Values

Upstream entity unavailable action

This parameter determines DualSink’s behavior upon receiving a response from Transaction Manager, indicating that the upstream entity is unavailable. It is specified as

UPSTREAM_UNAVAIL_ACTION=x, where x is one of:

  • 0 - Take no action.

  • 1 - Swap the connection to the alternate sink.

  • 2 - Swap the connection to the alternate sink and attempt to retransmit the transaction to that sink. (Note that an attempt is only made to retransmit the transaction if the response from Transaction Manager indicates that the upstream entity is unavailable (and not a case where a timeout occurred). This is indicated by the Auth Reason sub-value of the Auth Profile field being set to 1, 4, or A. If no Auth Profile field is set, and the response code is 96, the retransmit also occurs; this indicates that the message was turned around by Transaction Manager before the field was set.)

If this parameter is not specified, then DualSink defaults to taking no action. This parameter does not affect failover behavior in the following situations:

  • Connectivity is lost on the active link before a response is received, or a local timeout occurs. In these scenarios, Dual Sink always attempts to failover to the alternate sink.

  • The failover behavior is overridden by the presence of a known Postilion:UpstreamUnavailableAction value in the response message.

Sink entity names

This parameter specifies the tag names of the sink entities that DualSink will use. It is specified as:

SINK_NAMES=sink1,sink2

  • where sink1 and sink2 are the tag names of the sink entities, separated by a comma.

If this parameter is not specified, then DualSink defaults to the tag names "SINK1" and "SINK2".

Primary sink choice probability

When DualSink is configured, this parameter will be used to determine whether SINK1 will be the primary sink. The higher the value the more likely SINK1 will be the primary sink.

PRIMARY_SINK_SELECTION_PROBABILITY=x, where x is a percentage(1-100).

If this parameter is not specified, then DualSink defaults to using a 50% probability.

Realtime systems connected in Active/Active Mode

This parameter can be configured to indicate if the Realtime systems to which the sink entities are connected to, has been configured to operate in Active/Active mode. It is specified as

SNK_AA=x, where x is one of:

  • 0 - Active/Backup mode.

  • 1 - Active/Active mode.

If this parameter is specified as Active/Active then DualSink will try to send linked transactions to the active sink instead of the original sink. The default is Active/Backup.

Class Name: postilion.esocketpos.postilioninterface.DualSink

5.3.4. CallbackSink

The eSocket.POS CallbackSink uses the eSocket.POS callback mechanism to request an online authorization from the POS application. This is applicable when eSocket.POS does not have its own online authorization channel to an upstream payments system, and the POS has its own method of online authorization.

See the eSocket.POS Developer Guide for detailed information about the eSocket.POS callback mechanism.

The callback event raised by the CallbackSink has the event ID AUTHORIZE, and the data string associated with the callback describes the transaction data. The POS must register for this callback to be notified of this event.

In response to the callback, the POS returns a string containing the response data resulting from the authorization. If the callback sink does not receive a response to the callback, it times out and declines the transaction.

See the "Event ID" page of the eSocket.POS Developer Guide for detailed information about the AUTHORIZE callback.

Note: The CallbackSink does not provide any mechanism for delivering advice messages. When used, delivery of advice messages (including generating a reversal following a lost authorization request) is the responsibility of the POS application and does not involve eSocket.POS.

Parameters: The CallbackSink does not require any parameters.

Class name: postilion.esocketpos.postilioninterface.CallbackSink

5.3.5. MultiSink

eSocket.POS uses MultiSink to connect to multiple payment servers and not just Realtime. MultiSink itself does not connect to an upstream entity, but manages multiple sink entities. MultiSink determines which sink must process an incoming message, and hands the message to the appropriate sink.

To implement a MultiSink, you must configure the esp_classes table under the SINK tag. You can configure multiple sinks under the tags specified by the SINK_NAMES parameter (see below). If SINK_NAMES is not specified, MultiSink initialization fails during the initialization of the terminal.

MultiSink must have parameters as specified below, and the sink entities must have the corresponding parameters configured.

Parameters: Configure the MultiSink with the following parameter:

Parameter Values

1

SINK_NAMES

This parameter specifies the tag names of the sink entities that MultiSink uses. It is specified as:

SINK_NAMES=sink1,sink2

where sink1 and sink2 are the tag names of the sink entities, separated by a comma.

Class Name: postilion.esocketpos.postilioninterface.AMultiSink

5.4. SAP Factories

5.4.1. Service access point (SAP) factories

eSocket.POS includes additional service access point (SAP) implementations to enable custom communications protocols. The following is a list of implementations and of the features supported by each implementation:

5.4.2. eSocket.POS TCP SAP factory

The eSocket.POS TCP SAP Factory allows enabling a combination of the TCP/IP based communications protocols supported by eSocket.POS.

The details of how to configure a custom SAP factory depends on the interface on which the factory is configured. Where it is applicable to the interface’s configuration, the following values must be used:

  • SAP Factory Class Name postilion.esocketpos.ipc.EspTcpSapFactory

  • SAP Protocol Can be set to either 0 (Realtime TCP/IP) or 15 (Raw TCP/IP)

  • SAP Setup Data The factory takes named parameters as part of the setup data string. Note that each parameter has a long name and a short name, either the long or short name can be used. The factory parses parameters in a similar fashion to the Windows command-line. Parameters are separated by white-space (space, tab, carriage return, and new line characters). Double quotation marks can be used to group white space separated strings into a single parameter and a back-slash can be used to "escape" double quotation marks.
    For example, if you want to enable SSL and only trust connections where the certificate’s subject common name is Jo "Bloggs" terminal, then the setup data string looks as follows:
    -ssl-type=jsse -ssl-sub-cn="Jo \"Bloggs\" terminal"

The remainder of this page describes the various named parameters that can be configured as part of the setup data.

SSL connections

The following parameters are used to configure secure socket layer (SSL) connections, see the SSL section of the user guide for guideline on how to configure SSL.

Parameter Description Default Required

-ssl-type= <ssl type>

OR

-t= <ssl type>

Configure this parameter to enable SSL on the SAP connection; <ssl type> specifies the method that is used to establish a trust relationship with the remote entity.

  • jsse - Authenticate the remote entity by using the default JSSE trust algorithm configured for the Java Virtual Machine. This is the recommended setting.

  • remotesink - This is a RemoteSink connection. Use the legacy SSL implementation to verify that the remote entity is trusted.

  • configagent - This is a Configuration Agent connection. Use the legacy SSL implementation to verify that the remote entity is trusted.

Not applicable

Mandatory if SSL is required.

-ssl-remote-auth= <boolean>

OR

-ra= <boolean>

Boolean value indicating if the remote entity must be authenticated. The default value for this option can only be changed if the -ssl-type is set to jsse.

  • If it is set to false, then all remote entities are trusted, regardless of the certificate they send, and also if they do not provide a certificate.

  • If it is set to true, then the remote entity must provide a trusted certificate. Note that if the -ssl-type is jsse, then this requires access to trusted root certificates. This means that the SSL truststore must be configured.

  • If it is set to true on a server SAP, then eSocket.POS can only authenticate the client if it has access to a usable private key. This means that the SSL keystore must be configured.

true for client SAPs and false for server SAPs.

No

ssl-sub-cn= <subject name>

OR

-scn= <subject name>

The common name specified in the subject field of the certificate received from the remote entity must match <subject name>, otherwise the SSL handshake fails. <subject_name> is case-sensitive. Note that validation of the subject’s common name only takes place if the remote entity is authenticated.

No validation is done on the subject field from the certificate provided by the remote entity.

No

-ssl-issuer-cn= <issuer name>

OR

-icn= <issuer name>

The common name specified in the issuer field of the certificate received from the remote entity must match <issuer name>, otherwise the SSL handshake fails. <issuer name> is case-sensitive. Note that validation of the issuer’s common name only occurs if the remote entity is authenticated.

No validation is done on the issuer field from the certificate provided by the remote entity.

No

-ssl-local-cert= <alias name>

OR

-lc= <alias name>

Identifies the identity that must be used when authenticating eSocket.POS to a remote entity. The <alias name> is the alias of a key entry in the SSL keystore; it is not case-sensitive.

The SSL implementation queries the SSL keystore to find the private keys that are valid for authenticating the local side of the connection. If one of those keys matches <alias name>, it is used. Otherwise, eSocket.POS does not authenticate the local side of the connection.

By default, if there are multiple valid keys an arbitrary one is chosen.

No

-ssl-protocols= <protocols>

OR

-sp= <protocols>

<protocols> is a semi-colon separated list of SSL protocols that must be enabled on this SSL connection. The EspTcpSapFactory allows the following values:

  • TLSv1.2 - TLS version 1.2 protocol

  • TLSv1.1 - TLS version 1.1 protocol

  • SSLv2 - SSL version 2 protocol

  • SSLv3 - SSL version 3 protocol

  • TLSv1 - TLS version 1 protocol

  • SSLv2Hello - Enables sending of SSLv2 hellos. For compatibility reasons, some protocols, such as SSLv3 and TLSv1, allow sending SSLv3/TLSv1 hellos encapsulated in an SSLv2 format hello.

The default values must work in most cases, but it might be necessary to specify the protocol in some specialized deployments. For example, in most cases where the default configuration is used, eSocket.POS sends SSLv2 compatible 'hello' messages to the remote server. Some servers only supports SSLv3 in which case it might be necessary to set the value of this parameter to SSLv3.

Note that the supported values depends on the JSSE implementation distributed with the JVM on which eSocket.POS is running.

The protocols enabled by default depend on the JSSE implementation distributed with the JVM on which eSocket.POS is running.

No

Sink entity connections

The following parameters can be used when configuring the factory on the RemoteSink interface.

Parameter Description Default Required

-app-keep-alives= <time_wait>,<retries parameter>

OR

-aka= <time_wait>,<retries parameter>

Specify this parameter to enable application level connection keep-alives. The functionality that is enabled with this option is identical to that provided by the ConnectionKeepAliveSapFactory. The only difference is that the EspTcpSapFactory allows application level connection keep-alives to be used in combination with some of the other supported features.

Note that PosConnect must be configured to respond to application level keep-alives before this option can be enabled at eSocket.POS. PosConnect supports application level keep-alives with either the PosConnectTcpSapFactory or the ConnectionKeepAliveSapFactory. See the "Interface Configuration" section of the PosConnect User Guide for details on configuring a SAP factory class for PosConnect.

The parameter consists of two comma-separated values. The first is the number of milliseconds before a keep-alive message is sent. The second is the number of times keep-alive messages are sent without response before the connection is dropped.

Functionality is disabled by default.

No

-shared-sap= <boolean>

OR

-ss= <boolean>

Specify this parameter with a value of true to allow RemoteSink to share a single connection between multiple terminals. The functionality that is enabled with this option is identical to that provided by the Single Connection SAP Factory. The only difference is that the EspTcpSapFactory allows a shared connection to be used in combination with some of the other supported features.

Note that the connections are only shared by terminals that connect to the same remote host and port, and that has the same setup data string configured for the EspTcpSapFactory.

Functionality is disabled by default.

No

-msg-encrypt= <boolean>

OR

-me= <boolean>

Specify this parameter with a value of true to enable the encryption of messages sent to PosConnect. Message Encryption provides an alternative to an SSL secured connection between eSocket.POS and PosConnect. It might be preferred over SSL when the remote server is unable to cope with the additional overhead of establishing SSL connections with many terminals.

Message Encryption uses the same RSA Certificates that is used to enable strong data protection in eSocket.POS. Ensure that the following steps are completed before enabling message encryption:

  • Configure PosConnect for Message Encryption. This entails the configuration of

    • A custom SAP Factory on the PosConnect interface.

    • The RSA Certificate required for strong data protection.

    • A CMS service dependency.

See the PosConnect User Guide for more information on configuring PosConnect for Message Encryption.

  • Configure the Certificate Manager pipeline component.

  • Once message encryption is enabled, eSocket.POS can only send messages to PosConnect if the required RSA certificates are loaded. This means that either the initial certificate must be loaded manually, or the Certificate Manager Component must be allowed to do at least one successful key exchange before message encryption is enabled.

Functionality is disabled by default.

No

All connections

The following parameters are applicable to all TCP/IP connections.

Description Default Required

-tcp-keep-alives= <boolean>

OR

-tka= <boolean> Parameter

Specify this parameter with a value of true to enable TCP keep-alives on the connection. This can be used to detect when a connection is stale, or to prevent a disconnect due to network inactivity. The TCP keep-alive time and interval can be configured for the eSocket.POS machine in an OS dependent manner.

If eSocket.POS is installed on a Windows platform, the keep-alive time and interval can be adjusted by altering or adding the following registry values under the key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters:

  • KeepAliveTime - this is the period between keep-alive (ACK) packet transmissions or the last data packet sent upstream and is specified in milliseconds. By default, this value is set to 2 hours (7200000 milliseconds).

  • KeepAliveInterval - this is the period between keep-alive retransmissions until a response is received and is specified in milliseconds. By default, this value is set to 1 second (1000 milliseconds).

Functionality is disabled by default.

No

Please contact your primary support provider for further details about SAP factory classes.

5.4.3. Connection keep alive SAP factory

(This factory is used by the RemoteSink interface only.)

A connection keep-alive Service Access Point (SAP) factory class, ConnectionKeepAliveSapFactory, can be configured at eSocket.POS to ensure that a connection is alive during periods of inactivity. Note that this requires the same SAP factory to be configured at PosConnect as well. Refer to the "Interface Configuration" section of the PosConnect User Guide for details on configuring a SAP factory class for PosConnect.

The details of how to configure a custom SAP factory depends on the interface on which the factory is configured. Where it is applicable to the interface’s configuration the following values must be used:

  • SAP Factory Class Name

    postilion.esocketpos.ipc.ConnectionKeepAliveSapFactory

  • SAP Protocol

    0 (Always set to 0)

  • SAP Setup Data

    The Time wait and Retries parameters. (For example, "30000 3" where time wait is 30 seconds and retries is 3)

    The Time wait parameter is the number of milliseconds before a keep-alive message is sent.
    The Retries parameter is the number of times keep-alive messages are sent without response before the connection is dropped.

Please contact your primary support provider for further details about SAP factory classes.

5.4.4. Single connection SAP factory

(This factory is used by the RemoteSink interface only.)

The Single Connection SAP Factory class, TcpSingleSapFactory, can be configured at eSocket.POS. The Single Connection SAP Factory creates only a single connection to a Realtime for a particular IP/Remote port combination. This type of connection is typically used on an eSocket.POS installation, where eSocket.POS interfaces to multiple terminals. The single connection made to the Realtime system reduces both the resources required for the server that eSocket.POS is running on, as well as the resources required by the Realtime system.

The Single Connection SAP Factory requires another SAP Factory implementation to indicate the type of connection to be made to Realtime, of which only a single connection of this type is required.

The details of how to configure a custom SAP factory depends on the interface on which the factory is configured. Where it is applicable to the interface’s configuration the following values must be used:

  • SAP Factory Class Name

    postilion.esocketpos.ipc.TcpSingleSapFactory

  • SAP Protocol

    0 (Always set to 0)

  • SAP Setup Data

    The SAP Factory to use, the SAP protocol to use, and the SAP Setup Data (enclosed by single quotes) are specified here.

    For example, "postilion.esocketpos.ipc.ConnectionKeepAliveSapFactory 0 '30000 3'" - creates a single connection to be shared amongst all terminals to Realtime that has keep-alives enabled.

    or

    "postespos.core.node.TcpRawSapFactory" - creates a TCP connection to be shared amongst all terminals to Realtime.

Please contact your primary support provider for further details about SAP factory classes.

5.5. Pipelines

Transaction engine

The eSocket.POS Transaction Engine is an internal entity within eSocket.POS. It manages the processing of transactions via configurable components in a request and a response pipeline.

A large number of standard pipeline components are supplied with eSocket.POS, and custom components can also be developed where additional functionality is required.

Request pipeline

The request pipeline consists of a number of configurable pipeline components, each of which takes responsibility for one aspect of transaction processing. Transaction requests are passed to each component in turn. A component can be responsible for populating certain properties of the transaction, validation (including rejecting the transaction if validation fails), user interaction, or a number of other functions.

Response pipeline

The response pipeline consists of a number of configurable pipeline components, each of which takes responsibility for one aspect of transaction processing. Transaction responses are passed to each component in turn. A component is usually responsible for completing some aspect of the transaction, or for user interaction.

Each pipeline component takes responsibility for one aspect of transaction processing. Transactions are passed to each component in turn. The component can be responsible for populating certain properties of the transaction, validation (including rejecting the transaction if validation fails), user interaction, completing the transaction, or a number of other functions.

Internal message format

Internally, and in its connection to an upstream Realtime system, eSocket.POS uses messages formatted according to the ISO 8583 (1987) standard for bank card originated transactions.

When using the eSocket.POS API, XML interface, or Message front-end, each transaction request is translated to the ISO 8583 message representation, and the response message is translated back from ISO to the relevant transaction response format.

Note
Application programmers and integrators need not concern themselves with the ISO 8583 message protocol.

5.5.3. Recommended order of pipeline components

The recommended order of the pipeline components, if all the components are configured, is shown below. Client requirements might change this order slightly. See the descriptions of the required rank for each pipeline component for more detail.

Note: The letter in brackets after each component indicates whether the component is optional (o) or mandatory (m).

Request pipeline

The following pipeline components are listed first in the request pipeline:

  • RkdManager (o)

  • P2PE Security (o)

  • LineItemDisplay (o)

  • Pre-swipe (o)

  • Prepaid Card (o)

  • LateFallback (o)

  • LateFallForward (o)

  • Amount (m)

  • Alipay (o)

  • PAN (m)

  • Account (m)

  • Transaction Allowed (o)

  • Acquirer (o)

  • Device Data Capture (o)

  • Loyalty (o)

  • TranInquiry (o)

Followed by a selection of the following components, in any order:

  • AVS (o)

  • Gratuity (o)

  • Cashback (o)

  • CVV2 (o)

  • Date Time (m)

  • Effective Date (o)

  • Expiry Date (o)

  • Extended Payment (o)

  • Key Manager (o)

  • Prepay (o)

  • Service Code (o)

  • Transaction Cleaner (m)

  • Merchant (m)

  • Check Read (o)

  • Card Sequence Number (o)

  • Signature Capture (o)

  • Certificate Manager (o)

  • Verishield (o)

  • FinalAuth (o)

Followed by zero or more of the following pipeline components, in any order:

  • Card Acceptor ID Code (o)

  • Check Authorization (o)

  • Hotcard (o)

Followed by a selection of the following pipeline components in the order shown:

  • Rapid Payment Service (o)

  • Referral Advice (o)

  • Cardholder Name (o)

  • DCC (o)

  • Confirm (o)

  • EMV (o)

  • PIN (o)

  • Stand-in (o)

  • SCA (o)

  • TokenGeneration (o)

  • Reconciliation (o)

  • POS Config (m)

  • Wait For Authorization (o)

  • DeclinedAdvices (o)

  • EMV Config (o)

  • Monitoring (o)

  • ReferenceData (o)

  • Echo (m)

Response pipeline

The following pipeline components are listed first in the response pipeline:

  • Echo (m)

  • Monitoring (o)

  • LateFallback (o)

  • SCA (o)

  • DCC (o)

  • Stand-in (o)

  • EMV (o)

  • Reconciliation (o)

  • Rapid Payment Service (o)

  • TokenGeneration (o)

  • DeclineReferral (o)

Followed by zero or more of the following components, in any order:

  • Fallback Indicator (o)

  • Generate Referral Response (o)

  • Hotcard (o)

  • Response Code (o)

  • Call Auth Centre (o)

  • Card Product (o)

  • Funds Inquiry Response (o)

  • Check Authorization (o)

  • Cardholder Name (o)

  • Prepay (o)

  • Effective Date (o)

  • Signature (o)

  • SignatureCapture (o) (Note: Must be after Signature component)

  • Loyalty (o)

  • PAN (m)

  • DeclinedAdvices (o)

  • TranInquiry (o)

Followed by the following component(s):

  • AdviceCardData (o) (Note: Must be after PAN component)

  • LateFallForward (o)

  • RkdManager (o)

  • EMV Config (o)

  • P2PE Security (o)

  • Display Welcome (m)

5.5.4. Pipeline component - Account

Description: The Account component is responsible for setting the From Account, or the To Account for a credit transaction (for example, a refund, deposit, credit adjustment, gift card load or gift card activate with a deposit). The account is selected as follows:

  • If the PAN entry mode indicates that an EMV card is used, and the default account (type 00 - Default) is configured, or if only the default account is configured, then the default account is selected.

  • Otherwise, the account is selected from a list of available accounts. This list contains the accounts configured for this card with the default account removed, depending on the DISPLAY_DEFAULT property setting. If the list contains only one available account then that account is used. If it contains more than one account then the component prompts the user to select the account.

  • If the FILTER_ACCOUNTS_ON_AID_TYPE parameter is enabled, then the available accounts will be filtered against the configured AID Type.
    Filter rules: For a US Common Debit AID Type (3), only retain account types of Savings (10) and Check (20). For other AID Types, filter out account types of Savings (10) and Check (20).

If the Account field cannot be set, or the validation fails, the transaction is declined.

If a cashback amount is contained in the transaction, the Account component also sets the cashback account type.

If the transaction is a healthcare benefit transaction, or the card used is a healthcare card, eSocket.POS checks if the card is a valid healthcare card and declines the transaction if it is not.

Usage: Request pipeline, mandatory.

Rank: Must be configured immediately after the PAN component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentAccount

Parameters: The component may be configured with the following optional parameter:

Parameter Values

1

account order

The order in which the available accounts must be presented to the customer. This parameter consists of a single string (without spaces) of the ISO account types in the preferred order. For example, 302010 if the preferred order is Credit (30), Check (20), Savings (10).

If an account from this list is not available for the card being used, it is not displayed. Available accounts not included on this list are displayed after the listed accounts, in numerical order according to their ISO account type.

This parameter is optional.

The Account component can also be configured with the following named parameters:

Parameter Values

DISPLAY_DEFAULT

DISPLAY_DEFAULT=x, where x is one of:

  • 0 - Do not display the default account during account selection.

  • 1 - Display the default account during account selection.

This parameter is optional and has a default setting of 0.

FILTER_ACCOUNTS_ON_AID_TYPE

FILTER_ACCOUNTS_ON_AID_TYPE=x, where x is one of:

  • 0 - Do not use the configured AID Type to filter accounts.

  • 1 - Filter the account types against the configured AID Type.

This parameter is optional and has a default setting of 0.

Decline conditions:

Condition Response Code Message Reason Code

Transaction is a Check Guarantee or Check Verification transaction, and the card does not support check authorization

12 - Invalid Transaction

9756 - Not Valid for Transaction

Message did not contain a Processing Code field

30 - Format Error

9704 - Missing Processing Code

Message did not contain a supported account type, and no account was entered via a device

42 - No Universal Account

9705 - Missing Account

No supported accounts are available for this card, or card is not configured in the eSocket.POS database

56 - No Card Record

9751 - No Supported Accounts

Card number was entered manually, and card does not support manual entry

62 - Restricted Card

9752 - No supported accounts for manual entry

A smart card was read using the magnetic stripe and card does not support ICC fallback

62 - Restricted Card

9755 - No supported accounts for ICC fallback

5.5.5. Pipeline component - Activation

Description: This component manages TLS encryption keys and certificates for a terminal’s connection to the switch. When eSocket.POS is configured for TLS connections and this component is configured, it performs the following operations:

  • At initialization, determine if the terminal has a valid, signed public key certificate, which proves its identity to the switch during TLS negotiation. If it has no such certificate, it will start an activation sequence whereby the switch will sign a Certificate Signing Request (CSR) and return a signed certificate to the terminal, which it can use for future connections.

  • Decline any messages if the terminal does not currently have a valid, signed TLS public key certificate.

  • Periodically renew the public key certificate used during TLS negotiations, before it expires.

As part of the activation sequence, to validate the authenticity of an activation request, the switch expects a security value, which proves that the request could only have come from the terminal that sent it. Because a terminal has to be in possession of a pinpad to perform transactions and because pinpads can perform various secure operations which can be validated by the switch, we request a security value generated by some function on the pinpad and add that to the activation request. The switch then independently verifies the security value before signing the certificate signing request.

An important difference from standard TLS configuration is that the -ssl-local-cert configuration option must not be specified as it will be dynamically added before initiating the connection to the switch.

Usage: Mandatory in both the Request Pipeline and Response Pipeline.

Rank: Should be configured close to the start of the request pipeline (to allow messages from terminals that are not currently activated to be declined as soon as possible, before any user interaction occurs). Rank in the response pipeline is not prescriptive.

Class name: postilion.esocketpos.transactionengine.PipelineComponentActivation

Parameters:

The component can be configured with the following optional named parameters:

Parameter Values

STARTUP_DELAY

Amount of time in seconds to wait after initialization of this pipeline component before attempting the activation sequence for this terminal.

For example, STARTUP_DELAY=30

The default delay if this parameter is not configured is 10 seconds.

ERROR_DELAY

Amount of time in seconds to wait after an error occurs during activation before attempting the activation sequence again.

For example, ERROR_DELAY=120

The default delay if this parameter is not configured is 30 seconds.

DISCONNECT_DELAY

Amount of time in seconds to wait if eSocket.POS is currently not connected before attempting the activation sequence again.

For example, DISCONNECT_DELAY=300

The default value is 60 seconds.

REACTIVATION_DELAY

Amount of time in days before the expiry of a TLS public key certificate that the certificate should be renewed using the reactivation sequence.

Caution
Care should be taken to not set this period to longer than the certificate validity configured in PosConnect. If configured incorrectly, the terminal will reactivate continuously and not be able to transact.

For example, REACTIVATION_DELAY=10

The default value is 5 days.

Decline conditions:

Condition Response Code Message Reason Code

If a transaction is sent if the terminal is not yet activated.

03 - Invalid Merchant

4359 - Terminal Not Activated

Limitations:

  • Using this component with legacy TLS configuration is not supported. It is required to configure a key store and trust store in the eSocket.POS properties file.

  • The activation sequence only applies to switch connections. No activation/automatic certificate signing will be done for any other connections. As an example, a certificate to use for connection to the pinpad cannot be obtained in this manner.

  • By default, only connections from a RemoteSink entity supports certificates issued through the activation sequence. To confirm whether other upstream interfaces support activation, please contact your primary support provider.

5.5.6. Pipeline component - Acquirer

Description: The Acquirer component is responsible for setting Acquiring Institution ID Code (field 32) and Receiving Institution ID Code (field 100), if either of these fields are missing from the ISO 8583 request message. If the component finds the missing ID field in the esp_accounts table, it writes it to the request message in the appropriate field.

If the Acquiring Institution ID Code is not configured in the esp_accounts table, the component defaults to the acquiring_inst_id value set in the esp_pos_config table. Likewise, if the Receiving Institution ID Code is not configured in the esp_accounts table, the component defaults to the receiving_inst_id value set in the esp_pos_config table. If either field is found, the component sets the DefaultAcquirerIDSet subfield as 1 in the ISO 8583 request message structured data.

Usage: Optional in Request Pipeline.

Rank: Must be configured after the PAN and Account components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentAcquirer

Parameters: None.

Decline Conditions: None.

5.5.7. Pipeline component - AdviceCardData

Description: When OnGuard/P2PE is turned on, the card number, and the expiry date will not be returned to the POS for advices. When AdviceCardData component is configured it will populate a dummy PAN with 19 zeros, and the expiry date with the configurable expiry date parameter on the pipeline component.

Usage: Optional in Response Pipeline.

Rank: Must be configured after PipelineComponentPan in the response pipeline.

Class name: postilion.esocketpos.transactionengine.PipelineComponentAdviceCardData

Parameters: This parameter indicates the default value for the expiry date. It is specified as: DEFAULT_EXPIRY_DATE=x where x is the required expiry date in the future in the format YYMM.

5.5.8. Pipeline component - Alipay

Description: If the request transaction is an Alipay transaction, then the Alipay component performs the following:

  • Populates the Dummy PAN 0000000000000000000 in the message.

  • Populates the Receiving Institution ID (field 100) in the message, if not set.

  • Populates the WalletPayment subfield in the structured data (field 127.22)

Usage: Request pipeline, optional.

Rank: Must be configured before the PAN component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentAlipay

Parameters: The component must be configured with the following named parameters, separated by spaces. These parameters do support values containing the spaces. However, such a value should be enclosed in the double quotation marks, as given in the following example:

RECEIVING_INST_ID=11111111111 QUANTITY=4 TRANSACTION_NAME="Alipay Tran" STORE_ID=1234 MEMO=memo1

Parameter Values

1

RECEIVING_INST_ID

The value to be inserted into the Receiving Institution ID Code (field 100) of the ISO 8583 message if not already present, defining which sink node the payments system must route the transaction to. Format n..11.

This parameter is mandatory.

For example, RECEIVING_INST_ID=11111111111

2

QUANTITY

The value to be inserted into the Structured Data tag Quantity, if not already present inside the tag WalletPayment.

This parameter is optional.

For example, QUANTITY=1

3

TRANSACTION_NAME

The value to be inserted into the Structured Data tag TransactionName, if not already present inside the tag WalletPayment.

This parameter is optional. The default value is Alipay Payment

For example, TRANSACTION_NAME=Kiosk

4

STORE_ID

The value to be inserted into the Structured Data tag StoreId, if not already present inside the tag WalletPayment.

This parameter is optional.

For example, STORE_ID=1234

5

MEMO

The value to be inserted into the Structured Data tag Memo, if not already present inside the tag WalletPayment.

This parameter is optional.

For example, MEMO=memo1

Decline conditions:

Condition Response Code Message Reason Code

Alipay Transaction without Structured Data tag BarcodeData

30 - Format Error

9715 - Missing Barcode Data

5.5.9. Pipeline component - Amount

Description: The Amount component is responsible for setting the Amount field. If no Amount is present, the component prompts the user to enter the amount.

The Amount component also checks that the purchase, cashback, and transaction amounts fall within the configured maximum limits.

Usage: Request Pipeline, mandatory.

Rank: If EMV cards are used, and the Amount component is responsible for requesting the amount from the customer, then it must appear before the PAN component.

If the Amount component simply validates that the Amount is present in the message from the POS, then it can appear before or after the PAN and Account components, but it must appear after if it is required to perform maximum amount checking. Note that maximum amount checking is not typically available for EMV cards.

Class name: postilion.esocketpos.transactionengine.PipelineComponentAmount

Parameters: The component must be configured with the following parameter:

Parameter Values

1

repeat entry above maximum

Defines how the component must react if the amount exceeds the maximum amount allowed for the card and account.

0 - Reject the transaction

1 - Prompt the user to enter a new amount. (this option is only valid if the keypad device supports amount entry)

Decline conditions:

Condition Response Code Message Reason Code

The cashback amount exceeds the allowed maximum cashback amount for this card and account

13 - Invalid Amount

9761 - Cashback Amount Exceeds Maximum

The purchase amount exceeds the allowed maximum purchase amount for this card and account

13 - Invalid Amount

9760 - Purchase Amount Exceeds Maximum

The transaction amount exceeds the allowed maximum transaction amount for this card and account

13 - Invalid Amount

9762 - Transaction Amount Exceeds Maximum

The cashback amount exceeds the total transaction amount

13 - Invalid Amount

9770 - Cashback Exceeds Transaction Amount

Message did not contain a Transaction Amount, and Transaction Amount was not entered via a device

30 - Format Error

9700 - Missing Amount

Message did not contain a Currency Code, and a default Currency Code was not inserted

30 - Format Error

9707 - Missing Currency Code

Note
Referral Advices (0220 messages with message type set as 'REFERRAL') prompt for an amount, if the amount of the original message (Authorization Request or Transaction Request) could not be found on the same terminal. This is typically the case when the referral advice is processed on another terminal than the original message.

5.5.10. Pipeline component - AVS

Description: The AVS (Address Verification Service) component is responsible for inserting address verification details into a transaction.

  • For a customer-not-present (CNP) transaction, the AVS component will always prompt for a postal address. Prompting for a postal code is configurable.

  • For all other financial transactions the AVS component will not prompt for a postal address. Prompting for a postal code is configurable.

Usage: Request pipeline, optional.

Rank: Must be after the PAN and Account components, but before the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentAvs

Parameters: The component must be configured with the following parameters:

Parameter Values

1

postal code required CNP

Determines whether the component prompts for the postal code (ZIP code) to be entered for a CNP transaction.

0 - Do not prompt for postal code.

1 - Prompt for postal code.

2 (Optional)

postal code required non-CNP

Determines whether the component prompts for the postal code (ZIP code) to be entered for all financial transactions other than CNP transactions.

0 - Do not prompt for postal code (default value).

1 - Always prompt for postal code.

2 - Prompt for postal code on manual PAN entry only.

Note
If such transactions are EMV transactions, or they are validated by PIN, then this component will not prompt for the postal code.

The AVS component can also be configured with the following named parameters:

Parameter Values

EXCL_ACCS

A semi-colon separated list of excluded account types as used in field 3 - Processing Code. If a transaction contains one of these account types in either the To or From account, Address Verification prompting will not be done.

Example: EXCL_ACCS=30;70

This parameter is optional and by default all account types will trigger Address Verification prompting.

Decline conditions: None

Transaction Processing Results:

The AVS component sets the following Transaction Processing Results (TPR) in the request message for byte 1.

Note
In the table below, a dash (-) represents a bit that is not in use and RFU stands for "reserved for future use".
Name Bit Description

CheckCustomerNotPresentIncludeAccount

8

When set, this bit indicates that the check to insert AVS information into the transaction was performed.

CustomerNotPresentIncludeAccount

7

When set, this bit indicates that it was attempted to insert AVS information into the transaction.

CheckPromptZipCode

6

When set, this bit indicates that the check to insert only the zip code into the transaction was performed.

PromptZipCode

5

When set, this bit indicates that it was attempted to insert only the zip code into the transaction.

-

4

RFU

-

3

RFU

-

2

RFU

-

1

RFU

5.5.11. Pipeline component - Call auth center

Description: The Call auth center component is responsible for inserting a referral telephone number into a response when the response code indicates a referral. The referral telephone number is retrieved from the accounts configuration and then from the cards configuration, if not present in the accounts configuration.

Usage: Response pipeline, optional.

Rank: Any

Class name: postilion.esocketpos.transactionengine.PipelineComponentCallAuthCenter

Parameters: None

Decline conditions: None

5.5.12. Pipeline component - Card acceptor ID code

Description: The Card acceptor ID code component populates the Card Acceptor ID Code for this card and account. The value configured for a specific card and account can be used to override the value configured per terminal or per merchant.

Usage: Request pipeline, optional.

Rank: Must be configured after the merchant component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentCardAcceptorIdCode

Parameters: The component can be configured with the following optional named parameter.

Parameter Values

IS_CA_ID_REQUIRED

Specifies whether transactions should be rejected when field 42 is not set by this component.
Configure the parameter as follows:

  • 0 - Ignore this setting. (default)

  • 1 - Reject transactions when field 42 is not being set by this component.

Example: IS_CA_ID_REQUIRED=1

Decline conditions:

Condition Response code Message reason code

Field 42 cannot be populated by this component.

5 - Do not honor

9716 - Missing card acceptor ID

5.5.13. Pipeline component - Card product

Description: The Card Product component populates the Card Product name for this card in the response.

Additionally, the component can be configured to populate additional Card/Account information by setting the optional SEND_ADDITIONAL_CARD_INFO_OPTION named parameter. See the table that follows for details.

NOTE: The component acts on the following messages:

  • Financial:

    • 0110

    • 0130

    • 0210

    • 0230

    • 0410

    • 0430

  • Admin:

    • 0610 [Transaction Type: 95]

Usage: Response Pipeline, optional.

Rank: Any

Class name: postilion.esocketpos.transactionengine.PipelineComponentCardProduct

Parameters: The Card Product component can be configured with the following named parameter:

Parameter

Values

SEND_ADDITIONAL_CARD_INFO_OPTION

SEND_ADDITIONAL_CARD_INFO_OPTION=x, where x is one of:

  • 0 - Do not populate additional card information.

  • 1 - Always populate additional card information.

  • 2 - Only populated additional card information when processing CARD_READ , 0610 Transaction Type 95, messages.

  • 3 - Only populated additional card information when processing Financial messages. See the list at the top of this section for a complete list.

This parameter is optional and has a default setting of 0.

When the SEND_ADDITIONAL_CARD_INFO_OPTION is set to a non-zero value, additional account information will be returned. This information includes:

  • Account Name

  • Account Type

  • EMV Fallback Allowed

  • Default Pre-Auth Amount for Contactless
    Note: In ConfigServer, this value is defined in the DEFAULT_PREAUTH_AMOUNT_CTLS extended parameter, set on the Account.

  • Default Pre-Auth Amount for EMV
    Note: In ConfigServer, this value is defined in the DEFAULT_PREAUTH_AMOUNT_EMV extended parameter, set on the Account.

  • Default Pre-Auth Amount for MSR
    Note: In ConfigServer, this value is defined in the DEFAULT_PREAUTH_AMOUNT_MSR extended parameter, set on the Account.

Additionally, custom extractors can be configured using the Extended Parameters set on the Card Profile. The custom extractors take the form of:
Extract_CardInfo_<DataName> = <Field>,<Subfield>,<Offset>,<Length>

For example, to extract a value named MembershipId encoded in the first 10 characters of Track1’s Discretionary Data, the following custom extractor could be defined:
Extract_CardInfo_MembershipId=Track1,DiscretionaryData,0,10

Custom extractors can also be chained together using the pipe character (|). For example, if the MembershipId from the previous example is also found in Track2’s Discretionary Data, starting with the fourth character, the custom extractor could be defined as:
Extract_CardInfo_MembershipId=Track1,DiscretionaryData,0,10|Track2,DiscretionaryData,3,10
In the example above, eSocket.POS would first attempt to extract the MembershipId from Track1’s Discretionary Data. If Track1 is not available, or if the Discretionary Data is not long enough, eSocket.POS would then attempt to extract the MembershipId from Track2’s Discretionary Data.

Note: As the data that can be extracted is configurable, care should be taken to ensure that the extracted data does not have any security risks.

The definitions for the customer extractors are as follows:

Parameter

Values

DataName

DataName=x, where x:

Will identify/define the name of the Extracted data element; the extracted data will populate in the response returned to the Point of Sale (POS). This parameter will be capitalized and set as the name of the Extracted data element.

This parameter is required.

Field

Field=x, where x is one of:

  • Track2 or 35 - Extract from Track2/Field 35.

  • Track1 or 45 - Extract from Track1/Field 45.

  • StructuredData or 127.22 - Extract from StructuredData.

  • EmvTag - Extract from TlvIccDataExtended .

  • Field/Bit Number - Extract from the data populating the field number.
    Note: This value must be numeric.

This parameter is required.

Subfield

Subfield=x, where x is one of:

  • PAN - Extract from the primary account number (PAN) portion of Track1 or Track2.
    Valid for the Track1 and Track2 extractors only.

  • DiscretionaryData - Extract from the Discretionary Data portion of Track1 or Track2.
    Valid for the Track1 and Track2 extractors only.

  • FinalFieldSeparator - Extract starting from the final field separator in Track1 or Track2.
    Valid for the Track1 and Track2 extractors only.

  • Emv Tag - Extract from the EvmTag defined in TlvIccDataExtended.
    Example: 9F1F
    Valid for the EmvTag extractor only.

  • StructuredData Tag - Extract from the given tag in StructuredData
    Valid for the StructuredData extractor only.

This parameter is required for all extractors except the Field/Bit Number extractor.

Offset

Offset=x, where x is a zero-based offset into the Field/Subfield where the data extraction will begin.

This parameter must be numeric, greater than or equal to zero, and is required.

Length

Length=x, where x the length of the data to extract.
Note: If the Offset plus the Length is greater, then the length of the source data, no data will be extracted.

This parameter must be numeric, greater than or equal to one, and is required.

Note
All extended parameters mentioned here have to be defined in ConfigServer, as needed. Refer to the "Advanced application configuration" section of the ConfigServer User Guide for more details.

Decline conditions: None

5.5.14. Pipeline component - Card sequence number

Description: For magnetic stripe or manual-pan entry transactions, the Card Sequence Number component is responsible for setting and validating the Card Sequence Number (Issue Number), if it is required for the card.

If the card sequence number is required (the card_seq_nr_offset column in the esp_cards table is set to a non-zero value, then the card sequence number is retrieved as follows:

  • If the card is manually entered, the component prompts the user to enter the card sequence number manually.

  • If the magnetic stripe of the card is read, the Card Sequence Number is extracted from Track 2 using the offset and length configured for the card.

  • If the Card Sequence Number cannot be set, the transaction is declined.

  • The length of the Card Sequence Number supplied by the POS or entered on a device is validated against the configured Card Sequence Number length for that card in the eSocket.POS database. However, this validation is not performed if the length is configured as zero in the eSocket.POS database.

If the card sequence number is not required (the card_seq_nr_offset column in the esp_cards table is set to 0 or NULL), then the Card Sequence Number component clears the card sequence number (field 23).

Usage: Request Pipeline, optional.

Rank: Must be after the PAN and Account components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentCardSeqNr

Parameters: None

Decline conditions:

Condition Response Code Message Reason Code

Message did not contain a card sequence number and no card sequence number was entered via a device

30 - Format Error

9710 - Missing Card Sequence Number

The manually entered card sequence number has an invalid format due to one of the following conditions:

  • The offset of the card sequence number is incorrectly configured for the card in the database.

  • The length of the card sequence number is incorrectly configured for the card in the database.

  • The value of the manually entered card sequence number is not numeric.

  • The length of the manually entered card sequence number does not correspond with the length configured for the card in the database.

30 - Format Error

9763 - Card Sequence Number Invalid

5.5.15. Pipeline component - CardholderName

Description: The CardholderName component is responsible for retrieving the cardholder name from the card reader device, or alternatively from track 1 data, if it is available, and the PAN Entry Mode is not 01,07, or 91.

Usage: Request pipeline, optional.

Response pipeline, mandatory, if in the request pipeline.

Rank: In the request pipeline, the CardholderName component must be configured between the PAN and EMV components. In the response pipeline, it must be configured after the Stand-in component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentCardholderName

Parameters: None

5.5.16. Pipeline component - Cashback

Description: The Cashback component can be configured to either validate cashback for a transaction or insert cashback in a transaction.

Usage: Request pipeline, optional.

Rank: Must be configured after the PAN, Account and Amount components, but before the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentCashback

Parameters: Configure the component with the following mandatory parameter:

Parameter Values

1

cashback mode

Indicates how the component must function.

0 - Validate cashback
The component must validate the cashback included in the transaction, and decline the transaction, if invalid. The validation includes the following:

  • Is cashback supported for this card and account type?

  • Is the cashback amount, account type and currency code valid?

  • Are the requested cashback amount and transaction amount within the allowed limit?

1 - Insert cashback
The component can insert cashback into transactions. If the transaction qualifies for cashback, the component prompts the user to enter a cashback amount and inserts it into the transaction. If a qualifying transaction already contains a non-zero cashback amount, the component validates the cashback (including declining it if invalid - see above).

NOTE:

  • Cashback is not allowed for account type 98 - EBT food stamp.

  • For account type 96 - EBT cash benefit, the upstream entity must be online to validate the cashback.

Optional named parameters: You can configure the Cashback component with the following optional named parameters. If configured, append these parameters to the cashback mode mandatory parameter described before.

Parameter Values

SHOW_CASHBACK_REQUIRED_PROMPT

Indicates whether customers must be asked if they would like a cashback.
For example: Would you like cash back (Y/N)?

0 - Disabled.
1 - Enabled (default)

If the parameter is disabled, the device immediately prompts the customer for the cashback amount without first asking if they would like a cashback.

SHOW_FIXED_DENOMINATION_CASHBACK_PROMPT

Indicates whether the customer must be prompted with fixed denomination cashback options to choose from.
For example: Please select the cashback amount from the following list: $10, $50, $100, $500, $1000'.

0 - Disabled (default)
1 - Enabled

NOTE:

  • This parameter must not be configured when using device models that are not capable of displaying an options screen.

  • If both the SHOW_FIXED_DENOMINATION_CASHBACK_PROMPT and SHOW_NUMERIC_ENTRY_CASHBACK_PROMPT parameters are enabled, then the fixed denomination cashback prompt is displayed first, with an additional option of "Other". Customers selecting "Other" can then enter a numeric amount from the numeric entry screen.

  • If no maximum cashback amount is specified, the fixed denomination cashback prompt will not be shown.

SHOW_NUMERIC_ENTRY_CASHBACK_PROMPT

Indicates whether the customer must be prompted to enter a cashback amount using a numeric entry screen.

0 - Disabled.
1 - Enabled (default)

NOTE:

If both the SHOW_FIXED_DENOMINATION_CASHBACK_PROMPT and SHOW_NUMERIC_ENTRY_CASHBACK_PROMPT parameters are enabled, then the fixed denomination cashback prompt is displayed first, with an additional option of "Other". Customers selecting "Other" can then enter a numeric cashback amount using the numeric entry screen.

FIXED_CASHBACK_OPTIONS

Specifies the default list of cashback amounts to display on the PED at the fixed denomination cashback prompt. This parameter only applies if the SHOW_FIXED_DENOMINATION_CASHBACK_PROMPT user parameter is enabled.

The value format of this parameter is as follows:
DisplayLabel1:Amount1;DisplayLabel2:Amount2;…​;DisplayLabelN:AmountN

NOTE:

  • This parameter must not be configured when using device models that are not capable of displaying an options screen.

  • The display labels can either be the raw text to display for an amount option, or a key/index to an entry in the device driver’s display message/language configuration.

  • Each of the amounts must be specified in minor denomination, for example, 500, in the currency of the transaction. If an amount in the list is greater than the maximum cashback amount allowed for an account, the amount is displayed as one of the options on the PED.

  • If the SHOW_NUMERIC_ENTRY_CASHBACK_PROMPT parameter is enabled, then the customer is given the option of selecting an "Other Amount". If selected, the fixed denomination cashback prompt is replaced by the numeric entry cash amount screen.

  • The options list must contain two or more items for the fixed denomination prompt to be displayed. If there are less than 2 items (after removing any amounts greater than the maximum cashback amount allowed), then the prompt is not shown. The transaction either continues without cashback, or the numeric entry cashback prompt is displayed. This depends on how the SHOW_NUMERIC_ENTRY_CASHBACK_PROMPT is configured.

  • This parameter can be overridden on an account profile basis in ConfigServer, using the FixedCashbackOptions extended parameter.

CANCEL_MODE

Specifies the action to take when cancel is selected on the PED:

  • 0 - Cancel the transaction (default).

  • 1 - Cancel the cashback amount and continue with the transaction.

Example: CANCEL_MODE=1

DISABLE_CONTACTLESS_EMV_CASHBACK

Specifies whether or not cashback insert mode should be allowed for contactless EMV transactions.

  • 0 - Default, pipeline component cashback will prompt for cashback in insert mode for contactless transactions.

  • 1 - Cashback is disabled in insert mode for contactless transactions.

Example: DISABLE_CONTACTLESS_EMV_CASHBACK=1

CASHBACK_PROMPT_MAX_RETRY

Specifies the number of times the device should consecutively prompt a customer to enter a cashback amount. The device will re-prompt for a cashback amount if the entered amount is greater than the maximum cashback allowed.

  • [N] - Where N can be any Integer within the following range [0-99]. If not present or not a valid Integer this parameter will default to 99.

Example: CASHBACK_PROMPT_MAX_RETRY=3

Format: The optional named parameters are delimited by a " " (space) character. Within a parameter, the parameter name and parameter value are delimited by the "=" (equals) character.

See the following examples, where each one starts with the mandatory cashout mode parameter, followed by optional named parameters:

  • 0

  • 1

  • 1 SHOW_CASHBACK_REQUIRED_PROMPT=0

  • 1 SHOW_CASHBACK_REQUIRED_PROMPT=1 SHOW_FIXED_DENOMINATION_CASHBACK_PROMPT=1 FIXED_CASHBACK_OPTIONS=$1000:100000;$500:50000;$100:10000 SHOW_NUMERIC_ENTRY_CASHBACK_PROMPT=1

  • 1 SHOW_FIXED_DENOMINATION_CASHBACK_PROMPT=1 FIXED_CASHBACK_OPTIONS=$1000:100000;$500:50000;$100:10000 CANCEL_MODE=1

  • 1 CANCEL_MODE=1 DISABLE_CONTACTLESS_EMV_CASHBACK=1

Decline conditions:

Condition Response code Message reason code

Purchase amount exceeds maximum configured for this card and account

13 - Invalid amount

9760 - Purchase amount exceeds maximum

Cashback amount exceeds maximum configured for this card and account

13 - Invalid amount

9761 - Cashback amount exceeds maximum

Transaction amount exceeds maximum configured for this card and account

13 - Invalid amount

9762 - Transaction amount exceeds maximum

Cashback amount not present or zero in cashback transaction

30 - Format error

9706 - Missing cashback amount

Missing currency code

30 - Format error

9707 - Missing currency code

Cashback amount exceeds transaction amount

30 - Format error

9770 - Cashback amount exceeds transaction amount

Cashback amount present in non-cashback transaction

30 - Format error

9771 - Cashback in non-cashback transaction

Cashback and transaction account types do not match

30 - Format error

9773 - Cashback account type invalid

Currency code not set up correctly for cashback amount

30 - Format error

9774 - Cashback currency code invalid

Cashback transactions are not supported on this card

57 - Transaction not permitted to cardholder

9772 - Cashback not permitted to cardholder

5.5.17. Pipeline component - Certificate Manager

Description: The Certificate Manager component manages the exchange of an RSA Public Key Certificate with the upstream payments system via the PosConnect source node. The public key encoded in the certificate is used:

  • by the PAN component to encrypt the PAN when it is stored in the database to achieve strong data protection

  • for message encryption between eSocket.POS and PosConnect (this is an optional feature that can be enabled with the EspTcpSapFactory)

The certificate exchange is initiated after startup and at a configurable interval, in days, if eSocket.POS is connected to the upstream payments system.

If the Certificate Manager has not yet exchanged the certificate in a particular session, the PAN component, or the message encryption uses the certificate that was delivered in the previous session. This is secure, since the certificate is changed infrequently (RSA Certificates are valid for several months).

The location and format of the Certificate Manager’s key store file can be configured via eSocket.POS properties.

Note
Before the PAN is encrypted in the database, the PAN Component must be configured for encryption. The Certificate Manager component is only responsible for the exchange of certificates. To use message encryption, the Certificate Manager must be configured to do a key exchange. A successful key exchange is required before eSocket.POS is configured for message encryption.

Usage: Request Pipeline, optional.

Rank: Must be configured after the PAN and Account components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentCertificateManager

Parameters:

The component can be configured with the following optional parameters:

Parameter Values

1

certificate exchange delay

The delay after startup, before the first certificate exchange is attempted (in seconds).

Set to '9999', if no certificate exchange must occur.

The default value is 60 seconds.

2

certificate exchange interval

The interval, in days, between a successful certificate exchange, and the next attempt at a certificate exchange.

The default value is 2 days.

The component can also be configured with the following optional named parameters:

Parameter Values

certificate exchange error retry interval

If a certificate exchange is started and fails because the certificate change request response received from the upstream payments system is invalid, or fails because the certificate change was unsuccessful using the certificate contained in the response, this parameter then specifies the time interval between the failure and the next attempt at a certificate exchange.

The parameter is configured as RETRY_ON_ERROR=x, where x is the time interval in seconds.

The default value is 10 seconds.

eSocket.POS disconnected retry interval

If a certificate exchange is started and fails because eSocket.POS was not connected to the upstream payments system, this parameter specifies the time interval between the failure and the next attempt at a certificate exchange.

The parameter is configured as RETRY_DISCONNECTED=x, where x is the time interval in seconds.

The default value is 30 seconds.

server under load retry interval

If a certificate exchange is started and fails because the server is under load, this parameter specifies the time interval between the failure and the next attempt at a certificate exchange.

The parameter is configured as RETRY_UNDER_LOAD=x, where x is the time interval in seconds.

The default value is 90 seconds.

number of retries on error

If a certificate exchange is started and fails due to an error condition, this parameter specifies the number of times the Certificate Manager will re-attempt the certificate exchange. Once the configured number of retries are exhausted, eSocket.POS will only attempt a certificate exchange at the next scheduled interval.

The parameter is configured as NUMBER_OF_RETRIES_ON_ERROR=x, where x is the number of retries that will be attempted.

The default value is 3 retries.

Limitations:

If this pipeline component is configured in multiple terminal categories, only the configuration from the terminal category to be processed first will be used. This is because only one instance of the PipelineComponentCertificateManager pipeline component can exist per instance of the eSocket.POS Transaction Engine.

Loading Certificates Manually

If it is necessary for eSocket.POS to have an initial certificate available before the first certificate exchange occurs, the certificate can be loaded manually.

5.5.18. Pipeline component - Check authorization

Description: The Check authorization component can perform various functions:

  • Populates the CheckData subfield in structured data (field 127.22)

  • Populates the Check Data (field 127.7) and Receiving Institution ID Code (field 100) in check authorization request messages

  • Performs amount validation for check payment request messages

  • Performs stand-in processing for check payment requests, based on check limits and stand-in authorization, if no response is received

  • Prints data on the check for successful check payment response

The component ensures that Check Data is present, if the following conditions are met:

  1. The transaction is one of the following:

    • Check cash / guarantee (Transaction Type - 03)

    • Check verification (Transaction Type - 04)

    • Electronic check guarantee (Transaction Type - 03 and Extended Transaction Type(127.33) - 7112)

    • Electronic check verification (Transaction Type - 04 and Extended Transaction Type(127.33) - 7112)

    • Electronic check authorization (Transaction Type - 12 and Extended Transaction Type(127.33) - 7112)

  2. One of the following is true:

    • The PAN Entry Mode is manual.

    • The PAN is a dummy PAN (no card present).

    • The transaction value is higher than both the configured local check limit and the limit displayed on the check card.

If some check data is already present, it is not changed; otherwise, the component prompts the customer to enter the relevant information, confirm it, and repeat entry until the values are confirmed.

The component is also responsible for authorizing the transaction amount based on the named parameters (MIN_CHEQUE_LIMIT, MAX_CHEQUE_LIMIT, OVERRIDE_FLOOR_LIMIT and OVERRIDE_GUARANTEE_LIMIT) in order to decide whether the transaction must be approved, rejected or sent upstream.

Validation will occur in the specified order:

  1. If the transaction amount is below MIN_CHEQUE_LIMIT or above MAX_CHEQUE_LIMIT, the transaction is rejected.

  2. If the transaction amount is below OVERRIDE_FLOOR_LIMIT, an advice is sent upstream. The same component in the response component converts the advice response back to a request response.

  3. If the transaction amount is above OVERRIDE_GUARANTEE_LIMIT, a Check Guarantee request is sent upstream.

  4. If none of the previous limits were enforced (including if limits processing is disabled), a Check Verification request is sent upstream.

If configured in the response pipeline, then based on the OFFLINE_CHEQUE_LIMIT, the component can perform the following:

  • Stand-in check authorization when a response code of 91 - Issuer or Switch Inoperative is received. In this case, an advice message is sent.

  • Print merchant name, transaction date and amount on the check for a successful check payment response.

0420 (Reversal Advice) and 0620 (Administration Advice) messages will populate field 127.22 (StructuredData) with the Transaction Amount under the following tag: CheckTransactionAmount.

Usage: Request Pipeline, required if amount validation and stand-in is done for check payment requests, based on check limits. Response Pipeline, required if stand-in check authorization is done when no online response is received and data printing is done on check or when using the check advice functionality.

Rank: Must be configured after the Check read component, if configured. Otherwise, it must be configured after the PAN and Account components, preferably close to the end of the response pipelines on the response side.

Class name: postilion.esocketpos.transactionengine.PipelineComponentChequeAuth

Parameters: The component must be configured with the following parameters, separated by spaces:

Parameter Values

1

operating mode

A code defining the operating mode (behavior) of the component, supporting the following values:

0 - No check details. In this case, the component does not insert check details.

1 - Apply local limit and card limit. In this case, the component prompts for the check card limit, and inserts check details if the transaction amount is above both this limit, and the local check limit.

2 - No limits. In this case, the component always inserts check details.

This parameter is mandatory.

2

authorization ID code

The code to be inserted into check authorization responses as well as the Authorization/Transaction advices approved by the component. Format an..6.

This parameter is mandatory. If operating mode has a value of '2', the value is not used, so can be set to any value, for example, '0'.

3

data required

A 1-digit code defining the data which has to be obtained, supporting the following values:

1 - check number, institution code, account number

This parameter is conditional. It must be present if operating mode has a value of '1' or '2'.

4

receiving institution ID code

The value to be inserted into Receiving Institution ID Code ( field 100) of the ISO 8583 message, defining which sink node the payments system must route the transaction to. Format n..11.

This parameter is conditional when operating mode has a value of '0'. It must be present if operating mode has a value of '1' or '2'.

5

local check limit

The local limit below which all checks are authorized. Format n..12.

This parameter is conditional. It must be present if operating mode has a value of '1'.

The Check authorization component can also be configured with the following named parameters:

Parameter Values

OFFLINE_CHEQUE_LIMIT

This is the local limit below which the component performs stand-in check authorization, when no online response is received (offline stand-in).

This must be configured as OFFLINE_CHEQUE_LIMIT=n, where n is a numeric value with a maximum length of 12 digits.

This parameter is optional, if it is not present, and the component is configured in the response pipeline, then offline stand-in takes place, regardless of the amount.

MIN_CHEQUE_LIMIT

This is the minimum limit allowed for check payments. If the transaction amount for check payment is below this limit, and the component is configured in the request pipeline, then the request message is declined.

This must be configured as MIN_CHEQUE_LIMIT=n, where n is a numeric value with a maximum length of 12 digits.

This parameter is optional; if it is not present, and the component is configured in the request pipeline, then this limit will not be considered for amount validation.

MAX_CHEQUE_LIMIT

This is the maximum limit allowed for check payments. If the transaction amount for check payment is above this limit, and the component is configured in the request pipeline, then the request message is declined.

This must be configured as MAX_CHEQUE_LIMIT=n, where n is a numeric value with a maximum length of 12 digits.

This parameter is optional; if it is not present, and the component is configured in the request pipeline, then this limit will not be considered for amount validation.

OVERRIDE_FLOOR_LIMIT

This is the floor limit allowed for check payments. If the transaction amount for check payment is below this limit, and the component is configured in the request pipeline, then an authorization advice (0120) will be sent upstream. If this parameter is set, it will override the previous behavior of using the 'Floor Limit' extended parameter set on the account profile.

This must be configured as OVERRIDE_FLOOR_LIMIT=n, where n is a numeric value with a maximum length of 12 digits.

This parameter is optional; if it is not present, and the component is configured in the request pipeline, then this limit will not be considered for amount validation.

OVERRIDE_GUARANTEE_LIMIT

This is the guarantee limit allowed for check payments. If the transaction amount for check payment is above this limit, and the component is configured in the request pipeline, then a Check Guarantee request is sent upstream. If this parameter is set, it will override the previous behavior of using the 'Guarantee Limit' extended parameter set on the account profile.

This must be configured as OVERRIDE_GUARANTEE_LIMIT=n, where n is a numeric value with a maximum length of 12 digits.

This parameter is optional; if it is not present, and the component is configured in the request pipeline, then this limit will not be considered for amount validation.

DISABLE_LIMITS

This is an optional parameter that specifies whether limit processing should be bypassed or not. It must be configured as DISABLE_LIMITS=n, where n is a numeric value which can be set to any of the following values:

  • 0 - Do not bypass all limit processing. (default)

  • 1 - bypass all limit processing.

SEND_CHECK_ADVICE_MODE

This parameter must be configured as SEND_CHECK_ADVICE_MODE=n, where n is a numeric value which can be set to any of the following values:

  • 0 - Never (default) - Advices/reversals will never be sent based on responses or errors.

  • 1 - Upon any 0110 response - Upon reception of any 0110 message, if the message is successful, a transaction advice is sent upstream. If an error occurs (for either 0110 or 0210) or if the message is unsuccessful, a reversal is sent upstream.

  • 2 - Always except for:

    • 0110 declined.

    • 0110 forced merchant transaction acceptance (056 = 1381). Upon reception of any 0110 message, if the message is successful and forced transaction acceptance was not performed, a transaction advice is sent upstream. If an error occurs (for either 0110 or 0210) a reversal is sent upstream.

  • 3 - Only on error - If an error occurs during check printing, a reversal is sent upstream.

This parameter is optional.

PRINT_FRAUD_CHARACTER

This is an optional parameter that specifies if fraud characters should be printed around the cheque amount. It must be configured as PRINT_FRAUD_CHARACTER=n, where n is a numeric value which can be set to any of the following values:

  • 0 - Do not print anti-fraud characters around the cheque amount. (default)

  • 1 - Print anti-fraud characters around the cheque amount.

Decline conditions:

Condition Response Code Message Reason Code

Transaction amount is below minimum limit allowed for check payment.

13 - Invalid Amount

9767 - Tran Value Below Minimum

Transaction amount exceeds maximum limit allowed for check payment.

13 - Invalid Amount

9762 - Tran Value Exceeds Maximum

5.5.19. Pipeline component - Check read

Description: The Check read component accesses the check reader device to read the MICR (magnetic ink character recognition) line of a check. It then unpacks this data according to a specific national format and populates the relevant parts of the CheckData subfield in structured data (field 127.22).

The component reads the MICR line from the check, if the check number, institution code, or MICR account number is not already known and the transaction is one of the following:

  • Check cash/guarantee (Transaction Type - 03)

  • Check verification (Transaction Type - 04)

  • Electronic check guarantee (Transaction Type - 03 and Extended Transaction Type (127.33) - 7112)

  • Electronic check verification (Transaction Type - 04 and Extended Transaction Type (127.33) - 7112)

  • Electronic check authorization (Transaction Type - 12 and Extended Transaction Type (127.33) - 7112)

The relevant data from the MICR line is unpacked into the relevant parts of the check data, as long as the check reader device has read a valid MICR line, and the MICR line read is in a supported format.

The Check read component can be configured to recognize different national check formats.

Usage: Request Pipeline, when using a check reader to automatically read the MICR line of a check.

Rank: Must be configured after the PAN and Account components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentCheckRead

Parameters: The component must be configured with the following parameters, separated by spaces:

Parameter Values

1

national MICR line format

A code defining the national MICR line format, supporting the following values:

1 - USA. Both personal and business checks are supported.

2 - France CMC-7.

(other values to be defined when required)

This parameter is mandatory.

2

operating mode

A code defining what to do if an invalid MICR line is processed.

0 - Pass through. Responsibility for declining the authorization is passed on to subsequent components in the pipeline.

1 - Decline. The authorization is declined by this component.

This parameter is mandatory.

3

receiving institution ID code

The value to be inserted into Receiving Institution ID Code (field 100) of the ISO 8583 message, defining which sink node the payments system must route the transaction to. Format n..11.

This parameter is mandatory.

The Check read component can also be configured with the following named parameters:

Parameter Values

SHOULD_VALIDATE_REVERSALS

This parameter indicates whether reversal advices that are sent should be validated against the original check data in the database. If the data matches, the check is allowed to proceed, otherwise it is declined with a 9776 message reason code. This parameter is configured as SHOULD_VALIDATE_REVERSALS=n where n should be '1' to enable and anything else will disable it.

PRINT_CHECK_CANCEL

Use this parameter to indicate which character must be printed over the check data when a check is cancelled.

This parameter is configured as PRINT_CHECK_CANCEL=n where n should be a single digit number from 0 to 2.

0 - No data is printed on the cancelled check (default).

1 - Xs are printed over the check data on the cancelled check.

2 - Hyphens (-) are printed over the check data on the cancelled check.

Decline conditions:

Condition Response Code Message Reason Code

Unable to unpack MICR line.

30 - Format Error

9711 - Missing Check Data

Check data of the current message does not match the original transaction’s check data

05 - Do not honor

9776 - Check Data Mismatch

5.5.20. Pipeline component - Confirm

Description: The Confirm component displays the amount and selected account for this transaction, and prompts the user to confirm that the transaction must go ahead. If the user chooses to decline, the transaction is rejected. For a transaction with an accepted dynamic currency conversion (DCC) offer, the cardholder alpha currency code is also displayed. If the DCC offer is declined, the merchant alpha currency code is displayed. For EMV (chip & PIN) transactions, the pipeline component can be configured to display the name of the card application used to perform the transaction.

eSocket.POS can also be configured to suppress this prompt, if the user has entered a PIN. This behavior is controlled by the parameter CONFIRM_ON_PIN_ENTRY

Usage: Request Pipeline, optional.

Rank: Must be configured before the Stand-in and EMV components and after any other components that might decline the transaction or interact with the customer.

Class name: postilion.esocketpos.transactionengine.PipelineComponentConfirm

Parameters:

The Confirm component can be configured with the following named parameters:

Parameter Values

DISPLAY_AID

DISPLAY_AID=x, where x is one of the following:

  • 0 - Do not display the name of the card application used to perform the transaction.

  • 1 - Display the name of the card application used to perform the transaction. This only applies to EMV (chip and PIN) transactions.

This parameter is optional and has a default setting of 0.

Decline conditions:

Condition Response Code Message Reason Code

Customer chooses to cancel the transaction

17 - Customer cancellation

9630 - Customer cancellation

5.5.21. Pipeline component - CVV2

Description: The CVV2 component prompts for CVV2 entry when the PAN is manually entered, if required for this card and if the value is not yet present in the message. The component allows repeat entry until the format is correct (three digits for most cards, but four digits for American Express).

Usage: Request Pipeline, optional.

Rank: Must be configured after the PAN and Account components, but before the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentCvv2

Parameters: The component can be configured with the following optional parameter:

Parameter Values

1 (Optional)

prompt for CVV2

Determines whether the component prompts for the CVV2 code to be entered.

0 - No CVV2 prompting

1 - Always prompt

2 - On manual PAN entry (default value)

Decline conditions:

Condition Response Code Message Reason Code

Invalid length of CVV2 entered by the user

14 - Invalid Card Number

9769 - Invalid CVV2

Note
  • Referral advice messages (0220 messages with message type set as 'REFERRAL') prompt for the CVV2, if the CVV2 of the original message (Authorization Request or Transaction Request) cannot be found on the same terminal. For example, when a referral advice is processed on a terminal other than the terminal where the original message was processed. The configuration described above is still applicable, meaning that referral advices will not prompt for the CVV2 if such prompting is disabled on this component.

  • If a transaction (including a referral advice) is an EMV transaction, then this component will not prompt for CVV2.

5.5.22. Pipeline component - Date time

Description: The Date Time component sets the date and time, local date, and local time properties of the transaction.

Usage: Request Pipeline, mandatory.

Rank: Any

Class name: postilion.esocketpos.transactionengine.PipelineComponentDateTime

Parameters: None

Decline conditions: None

5.5.23. Pipeline component - DCC

Description: The DCC component is responsible for performing dynamic currency conversion (DCC) on eligible transactions. This includes initiating a DCC message flow to determine whether a DCC offer is available, orchestrating the display of the DCC offer to the cardholder, and updating the transaction amount and currency if the DCC offer is accepted.

For the DCC component to initiate DCC message flow, the following conditions must be met:

  • The terminal is configured to support DCC - see the dcc_support column in the esp_term_config table.

  • The transaction message is a 0100 or 0200 with a transaction type of 00 (goods and services) or 20 (return/refund).

  • The transaction does not include cashback.

  • The transaction does not have the EU multilateral interchange fee (MIF) indicator set.

  • The transaction is not already in a foreign currency.

  • The DCC component has determined that the card is not a local card. (This only applies to EMV contact and Quick Chip transactions.)

  • The transaction is sent online for authorization. This has the following implications for a transaction with an accepted DCC offer:

    • For magnetic stripe cards, no timeout stand-in is allowed.

    • For EMV contact transactions and Quick Chip transactions, offline approval is allowed (an offline decline can still occur). Furthermore, no timeout stand-in is allowed.

Note about Quick Chip transactions: A Quick Chip transaction is performed with an EMV contact card, but differs from a "normal" EMV contact transaction in that it allows for early removal of the chip card from the terminal. See the Quick Chip Processing section for details. When this page refers to "EMV contact", it refers to EMV contact without Quick Chip.

Additionally, the following limit conditions must be met before the DCC component initiates DCC message flow.

  • For EMV contact cards

    • The transaction amount is above or equal to the contact floor limit configured on the EMV AID.

  • For EMV contactless cards:

    • The transaction amount is above or equal to the contactless floor limit configured on the EMV AID.

    • The transaction amount is above or equal to the contactless CVM required limit configured on the EMV AID.

  • For magnetic stripe contact cards:

    • The transaction amount is above the local limit for goods and cash (auto-) configured on the account’s limit profile. The issuer limit is the default, but the acceptor limits are used, if enabled.

  • For magnetic stripe contactless cards:

    • The transaction amount is above the contactless floor limit configured on the account’s limit profile.

    • The transaction amount is above the contactless CVM required limit configured on the account’s limit profile.

      NOTES
    • These limits are configurable in the ConfigServer Cards Configuration console.

      • For magnetic stripe card limits, go to Account Profile > Limits.

      • For EMV card limits, go to EMV Card Parameters > AID Parameters.

    • For Quick Chip transactions, the EMV terminal floor limit must remain zero. See the Quick Chip Processing section for details.

The DCC component considers both card technology and card verification method (CVM) when choosing how to handle the transaction - using explicit or implicit DCC message flow. To understand the difference between implicit and explicit DCC message flow, see the Postilion DCC Implementation Guide or the "POS XML message flow examples" in the eSocket.POS Developer Guide.

Additionally, the default handling supports the following DCC best practices, which support Visa requirements:

  • The POS must make the DCC offer before the cardholder enters a PIN.

  • For EMV contact transactions and Quick Chip without pre-swipe transactions, the POS must make the DCC offer before the cryptogram is generated. This ensures that the transaction amounts and currencies in the message fields, and the EMV data of the DCC transaction are the same. Therefore, for an accepted DCC offer, the amount used to create the cryptogram is in the cardholder’s currency.

You can override the default handling by configuring the DCC flow optimization parameter. However, this is not advisable and can result in DCC best practices no longer being supported.

The following table lists the default handling and DCC flow optimization override options per card technology and CVM combination.

Card technology CVM Default handling DCC flow optimization overrides

EMV contact without Quick Chip

Any

Explicit DCC message flow

3 - Always use an implicit DCC message flow

Note
If you force an implicit DCC message flow on a EMV contact transaction, the EMV cryptogram is generated from the amount in the merchant currency and not the cardholder currency. Typically, this option is only used when the DCC provider and DCC acquirer are the same entity.

Quick Chip without pre-swipe

Any

Explicit DCC message flow

3 - Always use an implicit DCC message flow

Note
If you force an implicit DCC message flow on a Quick Chip without pre-swipe transaction, the EMV cryptogram is generated from the amount in the merchant currency and not the cardholder currency. Typically, this option is only used when the DCC provider and DCC acquirer are the same entity.

Quick Chip with pre-swipe

Any

Implicit DCC message flow

4 - Always use an explicit DCC message flow

EMV contactless

Online PIN

Explicit DCC message flow

2 - Use an implicit DCC message flow, except for transactions involving EMV contact and Quick Chip without pre-swipe 3 - Always use an implicit DCC message flow

EMV contactless

Not online PIN

Implicit DCC message flow

4 - Always use an explicit DCC message flow

Magnetic stripe contact & contactless

PIN

Explicit DCC message flow

2 - Use an implicit DCC message flow, except for transactions involving EMV contact and Quick Chip without pre-swipe 3 - Always use an implicit DCC message flow

Magnetic stripe contact & contactless

Not PIN

Implicit DCC message flow

4 - Always use an explicit DCC message flow

Usage: Request and Response Pipelines, optional. If required, must be present in both pipelines.

Rank: As follows per pipeline:

  • Request pipeline - Towards the end, after the Hotcard and Payment Interrupt components and immediately before the EMV and Confirm components.

  • Response pipeline - Towards the beginning, before the EMV component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentDcc

Parameter: The component can be configured with the following named parameter:

Parameter Values

DCC_FLOW_OPTIMIZATION

The DCC flow optimization parameter specifies the DCC message flows that the DCC component can use under certain circumstances. It overrides the default handling that is set per card technology and CVM combination.

Caution: Using this parameter can result in DCC best practices no longer being supported.

DCC_FLOW_OPTIMIZATION=x, where x is:

  • 1 - Use an implicit DCC message flow, except for transactions involving:

    • EMV contact

    • Quick Chip without pre-swipe

    • PIN

  • 2 - Use an implicit DCC message flow, except for transactions involving:

    • EMV contact

    • Quick Chip without pre-swipe

  • 3 - Always use an implicit DCC message flow

  • 4 - Always use an explicit DCC message flow

This parameter is optional and has a default setting of 1.

DISALLOW_DCC_IF_EMV_LOCALIZATION_DATA_ABSENT

The DCC component uses EMV localization data to determine whether an EMV contact card is a local card and has the same currency as the merchant. This parameter controls whether DCC is performed on an otherwise eligible-for-DCC transaction when the EMV localization data is absent. This only applies to EMV contact or Quick Chip transactions.

DISALLOW_DCC_IF_EMV_LOCALIZATION_DATA_ABSENT=x, where x is:

  • true - Disallow DCC when the EMV localization data is absent.

  • false - Allow DCC when the EMV localization data is absent.

Note: Currently, the EMV localization data consists of the EMV application currency code and EMV issuer country code.

This parameter is optional and has a default setting of "false".

ISSUER_COUNTRY_CODE_PRESCREENING_ENABLED

This DCC prescreening parameter controls DCC eligibility for transactions involving EMV contact or Quick Chip.

When the parameter is enabled:

  • An EMV contact transaction is not eligible for DCC under the following conditions:

    • Multi-country store currency: The EMV issuer country code exists in the configured country-to-currency mappings.

    • Single-country store currency: The EMV issuer country code matches the store country code.

  • An EMV contact transaction is eligible for DCC under the following conditions:

    • Multi-country store currency: The EMV issuer country code does not match the configured country-to-currency mappings for the store (if any).

    • Single-country store currency: The EMV issuer country code does not match the store country code.

ISSUER_COUNTRY_CODE_PRESCREENING_ENABLED=x, where x is:

  • true - Issuer country code prescreening is enabled.

  • false - Issuer country code prescreening is not enabled.

Note: Country-to-currency mappings are configured for multi-country currencies like the euro. See the Configuration Server User Guide for more information on country-to-currency configuration.

This parameter is optional and has a default setting of "false".

CURRENCY_CONV_INFO_ON_OFFER_DECLINE

This parameter controls whether currency conversion information is included in a transaction, if the DCC offer was declined by the cardholder.

CURRENCY_CONV_INFO_ON_OFFER_DECLINE=x, where x is:

  • true - Add currency conversion information on a declined DCC offer.

  • false - Do not add currency conversion information on a declined DCC offer.

This parameter is optional and has a default setting of "false".

FAILED_DCC_META_DATA

This parameter controls whether failed DCC metadata is included in a transaction if the DCC offer cannot be retrieved due to a timeout on the DCC provider, unavailability of the DCC sink node, or the DCC provider returning no offer.

FAILED_DCC_META_DATA=x, where x is:

  • true - Add the failed DCC metadata on a timeout, offline sink node or no DCC offer returned.

  • false - Do not add the failed DCC metadata on a timeout, offline sink node or when no DCC offer is returned.

This parameter is optional and has a default setting of "false".

ENABLE_DCC_REFUNDS

This parameter controls whether the terminal should perform DCC refunds.

ENABLE_DCC_REFUNDS=x, where x is:

  • true - Enable performing DCC refunds.

  • false - Disable performing DCC refunds

This parameter is optional and has a default setting of "false".

Decline conditions: This component declines transactions under the following circumstances:

  • The POS sends a 0220 or 0420 advice linked to a 0100 or 0200 request with an accepted DCC offer. The transaction amount and currency in the advice do not match the amount and currency in the request. In other words, the advice contains neither the amount in the merchant’s currency, nor the amount in the cardholder’s currency.

  • If a system error occurs such as, a software failure.

Events: If a DCC offer is presented to the cardholder, one of the following events is raised:

  • DCC_OFFER_ACCEPTED

  • DCC_OFFER_DECLINED

See the "Events and callbacks" page in the eSocket.POS Developer Guide for more information about these events.

Transaction Processing Results:

The DCC component sets the following Transaction Processing Results (TPR) in the request and response message for byte 1.

Name Bit Description

DccInfoFromOrigTran

8

When set, this bit indicates that the DCC information was loaded from a previous message.

ReqEligibleForDcc

7

When set, this bit indicates that the request can be eligible for DCC.

ConnectedOnline

6

When set, this bit indicates that an online connection was checked and exists.

EspSupportsDcc

5

When set, this bit indicates that a check was performed to ensure eSocket.POS supports DCC transactions.

DccFlowTypeNone

4

When set, this bit indicates that DCC flow type of NONE was selected.

DccFlowTypeExplicit

3

When set, this bit indicates that DCC flow type of EXPLICIT was selected.

DccFlowTypeImplicit

2

When set, this bit indicates that DCC flow type of IMPLICIT was selected.

PreventDcc

1

When set, this bit indicates that DCC was prevented or disabled for this message.

The DCC component sets the following Transaction Processing Results (TPR) in the request and response message for byte 2.

Name Bit Description

RspDccProcessing

8

When set, this bit indicates that the DCC processing was performed on the response message.

RspDccHasStatusCode

7

When set, this bit indicates that a status code has been provided.

ProcessImplicitRateRsp

6

When set, this bit indicates implicit rate processing was performed on the response message.

ContinueRspUnaltered

5

When set, this bit indicates that the response message remained unaltered.

AcceptDccOffer

4

When set, this bit indicates that the DCC offer was accepted.

RejectDccOffer

3

When set, this bit indicates that the DCC offer was rejected.

FailureEventLogged

2

When set, this bit indicates that a failure event was logged.

WarningEventLogged

1

When set, this bit indicates that a warning event was logged.

5.5.24. Pipeline component - DeclinedAdvices

Description: The DeclinedAdvices component is responsible for sending an advice to Transaction Manager to indicate that a 0100 or 0200 transaction is declined. The advice has as many fields set in the same manner as the original message as possible. If there is no PAN, then a declined advice is not sent to the upstream entity.

Request component

The Request Component checks for messages placed in the request pipeline by the response component. This is done by checking 0620 transactions for a flag in structured data. If the original message type is in structured data, then it is restored as well as the original processing code. The message is then sent on.

Response component

The Response Component checks structured data to ensure that this transaction is not sent to eSocket.POS by the upstream entity. If the transaction came from the upstream entity, then the message is returned unaltered. Only 0110 and 0210 response messages are eligible to have declined advices to be sent to the upstream entity. All other messages are returned unaltered. Once a message for which a declined advice must be sent to TM is identified, a 0620 dead-end Admin Advice message is constructed. This message takes as many fields as possible from the original Message. The original transaction type and Message type are added to Structured data, if there is enough information to form a 0120 or a 0220. The advice message is inserted into the request pipeline.

Usage: Request and Response Pipelines, optional. If required, must be present in both pipelines.

Rank: Must be configured at the end of the request pipeline, before the Monitoring Component and at the end of the response pipeline, before the Display Welcome Component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentDeclinedAdvices

Parameters: The component can be configured with the following optional parameters:

Parameter Values

1

Include or exclude response code list

Specifies whether declined advices must be sent for all the response codes in the comma separated list of response codes (parameter 2) or whether declined advices must be sent for all response codes except those on the list:

0 - Send advices for all response codes in the list

1 - Send advices for all response codes not in the list

2

Response code list

A comma separated list of response codes used to indicate when declined advice messages must be sent or not.

Note that if no parameters are configured, DeclinedAdvices are sent to the upstream entity for all response codes. If one parameter is configured, then both parameters must be configured.

5.5.25. Pipeline component - DeclineCompletion

Description: A completion message is a transaction advice message (0220 and 0221) that completes a prior 0100 message. The DeclineCompletion pipeline component is responsible for declining unlinked completion messages and duplicate completion messages. It declines these messages with the response codes 25 and 26, respectively. Using a parameter, you can configure the pipeline component to treat all transaction advice messages as completion messages.

For the DeclineCompletion pipeline component to operate, the following must be true:

  • The message type is 0220/0221.

  • Transaction type is 00 (Goods and services).

  • TreatAdviceAsCompletion is set to 1 or "IsCompletionMsg = 1" is present in structured data.

Usage: Request pipeline, optional

Rank: Near beginning

Class name: postilion.esocketpos.transactionengine.PipelineComponentDeclineCompletion

Parameters: Configure the DeclineCompletion pipeline component with the following three parameters, separated with semi-colons(;). For example: DECLINE_UNLINKED_COMPLETION=1;DECLINE_DUPLICATE_COMPLETION=1;TREAT_ADVICE_AS_COMPLETION=1

Parameter Values

1

DECLINE_UNLINKED_COMPLETION

Indicates whether the pipeline must decline unlinked completions.

Example: DECLINE_UNLINKED_COMPLETION=1

0 - False: Do not decline unlinked completions. (Default)
1 - True: Decline unlinked completions.

2

DECLINE_DUPLICATE_COMPLETION

Indicates whether the pipeline must decline duplicate completions.

Example: DECLINE_DUPLICATE_COMPLETION=1

0 - False: Do not decline duplicate completions. (Default)
1 - True: Decline duplicate completions.

3

TREAT_ADVICE_AS_COMPLETION

Indicates whether the pipeline must treat all transaction advice messages (0220) as completions.

Example: TREAT_ADVICE_AS_COMPLETION=1

0 - False: Do not treat advice messages as completions. (Default)
1 - True: Treat advice messages as completions.

Decline conditions:

Condition Response code Message reason code

DECLINE_UNLINKED_COMPLETION flag = 1 and an approved 0100 message does not exist within the set of linked transactions.

25 - Unable to locate record

_9720_ORIG_TRAN_NOT_FOUND

DECLINE_DUPLICATE_COMPLETION flag = 1 and an approved 0220 message exists within the set of linked transactions.

26 - Duplicate record

_9721_DUPLICATE_TRANSACTION

5.5.26. Pipeline component - Decline Referral

Description: This pipeline component is responsible for declining any referred responses for contactless card transactions.

Usage: Response pipeline, optional.

Rank: Must be configured after the Stand-in and EMV components but before the other optional pipeline components, for example, PipelineComponentCallAuthCenter.

Class name: postilion.esocketpos.transactionengine.PipelineComponentDeclineReferral

Parameters: This component requires no parameters.

Decline conditions:

Condition Response Code Message Reason Code

Referred response from contactless card transaction is received.

20 - Invalid response.

4020 - Invalid response no action taken

5.5.27. Pipeline component - Detokenize

Description: This component is used to detokenize a tokenized request (containing a token ID and a dummy/ghosted PAN) so that other components in the pipeline that need the BIN have a (potentially partially) detokenized PAN.

Note: In the event that a detokenization request fails, the transaction will continue to be processed with tokenized information.

All non-tokenized transactions will pass through unchanged.

Usage: This component only needs to be configured at the start of the request pipeline. It does not need to be configured in the response pipeline.

Rank: This component should be configured at the start of the request pipeline before all other pipeline components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentDetokenize

Parameters: There are no special parameters that need to be set for this pipeline component. However, a tokenized request typically will contain a dummy expiry date, which means Pipeline component Expiry Date will need to be configured to allow dummy expiry dates to pass through. For more information on how to configure this, please see the Pipeline component Expiry Date user guide page.

Pipeline component - TokenGeneration

Description: Use the TokenGeneration component to retrieve card tokens for transactions. Currently, token generation is supported for online stand-in and pre-swipe transactions. Token retrieval involves sending Create Token administrative request (0600) messages to the upstream entity responsible for generating tokens and accepting the generated tokens in the Create Token administrative response (0610) messages. The generated token is then sent back to the POS so that it can be used in future transactions. In this case, Token retrieval always requires that the upstream entity generating the token be online and connected.

Usage: Request and Response Pipelines, optional. If configured, must be present in both pipelines.

Rank: Must be configured after the EMV and Stand-in component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentTokenGeneration

Parameters: The component can be configured with the following optional parameter.

Parameter Values

1

DECLINE_IF_TOKEN_GENERATION_FAILS

This parameter enables magnetic stripe transactions approved by eSocket.POS before being sent to the upstream entity to be overridden and declined in situations where a token cannot be retrieved, or the token request times out.

0 - Do not decline the transaction (Default)

1 - Decline the transaction

Note:

1. EMV card transactions that are approved during EMV processing are not declined as part of this processing when tokens cannot be retrieved. This avoids overriding or interfering with standard EMV processing.

2. This parameter does not apply when for pre-swipe token generations.

2

ENABLE_ONLINE_STANDIN_TOKEN_GENERATION

This parameter enables token generation for online stand-in transactions.

0 - Does not enable token generation for online stand-in.

1 - Enable token generation for online stand-in. (Default).

3

ENABLE_PRESWIPE_TOKEN_GENERATION

This parameter enables token generation for pre-swipe transactions.

0 - Does not enable token generation for pre-swipe. (Default)

1 - Enable token generation for pre-swipe.

Decline conditions:

This component declines transactions under the following circumstances:

Condition Response Code Message Reason Code

Token retrieval returned an error for magnetic stripe transactions, and the DECLINE_IF_TOKEN_GENERATION_FAILS is set to 1

Response code of Token retrieval message

Message Reason code of Token retrieval message

Token retrieval times out for magnetic stripe transactions, and the DECLINE_IF_TOKEN_GENERATION_FAILS is set to 1

91 - Issuer or switch inoperative

9651 - Issuer timeout before response

Token retrieval does not return a Token for magnetic stripe transactions, and the DECLINE_IF_TOKEN_GENERATION_FAILS is set to 1

96 - System Malfunction

9600 - System Malfunction

5.5.28. Pipeline component - Device Data Capture

Description: The Device Data Capture component is responsible for extracting the following information from a device and sending it to the upstream Realtime system:

  • Make and model

  • Serial number

  • Manufacturing Serial number

  • Firmware version

  • Applications and version numbers

  • Device IP and MAC address (if supported by the configured device driver)

The Device Data Capture component processes Administration Request (0600) messages for device data capture with Transaction Type 91 and Extended Transaction Type of 2113 - Device Data Capture, and messages that have been initiated by a card or device interaction.

The following takes place when processing an Administration Request (0600) message for device data capture:

  • The device information is retrieved from Device Manager.

  • An Administration Advice (0620) message for device data capture with Transaction Type 93 and Extended Transaction Type of 2113 - Device Data Capture is constructed, and the device information is placed in XML format in the Term subfield within structured data (field 127.22).

  • The Administration Advice (0620) message is then sent to the upstream Realtime system.

  • A response to the Administration Request (0600) message for device data capture is sent back to the POS.

Provided that the ADD_SERIAL_NR_TO_MSG parameter is set to true, the component will process card/device interaction messages as follows:

  • The device serial number is retrieved from Device Manager.

  • The serial number is placed in XML format in the Term subfield within structured data (field 127.22) in the message.

The Device Data Capture component will also retrieve the device information from Device Manager and initiate an Administration Advice (0620) message a configurable amount of time after eSocket.POS starts up. This functionality is governed by the STARTUP_DELAY parameter. Thereafter, the component will continue to perform this periodically. This functionality is governed by the DATA_CAPTURE_INTERVAL parameter. Please refer to the component parameters listed in the table below for more information.

Usage: Request Pipeline, optional.

Rank: The component should be configured after the PAN component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentDeviceDataCapture

The Device Data Capture component can be configured with the following named parameters:

Parameter Values

ADD_SERIAL_NR_TO_MSG

If this parameter is set to 1 (true), the serial number from the device will be added to structured data for all card/device interaction request messages processed by the component.

Example: ADD_SERIAL_NR_TO_MSG=1

This parameter is optional and has a default value of 1 (true).

STARTUP_DELAY

This parameter represents the period of time after eSocket.POS starts up, before the first device data capture is initiated. The value should be expressed in seconds.

Example: STARTUP_DELAY=300

This parameter is optional and has a default value of 300 seconds.

DATA_CAPTURE_INTERVAL

This parameter represents the period of time between each device data capture that is initiated by the component. The value should be expressed in hours.

Example: DATA_CAPTURE_INTERVAL=24

This parameter is optional and has a default setting of 24 hours.

ERR_RETRY_PERIOD

This parameter represents the period of time between each retry attempt at retrieving the device data after a failure has occurred. The value should be expressed in seconds.

Example: ERR_RETRY_PERIOD=60

This parameter is optional and has a default value of 60 seconds.

NUMBER_OF_RETRIES

This parameter represents the number of retries that will be attempted, if the device data capture fails.

Example: NUMBER_OF_RETRIES=3

This parameter is optional and has a default value of 3.

The following is an example parameter string with all parameters configured: ADD_SERIAL_NR_TO_MSG=1 STARTUP_DELAY=300 DATA_CAPTURE_INTERVAL=24 ERR_RETRY_PERIOD=60 NUMBER_OF_RETRIES=3

Decline conditions:

Condition Response Code Message Reason Code

An error occurred whilst retrieving the data from the device.

06 - Error

9641 - Device Failure

To make use of this functionality, a device driver would need to implement support for retrieving the device information from the eSocket.POS Device Manager.

5.5.29. Pipeline component - Directory cleaner

Description: The Directory Cleaner component is responsible for removing old files from specified directories. It can, for example, be used to remove old firmware files that were deployed to eSocket.POS device drivers. The cleaner is run at a configured time once every 24 hours, and all files older than the configured retention period are deleted from the specified directories. The age of a file is determined by the last time it was modified. For example, if a file was last modified 12 hours ago, it is considered to be 12 hours old.

Usage: Either Request or Response pipeline (but not both). This pipeline component is optional.

Rank: Any

Class name: postilion.esocketpos.transactionengine.ComponentDirectoryCleaner

Parameters: The component must be configured with the following parameters, separated by spaces:

Parameter Values

1

cleaner time

The time in HHmm format at which the directory cleaner must be run every day.

2

file retention period

The number of hours (integer) for which files must be retained in the configured directories.

3

directories to clean

A comma-separated list of the directories that must be cleaned. For example:

C:\postilion\eSocket.POS\VerifoneFormAgent\files,C:\postilion\eSocket.POS\Trace

5.5.30. Pipeline component - Display welcome

Description: The Display Welcome pipeline component resets the display of a device being driven by eSocket.POS to display a welcome prompt at the end of a transaction.

If the structured data field, ResponseDisplay is populated with a value of 0, the component does not act, and the state of the display does not change. Otherwise, the component acts under one of the following conditions:

  • The message type is an Authorization Request Response, for example 0110

  • The message type is a Transaction Request Response, for example 0210

  • The message type is a Referral Advice Response, for example 0230, and the ReferralAdvice flag is set

  • The message type is an Admin Request Response, for example 0610, the transaction type subfield of the processing code (field 3) is not set to 96 - Preswipe, and the extended transaction type (field 127.33) is not set to 3040 - Rate Reqeust

Usage: Response Pipeline, mandatory if eSocket.POS is driving a device’s display, optional otherwise.

Rank: Must appear at the end of the response pipeline

Class name: postilion.esocketpos.transactionengine.PipelineComponentDisplayWelcome

Parameters: None

Decline conditions: None

5.5.31. Pipeline component - Echo

Description: For PCI-DSS reasons, PosConnect v5.2 and newer does not return sensitive cardholder data in response messages to eSocket.POS. Since components in the response pipeline might still require these fields, the Echo component caches masked versions of these fields from request messages.

Usage: Mandatory in both the Request Pipeline and Response Pipeline.

Rank: Must be configured at the end of the request pipeline and at the start of the response pipeline.

Class name: postilion.esocketpos.transactionengine.PipelineComponentEcho

Parameters: This component requires no parameters.

5.5.32. Pipeline component - Effective date

Description: The Effective date component ensures that the card has a valid effective date (start date), if this is required for the card. In addition, the component populates a subfield of Structured Data (field 127.22) with the effective date, if the card configuration indicates that either effective date validation is required or that there is an effective date available on the card.

The component either extracts the date from Track 2, or Structured Data (if set by the POS at the start of a manually-entered transaction), or prompts for it to be entered via the Device Manager. It then validates that the card is valid by checking that the current date is after the effective date.

Note that EMV transactions on pre-valid cards do not get declined by the Effective Date component, as this must be done by the EMV application on the terminal, using the EMV Terminal Action Codes. EMV transactions do not populate field 127.22 with the start date, since the EMV component populates this field.

Usage: Request and Response Pipelines, optional. If required, must be present in both pipelines.

Rank: Must occur after the PAN, Account and Expiry Date components, but before the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentEffectiveDate

Parameters: None

Decline conditions:

Condition Response Code Message Reason Code

Valid period checking is required for this card, and the Effective Date is not available or entered via a device

30 - Format Error

9709 - Missing Effective Date

Valid period checking is required for this card, and card is pre-valid

54 - Expired Card

9754 - Card not yet Effective

5.5.33. Pipeline component - EMV

Description: The EMV component is responsible for many aspects of the interaction between eSocket.POS and a smart card complying with the EMV (Europay, MasterCard, Visa) specification.

Request component

The details of this interaction depend on the specific EMV device that is used, but by the time the transaction reaches the EMV component in the request pipeline, application selection and card verification have already been performed (in the PAN component).

The EMV component then continues the card interaction up to the point when the first cryptogram is generated, and an online transaction must be sent, or the transaction is approved or declined offline. Depending on the EMV device, this can also include PIN entry or cashback amount entry. The EMV component then populates the ICC data in the message, and is responsible for declining the transaction or injecting an advice message, if required.

Non-EMV transactions involving an ICC are processed through the EMV component by requesting an AAC as the first cryptogram. In this context, receiving an AAC cryptogram is not viewed as a decline. The device is then reset.

Note
If Quick Chip processing is enabled, and the first cryptogram generation returns ARQC, the second cryptogram is generated with Authorization Response Code(Tag 8A) set to Z3(Unable to go online). The Smart Card Reader then waits for card removal.
Response component

The EMV component in the response pipeline is responsible for concluding the transaction, which means generating the second cryptogram if the first cryptogram is an ARQC requiring online authorization. Issuer scripts can also be applied at this stage. If the transaction is authorized, but the card then declines the transaction, the EMV component is responsible for reversing the transaction. It is possible to configure the account so that if the transaction is authorized online, and the device fails, the transaction is still approved. This configuration is done in the accounts table.

NOTE:

  • A second cryptogram will not be generated for a contactless EMV transaction or when Quick Chip processing is enabled.

Usage: Request and Response Pipelines, optional. If required, must be present in both pipelines.

Rank: Must be configured towards the end of the request pipeline. Must be configured after the PAN, Account and Amount components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentEmv

Parameters: The component can be optionally configured with the following three parameters (none, the first two or all three parameters must be configured):

Parameter Values

1

apply offline limit

Specifies whether an offline limit check must be applied after a transaction has failed to go online. If so, and the transaction amounts exceed the offline limits configured for the account, the card is requested to decline the transaction with an AAC.

0 - Do not apply offline limit check (Default)

1 - Apply offline limit check

2

refund processing

Specifies how the EMV component must deal with refund transactions.

0 - Full processing: This option includes Cardholder Verification (PIN entry), cryptogram generation, and possible online processing, as with Purchase transaction types. (Default)

1 - Offline: This option includes Cardholder Verification (PIN entry), as well as cryptogram generation, but the transaction is handled offline, regardless of whether an ARQC or TC is generated.

2 - Read card only: This option allows refunds to be processed as non-EMV transactions, that is, after the initial EMV card read by the PAN component, no further EMV interactions, such as PIN entry and cryptogram generation, are performed.

3 - Generate AAC: This option stops the refund transaction once the card data on the ICC is read by requesting an AAC cryptogram from the device.

4 - Read card only, except for consumer devices: This option is the same as option 2 (Read card only), except that full contactless EMV processing will be applied to contactless refunds performed using consumer devices, for example, mobile phones, watches, wristbands.

5 - Full processing for contactless transactions: Setting this option means that full contactless EMV processing will be applied to contactless refunds performed using a card or a consumer device.

6 - Pin Online: This option allows a refund transaction with PIN to be approved online by performing full processing (the same if as option 0) and without PIN to be approved offline after the first interaction with the device (the same if as option 1).

Note
All of the above options for refund processing can also be configured per AID by setting the required option to the tag REFUND_PROCESSING in the Custom Data for an AID.

For example: If the refund processing for a specific AID has to be set to 0-Full processing then the custom data for the AID should have the tag REFUND_PROCESSING=0.

The option set at the AID level will supersede the option set at the pipeline component level while processing a refund transaction for that AID.

3

authorization ID code

The component can be configured with an optional user parameter, the Authorization ID Code, to be inserted into field 38 when EMV stand-in is performed.

In addition, the EMV pipeline component can also be configured with the following named parameter:

Parameter Values

SUPPORTS_FORCE_DECLINE

This parameter indicates whether the device supports force declines or not. It is specified as:

SUPPORTS_FORCE_DECLINE=x, where x is 1, if the device supports force declines and x is 0, if the device does not support force declines. This influences the processing of non-EMV transactions.

If this parameter is not specified, then the EMV pipeline component defaults do not support force declines.

MERCHANT_AUTH_ENTITY

If MERCHANT_AUTH_ENTITY=1 (true) then field 123.9 (the cardholder authentication entity sub-field in the POS Data Code), is set to '4' - Merchant, if the CVM Results returned in the ICC Data indicated 'No CVM Required'. In this case field 123.8 (the cardholder authentication method sub-field in the POS Data Code) is also set to '5' - Manual.

If MERCHANT_AUTH_ENTITY=0 (false) then in the case where the CVM Results are set to 'No CVM Required', field 123.8 is set to '0' - No electronic authentication and field 123.9 is set to '0' - Not authenticated.

If this parameter is not specified, the default value is set to true.

TRANADV_USE_ICC2

If TRANADV_USE_ICC2=1 (true) and the request (for example, 0100) was declined, then the transaction advice (0220/0221) message will make use of the 2nd ICC Data (2nd ICC data is the same as the one in the response (for example, 0110) message).

If TRANADV_USE_ICC2=0 (false) and the request (for example, 0100) was declined, then the transaction advice (0220/0221) message will make use of the 1st ICC Data. (1st ICC data is the same as the one in the request (for example, 0100) message).

If this parameter is not specified, the default value is set to false. That is, 1st ICC data will be used by the transaction advice message.

SET_EXT_ICC_DATA

This parameter switches on sending additional EMV tags to the upstream entity. These tags are sent in a TLV formatted structure, which is set in Structured Data (field 127.22) under the key 'TlvIccDataExtended'. To switch this parameter on, the parameter needs to be set to one: SET_EXT_ICC_DATA=1.

By default, this parameter is switched off, which is equivalent to setting it to SET_EXT_ICC_DATA=0.

FORCE_ESP_TERM_CAPABILITIES

This parameter can be configured to ensure terminal capabilities configured for the terminal in eSocket.POS are always sent to the host. This parameter might be required when supporting transactions that modify the CVM capabilities of the terminal per transaction.

If FORCE_ESP_TERM_CAPABILITIES=1 (true), the terminal capabilities configured in eSocket.POS for the terminal will be always be sent in ICC data to the upstream host, regardless of the terminal capabilities captured during the interaction with the PED.

If FORCE_ESP_TERM_CAPABILITIES=0 (false), the terminal capabilities captured from the interaction with the PED will be sent upstream to the host.

The default value, if this parameter is not specified, is '0' (false).

QC_CR_TIMEOUT

This parameter specifies the maximum time, in seconds, eSocket.POS will wait for the card to be removed, while processing a Quick Chip transaction. If the card is not removed within this time period, transaction processing will still continue normally.

The default value is 30 seconds.

Note: If QC_CR_TIMEOUT value is set to 0 seconds when Quick Chip processing is enabled, then Pipeline Component Wait for Card Removal should be configured in the response pipeline to prompt for the card removal.

TRANAUTH_SENDS_ADV

If TRANAUTH_SENDS_ADV=1 (true), then Auth Transaction (0100) sends ICC2 data (0620) to upstream entity. (ICC2 data is the same as the one in the response (for example, 0110) message).

If TRANAUTH_SENDS_ADV=0 (false) no 0620 will be sent for 0100.

If this parameter is not specified, the default value is set to false.

USE_DEVICE_REASON_CODE

** If USE_DEVICE_REASON_CODE=1 (true), then a device decline/failure upon 2nd generate cryptogram will populate the message reason code provided in the device failure event in the reversal advice (0420).

If USE_DEVICE_REASON_CODE=0 (false), the default message reason code indicating EMV declined after online will be sent in the reversal advice (0420).

If this parameter is not specified, the default value is set to false.

PROCESS_CTLS_TRAN_REFUNDS_OFFLINE

If PROCESS_CTLS_TRAN_REFUNDS_OFFLINE=1 (true), refunds of contactless transactions will be processed offline.

If PROCESS_CTLS_TRAN_REFUNDS_OFFLINE=0 (false) refunds of contactless transactions will be processed online.

If this parameter is not specified, the default value is set to false.

EXT_ICC_DATA_TAGS

This parameter is used to specify a semi-colon separated list of EMV Tags to be sent upstream and to be returned to the POS.

Example: EXT_ICC_DATA_TAGS=5F20;9F10;8E

GENERATE_2ND_ICC_FOR_ONLINE_RSP

If no ICC response data is present from the issuer, then second ICC data should be generated.

If GENERATE_2ND_ICC_FOR_ONLINE_RSP=1 (true).

If GENERATE_2ND_ICC_FOR_ONLINE_RSP=0 (false).

If this parameter is not specified, the default value is set to true.

SEND_ADMIN_ADV_FOR_0210

If SEND_ADMIN_ADV_FOR_0210=1 (true), then online approved sale transaction responses (0210) will send ICC2 data (0620) to upstream entity.

If SEND_ADMIN_ADV_FOR_0210=0 (false), no 0620 will be sent for approved 0210.

If this parameter is not specified, the default value is set to true.

Note
To change the default Transaction Category Code (EMV tag 9F53) set by the EMV component (R - All Other Merchants/U.S. Post Exchange/Cardholder-Activated Terminal), please configure the Transaction Category Code.

Approve and decline conditions:

Condition Response Code Message Reason Code

TC returned by card at first generate AC

00 - Approved

9620 - EMV offline approved

AAC / AAR returned by card at first generate AC

05 - Do Not Honor

9621 - EMV offline declined

TC returned by card at second generate AC

00 - Approved

9622 - EMV approved after online

AAC / AAR returned by card at second generate AC

05 - Do Not Honor

9623 - EMV declined after online

Second generate AC failed due to device failure

05 - Do Not Honor

9623 - EMV declined after online (default)

9646 - Device not connected (** when USE_DEVICE_REASON_CODE is enabled)

Second generate AC failed due to card removed prematurely

05 - Do Not Honor

9632 - Card removed prematurely

Missing Contactless EMV Data

05 - Do Not Honor

9713 - Missing EMV Data

Authorization profile:

Condition Authorization Reason Authorization Type

TC returned by card at first generate AC for an Authorization request (0100).

2 - Online Stand-in. The transaction amount is below the local limits.

2 - Transaction authorized using card issuer limits.

ARQC returned by card at first generate AC. Authorization request (0100) not approved online, subsequently approved by the card.

4 - Offline Stand-in. The sink is not available.

2 - Transaction authorized using card issuer limits.

Transaction Processing Results:

The EMV component sets the following Transaction Processing Results (TPR) in the request message for byte 1, 2 and 3.

Note
In the table below, a dash (-) represents a bit that is not being used and RFU stands for "reserved for future use".
Name Byte Bit Description

ProcessedContactlessMagstripe

1

8

When set, this bit indicates that the contactless magnetic stripe transaction has been processed.

CompletedContactlessMagstripe

1

7

When set, this bit indicates that the contactless magnetic stripe transaction has been completed.

ProcessedAdviceMessage

1

6

When set, this bit indicates that the advice transaction has been processed.

GetFirstICCData

1

5

When set, this bit indicates that first card interaction was performed.

GetSecondICCData

1

4

When set, this bit indicates that second card interaction was performed.

IssuerDecisionAccepted

1

3

When set, this bit indicates that a decline/failure occurred during second cryptogram generation but is being ignored due to the account supporting "accept_issuer_decision".

ForceApprove

1

2

When set, this bit indicates that cryptogram information data indicates that the transaction should be approved.

ForceDeclinedOnNonAAC2ndICCData

1

1

When set, this bit indicates that cryptogram information data indicates that the transaction should be declined.

ContactlessICCCompleted

2

8

When set, this bit indicates that a contactless magnetic stripe transaction has been completed.

ApproveAndSendTransactionAdvice

2

7

When set, this bit indicates that the transaction was declined by upstream entity and cryptogram information data indicates that the transaction should be approved.

InsertICCDataFromOriginalTransaction

2

6

When set, this bit indicates that the ICC data is retrieved from the original transaction.

InsertStructuredDataFromOriginalTransaction

2

5

When set, this bit indicates that the structured data is retrieved from the original transaction.

ProcessedEMVTransaction

2

4

When set, this bit indicates that an EMV transaction has been completed.

ForceDeclinedMandatoryTagNotPresent

2

3

When set, this bit indicates that the transaction was declined because the ICC data does not contain mandatory tags.

InterveneResponseCodeForAACorAARCryptogram

2

2

When set, this bit indicates that the transaction was referred by upstream entity and cryptogram information data indicates that the referral was declined.

ReferByCryptogram

2

1

When set, this bit indicates that the transaction was referred by upstream entity and cryptogram information data indicates referral was passed to the POS.

ApproveOfflineContactlessRefundTransaction

3

8

When set, this bit indicates that the contactless EMV transaction’s refund was processed offline.

ApproveOfflineRefundTransaction

3

7

When set, this bit indicates that the transaction’s refund was approved offline.

ApproveOfflineRefundTransactionForTCCryptogram

3

6

When set, this bit indicates that the transaction was approved offline, based on cryptogram information data.

DeclineOfflineRefundTransactionForAACorAARCryptogram

3

5

When set, this bit indicates that the transaction was declined offline, based on cryptogram information data.

ProceedOnlineForContactlessRefundTransaction

3

4

When set, this bit indicates that the contactless EMV transaction’s refund was processed online.

ProceedOnlineForARQCCryptogramTransaction

3

3

When set, this bit indicates that the transaction’s authorization was processed online.

ProceedOnlineAACRefundTransaction

3

2

When set, this bit indicates that the contact EMV refund transaction was processed online using an AAC cryptogram.

CustomerTimeoutOnConfirmAfterOfflineApproval

3

1

When set, this bit indicates that the customer timed out during confirmation prompt after offline approval.

OperatorCancelledAfterOfflineApproval

4

8

When set, this bit indicates that the operator cancelled during confirmation prompt after offline approval.

CustomerCancelledAfterOfflineApproval

4

7

When set, this bit indicates that the customer cancelled during confirmation prompt after offline approval.

CustomerTimeoutOnConfirmBeforeOnlineApproval

4

6

When set, this bit indicates that the customer timed out during confirmation prompt, before online approval.

OperatorCancelledBeforeOnlineApproval

4

5

When set, this bit indicates that the operator cancelled during confirmation prompt, before online approval.

CustomerCancelledBeforeOnlineApproval

4

4

When set, this bit indicates that the customer cancelled during confirmation prompt, before online approval.

5.5.34. Pipeline component - EMV Config

Description: The EMV Config component manages the downloading of an EMV configuration file from an upstream entity. Primarily in this file, the component receives certifying authority (CA) public keys from an upstream entity and saves them to the eSocket.POS database. These online keys are then available to both POS and PED for EMV transaction processing.

Note
The upstream entity is the entity where the request for an EMV configuration file is sent to. It is governed by the Institution ID Code in the message.

Initially, ConfigServer loads the default CA public keys to the eSocket.POS database. To ensure that the online keys received from the upstream entity are not overwritten by ConfigServer, the two sets of keys are stored in two separate database tables:

  • esp_ca_public_key - stores keys received from ConfigServer

  • esp_capks_online - stores the online keys received in the EMV configuration file by means of the EMV Config pipeline component

The EMV Config pipeline component manages the EMV configuration file as follows:

  1. eSocket.POS sends a request for the latest EMV configuration file upstream. The request includes the current EMV file version. The upstream entity determines from the version information if an EMV file download is required and sends the file.

  2. eSocket.POS receives the EMV configuration file and loads the online keys to the eSocket.POS database, overwriting the keys in the esp_capks_online table. Once the database has been updated, the CAPK_RETRIEVAL_COMPLETE event will be raised.

  3. When the PED resyncs or re-initializes, it receives the online keys.

  4. When the POS requests the online keys, the keys previously downloaded will be returned.

Prerequisite: For the EMV Config to function, you must configure the eSocket.POS property, postilion.esocketpos.UseOnlineCaPublicKeys.

Limitations:

  • Each eSocket.POS installation can maintain or receive a single set of CA public keys from one upstream entity.

  • The default CA public keys must be loaded by ConfigServer as part of the process to configure the EMV AIDs.

  • CA public keys are only loaded to the device once the terminal re-initializes or resyncs.

  • eSocket.POS will suspend incoming request messages from terminal while EMV configuration download is in progress.

Request component

The component adds an EMV_FILE_VERSION tag into Structured Data with the latest version of the downloaded EMV file stored in the esp_capks_online database table for all 0100 and 0200 messages.

The component injects 0800 EMV File Download messages at a configured time, if a new download is required. The component can be configured to send 0800 EMV File Download Status messages during start-up or at a configured time determined, if a download is required.

The component intercepts 0800 EMV File Download messages received from the POS and will return the online keys already downloaded. If no online keys are available, the component will schedule an 0800 EMV File Download Status message to initiate an immediate download.

Response component

The component first retrieves the entire EMV configuration file before uploading the keys in the esp_capks_online database table.

Usage: Request and Response Pipelines, optional. If required, must be present in both pipelines.

Rank: Must be configured after the EMV component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentEmvConfig

The EMV Config pipeline component has the following mandatory named parameter:

Parameter Values

Institution ID Code

This parameter contains the Receiving Institution ID Code (field 100), which is populated in the 0800 EMV File Download messages:

INSTITUTION_ID_CODE=12345678901, the value is numeric and can be up to 11 digits in length.

In addition, the EMV Config pipeline component can be configured with the following named parameters:

Parameter Values

Retry Limit

This parameter indicates the number of times an EMV File Download message is retried, before the download is abandoned:

RETRY=x, where x is the number of retries

If this parameter is not specified, then the EMV Config pipeline component defaults to 3 retries.

Maximum number of messages

This parameter indicates the maximum number of allowed EMV File Download messages before the download is abandoned. It is designed to detect a scenario, where the host system never sends the "completed" indicator:

MAX_MSG=x, where x is number of download messages.

If this parameter is not specified, then the EMV Config pipeline component defaults to 40 messages.

Delay

This parameter indicates whether the component must delay the EMV File Download:

DELAY=x, where x is the number of seconds before the EMV File Download is sent.

If this parameter is not specified, then the EMV Config pipeline component defaults to either no delay, or the scheduled time as configured with the Scheduled Time parameter.

Note
The Schedule Time parameter overrides this functionality.

Scheduled Time

This parameter indicates the time that the EMV File Download must take place:

SCHEDULED_TIME=hhmmss, where hh is the hour, mm the minutes and ss the seconds of the next download.

If this parameter is not specified, then the EMV Config pipeline component uses the value of the Delay parameter.

Status Message

If this parameter is set, an EMV File Download Status message is sent to determine if a download is required.

STATUS_MESSAGE=hhmmss, where hh is the hour, mm the minutes and ss the seconds of the next status message.

STATUS_MESSAGE=999999, if the status message must be sent during start-up.

If this parameter is not specified, a status message is not sent.

Send Completion

If this parameter is set, an EMV File Download Completion State message is sent with the status of the configuration download, after the process is completed.

SEND_COMPLETION=1.

If this parameter is not specified, a completion state message is not sent.

5.5.35. Pipeline component - Expiry date

Description: The Expiry Date component validates the expiry date, if this is required for the card.

Note
EMV transactions on expired cards do not get declined by the Expiry Date component; this must be done by the EMV application on the terminal, using the EMV Terminal Action Codes.

Usage: Request Pipeline, optional.

Rank: Must be configured after the PAN and Account components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentExpDate

Parameters: The component must be configured with the following parameters:

Parameter Values

1

null expiry date

Specifies whether a null expiry date of '0000' is allowed.

0 - Null expiry dates are not allowed (an expiry date of '0000' is rejected by eSocket.POS, if expiry date checking is enabled for the card)

1 - Null expiry dates are allowed (an expiry date of '0000' is accepted by eSocket.POS)

2

Force Online

Specifies whether the expiry date must be validated or if the transaction must be forced online.

0 - Validate the expiry date. Decline expired cards and cards with incorrectly formatted expiry dates.

1 - Validate the expiry date. If the card is expired, force the transaction online. Do not decline expired cards.

Decline conditions:

Condition Response Code Message Reason Code

Message did not contain an Expiry Date, and Expiry Date was not entered via a device

30 - Format Error

9702 - Missing Expiry Date

The expiry date on the card is invalid (that is, it is not in YYMM format)

30 - Format Error

9756 - Not Valid for Transaction

Expiry Date validation is required for this card, and card has expired

54 - Expired Card

9750 - Expired Card

Advice message did not contain an Expiry Date, and Expiry Date could not be retrieved from an earlier linked transaction

30 - Format Error

9702 - Missing Expiry Date

Note
Referral Advices (0220 messages with message type set as 'REFERRAL') prompt for the expiry date, if the expiry date for the original message (Authorization Request or Transaction Request) could not be found on the same terminal. This is typically the case when the referral advice is processed on another terminal than the original message.

5.5.36. Pipeline component - Extended payment

Description: The Extended Payment component checks whether extended payment (also known as budget) is supported for the amount and account selected for this transaction. Extended Payment occurs when the cardholder chooses to repay the transaction amount over more than one payment period.

If extended payment is supported for this amount and account, the component asks the user if extended payment is required, and prompts for the extended payment period to be selected.

Usage: Request Pipeline, optional.

Rank: Must be configured after the PAN and Account components, but before the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentExtPayment

Parameters: The component must be configured with the following parameters:

Parameter Values

1

stand-in allowed on budget transactions

Specifies whether stand-in must be performed on budget transactions.

0 - Stand-in not allowed on budget transactions

1 - Stand-in allowed on budget transactions

2..

extended payment periods

A list of extended payment periods (in months), which can be selected for extended payment, separated by spaces.

For example, '6 12 24 36'

Decline conditions: None

5.5.37. Pipeline component - Fallback indicator

Description: The Fallback Indicator component is responsible for setting the Fallback, FallbackType and FallbackReason tags in Structured Data (field 127.22) to indicate if fallback occurred, the type of fallback that took place, and the reason that fallback occurred, if available.

Request component

The Fallback and FallbackReason elements are set as sub-fields of the "Postilion:TM" Structured Data tag.

Response component

The FallbackType and FallbackReason elements in Structured Data are set, if fallback occurred. If no fallback occurred, no indicator values are provided.

Fallback Indicator Values

The Fallback/FallbackType element can have the following values:

  • 0 - No fallback

  • 1 - Fallback from contact ICC

  • 2 - Fallback from magnetic stripe

  • 3 - Fallback from contactless

The FallbackReason element can have the following values:

  • 1 - Card unreadable

  • 2 - Chip error

  • 3 - No supported applications

Usage: Request and Response Pipeline, optional.

Rank: For Request Pipeline must be configured after the Late Fallback, EMV, Stand-in and Pos Config components. For Response Pipeline must be configured after the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentFallbackIndicator

Parameters: None

Decline conditions: None

5.5.38. Pipeline component - Final Auth

Description: The final auth component populates the transaction authorization indicator in the message as a structured data tag (FINAL_AUTH_IND) depending on the configuration. This component will only populate the authorization indicator in structured data, if this was not received by the POS or if the POS sends an invalid authorization indicator.

This component only processes 0100 (Authorization Request) messages.

Usage: Request pipeline, optional.

Rank: Must be configured after the Amount component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentFinalAuth

Parameters: This component must be configured with the following parameter:

Parameter Values

FINAL_AUTH_IND

This parameter is used to populate the authorization indicator in the authorization transactions to indicate the actual or estimated amounts.
The values for this parameter 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)

Example: FINAL_AUTH_IND=1

Decline conditions: None

5.5.39. Pipeline component - Funds inquiry response

Description: The Funds Inquiry Response component displays the outcome of available funds and balance inquiry transactions.

Usage: Response Pipeline, optional.

Rank: Any

Class name: postilion.esocketpos.transactionengine.PipelineComponentFundsInquiryResponse

Parameters: None

Decline conditions: None

5.5.40. Pipeline component - Generate referral response

Description: The Generate Referral Response component generates a referral response for a transaction, if the following conditions are met:

  • eSocket.POS is disconnected (or times out waiting for a response).

  • The option is allowed for the account concerned. This is indicated by the field generate_referral in the table esp_accounts.

  • Transaction type is 00 (Goods and services) or 09 (Cashback).

  • Transaction is not an ICC or Contactless transaction.

Usage: Response Pipeline, optional.

Rank: Must occur after the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentGenerateReferral

Parameters: The component must be configured with the following parameter:

Parameter Values

1

referral response code

The referral response code to be used, in format n2.

The suggested value is '01'.

Decline conditions: None

5.5.41. Pipeline component - Gratuity

Description: The Gratuity component prompts the customer, on the PIN entry device (PED), to add a gratuity to their transaction.

The Gratuity component ignores messages that already have a gratuity amount present. It only prompts the customer to enter a gratuity for the following message types:

  • Authorization request (0100)

  • Transaction request (0200)

  • Transaction completion request (0220)

  • Transaction completion request repeat (0221)

These messages must have a Purchase account type.

This component must be configured before Pipeline Component Pan in order to support contactless transactions.

Usage: Request pipeline, optional.

Rank: Must be configured after the Account and Amount components, but before the EMV and Stand-in components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentGratuity

Parameters: Configure the following optional parameters, as required.

Parameter Values

GRATUITY_PERCENTAGES

Specifies the percentage options that are offered to the customer at the PED. These are also used to calculate the gratuity amounts prompted. Configure as a comma-separated list of numbers representing gratuity percentages.

Example: GRATUITY_PERCENTAGES=5,10,15
For a transaction with an amount of $100, the customer is prompted with the calculated gratuity amounts of $5, $10, and $15.

There is no default setting for this parameter.

CUSTOM_GRATUITY_ALLOWED

Specifies whether the customer is prompted to enter an amount at the gratuity prompt. The prompt wording depends on the PED configuration.
Configure the parameter as follows:

  • 0 - The customer is not given the option to enter a gratuity amount.

  • 1 - The customer is given the option to enter a gratuity amount (default).

Example: CUSTOM_GRATUITY_ALLOWED=1

CANCEL_MODE

Specifies the action to take when the cancel button is selected on the PED:

  • 0 - Cancel the transaction (default).

  • 1 - Cancel the gratuity prompt and continue with the transaction.

Example: CANCEL_MODE=1
NOTE: The transaction will not be canceled when pipeline component Gratuity is configured with CANCEL_MODE=0 PROMPT_MESSAGE_TYPE=1. A transaction cannot be canceled when prompting for gratuity in a 0220 or 0221 request message.

PROMPT_MESSAGE_TYPE

Specifies the message type used to prompt for gratuity:

  • 0 - Prompts for gratuity during the 0100 and 0200 request messages (default). The selected or entered gratuity amount will be populated in the authorization request (0100) and transaction request (0200) messages.

  • 1 - Prompts for gratuity during the 0220 and 0221 request messages. The selected or entered gratuity amount will be populated in the transaction completion request (0220) and advise (0221) messages.

Example: PROMPT_MESSAGE_TYPE=1 Note: In order to display the transaction outcome when using PROMPT_MESSAGE_TYPE=1, see Pipeline Component - Response Code for additional configuration.

DISABLE_CONTACTLESS_EMV_GRATUITY

Specifies whether gratuity should prompt for contactless EMV transactions.

  • 0 - Gratuity will prompt for contactless EMV transactions (default).

  • 1 - Gratuity will not prompt for contactless EMV transactions.

Example: DISABLE_CONTACTLESS_EMV_GRATUITY=1

Note
Although the parameters are optional, they must be configured in a logical manner. For example, the following combination results in the Gratuity pipeline component initialization failing. The percentages are not configured, and the user cannot enter a gratuity, resulting in no prompt for gratuity.
  • Parameter GRATUITY_PERCENTAGES is not configured.

  • Parameter CUSTOM_GRATUITY_ALLOWED is set to 0.

Decline conditions:

Condition Response code Message reason code

The sum of the transaction amount, and the chosen gratuity amount exceeds the maximum character length of 12 digits.

13 - Invalid amount

9756 - Not Valid for Transaction

The gratuity amount values in Additional Amounts (Field 54) and in StructuredData (Field 127.22) are different.

30 - Format error

9756 - Not Valid for Transaction

5.5.42. Pipeline component - Hotcard

Description: The Hotcard component is responsible for checking the PAN and card sequence number against the hotcard list held by eSocket.POS.

In some environments or situations, the behavior of the Hotcard component varies as follows:

  • When a transaction (with a card sequence number) is handled by the Hotcard component, and a hotcard exists in the hotcard list without a card sequence number (for example, NIL), the component can match the hotcard if the following hotcard checking property is set to true:
    postilion.esocketpos.AllowNullCSNMatchingForConfiguredHotcards

  • EMV transactions on hotcards are not declined or forced online by the Hotcard component; this must be done by the EMV application on the terminal using the EMV terminal action codes.

  • Gift card activation (without a deposit) and gift card deactivation (without cashback) transactions are not processed by the Hotcard component. It is assumed that the upstream entity performs this check.

  • If hotcard checking is required in a point-to-point encryption (P2PE) environment, the Hotcard component handles the hotcard check as follows:

    • The Hotcard component receives a tokenized form of the PAN, which was calculated at the PED, using a tokenization key. It also receives the tokenization check value.

    • It compares the check value of the tokenization key against the tokenization check value from the eSocket.POS keystore hotcard upload files.

    • If the check values match, the hotcard processing continues as normal, using the tokenized form of the PAN. However, if the check values do not match, an error is reported, and the transaction continues without further hotcard checking.

      Note
      When used in a P2PE environment, a salt is referred to as a tokenization key, and a hashed PAN as a tokenized PAN.

See the hotcard file format for more information, including hotcard categories and response codes.

Usage: Request pipeline, optional. Response pipeline, optional. However, if the treatment parameter is set to 0 or 1, or if any of the <treatment> values of the category_treatment parameter are set to 0 or 1, the Hotcard component must be configured in the response pipeline.

Rank: Must be configured after the PAN, Account and Card Sequence Number (if configured) components, but before the Stand-in component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentHotcard

Parameters: The component can be configured with the following optional (space-delimited) parameters, in the following order. If not set, the default values are used.

Parameter Values

1

Treatment

Specifies how the component must react when a hotcard is detected, if not overridden for the particular card (see category_treatment).

  • 0 - Hotcard transactions are forced online. When the upstream entity is not available, the transaction is declined using the response code configured against the hotcard in the eSocket.POS database. This is the default setting.

  • 1 - Hotcard transactions are declined, and a confirmation advice message is sent upstream. Both messages have the response codes configured against the hotcard.

  • 2 - Hotcard transactions are declined with the response code configured against this hotcard, but no advice message is sent upstream.

2

Check only when offline

Specifies online hotcard checking as follows:

  • 0 - Always check if card is hot (default).

  • 1 - Only check if card is hot if there is no connection upstream.

3

category_treatment

Defines the treatment of "hotcard categories" and takes precedence over the treatment parameter. Configure as a tag=value pair as follows:

category_treatment=<category>|<treatment>;<category>|<treatment>;…​

For example: category_treatment=W|0;H|1

Where:

  • <category> refers to the hotcard category configured against the hotcard. The format is 1 or 2 alphanumeric characters. For example: W = "warm" hotcards and H = "hot" hotcards.

  • <treatment> defines the treatment of the hotcard category and refers to a treatment option specified in Parameter 1: either 0, 1, or 2.

Note
The tag=value string does not contain spaces.

Decline conditions:

Condition Response code Message reason code

Card is on hotcard list, and the treatment parameter is set to 1 or 2.

Retrieved from hotcard file.

  • 3000 - Lost card

  • 3001 - Stolen card

5.5.43. Pipeline component - Key manager

Description: The Key manager component manages key exchange with the upstream payments system via the PosConnect source node. Key exchange is initiated at startup and at a fixed time every 24 hours, if eSocket.POS is connected to the upstream system. While the key change is in progress, PIN-based transactions are declined by eSocket.POS.

Usage: Request Pipeline, optional.

Rank: Must be configured after the PAN and Account components, but before the PIN component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentKeyManager

Parameters: The component must be configured with the following parameter:

Parameter Values

1

keychange time

The time of the key exchange, in HHmm format.

Set to '9999' if no key exchange must occur.

In addition, the component can be configured with the following named parameters:

Parameter Values

ERR_RETRY_PERIOD

ERR_RETRY_PERIOD=x, where x is a numeric value in seconds

This is the period in seconds between key loads to the device when an error occurred. Depending on the setting of the ERR_RETRY_NR property (see below), it would request for a new key and then load this key to the device, or re-attempt to load the key to the device, using the last successful key it obtained.

ERR_RETRY_NR

ERR_RETRY_NR=x, where x is a numeric value specifying the number of times the Key Manager component must re-attempt to load a key to the device using the same key before requesting for a new key after an error occurred.

KEY_EXCHANGE_JITTER_TIME

KEY_EXCHANGE_JITTER_TIME=x, where x is a numeric value in seconds

A random value between 0 and the number of seconds configured here is added to the key exchange time in order to ensure key exchange messages are not sent simultaneously.

Default: 30 seconds

Decline conditions:

Condition Response Code Message Reason Code

Transaction requires PIN, but a key exchange is currently in progress

21 - No action taken

9680 - Key change in progress

5.5.44. Pipeline component - LateFallback

Description: The LateFallback component is responsible for processing EMV transactions, where a chip failure occurs in the EMV component (as opposed to the PAN component). It handles fallback processing to allow the card’s magnetic stripe to be read, after which the transaction is treated as a normal magnetic stripe transaction.

Usage:

  • If configured, must be present in both Request and Response pipelines, optional.

  • Only one of LateFallForward or LateFallback needs to be configured in the Request pipeline.

Rank: It must be configured at the start of the Request pipeline and in the Response pipeline before the stand-in, EMV and Response Code components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentLateFallback

Parameters: None

Decline conditions:

Condition Response code Message reason code

A smart card was read using the magnetic stripe and card does not support ICC fallback.

62 - Restricted Card

9755 - No supported accounts for ICC fallback

5.5.45. Pipeline component - LateFallForward

Description: The LateFallForward component is responsible for processing contactless transactions, where the transaction is either declined online, or declined without going online. For specific response codes and message reason codes, this component handles FallForward processing to allow the card’s chip to be read, after which the transaction is treated as a normal EMV transaction.

Usage:

  • If configured, must be present in both Request and Response pipelines, optional.

  • Only one of LateFallForward or LateFallback needs to be configured in the Request pipeline.

Rank: It must be configured at the start of the Request pipeline and in the Response pipeline after the EMV component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentLateFallForward

Parameters: None

Note
The LateFallForward component uses optional extended contactless card parameters (OFFLINE_DECLINE_FALLFORWARD_RSP_CODES and ONLINE_DECLINE_FALLFORWARD_RSP_CODES) as specified in the device driver documentation.

Transaction Processing Results:

The LateFallForward component sets the following Transaction Processing Results (TPR) in the request and response message for byte 1.

In the table below, a dash (-) represents a bit that is not being used and RFU stands for "reserved for future use".

Name Bit Description

FallForwardOccured

8

When set, this bit indicates that late fall forward processing has occurred.

OnlineDecline

7

When set, this bit indicates that the message was declined online (not by this component).

OfflineDecline

6

When set, this bit indicates that the message was declined offline (not by this component).

DeviceDecided

5

When set, this bit indicates that the decision to fall forward or not was performed by the device driver.

EspRspCodeDecided

4

When set, this bit indicates that the decision to fall forward or not was performed by eSocket.POS.

NoCache

3

When set, this bit indicates that the request leg of the message could not be found.

NoAidInfo

2

When set, this bit indicates that no AID information for the current transaction could be found.

AmexChecked

1

When set, this bit indicates that AMEX check was performed to decide whether to fall forward or not.

5.5.46. Pipeline component - Line Item Display

Description: The Line Item Display component allows the customer to view the individual items purchased on the PIN entry device (PED), while the items are being scanned at the point of sale (POS). It also allows the customer to present the card, while the items are being scanned. Following the card read, the card details are stored in memory and used when all the items are scanned, and the financial transaction is processed by eSocket.POS. The component also enables the PED to display the result of a transaction that was processed at the POS.

The POS sends the line item details as callback events. The pipeline processes these events from the POS and sends appropriate line item details to the PED. The pipeline also returns the results of the callback event to the POS.

Events:

This pipeline processes four kinds of callback events from the POS:

Callback Description

Start Line Display

The POS begins the line display session by sending a callback event with ID 'LINE_ITEM_DISPLAY' and a data "lineItemDisplay:start".

This event has the following optional data elements:

  • scanAhead: <on/off> - To indicate if the customer can present the card while the items are being scanned.

  • scanAheadMessage : <message> - Custom card prompt message displayed in the PED. Default system message will be used, if this is not present.

  • sendCardData : <true/false> - To indicate whether the obfuscated track 2 data and card product name should be sent in the CARD_READ event raised by eSocket.POS after a card read has occurred while items are being scanned. If set to false, only the PAN entry mode will be sent in the event. Defaults to false.

  • tranType : <2-digit ISO8583 transaction type> - Indicates the transaction type when scan-ahead is enabled. For EMV refund scan-ahead, a value of "20" (returns) must be specified. If not specified, the transaction type will be assumed to be "00" (goods and services).

This callback event puts the terminal in line item mode and returns the display configuration of the PED to the POS.

Item Detail Display

For each scanned line item the POS will send a callback event with ID 'LINE_ITEM_DISPLAY', and a data containing the line item details.

The line item detail data can be in one of the following three formats:

  • lineItemDisplay:itemDetail; additionalInfoItem1 : <value> ; additionalInfoItem2 : <value> ; additionalInfoItem3 : <value> ; additionalInfoItem4 : <value> ; formattedItemDisplayLine: "<item details line 1>" "<item details line 2>" "<subtotal amount>"

  • lineItemDisplay:itemDetail; additionalInfoItem1 : <value> ; additionalInfoItem2 : <value> ; additionalInfoItem3 : <value> ; additionalInfoItem4 : <value> ; formattedItemDisplayLine: "<item details line 1>" "<item details line 2>" "<subtotal amount detail>" "<additional total detail>" "<additional total detail>" "<total amount>"

  • lineItemDisplay:itemDetail; itemNum : <value> ; quantity : <value> ; unitPrice : <value> ; lineTotal : <value> ; voided : <value> ; itemDescription : <value> ; subtotal : <value> ; additionalInfoItem1 : <value> ; additionalInfoItem2 : <value> ; additionalInfoItem3 : <value> ; additionalInfoItem4 : <value> ;

The pipeline extracts the line item details and sends it to the PED.

Note
The additionalInfoItems are optional.
Note
For the additionalInfoItem <value>, a name and value pair separated by a '=' should be specified for each item. For example, additionalInfoItem1: <label>=<value>.
Note
If present, the additionalInfoItems must be specified before the formattedItemDisplayLine items.

Transaction Result Display

To display the transaction result the POS will send a callback event with ID 'LINE_ITEM_DISPLAY' and a data containing the results of the transaction.

The transaction result data should be of the following format:

  • lineItemDisplay:tranResult; formattedItemDisplayLine: "<transaction result>"

The pipeline extracts the transaction result details and sends it to the PED.

End Line Display

The POS ends the line display session by sending a callback event with ID 'LINE_ITEM_DISPLAY' and a data "lineItemDisplay:end". This callback event will remove the terminal from line item mode.

This event has the following optional data elements:

  • resetTran: <true/false> - Indicates whether card details that have been read and cached during scan-ahead should be cleared from eSocket.POS and whether any pending EMV card reads should be aborted, if a card has been inserted. For example, if the POS application needs to abort a transaction while eSocket.POS is performing scan-ahead and displaying line items, this data element can be set to true to request the cardholder to remove an EMV card and revert the PED to its idle state. This data element defaults to true when no line item details or transaction results are being displayed on the PED (that is, when the Start Line Display callback is immediately followed by an End Line Display callback, without Item Detail Display and Transaction Result Display callbacks in-between). Otherwise, it defaults to false.

NOTE:

  • Any financial transactions from a terminal are processed by this pipeline, but only if the terminal is not in line item display mode.

  • An Item Detail Display event, or a Transaction Result Display event cannot both occur during the same Start and End Line Display session.

Limitations:

  • Line Item Display is only supported for purchase transactions, and not other transaction types such as balance inquiry, deposit, refund and so on.

Usage: Request Pipeline, optional.

Rank: Must be configured before the Pre-Swipe component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentLineItemDisplay

Parameters: Configure the following optional parameter as required.

Parameter Values

FORCE_END_LINE_ITEM

Specifies whether the terminal should be taken out of line item mode when Line Item End callback fails because of device failure.
Configure the parameter as follows:

  • 0 - Do not take terminal out of line item mode in case of Line Item End callback failure (default).

  • 1 - Take terminal out of line item mode in case of Line Item End callback failure.

Example: FORCE_END_LINE_ITEM=0

FORCE_RESET_TRAN

Specifies whether a Line Item Start callback immediately followed by a Line Item End callback while in scan-ahead mode, will clear any card details that have been read and cached. This parameter results in similar behavior to the Line Item End 'resetTran' data element.

  • 0 - Line Item End callbacks sent immediately after Start callbacks do not clear cached card details read during scan-ahead (default).

  • 1 - Line Item End callbacks sent immediately after Start callbacks will clear cached card details read during scan-ahead.

Example: FORCE_RESET_TRAN=0

TRAN_END_LINE_ITEM

Specifies how an incoming transaction is handled if line item display mode is active.

  • 0 - The transaction is declined (default).

  • 1 - Line Item mode ends, and the transaction continues.

Example: TRAN_END_LINE_ITEM=1

Decline conditions:

Condition Response Code Message Reason Code

Financial transaction comes for a terminal that is in line item display mode

06 - Error

9722 - Incomplete Line Item Display Mode

5.5.47. Pipeline component - Loyalty

Description: This component is responsible for determining loyalty eligibility and retrieving loyalty information from the card. The loyalty identification for magstripe cards can be configured on the Cards console, under the Card Profiles tab.

The loyalty identification for EMV cards can be configured on the Cards console under the EMV Card Parameter, under the AID Parameter sub-tab.

Note
Only contact magstripe and EMV cards are supported.
Request component

The following message types are supported:

  • Authorization Request (0100)

  • Transaction Request (0200)

The following transaction types are supported:

  • Goods and Services (00)

  • Goods and Services Cash Back (09)

When a card that is eligible for loyalty processing is used for a payment, the loyalty configuration is used to retrieve loyalty data from a card.

Once the data has been validated to determine if the card is eligible for loyalty processing, the LOYALTY_INTERRUPT callback is raised, containing the loyalty information.

A response is received that contains a new transaction amount.
The POS might also send an Abort response, if the transaction should be declined.

If a response takes too long to be received, a timeout will occur, and the transaction will be declined.

Response component

The following message types are supported:

  • Authorization Request (0610)

The following transaction types are supported:

  • Card Read (95)

If a 0610 message is received for a loyalty card, the configured loyalty data is used to retrieve loyalty data from a card.

Once validated, this data is put into structured data (field 127.22) under the subfield LoyaltyAccount.

The LoyaltyAccount subfield contains:

  • IdentificationSupport: Always set to LoyaltyCard.

  • EntryMode: ICC for EMV transactions. MagStripe for magstripe transactions.

  • LoyaltyBrand: The loyalty brand configured for the card.

  • LoyaltyID: The loyalty ID retrieved from the card. This will either be in discretionary data or in a specified EMV tag, depending on the card.

  • IdentificationType: Always set to AccountNumber.

  • LoyaltyEligibility: Y if the loyalty information was retrieved and validated successfully. N, if the validation of the data failed.

Events:

Callback Description

LOYALTY_INTERRUPT

Once the data has been validated to determine if the card is eligible for loyalty processing, the component sends a callback event with ID LOYALTY_INTERRUPT and the following data:

  • Identification Support: Always set to LoyaltyCard.

  • Entry Mode: ICC for EMV transactions. MagStripe for magstripe transactions.

  • Loyalty Brand: The loyalty brand configured for the card.

  • Loyalty ID: The loyalty ID retrieved from the card. This will either be in discretionary data or in a specified EMV tag, depending on the card.

    • Identification Type: Always set to AccountNumber.

  • Loyalty Eligibility: Y if the loyalty information was retrieved and validated successfully. N if the validation of the data failed.

Examples:

  • identificationSupport=LoyaltyCard;entryMode=ICC;loyaltyBrand=AAAA;loyaltyIdentifier=12345;identificationType=AccountNumber

  • identificationSupport=LoyaltyCard;entryMode=MagStripe;loyaltyBrand=AAAA;loyaltyIdentifier=12345;identificationType=AccountNumber

  • loyaltyEligibility=N

Note
The loyaltyEligibility is only included when Loyalty Eligibility is N.

Usage: Request and Response Pipelines, optional.

Rank: Must be configured after the PAN component, but before the EMV component and the following optional components: Gratuity, Confirm, Stand-in.

Class name: postilion.esocketpos.transactionengine.PipelineComponentLoyalty

Parameters: Configure the following optional parameter as required.

Parameter Values

ERROR_MODE

Determines the handling of transactions where we have appropriate loyalty configuration for the card, but the card data is evaluated as incorrect:

  • 1 - Always raise LOYALTY_INTERRUPT callback, regardless of whether transactions are loyalty eligible or not loyalty eligible.

  • 2 - Only raise LOYALTY_INTERRUPT callback when a transaction is loyalty eligible.

  • 3 - Decline transactions immediately when they are not loyalty eligible. Callback will not be raised (default).

Example: ERROR_MODE=1

TIMEOUT_MODE

Determines how a timeout response to the LOYALTY_INTERRUPT callback is handled:

  • 0 - Decline the transaction (default).

  • 1 - Continue processing.

Example: TIMEOUT_MODE=0

Decline conditions:

Condition Response Code Message Reason Code

An Abort response was received from the POS.

05 - Do Not Honor

9631 - Operator Canceled

Either a Timeout message was received from the POS, or no (null) message was received.

05 - Do Not Honor

9665 - Loyalty Timeout

Any other response was received.

20 - Invalid Response

9666 - Loyalty Failed

5.5.48. Pipeline component - Merchant

Description: The Merchant Config component sets various merchant-related properties of the transaction. These are the Merchant Type, Card Acceptor ID Code, and Card Acceptor Name Location.

The Card Acceptor ID Code and Card Acceptor Name Location can be configured per terminal, or per merchant. If no values are configured for this terminal, the values configured for the merchant are used instead.

Usage: Request Pipeline, mandatory.

Rank: Must be configured after the PAN and Account components, but before the Card Acceptor ID Code component (if configured).

Class name: postilion.esocketpos.transactionengine.PipelineComponentMerchantConfig

Parameters: None

Decline conditions: None

5.5.49. Pipeline component - Monitoring

Description: This component is responsible for acquiring and sending monitoring information upstream regarding the terminal status. In addition, this component also sends support events logged against the terminal upstream so that they can be handled by the Realtime support framework, provided it is configured to do so and the appropriate log driver is configured. (Note that this functionality requires PosConnect version 2.1 or later.)

Upon receipt of a 0100 - Authorization Request, a 0200 - Transaction Request, a 0600 - Administration Request, or a 0800 - Network Management Request message within a configurable monitoring interval, this component queries the terminal status and populates the Additional Data field (field 48) with the result (see monitoring commands for the format). If the terminal status has changed, it might also send a status update event describing the status change as well as any errors detected by monitoring leading up to the status change (via the _StatusUpdate entry in field 127.22) if configured to do so (see the report status change…​ parameters). Furthermore, depending on the PosConnect logging level parameter, any support events logged against the terminal are included (via the Events entry in field 127.22).

If no 0100, 0200, 0600, or 0800 is received during the monitoring interval, this component generates a 0800 at the end of the monitoring interval when the terminal status changes to CRITICAL (default), or when required by the configured monitoring level. This component also allows for the configuration of no monitoring polling, in which case no 0800 message is generated at the end of the monitoring interval.

This component also supports an update message timer which defines a time period of inactivity since the last response was processed. If it expires, a 0800 is generated unconditionally (that is, regardless of whether the terminal status has changed), containing the terminal status (field 48), status update event if applicable (_StatusUpdate entry in field 127.22), and support events (Events entry in field 127.22).

Note
If this component is configured to send events that are logged, events are added to all online message types passing through this component (including 0100s, 0200s, 0600s, and 0800s), as well as to advice messages.

Usage: Request and Response Pipelines, optional. If required, must be present in both pipelines.

Rank: This component must be configured at the end of the Request pipeline, and at the beginning of the Response pipeline.

Class name: postilion.esocketpos.transactionengine.PipelineComponentMonitoring

Parameters: This component must be configured with the following parameters in the Request pipeline, separated by spaces. NOTE: The same parameters must be configured for both the Request, and the Response pipelines.

Parameter Values

1

Monitoring Interval

The interval (in seconds) this component must poll for the terminal status when no 0100, 0200, 0600, or 0800 was received during the interval.

Set to 0 if no monitoring polling must occur.

2

Report status change to OK

Rule for sending a support event describing the status change as well as any errors detected by monitoring leading up to the status change when the terminal status changes from SUSPECT or CRITICAL to OK.

Set to 1 if a support event must be sent in this case.

3

Report status change from OK to SUSPECT

Rule for sending a support event describing the status change as well as any errors detected by monitoring, leading up to the status change when the terminal status changes from OK to SUSPECT.

Set to 1 if a support event must be sent in this case.

4

Report status change from CRITICAL to SUSPECT

Rule for sending a support event describing the status change as well as any errors detected by monitoring leading up to the status change when the terminal status changes from CRITICAL to SUSPECT.

Set to 1 if a support event must be sent in this case.

5

Report status change to CRITICAL

Rule for sending a support event describing the status change as well as any errors detected by monitoring leading up to the status change when the terminal status changes from OK or SUSPECT to CRITICAL.

Set to 1 if a support event must be sent in this case.

6

Monitoring Level (optional, must be configured if a Logging Level is also configured)

The level of monitoring required (at the end of the monitoring interval).

Set to 1 if a 0800 message must be sent when the terminal status changes to CRITICAL
Set to 2 if a 0800 message must be sent when the terminal status changes to SUSPECT or CRITICAL
Set to 3 if a 0800 message must be sent when the terminal status changes to OK, SUSPECT or CRITICAL.

By default, a 0800 message is only sent if the terminal status changes to CRITICAL.

7

PosConnect Logging Level (optional)

The severity of events that must be sent to PosConnect to be reported centrally.

Set to 1 if events with a severity of Error must be sent
Set to 2 if events with a severity of Error or Warning must be sent
Set to 3 if events with a severity of Error , Warning or Informational must be sent

By default, no events are included in transaction messages.

In addition, the monitoring pipeline component can also be configured with the following named parameter:

Parameter Values

Update message timer

This parameter indicates the length of the period of inactivity which results in the construction of a status message. It is specified as:

UPDATE_MSG_TIMER=x, where x is a numeric value that specifies time period in minutes.
The time period can also be specified in seconds by appending an "s" after the numeric value.

If this parameter is not specified, then the Monitoring component defaults to taking no action in this scenario.

Maximum number of support events in messages

Indicates the maximum number of support events that can be added to messages. Note that this does not apply to 0800 messages generated by this component. The number of support events in these messages are limited to the maximum between the value configured for this parameter and 200.

The number of support events included in messages is limited so that a large number of support events pending delivery do not cause a delay on transactions. If a small value is configured for this parameter, then the EVENT_AGE_POLL_INTERVAL and MAX_EVENT_AGE parameters must be configured sensibly to ensure that support events get delivered.

This parameter is specified as MAX_NR_EVENTS=x, where x is the number of events.

If this parameter is not specified, then a default value of 20 is used.

Support event poll interval

The time interval in which the database must be polled for the age of support events. Each time this interval expires, this component polls the database if it was not polled within the last interval, or if the last poll indicated that there are support events older than the MAX_EVENT_AGE.

This parameter is specified as EVENT_AGE_POLL_INTERVAL=x, where x is the poll interval in minutes.

If this parameter is not specified, then a value of 1 minute is used. Set this parameter to 0 to disable polling of the database.

Maximum desired age for undelivered support events

Indicates the desired maximum age for support events before they must be delivered. This component polls the database for events older than this value. If any are found, it generates a 0800 message.

This parameter is specified as MAX_EVENT_AGE=x, where x is the desired maximum age for support events in minutes.

If this parameter is not specified, then a value of 10 minutes is used.

Jitter time for monitor message interval

This parameter is used to stagger the generation of terminal monitoring messages for different terminals to ensure that the terminal monitoring messages for many terminals are not sent simultaneously to the upstream entity. This is achieved by adding a random value between 0, and the number of seconds configured in this parameter to the time interval configured in Update message timer and Monitoring Interval parameter, resulting in different time intervals for each terminal.

This parameter is specified as MONITOR_JITTER_TIME=x, where x is a numeric value in seconds.

If this parameter is not specified then a value of 60 seconds is used.

5.5.50. Pipeline component - OPC

Description: This component is responsible for handling the Operation Code (OPC) functionality.

OPCs define the payment plan under which a transaction should be processed. Customers using retailer cards are extended a benefit by the retailer, through a choice of payment plans (OPCs). Some examples of payment plans are:

  1. Pay in full with immediate debit.

  2. Pay in full with deferred debit (at the end of the current month).

  3. Pay in x monthly installments.

When a card and transaction are both eligible for OPC selection, the list of OPCs will be presented on the device or POS screen (if the merchant does the OPC selection).

For magstripe and manual PAN entry, this list is based on the BIN and the esp_opc_bin_map tables.

For EMV cards, it is based on the code support found in the EMV tag configured using the OPC_TAG parameter, and the esp_opc_bin_map tables.

The transactions that are supported by default are:

  1. 0100/0200s that are not returns (transaction type 20)

  2. 0600s that are card activations or card deactivations (transaction type 91 with extended type 3100/3101).

After selection, a confirmation screen will be displayed. If this confirmation prompt is canceled for cardholder OPC selection, the transaction will be canceled. For merchant OPC selection, if the confirmation prompt is canceled, this will cause the screen to cycle back to the OPC selection screen so that a new OPC can be selected. Alternatively, the correction button on the device can be pressed, which will cause the screen to cycle back to the OPC selection screen so that a new OPC can be selected.

The merchant can set the OPC selection mode in the transaction by using the MerchantOpcSelection flag. If this flag is set to 1, then this indicates that merchant OPC selection should be applied to the transaction. If this flag is not set, or is set to 0, then cardholder OPC selection should be applied.

An OPC request is eligible for reselection when the host indicates that the selected OPC is not permitted for the transaction, and a reattempt is allowed. The cardholder will be prompted to select another OPC, after which the PIN entry will be bypassed.

NOTE:

  1. Only contact magstripe, manual PAN entry and EMV transactions will be considered for OPC selection functionality.

  2. The card profile’s default OPC value will be set when OPC selection is mandatory, but no OPC options are configured. No OPCs will be presented on the device or POS screen.

Events:

Callback Description

OPC_SELECTION

When the MerchantOpcSelection flag is set, the component sends a callback event with ID OPC_SELECTION and the following data:

  • Title: The card product name of the card used for payment, always present.

  • OPC List: A list of OPCs, for example opcList=<paymentOptionCode>:<opcDisplayOrder>:<longLabel>.

  • Is Retry: Indicates whether OPC selection was a re-attempted.

Examples:

  • title=TestCard;opclist=AAAAA:3:long1,BBBBB:1:long2,CCCCC:2:long3;isRetry=0

OPC_CONFIRMATION

When the response is received for OPC selection, the component sends a OPC confirmation callback event with ID OPC_CONFIRMATION and the following data:

  • Selected OPC: The OPC that was selected by the POS, for example selectedOpc=<paymentOptionCode>:<longLabel>.

  • Amount: Transaction Amount in 12-digit, minor denomination.

  • Currency Code: Indicates the currency used for the transaction.

Examples:

  • selectedOpc=CCCCC:long3;amount=000000010000;currencyCode=710;

Usage: If configured, must be present in both Request and Response Pipelines, optional.

Rank: Must be configured after the PAN and Cashback components, but before the PIN component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentOpc

Parameters: The component can be configured with the optional named parameters listed below.

Parameter Values

RETRY_LIMIT

A numeric value specifying the number of OPC selection attempts allowed for transactions eligible for OPC reselection.

This parameter is optional and has a default setting of 2.

RETRY_DISPLAY_FILTER_ENABLED

Specifies whether the selected OPC of the previous attempt should be removed from the OPC selection list on the next retry.

  • 1 or true - OPC selection filtering is enabled.

  • 0 or false - OPC selection filtering is disabled.

This parameter is optional and has a default setting of false.

DISPLAY_OPC_SELECTION_PROMPT

Specifies whether the OPC selection screen should be displayed when a single OPC is configured.

  • 1 or true - OPC selection is required.

  • 0 or false - OPC selection is not required.

This parameter is optional and has a default setting of true.

DISPLAY_OPC_CONFIRMATION_PROMPT

Specifies whether the OPC confirmation screen should be displayed when a single OPC is configured.

  • 1 or true - OPC confirmation is required.

  • 0 or false - OPC confirmation is not required.

This parameter is optional and has a default setting of true.

OPC_TYPE_FILTER_MODE

Specifies whether the list of OPCs to select should be filtered, depending on the type assigned to each OPC.

The values for this parameter are:

  • 0 - OPC selection filtering by type is disabled.

  • 1 - OPC selection filtering is enabled. Exclude OPCs that do not have a type when selecting OPCs.

  • 2 - OPC selection filtering is enabled. Include OPCs that do not have a type when selecting OPCs.

The different types that define when an OPC should be used are:

  • 0 - Cardholder selected OPC, message type 0100 or 0200 with transaction type 00 or 09 or 20 (Goods and Services/Cashback/Returns)

  • 1 - Merchant selected OPC, message type 0100 or 0200 with transaction type 00 or 09 or 20 (Goods and Services/Cashback/Returns)

  • 2 - Cardholder selected OPC, message type 0100 or 0200 with transaction type 01 (Cash)

  • 3 - Cardholder selected OPC, message type 0100 or 0200 with transaction type 31 (Balance Inquiry)

  • 4 - Cardholder selected OPC, message type 0600 with transaction type 91 and extended transaction type 3100 (Card Activation)

  • 6 - Cardholder selected OPC, message type 0600 with transaction type 91 and extended transaction type 3101 (Card Deactivation)

This parameter is optional and has a default setting of 2.

Note
There is no 5 in the list above, as there are no filtering requirements for it.

DATE_FILTER_ENABLED

Specifies whether the list of OPCs to select should be filtered depending on the start and end date assigned to each OPC. If a date is not assigned to an OPC the validation will be skipped for only that date. For example, an OPC with start_date = 00000101 and end_date = NULL will not be removed from the selectable OPC list, even though it has an end date of NULL.

  • 1 or true - OPC selection filtering, based on the date is enabled.

  • 0 or false - OPC selection filtering, based on the date is disabled.

This parameter is optional and has a default setting of true.

SELECTED_OPC_TAG

Specifies the name for the structured data tag, which contains the selected OPC.

This parameter is optional and has a default setting of SelectedOpc.

Note
This tag should be unique and should not conflict with any of the existing structured data tags, as this could lead to loss of data.

INCLUDED_TRAN_TYPES

Specifies a number of transaction types, delimited by a semicolon (;), to be supported for OPC processing.

Each transaction type can have extended transaction types, if followed by a colon (:).

The extended transaction types are delimited by a comma (,).

Example value: INCLUDED_TRAN_TYPES=00;01;09;20;31;91:3100,3101

By default, all transaction types except 20 are supported.

UPDATE_AUTH_PROFILE

Specifies whether the Authorization Profile field should be updated during OPC processing.

Note
The Authorization Profile is only updated if OPC processing has occurred for this transaction.
  • 0 - the Authorization Profile is not updated.

  • 1 - the Authorization Profile is updated if the OPC has an offline stand-in limit configured.

  • 2 - the Authorization Profile is always updated during OPC processing.

This parameter is optional and has a default setting of 0.

UPDATE_TRANSMISSION_DATE_TIME_ON_RETRY

Specifies whether the Transmission Date and Time (field 7) should be updated on OPC retry.

  • 1 or true - The Transmission Date and Time will be updated on OPC retry.

  • 0 or false - The Transmission Date and Time will not be updated on OPC retry.

This parameter is optional and has a default setting of true.

Parameters: The component can be configured with the optional terminal parameters. Please see the OPC Overview page for more information.

Decline conditions:

Condition Response code Message reason code

The callback for merchant OPC selection was canceled by the merchant.

05 - Do not honor

9631 - Operator cancellation

The callback for merchant OPC selection/confirmation timed out.

05 - Do not honor

9635 - Customer timeout

The card is eligible for OPC selection, but there are no available options.

05 - Do not honor

9717 - Missing OPC data

OPC reselection attempts exceed the configured allowed limit.

57 - Transaction not permitted to cardholder

9794 - OPC retries exceeded

OPC reselection resulted in the removal of all configured OPCs.

57 - Transaction not permitted to cardholder

9795 - No OPC available for reselection

The callback for merchant OPC selection responded with an invalid response.

20 - Invalid Response

9796 - OPC selection failed

The callback for merchant OPC confirmation responded with an invalid response.

20 - Invalid Response

9797 - OPC confirmation failed

5.5.51. Pipeline component - OPC Configuration

Description: This component is responsible for handling the Operation Code (OPC) dynamic configuration update functionality.

OPCs define the payment plan under which a transaction should be processed. Customers using retailer’s cards are extended a benefit by the retailer through a choice of payment plans (OPCs). Some examples of payment plans are:

  1. Pay in full with immediate debit

  2. Pay in full with deferred debit (at the end of the current month)

  3. Pay in 'x' monthly installments

The configuration for these OPCs can be dynamically updated by the OPC provider.
This pipeline component is responsible for initiating an OPC configuration update in the form of an 0800 request message. On a successful 0810 response from the OPC provider, this component will update the existing configuration from the contents of the response message.

An 0800 will be sent online, requesting new configuration on the following events:

  • When eSocket.POS starts up or resyncs.

  • At a specific pre-configured time of day.

    • If no online OPC configuration is present, then at the time of day governed by the DEFAULT_SCHEDULE_TIME parameter.

    • If OPC configuration is present, then at the time of day governed by the schedule data from the successful 0810 response from the OPC provider.

  • When new configuration from the successful 0810 response from the OPC provider indicates a new schedule time.

  • When an OPC 0110/0210 response message is declined. See Pipeline component - OPC Configuration for more details on OPC transaction processing.

Usage: Response pipeline, mandatory when making use of Pipeline Component OPC.

Rank: Can be configured anywhere in the response pipeline.

Class name: postilion.esocketpos.transactionengine.PipelineComponentOpcConfig

Mandatory Parameters: The OPC Config pipeline component has the following mandatory named parameters:

Parameter Values

INSTITUTION_ID_CODE

This parameter contains the Receiving Institution ID Code (field 100), which is populated in the 0800 OPC configuration request messages:

INSTITUTION_ID_CODE=12345678901, the value is numeric and can be up to 11 digits in length.

STARTUP_DELAY

This parameter specifies the period (in seconds) after initialization before the component attempts to request new OPC configuration from the upstream entity. This parameter is configured as STARTUP_DELAY=x, where x is a numerical value in seconds.

Example: STARTUP_DELAY=10

To disable the startup timer set the delay to 9999.

Optional Parameters: The component can be configured with the following parameter:

Tag Values

STARTUP_JITTER

STARTUP_JITTER=x, where x is a numeric value in seconds.

A random value between 0 and the number of seconds configured here is added to the startup delay time to ensure OPC configuration request messages are not sent simultaneously.

Example: STARTUP_JITTER=5

Default: 0 seconds

SCHEDULE_JITTER

SCHEDULE_JITTER=x, where x is a numeric value in seconds.

A random value between 0 and the number of seconds configured here is added to the startup delay time to ensure OPC configuration request messages are not sent simultaneously.

Example: SCHEDULE_JITTER=5

Default: 0 seconds

DEFAULT_SCHEDULE_TIME

This parameter specifies a default schedule time for when the schedule timer should ask for new configuration and is used for when the terminal initializes with no online schedule data.

If this parameter is not configured, and the terminal initializes with no online schedule data, a default value of 10:30 pm will be used. Note that new online schedule data takes precedence over the default time.

A special value of 9999 will disable the schedule timer altogether.

Example: DEFAULT_SCHEDULE_TIME=11:23:30

DEFAULT_SCHEDULE_TIME=x, where x is a time value complying with the following convention:
hh:mm:ss
where hh is the hour, mm is the minute, and ss are the seconds.

Default: 22:30:00

ACQUIRER_NAME

ACQUIRER_NAME=x, where x is an alphanumeric value no more than 15 characters in length.

This parameter specifies the name of the acquirer for which the card acceptor ID code mapping applies.

If this parameter is not configured, the card acceptor ID code that is internally configured is used.

This parameter is only available to be used for Normalized Configuration Data.

More information on Normalized Configuration Data, the card acceptor ID code mapping, and the corresponding acquirer name can be found in the Configuration Server User Guide.

Example: ACQUIRER_NAME=Acquirer or "ACQUIRER_NAME=Big Acquirer"

Decline conditions: None

5.5.52. Pipeline component - P2PE Security

Description: The P2PE Security component is responsible for blocking access to the card reader, when the host has determined that a security breach might have occurred.

Request component

The pipeline component intercepts all 0100/0200 messages and checks whether a block has been placed on the PED, before allowing the messages to proceed. If blocked, the messages are immediately declined.

Sign-on 0800 request messages are not intercepted.

Response component

The pipeline component intercepts all response messages and checks whether the response from upstream indicates that the PED should be blocked. If so, a flag is set, preventing further transactions from the POS until it is unblocked from upstream.

If an 0810 key exchange response message is received, which does not indicate that the PED should be blocked, the pipeline component releases the block and allows transactions to proceed upstream once again.

Usage: Request and Response Pipelines, optional. If required, must be present in both pipelines.

Rank: Must be configured towards the beginning of the request pipeline. Must be configured before the PAN, Account and Amount components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentP2PESecurity

Parameters: The component must be configured with the following parameter:

Parameter Values

1

device name

Specifies the device name for the device driver used.

Limitations
  • This component is only suitable for Merchants who are either prepared to re-initialize the terminal to begin the unblock process or are prepared to wait for the key exchange interval of the RkdManager component for an unblock to take effect.

  • This component is not suitable for a store-server deployment.

5.5.53. Pipeline component - PAN

Description: The PAN component is responsible for the track 2 data and PAN in the message.

Request component

This component behaves as follows in the request pipeline:

  • If neither track 2 data nor PAN is present, the component prompts for a card swipe.

  • If the swipe fails, it prompts for manual PAN entry.

  • If PAN validation is required, the Luhn check is applied.

  • If the PAN cannot be set, or the validation fails, the transaction is declined.

  • If the PAN must be encrypted in the database, it is encrypted by the PAN component, and the result is stored in Structured Data (field 127.22).

  • If Quick Chip processing is enabled, a Structured Data tag 'QuickChip' is added with the value 1.

If point-to-point encryption (P2PE) is configured, then all sensitive data is encrypted by the PED. The result is again stored in Structured Data, while masked versions of this data is placed in their respective fields. The masked PAN is not stored in the database. For non-P2PE messages, the PAN will be considered whitelisted and remain in the clear.

For a linked authorization, transaction, or reversal advice, the PAN component retrieves the values from the original message if they are set. If the PAN is encrypted in the database, the encrypted version is retrieved and stored in Structured Data.

Additionally, the PAN component populates several related fields, including the following:

  • Track 1 data

  • PAN entry mode

  • Expiry date

  • Card sequence number

  • Service restriction code

In some cases, the POS can request a stand-alone card read to access the card reader device, either for an EFT card or for another card, such as a loyalty card or supervisor card. If the PAN or track 2 data has already been set, then the Card Product Name field is populated. Otherwise, the PAN component accesses the card reader and returns a response containing magnetic stripe data, and the card product name. The transaction does not go online to the payments system.

The PAN component reports a successful card read using an event with the event ID CARD_READ. The event also includes a data string that contains the PAN entry mode. The POS can use the PAN entry mode to determine whether card data was obtained by reading a magnetic stripe or a chip.

You can configure a card such that the last four digits of the PAN embossed on the card are checked against the PAN. If the check is configured to be optional, the check can be canceled. If the check is mandatory, cancel is regarded as a failure, and the transaction is declined. This check is never done, if the PanEntryMode field indicates that the PAN was obtained with a card insert.

Note
If the POS condition code is not set, then the PAN component sets this field according to the value of the cardholder present in the POS data code. If the cardholder is not present, the POS condition code is set to customer not present. Otherwise, the following is considered:
  • If the POS data code is also not set, then for 0220/0400/0420 messages, it is populated from the original transaction, if it is present in the database.

  • If the cardholder present in the POS data code is set to 0, or the original transaction is not found for 0220/0400/0420 messages, then it is set to normal presentment.

RFID processing occurs when an RFID tag is used for payment, and the read is successful. In this case, RFID processing replaces normal card processing, and the PAN component does only the following:

  • The RFID data will be placed in Structured Data tag RfidData.

  • Sets the PAN Entry Mode to 00 - Unspecified

  • Sets the PAN to the dummy PAN (19 zeros).

Note
If RFID processing is not enabled, processing continues as if for a normal card.
Response component

The PAN component in the response pipeline is responsible for ensuring that sensitive data (PAN, track 1, track 2, and service restriction code) that is returned to the POS application is masked. Each card product within eSocket.POS can be configured to mask the sensitive data returned to the POS application.

If the last four digits of the PAN embossed on the card are checked against the PAN, the response component also adds a flag to Structured Data in the response message to indicate whether the embossed PAN check passed, failed, or was canceled.

Usage: Mandatory in both the request pipeline and response pipeline.

Rank: Must be configured at, or very near the start of the request pipeline, normally after the Amount pipeline component. Must be configured after the Stand-in pipeline component in the response pipeline.

Class name: postilion.esocketpos.transactionengine.PipelineComponentPan

Parameters: The component can be configured with the following optional parameters:

Parameter Values

1

Fallback to manual PAN entry conditions

Specifies when the component must prompt for the manual entry of the PAN. This parameter is specified as a concatenation of any of the following conditions (as a single parameter, without any spaces):

0 - Card read failure

1 - Customer cancellation

2 - Customer card swipe or insert timeout

3 - Deprecated: Customer cancellation, card swipe or insert timeout - use the combination of 1 and 2

4 - Card read retries exceeded

5 - Device Serial Number Validation failed. Note that this relies on the keypad not being the device that failed serial number validation and that this is only applicable if the device and device driver support serial number retrieval and if eSocket.POS is configured for Serial Number Validation.

For example, use '24' to specify that manual PAN entry must be enabled for 'Customer card swipe or insert timeout' and for 'Card read retries exceeded'.

Configure as a dash (-) to never fallback to manual PAN entry.

2

PAN Encryption

0 - The PAN is not encrypted in the database.
WARNING: Selecting this option results in PCI non-compliance.

1 - The PAN is encrypted in the database. If PAN encryption is used, the Certificate Manager pipeline component must be configured. By setting this parameter, eSocket.POS stores an encrypted token in the database for future advices to use. It does not encrypt the PAN being sent upstream.

2 - Use point-to-point encryption. Sensitive data is encrypted by the PED and stored in this form in the database. The Certificate Manager pipeline component is not required in this mode.

3 - Reserved for use by the eSocket.ITK plug-in.

4 - Use VeriShield encryption. The VeriShield pipeline component is required in this mode.

5 - Use TransArmor non-format-preserving encryption. Currently supported schemes:

  • TransArmor RSA encryption

The default is 1.

The component can be configured with the following named parameters:

Parameter Values

Mask sensitive data by default

This is an optional parameter that specifies if sensitive data must be masked for card products that are not configured in the eSocket.POS database. The parameter is configured as DEFAULT_MASK_SENSITIVE_DATA=x, where x is one of

  • 0 - Do not mask sensitive data (default)

  • 1 - Mask sensitive data

Relax Track 2 validation

This is an optional parameter that specifies if track 2 data must be validated for a correct PAN, expiry date, service restriction code, and country code. The parameter is configured as RELAX_TRACK2_VALIDATION=x, where x is one of the following:

  • 0 - Do not relax track 2 validation (default)

  • 1 - Relax track 2 validation

Use Lookup PAN Entry Mode

This is an optional parameter that can be used to specify whether the PAN Entry Mode (Field 22, positions 1 & 2) should reflect the fact that card details were not physically obtained from the card, but automatically entered by the system. This only applies to advice messages linked to an original transaction. The parameter is configured as USE_LOOKUP_PEM=x, where x is one of

  • 0 - The PAN Entry Mode and PosDataCode are set from the original transaction. (default)

  • 1 - PAN Entry Mode will be set to '82' (auto-entry via server) and Card Data Input Method set to '1' (manual) to indicate that the PAN was populated by the system.

Decline Null P2PE Luhn Check

This is an optional parameter that can be used to specify whether PipelineComponentPan declines the transaction when no Luhn check value is received from the pinpad, whilst in P2PE or VeriShield mode. The parameter is configured as DECLINE_NULL_P2PE_LUHN_CHECK=x, where x is one of

  • 0 - The transaction will not be declined when no Luhn check value is present (default).

  • 1 - The transaction will be declined with a response code of 14 - Invalid Card Number when no Luhn check value is present.

Encrypt Non-P2PE Data

This is an optional parameter that can be used to specify whether PipelineComponentPan encrypts the PAN saved to the database for non-P2PE transactions, whilst in P2PE mode. The parameter is configured as ENCRYPT_NON_P2PE_DATA=x, where x is one of

  • 0 - The PAN is saved to the database in the clear, acting as a whitelisted PAN (default).

  • 1 - The PAN is encrypted when saved to the database. For this to function, the Certificate Manager pipeline component must be configured.

The component can be configured with the following extended parameters:

Parameter Values

WhitelistFileName

When P2PE is in use, a file consisting of white-listed BINs can be supplied to the PED. Such a file must first be digitally signed by the DataSigner tool in PosConnect. This parameter is then set to the symbolic name given to the file so that PosConnect can check that the PED is using the current version of the whitelist.

Decline conditions:

Condition Response Code Message Reason Code

Card could not be read during a card read inquiry

05 - Do not honor

9791 - Administrative response

The PAN on the card chip did not match the PAN in the track 2 equivalent data on the chip

05 - Do not honor

9764 - Inconsistent data on chip

Card number requires Luhn checking, and Luhn check fails

14 - Invalid card number

9753 - Luhn check failed

Card number contains invalid data

14 - Invalid card number

9759 - Card number format invalid

Message did not contain a PAN, and PAN was not entered via a device

30 - Format error

9701 - Missing PAN

Card is not configured in the eSocket.POS database

56 - No card record

9751 - No supported accounts

A reversal was received for which no original transaction was found

25 - Unable to locate record

9720 - Original transaction not found

The embossed digits on the card did not match the PAN

59 - Suspected fraud

9765 - Inconsistent track 2 data

The track 2 data is invalid

30 - Format error

9766 - Invalid track 2 data

Events:

If a card is successfully read, the PAN component reports this using an event with the event ID CARD_READ.

Event Data String

CARD_READ

The data string associated with the event consists of a key-value pair with the value inside single quotes as illustrated in the following example:

PanEntryMode='05'

Values are as specified for the PanEntryMode property in the eSocket.POS Developer Guide.

Note
Referral Advices (0220 messages with message type set as REFERRAL) prompt for the PAN if the PAN of the original message (authorization request or transaction request) could not be found on the same terminal. This is usually the case when the referral advice is processed on a terminal other than the one that processed the original message.

Transaction Processing Results:

The PAN component sets the following Transaction Processing Results (TPR) in the request and response message for byte 1.

Note
In the table below, a dash (-) represents a bit that is not being used and RFU stands for "reserved for future use".
Name Bit Description

CardRead

8

When set, this bit indicates that a card read has been processed.

GetPanFromCardRead

7

When set, this bit indicates that the PAN was obtained from a card read.

GetPanManually

6

When set, this bit indicates that the PAN was obtained manually.

ProcessedMagstripeTransaction

5

When set, this bit indicates that a transaction using the cards magnetic stripe has been processed.

ProcessedManualPanEntry

4

When set, this bit indicates that a transaction using manual PAN entry has been processed.

-

3

RFU

-

2

RFU

-

1

RFU

5.5.54. Pipeline component - Partial Approval

Description: The Partial Approval component is responsible for processing partial approvals from the upstream entity - it will send a prompt message to the Prompts pipeline component, asking the customer to accept or reject the partial approval, and based on the outcome, either continue the transaction, or cancel it and send a reversal upstream. The Prompts pipeline component must be configured for this processing to occur. As such, the functionality provided by this component will only be available on devices and device drivers which support generic prompting.

Response messages are processed as follows:

  • If the message response code is set to '10' (Approved, partial), a prompt message is generated and sent to the Prompts pipeline component. The Prompts component and specific device driver implementation will handle the actual prompting to the cardholder.

  • Depending on the outcome of the prompt, the following occurs:

    • If the cardholder accepts the partial approval, the transaction is approved and further response processing occurs.

    • If the cardholder rejects the partial approval, or a prompt timeout occurs, the transaction is declined, and reversed.

The timeout value of the prompt is determined by the timeout value configured for the Prompts pipeline component. Please see that component’s page for details on how to configure it.

Events:

This pipeline processes following callback events:

Callback Description

Partial Approval

The eSocket.POS sends a callback event with ID 'PARTIAL_APPROVAL'. This callback requests Partial Approval Confirmation from the POS.

POS can respond with following data:

  • TRUE :- Indicates Partial Approval Confirmation is approved by the POS.

  • FALSE:- Indicates Partial Approval Confirmation is declined by the POS.

NOTE:

  • POS must register the callback event with ID: 'PARTIAL_APPROVAL'.

Usage: Response pipeline, optional.

Rank: Must be configured before the EMV component, or any component which performs EMV processing on response messages (such as the LateFallback and LateFallForward components).

Class name: postilion.esocketpos.transactionengine.PipelineComponentPartialApproval

Parameters: The component can be configured with the following optional named parameters.

Parameter Values

APPROVAL_PROMPT

Specifies whether the partial approval confirmation should be requested from the PED or POS.
Possible values are:

  • 0 - PED Prompt.(default)

  • 1 - POS Prompt.

Example: APPROVAL_PROMPT=1

Decline conditions:

Condition Response Code Message Reason Code

The cardholder did not accept the partial approval.

05 - Do not honor

9630 - Customer cancellation

A timeout occurred while waiting for cardholder interaction

05 - Do not honor

9635 - Customer timeout

5.5.55. Pipeline component - Payment Interrupt

Description: eSocket.POS uses the Payment Interrupt pipeline component to interrupt the payment process if the transaction amount must be updated. This is called a payment interrupt. To interrupt the payment process, the card must be eligible for payment interrupts. See the store and lane groups configuration in the eSocket.POS Configuration Server User Guide.

The following message types are supported:

  • Authorization request (0100)

  • Transaction request (0200)

The following transaction types are supported:

  • Goods and Services (00)

Usage: Request pipeline, optional.

Rank: Must be configured after the PAN component, but before the EMV component and the following optional components: Gratuity, Confirm, Stand-in.

Class name: postilion.esocketpos.transactionengine.PipelineComponentPaymentInterrupt

Parameters: The component can be configured with the following optional named parameters.

Parameter Values

IS_PAN_REQUIRED

Specifies whether the payment interrupt callback should contain obfuscated PAN.
Configure the parameter as follows:

  • 0 - Do not send PAN information.(default)

  • 1 - Send the PAN information.

Example: IS_PAN_REQUIRED=1

IS_AMOUNT_REQUIRED

Specifies whether the payment interrupt callback should contain amount. Amount is send in 12-digit, minor denomination.
Configure the parameter as follows:

  • 0 - Do not send the amount in the interrupt.(default)

  • 1 - Send the amount in the interrupt.

Example: IS_AMOUNT_REQUIRED=1

DECLINE_TRAN_IF_NO_RESPONSE

Specifies whether the payment interrupt pipeline should decline the transaction if no response received from POS to the callback, or an invalid amount is received.
Configure the parameter as follows:

  • 0 - Do not decline the transaction. Use the existing amount for further processing.

  • 1 - Decline the transaction with condition mentioned below.(default)

Example: DECLINE_TRAN_IF_NO_RESPONSE=0

The following is an example of a valid parameter list: IS_AMOUNT_REQUIRED=1 IS_PAN_REQUIRED=1

Decline conditions:

Condition Response code Message reason code

The card is eligible for payment interrupt, but the POS returns an unsuccessful result, or the transaction has an invalid amount.

6 - Error

9775 - Payment interrupt failed

5.5.56. Pipeline component - PIN

Description: The PIN component checks if a PIN is required for a transaction. If required, it prompts the customer to enter the PIN via the device’s PIN pad. The PIN is encrypted within the PIN pad, and the encrypted PIN block is returned to eSocket.POS to be sent online for authorization.

For non-EMV transactions, the component prompts for PIN entry based on the card and account parameters, as well as the Service Restriction Code of the card. In the case of a contactless magnetic stripe transaction, however, if the transaction amount is below or equal to the CVM Required Limit account parameter, the component will not prompt for a PIN. The component will re-prompt for a PIN when instructed by the response message, and the response pipeline is configured.

For EMV transactions, the PIN component prompts for PIN entry, based on whether the value in the ICC Data field CVM Results indicates online PIN verification. The PIN component is not involved in PIN entry, where the PIN is verified offline by the ICC.

The PIN component supports both Master-Session PIN Key Management and Derived Unique Key Per Transaction (DUKPT). If DUKPT is used, a Key Sequence Number is also returned by the PIN pad and sent online.

Note
By default, Visa magnetic stripe Rapid Payment Services (RPS) transactions do not require a PIN (this only applies to accounts that have been configured for RPS). The default PIN requirements for RPS transactions can be changed using the RPS_PIN_BYPASS user parameter. See Pipeline Component RPS for an overview of RPS in eSocket.POS.

RFID processing occurs when an RFID tag is used for payment. The PIN component prompts the customer for their PIN. When a PIN is successfully entered, the key serial number (KSN), encrypted data, and the initialization vector are placed in the Structured Data field RfidPin. The PIN component does no other processing.

Usage: Request and Response pipelines, optional. Must not be configured if there is no PIN pad configured.

The Request pipeline becomes mandatory, when the Response pipeline is required.

Rank: Must be configured after the PAN, Account and EMV components, but before the Stand-in component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentPin

Parameters: The component can be configured with the following named parameters:

Parameter Values

RPS_PIN_BYPASS

This parameter specifies the list of RPS programs for which PIN entry can be bypassed. The parameter is specified as RPS_PIN_BYPASS=<programs>, where <programs> are a semicolon-separated list of RPS programs for which PIN entry can be bypassed.

Valid names for the RPS programs are Visa and MasterCard. A value of None can be specified to indicate that PIN entry cannot be bypassed for any RPS transactions.

For example:

  • A parameter value of RPS_PIN_BYPASS=None specifies that PIN entry cannot be bypassed for any RPS transactions.

  • A parameter value of RPS_PIN_BYPASS=Visa;MasterCard specifies that PIN entry can be bypassed for both Visa and MasterCard RPS transactions.

  • A parameter value of RPS_PIN_BYPASS=MasterCard specifies that PIN entry can only be bypassed for MasterCard RPS transactions.

If the parameter is not specified, the default behavior is to allow PIN bypass for Visa RPS transactions, but not for MasterCard RPS transactions.

Note
PIN entry bypass is only applicable for magnetic stripe RPS transactions.

REQUEST_RFID_PIN

This parameter specifies whether the customer is required to input their PIN. REQUEST_RFID_PIN=x, where x is one of the following:

  • 0 - PIN entry is not required to authorize the RFID transaction.

  • 1 - PIN entry is required to authorize the RFID transaction (default).

RFID_MIN_PIN_LEN

This parameter specifies the minimum length of an RFID PIN.
RFID_MIN_PIN_LEN=x, where x is the minimum length.
If the parameter is not set, the default value is 4 digits.

RFID_MAX_PIN_LEN

This parameter specifies the maximum length of an RFID PIN.
RFID_MAX_PIN_LEN=x, where x is the maximum length.
If the parameter is not set, the default value is 5 digits.

Decline conditions:

Condition Response code Message reason code

The transaction requires a PIN, but no PIN was entered.

30 - Format Error

9703 - Missing PIN data

The RFID transaction requires a PIN, but no PIN was entered.

5.5.57. Pipeline component - POS config

Description: The POS config component sets various POS-related properties of the transaction.

The following properties are set, based on values configured for the POS:

  • Terminal ID

  • Card Data Input Capability

  • Cardholder Authentication Capability

  • Card Capture Capability

  • Operating Environment

  • Cardholder Presence

  • Card Present (set based on the value configured for the Cardholder Presence)

  • Card Data Output Capability

  • Terminal Output Capability

  • PIN Capture Capability

  • POS Geographic Data

  • Terminal Operator

  • Terminal Type

Other properties are set to default values, unless a value has already been set by another component. The default values are indicated in brackets:

  • Card Data Input Mode (set according to the PAN Entry Mode)

  • Cardholder Authentication Method (manual)

  • Cardholder Authentication Entity (merchant)

Usage: Request Pipeline, mandatory.

Rank: Must be configured towards the end of the pipeline, after the Stand-in, PIN and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentPosConfig

Parameters: None

Decline conditions: None

5.5.58. Pipeline component - Pre-swipe

Description: Customers use the Pre-swipe component to initiate a transaction by swiping, inserting, or tapping a card before the POS operator has finished scanning the goods, and before the POS sends a transaction to eSocket.POS. Following the card read, the component either injects a 0600 message with the card details into the pipeline or stores the card data as-is in the memory, depending on the send0600Msg data element in the PRE_SWIPE Enable event. When the component injects a 0600 message, the customer can continue with account selection, PIN entry, and cashback entry, depending on the card, and the eSocket.POS pipeline configuration. The eSocket.POS turns the e600 around without going upstream and is stored in the memory.

When the cashier finishes scanning the goods, the POS sends a 0100 or 0200 transaction, including the amount and other details, and eSocket.POS combines this with the card number, account, encrypted PIN, and other details, which were already entered. If the 0100 or 0200 is received while the 0600 pre-swipe process is in progress, the 0100 or 0200 only proceeds after the customer completes the interactions required for the 0600.

The Pre-swipe pipeline component supports EMV reads with Quick Chip processing. See the Quick Chip overview section for details about the Quick Chip EMV Pre-swipe functionality.

Limitations:

  • Pre-swipe is only supported for purchase transactions, not other transaction types such as balance enquiry, deposit, refund and so on.

  • Support for EMV reads during pre-swipe is dependent on the device driver in use. If EMV pre-swipe is not supported by the device driver, or if the device driver has been configured to disable EMV pre-swipe, the Pre-swipe component will only attempt magstripe reads.

  • By default, contactless EMV reads during pre-swipe are downgraded to contactless magstripe, to avoid the need for the cardholder to tap a card twice: once during the pre-swipe phase of a transaction, and another during the transaction request phase after the final transaction amount is known. This behavior is configurable using the DOWNGRADE_CTLS_EMV user parameter.

Usage: Request Pipeline, optional.

Rank: Must be configured before the PAN component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentPreSwipe

Parameters: The component takes the following parameters:

Parameter Values

1

Block transactions

Indicates whether the component must delay 0100 and 0200 transactions while a 0600 pre-swipe process is in progress. This prevents two different transactions trying to interact with the device and the customer simultaneously.

Possible values:

1 - Delay all 0100 or 0200 transactions.

This is the safest option; however, delaying transactions is unnecessary if they do not require device interaction.

0 - Do not delay transactions, unless card or account details are missing. This allows the POS to perform non-interactive transactions, such as deposits, while the pre-swipe is in progress. If this parameter is used, it is important to ensure that these transactions do not disrupt the pre-swipe device interactions.

The following optional named user parameters can also be configured as space-separated name=value pairs:

Parameter Description

DOWNGRADE_CTLS_EMV

Specifies whether contactless EMV card reads must be downgraded to contactless magstripe during pre-swipe.

Since the final transaction amount is not known during the pre-swipe stage of a transaction, two taps will be required for contactless EMV card reads: once during the pre-swipe phase of the transaction, and another during the transaction request phase after the transaction amount is known. The transaction amount is required for EMV cryptogram generation.

To avoid a second tap, this parameter can be set to 1 to force all contactless reads that occurred during the pre-swipe stage to be regarded as contactless magstripe reads.

Values:

  • 1 - Downgrade contactless EMV reads during pre-swipe to contactless magstripe (default).

  • 0 - Do not downgrade contactless EMV reads during pre-swipe. A second tap will be required during the transaction request phase of the transaction.

NOTE: * Contactless EMV requires a device driver that supports EMV reads during pre-swipe. If EMV pre-swipe is not supported by the device driver, or if the device driver has been configured to disable EMV pre-swipe, all contactless reads will be regarded as contactless magstripe, regardless of the value of this parameter. * This value configured in this parameter will be ignored if Quick Chip Contactless is supported.

CANCEL_CALLBACK_TIMEOUT

Specifies the wait time (in seconds) to receive the canceled transaction response, before processing the Cancel Pre-swipe request.

If the parameter is not set, the default value is 30 seconds.

CARD_READ_EVENT_MODE

This parameter allows Pre-swipe to operate in two modes, depending on the value provided.

Possible values:

0 - Mode one: when set to 0, the CARD_READ event message will be sent to the POS before an associated 0600 is sent through the pipeline with the card details.

1 - Mode two: when set to 1, the CARD_READ event message will be sent to the POS after Pre-swipe receives a response to the 0600 that can be sent. Operating in this mode, Pre-swipe can indicate additional information to the terminal about the card details. If the 0600 sent through the pipeline is declined, the POS is informed through the optional presence of 'ResponseCode' and 'MessageReasonCode'. See the CARD_READ event message.

If the parameter is not set, the default value is 0.

CARD_READ_FIELDS

This parameter allows a user to specify a comma-separated list of fields to be sent in the CARD DATA event.

The following fields are supported:

  • PanEntryMode

  • Track2

  • CardProductName

  • Account

  • MessageReasonCode

  • ResponseCode

  • PinEntryStatus

If the parameter is not set, the default value is used, namely:
PanEntryMode,Track2,CardProductName,Account,MessageReasonCode,ResponseCode.

See the CARD DATA event message for additional information on individual fields.

CARD_READ_SD_FIELDS

This parameter allows a user to specify a comma-separated list of structured data fields to be sent in the CARD_READ event. These structured data fields are also saved in memory and copied into the subsequent 0100 or 0200 message sent by the POS. The field name specified in this parameter must match the respective tag in the structured data (Field 127.22) of the ISO 8583 message. Ensure that Payment Card Industry (PCI) Data Security Standard (DSS) compliance rules are maintained, while specifying the structured data fields in this parameter.

Note
Currently, these structured data fields are populated only when send0600Msg data element in the PRE_SWIPE Enable event is set to true.

Example Configuration: 1 DOWNGRADE_CTLS_EMV=1 CANCEL_CALLBACK_TIMEOUT=10 CARD_READ_EVENT_MODE=1
CARD_READ_FIELDS=PanEntryMode,Track2,CardProductName,Account,MessageReasonCode,ResponseCode
CARD_READ_SD_FIELDS=CardToken,CardType,PaymentType,Prepaid Flag

Decline conditions: None

Events:

Event Description

PRE_SWIPE Enable

The POS can use an event with EventId 'PRE_SWIPE' with data of 'Enable' to enable the pre-swipe prompt. This clears previous pre-swiped data and prompts the customer to present their card.

The event data can contain the following data elements separated by semicolons:

  • send0600Msg: <true/false> - Indicates whether a 0600 message has to be sent. Defaults to true.

  • scanAheadMessage: <message> - Custom swipe message displayed in the PED. The default system message will be used, if this is not present.

  • sendCardData: <true/false> - Indicates whether the Track 2 data and card product name should be sent in the CARD DATA event raised by the component, after a card read has occurred. If set to false, only the PAN entry mode will be sent. Defaults to false.
    Track 2 data is either obfuscated or in the clear.

  • tranType: <2-digit ISO8583 transaction type> - Indicates the transaction type for which pre-swipe should be performed. For EMV refund pre-swipes, a value of "20" (Returns) must be specified. If not specified, the transaction type will be assumed to be "00" (Goods and Services).

The following examples show how the data elements can be used in a PRE_SWIPE Enable event:

  • "Enable;send0600Msg:false;tranType=20"

  • "Enable;send0600Msg:false;scanAheadMessage:Please swipe card;sendCardData=true"

PRE_SWIPE Cancel

The POS can cancel pre-swipe using the PRE_SWIPE event with the data 'Cancel'.

The event data can contain the following optional data element:

  • displayWelcome: <true/false> - flag to indicate whether a welcome message must be displayed after canceling the prompt. Defaults to true.

Note
If the Cancel event is received from the POS after a card has already been presented (that is, after the POS has received the CARD DATA event), it does not cancel the subsequent pre-swipe steps, such as account selection. The pipeline must run to completion, either normally or through customer cancellation or timeout. However, after the pipeline has completed, the Cancel event means that the pre-swipe values collected are not used.

PRE_SWIPE Stop_Listen

The POS can use the PRE_SWIPE event with the data 'Stop_Listen' to stop the pipeline component listening for a card read.

The event data can contain the following optional data element:

  • displayWelcome : <true/false> - flag to indicate if a welcome message must be displayed after canceling the prompt. Defaults to true.

Note
If the Stop_Listen event is received from the POS after a card has already been read (that is, after the POS has received the CARD DATA event), the card details are used in the subsequent pre-swipe steps.

PRE_SWIPE_CANCELLED

Informs the POS when pre-swipe was enabled but must be disabled due to eSocket.POS processing or external cancellation.

The event data contains an integer value indicating the reason for canceling pre-swipe:

  • Generic error (0)

  • Processing suspended due to a device update, resync, or key exchange (1)

  • Pre-swipe canceled by customer (2)

  • Pre-swipe canceled by operator (3)

PRE_SWIPE_ERROR

The Pre-swipe component reports any errors that occur when attempting to enable pre-swipe.

The event data contains an integer value indicating the error encountered:

  • Generic error (0)

  • Device busy (1)

CARD_READ

The Pre-swipe component reports a successful card read with a CARD_READ event with the ID 'CARD_READ'.

The event data consists of key-value pairs separated by semicolon characters, where the value for each pair is enclosed in single quotation marks. The following information can be present in the event data:

  • The PAN entry mode (always sent).

  • The obfuscated Track 2 data (only sent if the sendCardData element was set to true in the PRE_SWIPE Enable event). For non-P2PE transactions and whitelisted cards, clear Track 2 data will be returned, if the "Mask Sensitive Data" option is cleared for the card profile configuration in ConfigServer.

  • The card product name (only sent if the sendCardData element was set to true in the PRE_SWIPE Enable event).

  • The account type (only sent if the optional parameter CARD_READ_EVENT_MODE is set to 1).

  • The message reason code (only sent if the optional parameter CARD_READ_EVENT_MODE is set to 1, and the 0600 response message is a decline).

  • The message response code (only sent if the optional parameter CARD_READ_EVENT_MODE is set to 1, and the 0600 response message is a decline).

  • The PIN entry status (only sent if the optional parameter CARD_READ_EVENT_MODE is set to 1 and quick chip is enabled). The following is the list of the statuses returned:

    • PinEntered: This status is returned when the PIN is entered.

    • PinNotRequired: This status is returned when the PIN is not prompted.

    • PinBypass: This status is returned when the PIN prompt is bypassed by the customer.

      Note
      The PinEntryStatus key-pair is not supported for contactless EMV transactions, as PIN entry statistics are not available for these transactions when Pre-swipe is enabled. See the DOWNGRADE_CTLS_EMV parameter for more details.
      An optional user parameter, CARD_READ_FIELDS, can be used to explicitly configure the list of fields to be sent in the CARD_READ event data. The inclusion of these fields still depends on the respective conditions described previously, even if the CARD_READ_FIELDS parameter is set. If the parameter is not set, the PanEntryMode, Track2, CardProductName, Account, MessageReasonCode, and ResponseCode fields are sent by default.

Examples:

  • PanEntryMode='90'

  • PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard'

  • PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard';Account='10'

  • PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard';ResponseCode='05';MessageReasonCode='9631'

  • PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard';Account='10';ResponseCode='05';MessageReasonCode='9631'

  • PanEntryMode='05';Track2='12345600000008765';CardProductName='MyCard';PinEntryStatus='PinNotRequired'

5.5.59. Pipeline component - Prepaid card

Description: The Prepaid Card component is responsible for handling prepaid card (gift card) transactions. It specifically processes gift card reversals by ensuring that the transaction type and extended transaction type of the reversal is the same as in the original linked transaction.

Usage: Optional, request pipeline. It needs to be configured to process gift card transactions.

Rank: Before the PAN component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentPrepaidCard

Parameters: None

Decline conditions: None

5.5.60. Pipeline component - Prepay

Description: The Prepay component is responsible for handling prepaid merchandise transactions. Merchandise products are configured in eSocket.POS per POS product ID (see table esp_merchandise_config).

This component is also responsible for mapping the POS product ID to the product ID and network ID, as required by the prepay network.

Depending on the configuration for a POS product ID, the component is capable of performing the following tasks:

  • Prompt the user and obtain a User ID (for example, a mobile phone number)

  • Prompt the user to confirm a User ID

  • Prompt the user and obtain the Track 2 value from merchandise card

Usage: Optional, request and response pipelines. If this component is used, it needs to be present in both pipelines.

Rank: Any

Class name: postilion.esocketpos.transactionengine.PipelineComponentPrepay

Parameters: None

Decline conditions:

Condition Response Code Message Reason Code

Customer cancels the transaction on the device

17 - Customer cancellation

9630 - Customer cancellation

Original transaction for a reversal or completion could not be found

25 - Unable to locate record

9708 - Missing merchandise data

Invalid or missing prepaid merchandise data in message

30 - Format Error

9708 - Missing merchandise data

5.5.61. Pipeline component - Prompts

Description: The Prompts component provides generic prompting functionality. The component processes prompt-XML data (sent from the downstream entity) within the Prompts or DisplayData subfields of Structured Data (field 127.22). The component only processes 0600 messages with an Extended Transaction Type (field 127.33) of 2122 (Display Request) or 2121 (Generic Prompt) or 2120 (Credit Application Prompt). The Prompt requests are retrieved from the XML within Structured Data and are sent to the Device Manager for processing. The Prompt requests are sent to the Device Manager one request at a time, as defined by the order of the prompt-XML data. The Prompt responses received from the Device Manager are placed in Structured Data in XML format.

Usage: Request Pipeline, optional.

Rank: The component should be configured before any other components that rely on the results of the prompts.

Class name: postilion.esocketpos.transactionengine.PipelineComponentPrompts

Parameters: The component can be configured with the following parameter:

Parameter Values

1

prompt timeout

The number of seconds to wait for user interaction, before a timeout event occurs.

A timeout event results in the transaction being declined.

This parameter is optional (the default value is 60).

The Prompts component can also be configured with the following named parameter:

Parameter Values

SEND_UPSTREAM

A comma-separated list of Extended Transaction Types (field 127.33) to be sent upstream.

Example: SEND_UPSTREAM=2120;2121;

This parameter is optional and has a default setting of 2120 (Credit Application Prompts).

The following is an example parameter string with all parameters configured: 60 SEND_UPSTREAM=2120;2121;

Decline conditions:

Condition Response code Message reason code

A timeout occurred

05 - Do Not Honor

9635 - Customer Timeout

The customer cancels the transaction on the device

17 - Customer Cancellation

9630 - Customer Cancellation

Device failure occurred

05 - Do Not Honor

9641 - Device Failure

Note
To use this functionality, the device driver must support generic prompt requests sent from the eSocket.POS Device Manager.

To send a generic prompt request, place the XML into Structured Data in the Prompts subfield, according to the XML structure specified in the table below. Retrieve the prompt answer from Structured Data, after the prompt has taken place.

The following table describes the Prompts XML structure:

Key value = "Prompts" , Top level element = "Prompts"

Field

Type

Condition

Format

Description

Prompts

The top-level element of the Prompts XML document, which can contain one or more Prompt elements.

Prompt

Element

Zero or more

A list of prompts that are displayed to the user. The prompts are displayed in the order in which they are received in the XML.

Id

Attribute

Optional

ans..

A unique number assigned to this prompt. This value need only be unique per Prompt element.

Name

Attribute

Mandatory

ans..

The name of the prompt. This must always be present in all Prompt requests and Prompt responses.

DataType

Attribute

Optional

a1

The type of data that will be entered for the prompt.

Valid values are:

  • A (Alphanumeric)

  • N (Numeric)

  • B (Boolean)

  • C (Continue)

  • M (Money)

  • K (Acknowledge)

  • O (Option)

  • S (Signature)

MinLength

Attribute

Optional

n..

The minimum length of the prompt value to be entered.

MaxLength

Attribute

Optional

n..

The maximum length of the prompt value to be entered.

InputType

Attribute

Optional

a1

The visibility of the data entered. This field provides backwards compatibility for legacy applications.

Valid values are:

  • C (Clear) - The data entered is displayed as unmasked on the POS.

  • M (Masked) - The data is entered unencrypted, but is displayed as masked on the POS.

  • D (Do Not Print) - The data is displayed in the clear on the POS, but not printed on the receipt.

  • H (Hidden) - The prompt is not displayed on the POS or printed on the receipt. Used for prompts with auto-populated answers.

Timeout

Attribute

Optional

n..

The length of time (in milliseconds) that the device should wait for the user to enter an answer, before aborting the prompt.

AcceptText

Attribute

Optional

ans..

The actual text displayed on the Accept Button on the device.

Note
Limited device driver support.

DeclineText

Attribute

Optional

ans..

The actual text displayed on the Decline Button on the device.

Note
Limited device driver support.

Source

Attribute

Optional

a1

The source of the prompt, that is, where the prompt is displayed. This field provides backwards compatibility for legacy applications.

Valid values are:

  • T (Terminal) - The prompt is displayed as an edit box on the POS.

  • K (Keypad) - The prompt is displayed as a numerical keypad on the POS.

  • L (List) - The prompt is displayed as a list of options (in other words, a selection panel) on the POS.

DisplayText

Attribute

Optional

ans..

This field provides backwards compatibility for legacy applications.

Image

Attribute

Optional

ans..

This field provides backwards compatibility for legacy applications.

Value

Attribute

Optional

ans..

The answer to the prompt. This field is required in the prompt response.

SignatureFormat

Attribute

Optional

ans..

The format of the signature. This field is required in the signature prompt response.

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

Additionally, the Prompts pipeline components processes Display Request from the downstream entity. Below, the structure of the Display Request xml. Consult the appropriate device driver user guide for limitations around which of the following Display Request features is supported.

Field Type Condition Format Description

Display

Top level element of the Display XML message, which can contain one DisplayData element and zero or more DisplayResult elements.

DisplayData

Element

One

List of Display messages and parameters associated with a Display message. These must be sent to the device in the order received.

ResponseRequired

Attribute

Optional

a

Indicates whether eSocket.POS requires a response to the display message.

DisplayTime

Attribute

Optional

n..

Time period (in seconds) that the message must be displayed for.

Device

Attribute

Mandatory

an

Device on which the message must be displayed:

* POS * PED

DisplayType

Attribute

Optional

a

Type of information to be displayed.

BacklightEnabled

Attribute

Optional

a

Indicates whether the backlight on the device should be switch on or not.

DisplayContent

Element

Optional

Content to be displayed.

Format

Attribute

Optional

a

Format of the output:

* MessageReference * Text * Barcode * XHTML

OutputText

Element

Zero or more

Text object to display - must be present if the Format field is equal to "Text".

Text

Attribute

Optional

ans

Actual text to display.

Font

Attribute

Optional

an

Font of the text to display.

StartRow

Attribute

Optional

n

Row from which to start the text display - vertical alignment.

StartColumn

Attribute

Optional

n

Column from which to start the text display - horizontal alignment.

Color

Attribute

Optional

a

Color of the text to display:

* White * Black * Red * Green * Blue * Yellow * Magenta * Cyan

CharStyle

Attribute

Optional

a

Style of the characters to display:

* Normal * Bold * Italic * Underline

NewLineFlag

Attribute

Optional

a

Indicates whether a carriage return must be displayed.

Alignment

Attribute

Optional

a

Positional alignment of the characters to display:

* Left * Right * Centred * Justified

OutputXHTML

Attribute

Optional

ans

Base64 representation of XHTML data to display - must be present if the Format field is equal to "XHTML".

CustomDisplayData

Element

Zero or more

Custom parameters associated with a DisplayData object - the order of this list must match the list of DisplayData objects.

DisplayContent

Element

Optional

Custom content object.

PredefinedContent

Element

Zero or One

a

Predefined display content - must be present if the Format field is equal to "MessageReference".

ReferenceID

Attribute

Optional

an

Referenced to the predefined content.

Language

Attribute

Optional

a

Language of the predefined content.

OutputText

Element

Zero or more

Custom Output text object - must match the order of the DisplayContent.OutputText structure.

CharSet

Attribute

Optional

an

IANA character encoding of the text to display.

CharWidth

Attribute

Optional

a

Width of the characters to display:

* SingleWidth * DoubleWidth

CharHeight

Attribute

Optional

a

Height of the characters to display:

* SingleHeight * DoubleHeight * HalfHeight

OutputBarcode

Element

Optional

Must be present if the Format field is equal to "Barcode".

Type

Attribute

Optional

an

Type of barcode encoding:

* EAN13 * EAN8 * UPCA * Code25 * Code128 * PDF417

Value

Attribute

Optional

an

Barcode value to display.

OutputSignature

Attribute

Optional

ans

Signature associated with the text - in base64 format.

DisplayResult

Element

Zero or more

Lists the display results, matching them to the DisplayData items, and in the same order.

Result

Attribute

Optional

a

Indicates the result of the transaction:

* Success * Failure

ErrorCondition

Attribute

Optional

an

Error condition, if the Result field is equal to "Failure".

AdditionalResponse

Attribute

Optional

an

Additional information associated with the response.

5.5.62. Pipeline component - Receipt Printer

Description: The Receipt Printer component is responsible for formatting, validating, and printing receipts. Receipts are defined using either the eSocket.POS Structured Receipt Scripting Language (SRSL), the HTML template file, or a template defined on the PIN Entry Device (PED).

This page contains the following sections:

Operation

The Receipt Printer component prints receipts in response to messages. Receipts can be printed in response to both request and response messages, with the exact behavior defined by the component’s configuration.

Receipts printed using SRSL are defined in a text file containing SRSL declarations. This receipt definition must contain all the possible elements that can be printed on a receipt. Receipts printed using HTML uses the HTML template file present on the PED.

Request component

This component provides the following functionality in the request pipeline:

  • Reprinting a previously printed receipt

  • Requesting batch totals

Reprinting a previously-printed receipt

To reprint a receipt, send a Receipt Reprint Administration Request message to this component in the request pipeline. A Receipt Reprint Administration Request is a 0600 message with an Extended Transaction Type (field 127.33) value of 2130 (Receipt Reprint).

On receiving a Receipt Reprint Administration Request, the Receipt Printer component does the following:

  • Retrieves the original transaction from the eSocket.POS database.

  • Prints the receipt(s) for the original transaction.

  • Approves the Receipt Reprint Administration Request, if the reprint was successful.

  • Declines the Receipt Reprint Administration Request, if the reprint was not successful.

The Receipt Printer component uses the value of the ReprintTranLinkNr field of Structured Data (field 127.22) in the Receipt Reprint Administration Request to retrieve the original transaction. For example, if eSocket.POS is configured to link on Retrieval Reference Number (field 037), the Receipt Reprint Administration Request must have field 127.22.ReprintTranLinkNr set to the same Retrieval Reference Number value as the transaction for which a reprint is being requested.

Note
Receipts are not stored in the database. The Receipt Printer component must recreate the receipt(s) required for a reprint from the transaction in the eSocket.POS database. This means that the component only has the database information available to it. If the transaction contained sensitive data, or data that was purposely not persisted, this information does not appear in reprinted receipts. Similarly, if the original transaction has been deleted from the eSocket.POS database, the receipt will not reprint.
Requesting batch totals

The Receipt Printer component can be configured to print receipts for Acquirer Reconciliation Response (0510) messages. This allows for a merchant batch totals receipt. In some environments, there is no 0500/0510 message flow to request batch totals from the upstream system. In this scenario, the Receipt Printer component can be configured to inject an Acquirer Reconciliation Request (0500) message to request batch totals. This behavior is initiated when the Receipt Printer component receives an Acquirer Reconciliation Advice (0520) message in the request pipeline.

If the tx option has been configured, the message flow is as follows:

  • The Receipt Printer component (in the request pipeline) receives an Acquirer Reconciliation Advice (0520) message.

  • The Receipt Printer component sends an Acquirer Reconciliation Request (0500) message upstream to request batch totals.

  • After receiving the Acquirer Reconciliation Response (0510) message, the component sends the Acquirer Reconciliation Advice (0520) message upstream to be processed, as normal.

Note
The Receipt Printer component in the request pipeline does not print the batch totals receipt. This is the responsibility of the component in the response pipeline. The component in the request pipeline is solely responsible for injecting an Acquirer Reconciliation Request (0500) message to the upstream system, before the Acquirer Reconciliation Advice (0520) message is sent upstream.
Response component

In the response pipeline, this component is responsible for printing receipts according to the component’s configuration, as well as a number of customized parameters.

Configuration

Usage: Request and response pipelines, optional

  • To use receipt types that are printed in response to request messages, the Receipt Printer component must be configured in the request pipeline.

    Similarly, to print receipt types from response messages, the component must be configured in the response pipeline.

  • To use the requesting batch totals functionality, the Receipt Printer component must be configured in both pipelines.

  • To use the receipt reprint functionality, the Receipt Printer component must be configured in the request pipeline and must have the same supported receipt types configured as the component in the response pipeline.

Rank: Must be configured after the Signature component in the response pipeline.

Class name: postilion.esocketpos.transactionengine.PipelineComponentReceiptPrinter

Parameters: The following component parameters are mandatory.

Parameter Values

1

supported receipt types

A comma-separated list of receipt types that must be printed by this component. Valid values are:

c - Customer receipt

m - Merchant receipt

rc - Customer reversal receipt

rm - Merchant reversal receipt

t - Merchant batch totals receipt

tx - Merchant batch totals receipt (with injected batch totals request)

Note
The tx option is intended for card acceptors that do not have a 0500/0510 flow before the batch close (0520/0530) message. With the tx option enabled in the request pipeline, the component intercepts a 0520 and sends a 0500 upstream to request batch totals. See Requesting batch totals.

The tx option only changes the behavior of the component in the request pipeline. In the response pipeline, the tx option is equivalent to the t option.

The following named parameters are optional:

Parameter Values

PAUSE_TIME

This parameter indicates the waiting time between printing consecutive receipts. This pause allows the operator to tear off a receipt, before the next receipt is printed. It is specified as follows:

PAUSE_TIME=<milliseconds>, where <milliseconds> are the number of milliseconds to pause between receipts.

If not specified, the pause time defaults to 5000 milliseconds (5 seconds).

PRINT_DECLINED_AMOUNTS

This parameter indicates whether the original requested amount should be printed for declined transactions. It is specified as:

PRINT_DECLINED_AMOUNTS=<condition>, where <condition> is 1 or true, if the original requested amounts should be printed for declined transactions (enabled), otherwise 0 or false (disabled).

If not specified, this parameter will be disabled by default.

PAN_MASKING_SCHEME

This parameter specifies the Primary Account Number (PAN) masking scheme to use when the PAN SRSL object is referenced in a receipt definition. It is specified as:

PAN_MASKING_SCHEME=<masking_scheme>, where <masking_scheme> is one of the following:

1 - (Default) Mask everything except the first 6 and last 4 digits by default (standard obfuscation) OR apply the masking scheme specified in the P2PE whitelist for the BIN range (for example, the first 8 and last 2 digits in the clear).

2 - Mask everything except the last 4 digits.

If this parameter is not specified, 1 is used as the default.

PRINT_STRATEGY

This parameter specifies the format of receipt definition to use when printing receipts. It is specified as:

PRINT_STRATEGY=<print_strategy>, where <print_strategy> is one of the following:

srsl - (Default) Uses the SRSL receipt definition to print receipts.

html - Uses the HTML template file to print receipts.

ped - Uses a template defined on the PED to print receipts.

If this parameter is not specified, srsl is used as the default.

The customized parameters that follow are supported when PRINT_STRATEGY is either set to srsl or is not set. These parameters are defined at the terminal category level in ConfigServer. See the eSocket.POS Configuration Server User Guide for more information.

Tag Mandatory Name Format Value

ReceiptProfile

Yes

Any descriptive name, for example: The SRSL receipt definition

ans..9999

The SRSL definition to be used when printing receipts. This parameter is required for the Receipt Printer component to function.

If this parameter is not set, the component logs a warning and does not perform any functions on messages.

ReceiptMessages

Can be optionally appended with locale information of the form: _language or _language_country where:

language is a valid ISO 639 2-character and language code country is a valid ISO 3166 2-character country code

Valid examples:

ReceiptMessages
ReceiptMessages_en
ReceiptMessages_en_US

No

Any descriptive name, for example: The messages bundle for locale en_US

ans..9999

This tag is used to specify a resource bundle family for looking up values defined in a SRSL receipt definition.

If the tag is specified as ReceiptMessages, with no locale specified, it is treated as the default messages bundle.

If the tag is specified as ReceiptMessages_language_country (for example: en_US), the value is used as the preferred messages bundle for SRSL lookups performed with the specified locale. See Resource bundles for more information.

The value of this tag is the contents of a valid Java properties file.

The contents of this value can consist of the following two types of mappings:

  • Standard resource bundle message mappings, for example: welcome=Welcome to the store. These mappings are used by the SRSL lookup command.

  • SRSL name mappings (identified by an @ symbol), for example: @header=Luxury Resorts. All occurrences of the SRSL name in the SRSL definition are replaced by the specified value.

CurrencySymbols

Can be optionally appended with locale information of the form:
_language
or
_language_country
where:

language is a valid ISO 639 2-character and language code country is a valid ISO 3166 2-character country code

Valid examples:

CurrencySymbols
CurrencySymbols_en
CurrencySymbols_en_ZA

No

Any descriptive name, for example: The messages bundle for locale en_US

ans..9999

This tag is used to specify a resource bundle family for looking up currency symbols when printing amount fields in a SRSL receipt definition.

If the tag is specified as CurrencySymbols, with no locale specified, it is treated as the default messages bundle.

If the tag is specified as CurrencySymbols_language_country (for example: en_US), the value is used as the preferred messages bundle for currency symbols. See Resource bundles for more information.

This parameter is only required if the default currency symbol support in eSocket.POS needs to be overridden.

The value of this tag is the contents of a valid Java properties file.

The contents of this value are one or more key=value mappings, where:

  • Each key is a valid 3-digit currency code, as per ISO 4217.

  • Each value is a currency symbol. Values can be specified using 4-character Unicode designations (in hexadecimal) of the form \uxxxx.

Examples:
840=$
840=\u0024
191=\u006b\u006e

The following customized parameters are supported when PRINT_STRATEGY is set to ped. These parameters are defined at a terminal category level in ConfigServer. See the eSocket.POS Configuration Server User Guide for more information.

Tag Mandatory Name Format Value

PrintTags

Yes

Any descriptive name, for example: Tags to print on device

ans..9999

Semicolon separated list of tags to be used when printing receipts.

Example: pan;location;time;amount
This parameter is required for the Receipt Printer component to function.

Please refer to Value String for a list of supported tags.

If this parameter is not set, the component logs a warning and does not perform any functions on messages.

FormName

Yes

Any descriptive name, for example: Custom template or form defined on the PED

ans..9999

Relative name of the template or form loaded on the PED, to be used for printing receipts.
Example: ReceiptScreen
This parameter is required for the Receipt Printer component to function.

If this parameter is not set, the component logs a warning and does not perform any functions on messages.

ReceiptMessages

Valid examples:

ReceiptMessages

No

Any descriptive name

ans..9999

This tag is used to specify a resource bundle family for populating values that are used in the form or template on the PED.

The value of this tag is the contents of a valid Java properties file.

The contents of this value can consist of the following type of mappings:

  • Standard resource bundle message mappings, for example: welcome=Welcome to the store.

  • Resource bundle key-value mappings, where if the key is given a specific value, it is updated to a more readable version from the resource bundle. The format of this is the <value string>_<expected value>=<readable value> For example: is_approved_1=Approved

  • The format of the date/time value used for the value string "time" can be changed from its default value of "yyyy-MM-dd HH:mm:ss" by setting time_format=<date/time format>. For example: date_format=dd/MM/YY HH:mm:ss. Please refer to Date/time formatting for more information.

CurrencySymbols

Valid examples:

CurrencySymbols

No

Any descriptive name

ans..9999

This tag is used to specify a resource bundle family for looking up currency symbols when printing amount fields on the receipt on the PED.

The value of this tag is the contents of a valid Java properties file.

The contents of this value are one or more key=value mappings, where:

  • Each key is a valid 3-digit currency code, as per ISO 4217.

  • Each value is a currency symbol. Values may be specified using 4-character Unicode designations (in hexadecimal) of the form \uxxxx.

Examples:
840=$
840=\u0024
191=\u006b\u006e

The following customized parameters are supported when PRINT_STRATEGY is set to html. These parameters are defined at a terminal category level in ConfigServer. See the eSocket.POS Configuration Server User Guide for more information.

Tag Mandatory Name Format Value

HtmlPrintTags

Yes

Any descriptive name, for example: Html Tags to print on device

ans..9999

Semicolon separated list of tags to be used when printing receipts.

Example: pan;location;time;amount
This parameter is required for the Receipt Printer component to function.

Please refer to Value String for a list of supported tags.

If this parameter is not set, the component logs a warning and does not perform any functions on messages.

HtmlFileName

Yes

Any descriptive name, for example: Html custom template definition

ans..9999

Relative name of the HTML template file loaded on the PED, to be used for printing receipts.
Example: mapp/custom.html
This parameter is required for the Receipt Printer component to function.

If this parameter is not set, the component logs a warning and does not perform any functions on messages.

ReceiptMessages

Valid examples:

ReceiptMessages

No

Any descriptive name

ans..9999

This tag is used to specify a resource bundle family for populating values that are used in HTML receipt templates.

The value of this tag is the contents of a valid Java properties file.

The contents of this value can consist of the following type of mappings:

  • Standard resource bundle message mappings, for example: welcome=Welcome to the store. These mappings are used by HTML receipt template.

CurrencySymbols

Valid examples:

CurrencySymbols

No

Any descriptive name

ans..9999

This tag is used to specify a resource bundle family for looking up currency symbols when printing amount fields in an HTML receipt definition.

The value of this tag is the contents of a valid Java properties file.

The contents of this value are one or more key=value mappings, where:

  • Each key is a valid 3-digit currency code, as per ISO 4217.

  • Each value is a currency symbol. Values can be specified using 4-character Unicode designations (in hexadecimal) of the form \uxxxx.

Examples:
840=$
840=\u0024
191=\u006b\u006e

Internal tags for HTML/PED receipts:

HTML receipts can use the internal tags that follow, based on receipt printing requirements.

Tags Description

cust_copy_flag

This tag exists with value as true, if type of receipt getting printed is a Customer receipt (receipt type= c)

merch_copy_flag

This tag exists with value as true, if type of receipt getting printed is a Merchant receipt (receipt type= m)

cust_rev_copy_flag

This tag exists with value as true, if type of receipt getting printed is a Customer reversal receipt (receipt type= rc)

merch_rev_copy_flag

This tag exists with value as true, if type of receipt getting printed is a Merchant reversal receipt (receipt type= rm)

merch_batch_total_flag

This tag exists with value as true, if type of receipt getting printed is a Merchant batch totals receipt (receipt type= t/tx)

currency_symbol

This tag exists only if customized parameter HtmlPrintTags/PrintTags has configured the tag currency_code.
The value for the tag currency_symbol is the symbol for the currency_code of the transaction.

Note
These internal tags need not be configured in the customized parameter HtmlPrintTags/PrintTags, as they are populated internally.
Resource bundles

The resource bundles used by this component use Java’s built-in support for resource bundle families. This allows for lookups based on locale.

For example, given the following resource bundle configuration in the customized parameters:

Tag Value

ReceiptMessages

welcome=Welcome
goodbye=Goodbye
sign=Please sign on the line

ReceiptMessages_en

welcome=Welcome to the store
goodbye=Take care

ReceiptMessages_en_US

welcome=Greetings
goodbye=Thank you for stopping by

ReceiptMessages_es

welcome=Bienvenido
goodbye=Hasta luego

The following behavior is exhibited when using the SRSL locale and lookup functions:

SRSL Result

locale("en_US")
lookup("welcome")

Greetings

locale("en")
lookup("goodbye")

Take care

locale("")
lookup("goodbye")

Goodbye

` locale("en")`
lookup("sign") locale("es")
lookup("sign")

Please sign on the line

Por favor, firme en la linea

In this scenario, only the default messages file has a mapping for "sign". This means that the default message is displayed, regardless of the specified locale.

Note
All resource bundles must be specified in the format of a Java properties file.
SRSL printers

SRSL makes use of conceptual printer names to selectively print only the sections of a receipt definition that apply to the current transaction. See SRSL Printers for more information.

When Receipt Printer processes a message, it uses the message characteristics, and the component’s configuration to select one or more SRSL printer names to create the receipt.

Receipt Printer supports the following printer names in SRSL receipt definitions:

Printer name Description

all

Matches any printer name. Therefore, the SRSL statements that follow printer(all), apply to all receipts.

Customer receipt printers

cust_approved

A customer receipt for an approved transaction.

cust_declined

A customer receipt for a declined transaction.

cust_reprint_approved

A reprint of a customer receipt for an approved transaction.

cust_reprint_declined

A reprint of a customer receipt for a declined transaction.

Merchant receipt printers

merch_approved

A merchant receipt for an approved transaction.

merch_declined

A merchant receipt for a declined transaction.

merch_reprint_approved

A reprint of a merchant receipt for an approved transaction.

merch_reprint_declined

A reprint of a merchant receipt for a declined transaction.

Merchant totals printers

merch_totals_approved

A batch totals receipt for an approved batch totals response.

merch_totals_declined

A batch totals receipt for a declined batch totals response.

Signature printers

signature

Used for any receipt that requires a signature line printed on the receipt.

Transaction Processing Results:

The Receipt Printer component sets the following Transaction Processing Results (TPR) in the request and response message for byte 1.

Name Bit Description

RequestPrint

8

When set, this bit indicates that a receipt print was requested.

RequestReprint

7

When set, this bit indicates that a receipt re-print was requested.

RequestRecon

6

When set, this bit indicates that a receipt print was requested from a reconciliation request

ResponsePrint

5

When set, this bit indicates that a receipt print was initiated from the response message.

CustomerReceipt

4

When set, this bit indicates that a customer receipt was printed.

MerchantReceipt

3

When set, this bit indicates that a merchant receipt was printed.

MerchantTotalsReceipt

2

When set, this bit indicates that a merchant totals receipt was printed.

NoEspConfiguredPrinter

1

When set, this bit indicates that no printer was configured, so the receipt is placed into the message instead.

5.5.63. Pipeline component - RKD Manager

Description: The Remote Key Distribution (RKD) Manager component is responsible for key exchanges between PEDs and PosConnect as a part of point-to-point encryption (P2PE). Since not all P2PE devices will require RKD, this component should only be configured when such devices are in use. When in use, the component will initiate a key exchange a configurable amount of time after eSocket.POS starts up.

Note
An RKD request from the POS does not imply that a key exchange will actually occur; it is at the discretion of the host to decide whether a key exchange should actually take place.

Usage: Mandatory in both the request pipeline and response pipeline, when RKD is required.

Rank: Should be configured at the start of the request pipeline. Should be configured before the Display Welcome component but after all other components in the response pipeline.

Class name: postilion.esocketpos.transactionengine.PipelineComponentRkdManager

Parameters: The component must be configured with the following parameter:

Parameter Values

1

Device Name

This parameter contains the names of all the connected devices that require RKD. Please refer to the device driver user guides for the respective Device names. It is mandatory to specify at least one or more device names or eSocket.POS will fail to start.

The following is an example of a valid Device Name list: Ingenico_RBA Verifone_FORMAGENT SC5000 VX810

In addition, the component can be configured with the following optional named parameters:

Parameter Values

Start-up delay

This parameter specifies the period (in seconds) after initialization, before RKD is attempted for the first time. This parameter is configured as START_UP_DELAY=x, where x is a numerical value in seconds. The default value is 5.

Retry period upon error

This parameter specifies the period (in seconds) between RKD attempts when an error occurs on the PED, eSocket.POS is disconnected from PosConnect, or a request to PosConnect times out. This parameter is configured as ERR_RETRY_PERIOD=x, where x is a numerical value in seconds. The default value is 15.

Number of retries

This parameter specifies the number of times this component should re-attempt an RKD key exchange. This parameter is configured as ERR_RETRY_NR=x, where x is a numerical value. A special value of 0 indicates an infinite number of retries, and this is also the default value.

Key exchange interval

This parameter specifies the time interval (in hours) between RKD requests to the host. This parameter is configured as KEY_EXCHANGE_INTERVAL=x, where x is a numerical value. A special value of 0 indicates that an RKD request will only be initiated at start-up, and not thereafter. The default value is 8 (hours).

Host status timer interval

This parameter specifies the time interval (in minutes) between the instants when the host status is inspected by the RKD pipeline component (a host status field from PosConnect can indicate that a P2PE key has been compromised and that an RKD needs to be started by eSocket.POS). This parameter is configured as HOST_STATUS_TIMER_INTERVAL=x, where x is a numerical value. A special value of 0 indicates that this functionality is disabled, and the default value is 5 (minutes). Values less than 5 minutes can result in performance problems. Contact your support provider for more information on this parameter.

Retailer ID

This parameter specifies the mandatory retailer ID, if RKD of tokenization keys is required. See the ConfigServer user guide for more details about the retailer ID. This parameter is configured as RETAILER_ID=x, where x is an alpha-numeric value.

RKD of tokenization keys start-up delay

This parameter represents a delay (in seconds) from the delay specified in START_UP_DELAY, before RKD of tokenization keys is attempted for the first time. This parameter is configured as TOKEN_RKD_DELAY_OFFSET=x, where x is a numerical value in seconds. The default offset value is 30 (seconds).

Active-active and active-backup compatibility

This parameter indicates whether this pipeline component will function with multiple device groups (an active-active or active-backup environment). With this disabled, RKD will only function for the first device in a group (device at rank 0). This parameter is configured as ACTIVE_COMPATIBILITY=x, where x is 1 to enable compatibility and 0 to disable it. The default is 0.

Decline Reponse Codes

A semicolon separated list of 2 digit response codes which eSocket.POS will process as valid declines.

Example: RSP_CODES=21;25

If RSP_CODES is not defined, eSocket.POS will default to processing only response code 21 as a decline.

The following is an example of a valid parameter list: SC5000 VX810 ERR_RETRY_PERIOD=30

5.5.64. Pipeline component - Rapid payment service

Description: This component provides functionality for checking, if a transaction qualifies for rapid payment service (RPS) processing. RPS programs are offered by MasterCard (branded as QPS - quick payment service) and Visa (branded as EPS - express payment service). These programs allow merchants to waive certain cardholder verification requirements for transactions under a certain limit, resulting in increased transaction processing speed.

The component determines if a transaction qualifies for RPS processing, based on the following:

  • Several transaction properties, which are program dependent

  • This component’s configuration

  • The configuration of the account and EMV AID involved

The following transactions are eligible for RPS:

  • Magnetic stripe and EMV contact goods and services transactions with a POS condition code set to "00" (normal presentment)

  • EMV Quick Chip goods and services transactions with a POS condition code set to "00" (normal presentment)

  • EMV pre-swipe with Quick Chip goods and services transactions with a private transaction type of "96" (pre-swipe), and a POS condition code set to "00" (normal presentment)

Certain merchant category codes (MCCs) do not qualify for RPS. Validation of the MCC of the terminal is not performed by the RPS component. It is assumed that if RPS is configured for a terminal in eSocket.POS, the merchant has taken adequate steps to ensure they are eligible for the configured RPS program.

To configure RPS for magnetic stripe cards (contact and contactless) or EMV contact cards (including Quick Chip), see Configure rapid payment service processing.

Usage: Request Pipeline, optional. Response Pipeline, optional. If required, must be present in both pipelines.

Rank: Request Pipeline: Must be configured after the PAN, Account and Hotcard components, but before the EMV, PIN and Stand-in components. Response Pipeline: Must be configured before the Signature and Stand-in components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentRPS

Parameters: The component can be configured with the following named parameters:

Parameter Values

OFFLINE_AUTH_ALLOWED_PROGRAMS

This parameter is only applicable for accounts that are configured to force RPS transactions online. By default, stand-in is not permitted for force online RPS transactions, and they are declined if online approval is not possible (for instance, if the network connection is down, or if a timeout response is received). This parameter specifies the list of RPS programs for which offline stand-in is allowed for forced online RPS transactions. For these programs, if online approval is not possible, then the stand-in component is permitted to authorize the transaction against the offline stand-in limits.

The parameter is specified as OFFLINE_AUTH_ALLOWED_PROGRAMS=< programs >, where <programs> are a semi-colon separated list of RPS programs, offline stand-in is allowed.

Valid names for RPS programs are Visa and MasterCard.

See the following examples of parameter values:

  • OFFLINE_AUTH_ALLOWED_PROGRAMS=Visa;MasterCard
    Specifies that offline stand-in is allowed for both Visa and MasterCard forced online RPS transactions

  • OFFLINE_AUTH_ALLOWED_PROGRAMS=MasterCard
    Specifies that offline stand-in is only allowed for MasterCard forced online RPS transactions

CUSTOM_EMV_CONFIGURATION

Enables the use of a custom EMV RPS program, when an EMV contact transaction is eligible for Rapid Payment Service.

0 - Do not use custom EMV RPS program

1 - Use custom EMV RPS program

The default value is 0.

RPS_QUICK_CHIP_MODE

This parameter is used to control when a Quick Chip transaction uses RPS terminal capabilities, when the amount is not known. EMV processing requires the terminal capabilities be known at the time the first cryptogram is generated.

0 - Use RPS terminal capabilities to suppress signature

1 - Use RPS terminal capabilities

2 - Use RPS terminal capabilities and enable offline PIN entry, if the terminal capabilities support offline PIN

Note
If this parameter is configured to value = 1, the merchant accepts liability for fraudulent transactions. To disable CVM processing, do not configure the RPS CVM capability.

The default value is 0.

5.5.65. Pipeline component - Reconciliation

Description: The Reconciliation component provides eSocket.POS with the capability to process Reconciliation Request messages from the POS. If Reconciliation messages are used, then this component must be configured in the request and response pipelines. This component provides business processing that is specific to Reconciliation messages.

If eSocket.POS determines that the Net Settlement amount can be accurately determined, it sends the message online to Realtime, and return the totals received from Realtime back to the terminal.

However, if eSocket.POS is not connected to Realtime (for instance, if the network connection is down, or if a timeout response is received), the cutover message is put into the Store and Forward queue for later delivery to Realtime.

When eSocket.POS determines that it is not possible to get the totals from the payments system, or the Net Settlement Amount might be incorrect, the POS totals are not sent to the payments system, and the payments system’s totals are not returned to the terminal. The Message Reason Code sent back to the terminal is 9670 - Batch Totals not Available. eSocket.POS determines that it is not possible to get the totals as follows:

  • There are transactions in the Store and Forward Queue, due to previous timeout conditions, or connections not being available. Note that for this condition, it is possible for the totals returned by eSocket.POS for the next batch cutover to be incorrect.

  • The connection to Realtime is not available.

  • eSocket.POS timed out waiting for a response from Realtime.

  • Realtime returns an error response for the cutover message.

When eSocket.POS does return the totals, the terminal application receiving the totals needs to be aware of the following:

  • If a previous request to cutover a batch resulted in the Batch Totals not being available, the current totals returned might not match the terminal totals (for example, if the previous batch totals are not available due to there being transactions in the Store and Forward queue, the previous batch cutover requested would have been put into store and forward. If an online message (that affects batch totals) for the next batch went up to Realtime before the batch cutover message in the Store and Forward queue is sent up, the totals of the previous batch are updated instead of the current batch)

  • If eSocket.POS did a stand-in for any reason while the batch was open, some totals might be incorrect. For example, if the stand-in was due to a timeout response for a financial transaction, eSocket.POS reverses the transaction, and then puts a new transaction into the Store and Forward queue (this is transparent to the terminal application). The Net Settlement amount must, however, be correct.

Usage: If configured, must be present in both Request and Response Pipelines. Optional.

Rank: Must appear at or near the end of the request pipeline, after the Stand-in component, and at or near the beginning of the response pipeline, before the Stand-in component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentReconciliation

Parameters: None

Decline conditions: None

5.5.66. Pipeline component - Reference Data

Description: The reference data component is responsible for echoing the scheme and acquirer reference data in advices. The scheme and acquirer reference data will be populated as two Structured Data (field 127.22) tags, namely SCHEME_REFERENCE_DATA and ACQUIRER_REFERENCE_DATA.

This component only processes 0220 (Transaction Advice) messages.

Note
The Structured Data tags SCHEME_REFERENCE_DATA and ACQUIRER_REFERENCE_DATA will only be populated if it was present in the original authorization response.

Usage: Request pipeline, optional.

Rank: Any.

Class name: postilion.esocketpos.transactionengine.PipelineComponentReferenceData

Parameters: None

Decline conditions: None

5.5.67. Pipeline component - Referral advice

Description: Note that this component is deprecated. The Referral Advice component is used in conjunction with the REFERRED MessageType (deprecated and replaced by the REFERRAL MessageType) in the eSocket.POS API. The REFERRED message type allows the POS to send a 0200 request instead of a 0220 advice, following a transaction approved offline via referral. Because a request message is used, this enables device interaction, such as electronic signature capture, which would otherwise not be possible with the CONFIRM message type. The Referral Advice component turns the 0200 request message into a 0220 advice once the device interaction is complete, but prior to sending the message online.

Usage: Request Pipeline, optional.

Rank: Before the Confirm, EMV and Stand-in components

Class name: postilion.esocketpos.transactionengine.PipelineComponentReferralAdvice

Parameters: None

Decline conditions: None

5.5.68. Pipeline component - Response code

Description: The Response Code component displays the results of the transaction (for example, "Approved" or "Declined") to the user.

Usage: Response Pipeline, optional.

Rank: Must be configured after the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentRspCode

Parameters: Configure the following optional parameters, as required.

Parameter Values

DISPLAY_ADVICE_OUTCOME

Specifies whether the transaction outcome should be displayed for advice (0120/0220) messages. Note that the transaction outcome for eSP stand-in advices will not be displayed, even if this parameter is enabled.
Configure the parameter as follows:

  • 0 - Do not display transaction outcome for advice messages (default).

  • 1 - Display transaction outcome for advice messages.

Example: DISPLAY_ADVICE_OUTCOME=0

DISPLAY_HOST_UNAVAIL

Specifies whether the transaction outcome should be displayed for transactions declined with response code 91 (Issuer or switch inoperative).
Configure the parameter as follows:

  • 0 - Do not display transaction outcome for transactions declined with response code 91.

  • 1 - Display transaction outcome for transactions with declined response code 91 (default).

Example: DISPLAY_HOST_UNAVAIL=1

PROMPT_REVERSAL_OUTCOME

Specifies whether the PROMPT_REVERSAL_OUTCOME event will raise for reversal advice response messages (0430).
Configure the parameter as follows:

  • 0 - Do not display transaction outcome for reversal advice messages (default).

  • 1 - Display transaction outcome for reversal advice messages.

Example: PROMPT_REVERSAL_OUTCOME=1

Decline conditions: None

5.5.69. Pipeline component - SCA

Description: The SCA (Strong Customer Authentication) component is responsible for processing online contactless EMV transactions, where the transaction is declined online, with a response indicating that SCA is required. For response code 65 and specific extended response codes, this component can do one of the following:

  • 1600 - Prompt for a PIN and continue the contactless transaction.

  • 1601 - Cause the transaction to fall forward to allow the card’s chip to be read, after which the transaction is treated as a normal EMV transaction (Visa only).

Note
This is only required for online PIN and/or Visa SCA processing.

See SCA Configuration to configure SCA in eSocket.POS.

Usage: If configured, must be present in both Request and Response Pipelines, optional.

Rank: It must be configured in the Request pipeline, after the EMV component, and at the start of the Response pipeline after the Echo pipeline component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentSCA

Parameters: None

Transaction Processing Results:

The SCA component sets the following Transaction Processing Results (TPR) in the request and response message for byte 1.

Note
In the table below, a dash (-) represents a bit that is not being used and RFU stands for "reserved for future use".
Name Bit Description

RequestScaEligible

8

When set, this bit indicates that the request is eligible for SCA processing.

ResponseScaEligible

7

When set, this bit indicates that the response is eligible for SCA processing.

RequestPin

6

When set, this bit indicates that the SCA component will attempt to request a PIN to be entered by the user.

CardFallForward

5

When set, this bit indicates that fall forward to EMV will be attempted.

NoReqMsgFound

4

When set, this bit indicates that the request message could not be found, which would abort SCA processing.

NoLimitReinject

3

When set, this bit indicates that the message was injected with CVM limit set to zero.

DeviceSupportsCvmLimitChangeChecked

2

When set, this bit indicates that validation of device support for setting the CVM limit to zero was performed.

-

1

RFU

Pipeline component - Service code

Description: The Service code component is responsible for checking the service restriction code retrieved from the card (for example, from Track 2 data on the magnetic stripe), if this check is configured for the card.

If the service code indicates that the card requires online authorization, the component prevents stand-in from being applied to this transaction. The transaction is rejected under the following circumstances:

  • If the service code indicates that this is an ATM only card.

  • If the service code indicates that this is a Goods and Services only card, and the transaction type is not Goods and Services.

  • If the service code indicates that PIN entry is required and no PIN pad is configured.

  • If the service code indicates that this is a Cash only card, and the transaction type is not Goods and Services with Cashback, or the cashback amount is not the same as the transaction amount.

Usage: Request Pipeline, optional.

Rank: Must be configured after the PAN and Account components, but before the Stand-in, EMV and PIN components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentSvcCode

Parameters: The component can be optionally configured with the following parameters:

Parameter Values

1

check svc for emv

Specifies whether the service code should be checked for emv transactions

0 - Do not check service code for emv transactions

1 - Check service code for emv transactions (Default)

Decline conditions:

Condition Response Code Message Reason Code

Service code indicates an ATM-only card

57 - Transaction not permitted to cardholder

9756 - Not valid for transaction

Service code indicates a Goods and Services only card and transaction type is not Goods and Services

57 - Transaction not permitted to cardholder

9756 - Not valid for transaction

Service code indicates PIN entry is required and no PIN pad is configured

57 - Transaction not permitted to cardholder

9756 - Not valid for transaction

5.5.70. Pipeline component - Signature

Description: For an approved or referred response to a purchase, refund, deposit, gift card activate with a deposit, gift card unload, or gift card load transaction, this component determines whether signature verification is required by checking the account configuration in the eSocket.POS database and/or the CVM Results (if this is an EMV transaction). If either the account configuration or the CVM results specify that a signature is required, the component displays a message indicating this, and populates a value in the response, which indicates to the POS that signature is required. In the event of a contactless magnetic stripe transaction, if the transaction amount is below or equal to the contactless CVM required limit, no signature will be required, even if the account configuration specifies that a signature is required.

Prompting the operator to get the customer’s signature is the responsibility of the POS application. If the operator determines the signature does not match the one on the card, the POS application must allow the operator to cancel the authorization and send a reversal to eSocket.POS.

Note
MasterCard and Visa RPS transactions do not require a signature. This only applies to accounts that are configured for RPS. See Pipeline Component RPS for RPS configuration details.

Note that a signature is not required, if the POS Condition Code indicates that the customer is not present.

Usage: Response Pipeline, optional.

Rank: Must be configured after the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentSignature

Parameters: The component can be configured with the following optional parameter:

Parameter Values

1

CVM result usage

Specifies how the account configuration, and the CVM results in an EMV response must be used to determine whether signature is required.

0 - Use CVM results and Account
Signature is required, if either the CVM results, or the account configuration indicate this.

1 - Use only CVM results if present
If CVM results are present, the component uses only this to determine whether signature is required. Otherwise, the account configuration is used.

2- Use only Account configuration
Signature is required only if the account configuration indicates this.

Note
Use this parameter value to suppress signature for EMV Credit and Debit transactions on all major card brands (Visa, MasterCard, Discover and American Express).

This parameter is optional and has a default setting of 0.

Note
This parameter can also be configured per account by setting the tag USE_CVM_RESULTS_ONLY in the Custom Data for an account.

For Example: If the only CVM results should be used to determine the signature requirement for a specific account, then the custom data for that account should have the tag
USE_CVM_RESULTS_ONLY=1.

The option set at the account level will supersede the option set at the pipeline component level, while processing a transaction with that account.

The component can be configured with the following named parameters:

Parameter Values

Add signature required for intervene response codes

This is an optional parameter that specifies if transactions that return response codes (ISO field 39) that require user intervention will be evaluated when checking if signature is required. User intervention response codes are: 01, 02, 60, 77 and 78. The parameter is configured as INCLUDE_INTERVENE_RSP_CODES=x, where x is one of

  • 1 - Evaluates transactions with user intervention response codes (default)

  • 0 - Excludes transactions with intervene response codes

Add signature required for dynamic currency conversion (DCC) offers

This is an optional parameter that specifies if a signature is required for all transactions, where a DCC offer is accepted and authorized. The parameter is configured as DCC_SIGNATURE_REQUIRED=x, where x is one of the following:

  • 1 - A signature is required for all DCC offers that are accepted and authorized.

  • 0 - A signature is not required for DCC offers that are accepted and authorized, unless a signature is required by some other parameter.

    Note
    The default setting for this parameter is 0.

Decline conditions: None

Transaction Processing Results:

The Signature component sets the following Transaction Processing Results (TPR) in the response message for byte 1, 2 and 3.

Note
In the table below, a dash (-) represents a bit that is not being used and RFU stands for "reserved for future use".
Name Byte Bit Description

SignatureRequired

1

8

When set, this bit indicates that signature is required.

ExcludedMessageType

1

7

When set, this bit indicates that the message type is excluded for signature processing.

DCC

1

6

When set, this bit indicates that the message is a DCC transaction.

NoCVMOrCDCVM

1

5

When set, this bit indicates that no CVM was required or CDCVM was used for the transaction.

CVMSignature

1

4

When set, this bit indicates that the CVM indicates signature.

ContactlessEmv

1

3

When set, this bit indicates that the transaction was contactless EMV.

NoStructuredIccData

1

2

When set, this bit indicates that there is no Structured Icc Data in the message.

NoIccDataOrIccRequestData

1

1

When set, this bit indicates that there is no Icc data or Icc Request data in the Structured Icc Data.

TTQSignatureSupportedAndCvmRequiredSet

2

8

When set, this bit indicates that the TTQ has signature supported and CVM required set. (Visa Rid)

TTQSignatureSupportedAndCTQIsSignature

2

7

When set, this bit indicates that the TTQ is null or has signature supported, and the CTQ has signature required set, online PIN required not set and CDCVM performed is not set.

CustomerNotPresent

2

6

When set, this bit indicates that the Pos condition code indicates customer not present.

CardholderNotPresent

2

5

When set, this bit indicates that the Pos data code indicates cardholder not present.

ResponseCodeNotAllowed

2

4

When set, this bit indicates that the response code received is not valid for signature.

TranTypeNotAllowed

2

3

When set, this bit indicates that the transaction type is not valid for signature.

OnlyUseCvmResultsSignature

2

2

When set, this bit indicates that the CVM results indicate signature, or the CVM result usage is set to "use CVM only".

RPSSignatureBypass

2

1

When set, this bit indicates that RPS signature bypass is valid.

MagstripeAmountAboveCvmLimit

3

8

When set, this bit indicates that the magstripe transaction amount is above the CVM limit.

ContactlessMagstripeAmountAboveCvmLimit

3

7

When set, this bit indicates that the contactless magstripe transaction amount is above the CVM limit.

AccountRequiresSignature

3

6

When set, this bit indicates that the account requires signature verification.

-

3

5

RFU

-

3

4

RFU

-

3

3

RFU

-

3

2

RFU

-

3

1

RFU

5.5.71. Pipeline component - Signature capture

Description: The Signature Capture component captures an electronic form of the customer’s signature and sends it to the POS, where it can be printed on the receipt or stored. The instruction to capture the signature comes from the POS via an admin request for signature capture, or the Signature component indicates that it is required. The signature data can be sent upstream in an advice message, if required. Signatures are typically not verified, either at the POS or upstream, but are stored for future dispute resolution.

Note
eSocket.POS does not support the conversion of the signature image to ASCII format.

If you are experiencing issues with image conversion, Java might need to be run in headless mode. See the Running the XML interface page.

The following message flows are used:

  • 0100/0220:
    The signature is captured for an approved 0110 response, and returned to the POS in the response.
    If the signature must be sent upstream, it is sent in the subsequent 0220.
    0200/0620:
    The signature is captured for an approved 0210 response.
    If the signature must be sent upstream, a 0620 advice is injected.
    0600:
    The signature is captured for a signature capture admin 0600 request.

Transactions approved using an offline referral process are slightly more complex:

  • Referral/0220/0620:
    The signature is not captured for a referred 0110 or 0210 response.
    The merchant then obtains approval by an offline referral process.
    If signature capture is required, the POS uses the REFERRAL MessageType in the API, which results in a 0220 being sent to eSocket.POS with the 'ReferralAdvice' flag set in Structured Data. The signature is then captured for the REFERRAL 0230 response and returned to the POS.
    If the signature must be sent upstream, a 0620 advice is injected.

    The REFERRED message type is deprecated and is replaced by the REFERRAL message type. This flow is still supported to maintain backwards compatibility: If signature capture is required, the POS uses the REFERRED MessageType in the API, which results in a 0200 being sent to eSocket.POS.
    The Referral Advice component then translates the 0200 into a 0220 before sending upstream and returning a 0210 response.
    Signature is then captured for the REFERRED 0210 response and returned to the POS.
    If the signature must be sent upstream, a 0620 advice is injected.

Usage: Response Pipeline, optional.Must be used in conjunction with the Signature component.
Request Pipeline, optional. Used if signature is captured for a 0100 and must be populated by eSocket.POS in the subsequent 0220 advice.

Rank: In the Response Pipeline, must be configured after the Stand-in, EMV and Signature components. In the Request Pipeline, must be configured after Account component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentSignatureCapture

Mandatory parameters: The component must be configured with the following parameter:

Parameter Values

1

Send signature data online

Specifies whether signature data is sent upstream, following signature capture. For a 0200 message flow, a 0620 message is used, if this is selected.
For a 0100/0220 flow, the signature is captured when processing the 0110 response, and populated in the 0220 advice from the original request.

0 - Signature data is not sent upstream

1 - Signature data is sent upstream

Optional parameters: The component can be configured with the following parameters. If one parameter is used, then all of them must be specified:

Parameter Values

2

Is 0620 dead-end?

Specifies whether the 0620 sent upstream stops at Transaction Manager or is sent up to the sink node.

0 - 0620 is sent to the sink node

1 - 0620 stops at Transaction Manager (Transaction Type of '93')

3

Signature receiving institution ID

Specifies the ID of the institution receiving the signature capture information. The Receiving Institution ID Code (Field 100) is set to this value in Administrative Advice messages (0620) injected by this component. The value configured must be numeric and must not exceed 11 digits. If not used, it must be set to 'NONE'.

4

Signature Format

Specifies the format of the signature that is sent upstream and to the POS.

R - Raw Format

I - Image Format(with base64 encoding)

5

Default Signature Image Format

Specifies the default format of the signature image that is sent upstream and to the POS, when the format is not specified in the message from POS. Default is TIFF format.

TIFF - TIFF Format

ASCII - ASCII Format

JPEG - JPEG Format

PNG - PNG Format

Decline conditions:

Condition Response Code Message Reason Code

Signature Capture Admin Request (0600) is canceled by the user

17 - Customer Cancellation

9630 - Customer Cancellation

No signature returned by the PED for a Signature Capture Admin Request(0600)

20 - Invalid Response

9641 - Device Failure

Events: If signature capture is required, the component reports this by means of an event with the ID 'SIGNATURE_PROMPT'. There is no data associated with this event.

5.5.72. Pipeline component - Signature lookup

Description: A signature captured by the Signature Capture component is stored in the eSocket.POS database along with the transaction that required it. The Signature Lookup component is used to retrieve such a signature from the database at the request of the POS. The POS can request the retrieval of a signature by sending an admin request for signature lookup to eSocket.POS, where the request is linked to the original transaction via the Transaction ID. If the original transaction is successfully retrieved, and it contains a captured signature, that signature is returned to the POS in an admin request response message.

Usage: Request Pipeline, optional. Must be used in conjunction with the Signature Capture component.

Rank: Any

Class name: postilion.esocketpos.transactionengine.PipelineComponentSignatureLookup

Parameters: This component requires no parameters.

Decline conditions:

Condition Response Code Message Reason Code

The original transaction does not contain any signature data

25 - Unable To Locate Record

9712 - Missing Signature Data

The original transaction cannot be found

25 - Unable To Locate Record

9720 - Original Transaction Not Found

5.5.73. Pipeline component - Stand-in

Description: The stand-in component provides eSocket.POS with the ability to authorize a transaction without going online. If this component is configured, transactions are authorized by eSocket.POS, based on whether the transaction amount is below the configured limits for the particular card and account type. Transaction types for which stand-in is allowed include Purchase (00), Purchase with cashback (09), Refund (20), Deposit (21), Credit Adjustment (22) and Load (25, with an extended transaction type of 6501) transactions. The stand-in component can also authorize refund transactions that are processed by ICC devices in an MSR manner.

If eSocket.POS is not connected to the upstream entity (for instance, if the network connection is down, or if a timeout response is received), the transaction amount is compared to the offline limit configured for this card and account type. If the amount is less than the limit, the transaction is authorized offline. If eSocket.POS is currently connected, the limit that applies is the floor limit for this card and account type. Limits are applied to both the transaction amount, and the cashback amount. In the case of contactless magnetic stripe transactions (PAN Entry Mode set to 91 - Auto entry via contactless magnetic stripe), the contactless floor limit overrides the floor limit, if it is configured. Also, the contactless floor limit is applied only to the transaction amount. eSocket.POS can be configured so that stand-in occurs regardless of amount (no limit) for credit transactions (Refund, Deposit, Credit Adjustment and Load).

If the transaction is authorized by the stand-in component, the component converts the transaction from a request to an advice. The advice is sent online at a later stage, via a store-and-forward mechanism. The same component in the response component converts the advice response back to a request response.

If the transaction is not authorized by the stand-in component, it is passed through the remainder of the pipeline to the sink entity as normal. The sink entity attempts to send the transaction online for authorization.

NOTES
  • For Rapid Payment Service (RPS) transactions, if RPS is configured to stand-in, the RPS limits override the stand-in limits. Otherwise, the RPS transaction is forced online. If the RPS transaction cannot be forced online (for instance, if the network connection is down, or if a timeout response is received), the transaction can be authorized offline against the offline stand-in limits, but only if the RPS component is configured to allow this. This only applies to accounts that are configured for RPS. See Pipeline Component - Rapid Payment Service for RPS configuration details.

  • For healthcare benefit transactions, only the healthcare portion of the transaction is eligible for stand-in. The stand-in pipeline component compares the healthcare portion amount (instead of the total transaction amount) to the stand-in limits to determine whether stand-in is allowed. Additionally, if the healthcare portion is smaller than the total transaction amount, then partial approval is required. eSocket.POS checks that the property PosCondition (field 25) is set to 41, to confirm that the merchant supports partial approval. If not, the transaction is declined. If the transaction is allowed, the response code (field 39) in the response message is set to 10 to indicate partial approval.

  • For electronic benefits transfer (EBT) transactions, stand-in is not allowed for account types EBT cash benefit (type 96) and EBT food stamp (type 98).

  • For Operating Code (OPC) transactions, the account level offline limits are not used by default when determining whether offline stand-in should occur. Instead, the offline limit configured for each OPC is used.
    The account level offline limits can be used in addition to the OPC offline limit, based on the usage of the ENABLE_STANDARD_LIMIT_FOR_OPC parameter.

  • For Operating Code (OPC) transactions, transaction types for which stand-in is allowed include Cash (01), as well as those already mentioned.

Usage: If configured, must be present in both Request and Response Pipelines. Optional.

Rank: Must appear at or near the end of the request pipeline, after the Confirm and PIN components. Must be configured before the EMV pipeline component in the response pipeline.

Class name: postilion.esocketpos.transactionengine.PipelineComponentStandIn

Parameters: The component must be configured with the following parameters, separated by spaces:

Parameter Values

1

Stand-In Mode

Specifies whether stand-in is allowed based on limits, even if PIN data (field 52) is present in the message, possibly overriding the Service Restriction Code of the card. Note that in this case the PIN is not verified. Also, specifies what type of Stand-in is allowed for credit transactions (Refunds, Deposits, Credit Adjustments and Loads).

00 - No stand-in on PIN: Carry out limits-based stand-in for credit transactions.

10 - Allow stand-in on PIN - Carry out limits-based stand-in for credit transactions.

01 - No stand-in on PIN - Carry out stand-in for credit transactions, regardless of amount (no limit) when offline. No stand-in will be carried out for credit transactions when online.

11 - Allow stand-in on PIN - Carry out stand-in for credit transactions, regardless of amount (no limit) when offline. No stand-in will be carried out for credit transactions when online.

02 - No stand-in on PIN - Always stand-in for credit transactions.

12 - Allow stand-in on PIN - Always stand-in for credit transactions

2

Authorization ID Code (optional)

The component can be configured with an optional user parameter, the Authorization ID Code,to be inserted into field 38 when stand-in is performed.

3

Enable Authorization Advices (optional)

This parameter is optional. It controls whether the stand-in component will send 0120 messages upstream when it performs stand-in on a 0100.

0 - Authorization advices disabled

1 - Authorization advices enabled

If this parameter is not set, the component will default to authorization advices being disabled.

Note
For compatibility, parameter 1 (Stand-In Mode) can take a one-character value (0 or 1), then the component defaults to limits-based stand-in for credit transactions.

The optional parameters Authorization ID Code and Enable Authorization Advices have been deprecated and replaced by named parameters specified in the following table.

If both optional parameters and named parameters are specified, then named parameters take preference over optional parameters.

In addition, the stand-in pipeline component can also be configured with the following named parameters:

Parameter Values

VEPS_AUTH

This parameter indicates the value of field 38, the Authorization ID Code, for a VISA RPS transaction. It is specified as:

VEPS_AUTH=x where x is the required authorization ID Code.

If this parameter is not specified, then the stand-in component defaults to the authorization ID code entered as the second parameter.

QPS_AUTH

This parameter indicates the value of field 38, the Authorization ID Code, for a MasterCard RPS transaction. It is specified as:

QPS_AUTH=x, where x is the required authorization ID Code.

If this parameter is not specified, then the stand-in component defaults to the authorization ID code entered as the second parameter.

AUTH_ID_CODE

This parameter indicates the Authorization ID Code to be inserted into field 38 when stand-in is performed.

This parameter replaces the optional user parameter auth_id_code.

ENABLE_AUTH_ADV

This parameter is optional. It controls whether the stand-in component will send 0120 messages upstream when it performs stand-in on a 0100.

0 - Authorization advices disabled

1 - Authorization advices enabled

If this parameter is not set, the component will default to authorization advices being disabled.

This parameter replaces the optional user parameter Enable Authorization Advices.

ALLOW_ZERO_AMOUNT_STANDIN

This parameter is optional. This parameter indicates whether the stand-in component should stand-in for zero amount transactions.

0 - Do not perform stand-in for zero amount transactions

1 - Perform stand-in for zero amount transactions

If this parameter is not set, the component will not stand-in for zero amount transactions.

ENABLE_STANDARD_LIMIT_FOR_OPC

This parameter is optional. This parameter indicates whether the stand-in component should use the account offline limit and the OPC offline limit for an OPC transaction, or only use the OPC offline limit.

0 - Only use the OPC offline limit (default)

1 - Use the OPC offline limit and the offline cashback limit.

2 - Use all offline limits (Offline limit, OPC offline limit and offline cashback limit). The lowest of the offline limit and OPC offline limit will be used.

Example: If OPC offline limit=50000, offline limit=25000 and offline cashback limit=5000 are the configured limits, then stand-in will be allowed when the transaction amount (including cashback) is below or equal to 250.00, and the cashback amount is below or equal to 50.00.

Approve and decline conditions:

Condition Response code Message reason code

Online Stand-in Authorization

00 - Approved

1006 - Below floor limit

Offline stand-in authorization

00 - Approved

1007 - Stand-in at acquirers option

Authorization profile:

Condition Authorization reason Authorization type

91 (issuer or switch inoperative) response code received in an Authorization Response (0110) or a Transaction Response (0210), and stand-in is performed.

3 - Timeout stand-in. The sink node did not respond to a request.

3 - Transaction authorized using card acceptor (merchant) limits.

5.5.74. Pipeline component - Transaction Allowed

Description: The Transaction Allowed component checks if the transaction being processed is allowed, based on the account configuration associated with this transaction.

If the account has the Disallow Refunds option selected, and the transaction is a refund transaction, then the component will decline the transaction.

If the account has the Disallow Reversals option selected, and the transaction is a reversal transaction that was not generated be eSocket.POS, then the component will decline the transaction.

Usage: Request pipeline, optional.

Rank: Must be configured immediately after the Account component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentTransactionAllowed

Parameters: The component does not have any configurable parameters.

Decline conditions:

Condition Response Code Message Reason Code

Transaction is a reversal transaction that is not generated by eSocket.POS, and the account is configured not to allow reversal transactions

57 - Transaction not permitted to cardholder

9756 - Not Valid for Transaction

Transaction is a refund transaction, and the account is configured not to allow refund transactions

57 - Transaction not permitted to cardholder

9756 - Not Valid for Transaction

5.5.75. Pipeline component - Transaction cleaner

Description: The Transaction Cleaner component is responsible for cleaning old transactions from the database. The cleaner is run at a configured time once every 24 hours, and all transactions older than the configured retention period are deleted. In addition, when Point-to-point Encryption (P2PE) is in use, the cleaner must be used to remove encrypted PANs from transactions still present in the database.

Usage: Either Request or Response pipeline (but not both). Mandatory, as the database quickly grows out of hand if no cleaner is used.

Rank: Any

Class name: postilion.esocketpos.transactionengine.ComponentTranStoreCleaner

Parameters: The component must be configured with the following parameters, separated by spaces:

Parameter Values

1

cleaner time

The time in HHmm format at which the transaction cleaner must be run every day.

2

transaction retention period

The number of hours (integer) for which transactions must be retained in the database.

3

undelivered retention period

(Optional) The number of hours (integer) for which undelivered support events must be retained in the database.

4

PAN retention period

(Optional) The number of hours (integer) for which encrypted PANs must be retained in the database. This number cannot be larger than the transaction retention period.
This parameter is only used when the PAN component is set to perform point-to-point encryption.

To maintain backwards-compatibility, if the first parameter is set to '9999', the cleaner time is scheduled for '01h00'. If the second parameter is set to '0', the transaction retention period is set to 720 hours. If the third parameter is omitted, the value for the transaction retention period is used. If the fourth parameter is omitted or set to '9999', encrypted PANs will not be removed from the database. Note that the cleaner will never remove an encrypted PAN from a transaction that used software encryption, only from a transaction that uses P2PE.

Decline conditions: None

5.5.76. Pipeline component - Transaction Inquiry

The Transaction Inquiry pipeline component looks up transactions from the eSocket.POS local database. To initiate the lookup, eSocket.POS sends an administrative request (0600) message through the pipeline, with extended transaction type (ETT) 2115.

The 0600 message has the same transaction id and date time than the original transaction.

This component always returns a single transaction in its structured data. If more than one transaction is retrieved, this component always selects the first transaction in the list.

Usage: Request and Response pipelines, optional.

Rank: In the request pipeline, if the TranInquiry component is configured, it must be configured before the PAN pipeline component. In the response pipeline, if the TranInquiry component is configured, it must be configured after the PAN pipeline component and the EMV Component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentTranInquiry

Parameters: None

Decline conditions:

Condition Response code Message reason code

The lookup is complete and no transaction is found.

25 - Unable to locate record

9720 - Original transaction not found

An error occurred while looking up the transaction.

25 - Unable to locate record

9756 - Not valid for transaction

5.5.77. Pipeline component - Verishield

Description: The Verishield pipeline component is responsible for supporting VeriShield encryption in eSocket.POS. This pipeline component is required when eSocket.POS drives a Verifone device with VeriShield encryption enabled. For more information, see the appropriate eSocket.POS device driver user guide.

The Verishield pipeline component processes Administration Request messages (0600) with Extended Transaction Types (127.33):

  • 2111 - Register Device, which calls the Register Device command on the device

  • 2112 - Advance Encryption Key, which calls the Advance DDK command on the device

Responses from the device are placed in structured data (field 127.22) as follows:

  • Register Device command responses are placed in the RegisterDeviceResponse subfield.

  • Advance DDK command responses are placed in the AdvanceKeyResponse subfield.

Both these responses must be sent upstream to allow for decryption of the track data in subsequent transactions.

The Receiving Institution ID Code (field 100) is populated, if the RECEIVING_INSTITUTION_ID_CODE parameter is configured.

Usage: Request pipeline, when supporting VeriShield encryption

Rank: Must be configured after the PAN component

Class name: postilion.esocketpos.transactionengine.PipelineComponentVerishield

Parameters: The Verishield pipeline component can be configured with the following named parameter:

Parameter Values

RECEIVING_INSTITUTION_ID_CODE

This parameter handles routing of the Device Administrative Messages in Postilion. This parameter specifies the Receiving Institution ID Code (Field 100). The parameter is specified as RECEIVING_INSTITUTION_ID_CODE=x where x is a valid numeric entry and less than or equal 11 digits in length.

This parameter is optional and by default is not set.

Decline conditions:

Condition Response Code Message Reason Code

No response received from the device.

96 - System Malfunction

9641 - Device Failure

5.5.78. Pipeline component - VeriShield TransArmor

Description: The VeriShield TransArmor pipeline component is responsible for communicating VeriShield TransArmor configuration details to upstream entities.

The VeriShield TransArmor pipeline component processes and Verishield TransArmor Request messages, identified with a Structured Data tag EncryptionMode set to a value of 4.

Usage: Request pipeline, when supporting VeriShield TransArmor encryption/tokenization

Rank: Must be configured after the PAN component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentVerishieldTransArmor

Parameters: The VeriShield TransArmor pipeline component can be configured with the following named parameters:

Parameter Values

TRANSARMOR_TOKEN_TYPE

The VeriShield TransArmor token type in use. Specified as TRANSARMOR_TOKEN_TYPE=x, where x is a valid alphanumeric entry exactly 4 characters in length, for example: A0B1.

TRANSARMOR_ENC_TYPE

The VeriShield TransArmor encryption type in use. Specified as TRANSARMOR_ENC_TYPE=x, where x is a valid alphanumeric entry at most 2 characters in length, for example: 1K.

TRANSARMOR_SEC_LVL_IND

The VeriShield TransArmor security level indicator in use. Specified as TRANSARMOR_SEC_LVL_IND=x, where x is a valid alphanumeric entry at most 3 characters in length, for example: A2Z.

TRANSARMOR_DOMAIN

The VeriShield TransArmor domain value in use. Specified as TRANSARMOR_DOMAIN=x, where x is a valid alphanumeric entry at most 5 characters in length, for example: Do41N.

This parameter is used along with the TRANSARMOR_BRAND parameter to construct the TRANSARMOR_KEY_ID field which is stored in request messages processed by this pipeline component. When only the TRANSARMOR_DOMAIN parameter is supplied, the TRANSARMOR_KEY_ID field is constructed as
<TRANSARMOR_DOMAIN>:<TRANSARMOR_DOMAIN>.

TRANSARMOR_BRAND

The VeriShield TransArmor brand value in use. Specified as TRANSARMOR_BRAND=x, where x is a valid alphanumeric entry at most 5 characters in length, for example: Brnd8.

This parameter is used along with the TRANSARMOR_DOMAIN parameter to construct the TRANSARMOR_KEY_ID field which is stored in request messages processed by this pipeline component. When this parameter is supplied, along with the TRANSARMOR_DOMAIN parameter, the TRANSARMOR_KEY_ID field is constructed as
<TRANSARMOR_DOMAIN>:<TRANSARMOR_BRAND>.

RECEIVING_INSTITUTION_ID_CODE

This parameter handles routing of messages in Postilion. This parameter specifies the Receiving Institution ID Code (Field 100). The parameter is specified as RECEIVING_INSTITUTION_ID_CODE=x, where x is a valid numeric entry and less than or equal to 11 digits in length.

5.5.79. Pipeline component - Wait for authorization

Description: The Wait For Authorization pipeline component displays a message informing the customer that an authorization request is being processed online.

Usage: Request Pipeline, optional.

Rank: If configured, must appear towards the end of the Request Pipeline after the Stand-in and EMV components.

Class name: postilion.esocketpos.transactionengine.PipelineComponentWaitForAuth

Parameters: None

Decline conditions: None

5.5.80. Pipeline component - Wait For Card Removal

Description: The Wait For Card Removal component enables eSocket.POS to wait for the card to be removed from the card reader during a non-contactless EMV transaction.

Note
Using this component option requires device driver support and if not supported by the device, eSocket.POS will not wait for the card to be removed.
Request component

This component does not have a request component.

Response component

The Wait For Card Removal component in the response pipeline is responsible for enabling the device driver to wait for the card to be removed from the card reader once a non-contactless EMV transaction has been concluded.

Usage: Request Pipeline should not be configured, Response Pipeline optional when the EMV component is configured.

Rank: Must be configured after the EMV component.

Class name: postilion.esocketpos.transactionengine.PipelineComponentWaitForCardRemoval

Parameters:

The Wait For Card Removal pipeline component must be configured with the following named parameter(s):

Parameter Values

WAIT_FOR_CARD_REMOVAL

This parameter specifies the maximum time, in seconds, eSocket.POS will wait for the card to be removed while processing a non-contactless EMV transaction. If the card is not removed within this time period, transaction processing will still continue normally.

Approve and decline conditions: None

5.6. Devices

5.6.1. Devices

eSocket.POS is device independent. That is to say, eSocket.POS is aware of a number of logical device types (that is, a card reader, a PIN pad, and so on) with which it can interact. The specifics of communicating with these devices are left to device driver implementations. This allows eSocket.POS to communicate with any device given the correct device driver implementation. eSocket.POS supports a number of physical devices from a number of vendors. The device drivers which support particular physical devices are shipped separately to the eSocket.POS core product.

For information on a particular device see the user guide which comes packaged with the device. For a list of supported devices, contact your primary support provider.

The eSocket.POS Device Manager coordinates access to peripheral devices at the point of sale (POS). These are categorized into the following logical devices:

  • Card reader

  • Display

  • Keypad

  • PIN pad

  • Smart card reader

  • Check reader

  • Signature capture device

  • Printer

  • Barcode reader

These logical devices are grouped together in combinations based on customer requirements, and then associated with device drivers which support the logical devices. These device groups can then be assigned to terminals. A device group can only contain one of each logical device and requires one or more physical devices to support the logical devices in the device group.

When eSocket.POS is configured with multiple device groups the postilion.esocketpos.active_backup_mode property in the eSocket.POS properties file controls how eSocket.POS manages the initial interaction with device groups per transaction. The POS, through the XML interface API, can also direct eSocket.POS to communicate with a specific device group.

Prompt events

When eSocket.POS uses a display device to prompt a customer, events are posted using the eSocket.POS event mechanism. The POS application can register to receive these events, allowing the operator to be informed of what the customer is seeing, in case the operator cannot see the display.

See the Event ID page in the eSocket.POS Developer Guide for details about the available PROMPT events.

5.7. Card readers and fallback

eSocket.POS supports two logically separate card readers: a magnetic stripe reader and a smartcard reader. These may or may not be physically separate devices. Some smartcard readers can read only contact cards, and some can read both contactless and contact cards. The eSocket.POS can retrieve card data in the following ways:

  • Contactless smartcard read

  • Contact smartcard read

  • Magnetic stripe read

  • Manual PAN entry

5.7.1. Fallback

Fallback (also known as technology fallback ) is when an error occurs during a card read, and the process reverts to a lower capability than what is available. For example, a contactless smartcard is presented at a smartcard reader capable of contactless card reading; due to an error, the contactless read is unsuccessful; an attempt at a contact read is made, which is also unsuccessful due to an error; eventually the magnetic stripe is read and is successful. This fallback from smartcard to magnetic stripe is termed an ICC fallback. Because an ICC fallback represents a fraud risk, the transaction would typically be forced online for authorization. Furthermore, eSocket.POS does not accept an ICC fallback unless there was an attempt made to read the smartcard chip first. eSocket.POS manages the fallback process as described in the card read sequence below.

Note
The term CVM fallback is used when cardholder verification is done using signature instead of PIN entry. This is a different process and is not covered here. eSocket.POS supports CVM fallback depending on the device integration.

5.7.2. Card read sequence

eSocket.POS will always attempt to retrieve card data using the highest capability available (a combination of card reader capability and card capability):

  • If a contactless smartcard is presented at a smartcard reader capable of contactless reading, then a contactless smartcard read is attempted.

  • If a contactless smartcard is presented at a smartcard reader that is not capable of contactless reading, then a contact read is attempted.

  • If a card is presented at a reader that is only able to read magnetic stripe cards, then only the magnetic stripe read is attempted.

In the case of an error occurring during a card read, eSocket.POS will attempt to fallback to the next highest capability available:

  • A failed contactless smartcard read will fallback to a contact smartcard read.

  • A failed contact smartcard read will fallback to a magnetic stripe read.

When a magnetic stripe is read, but the service restriction code on the magnetic stripe indicates that there is a chip present, then an attempt is made to read the smartcard. Only if an attempt to read the smartcard has failed, will eSocket.POS accept an ICC fallback.

If no card information can be read, then eSocket.POS will allow an attempt at manual PAN entry, but only if this is supported by the card and account type.

5.8. Device updates

eSocket.POS provides a flexible means of automatically updating an external device. This can involve updating the firmware version on the device by loading a new device application over the serial cable. The nature of this update depends on the device manufacturer, and also on what is implemented in the eSocket.POS device integration code.

5.8.1. Overview of the steps involved in a device update

Preparing the update
  1. The device manufacturer supplies ACI Worldwide with an updated device application. This is packed into a zip file.

  2. ACI Worldwide might have to supply a patch for the eSocket.POS device integration code to support the updated application. This patch is also be packed into a zip file.

  3. ACI Worldwide supplies the retailer with the update zip files, together with instructions about distribution and configuration.

Configuring and distributing the update
  1. Using the central ConfigServer, the retailer associates the update zip files with a particular terminal category and specifies the location where it is unpacked.

  2. Using the ConfigServer, the retailer configures an update parameter string for the relevant device integration class.

  3. At some stage, the Configuration Agent on the till or store server automatically contacts the ConfigServer. In response, the server sends the update zip files, and a Terminal Data XML file which contains the update parameter string.

  4. The Configuration Agent automatically unzips the eSocket.POS patch zip file, and unpacks the device update zip file, but at this stage the device update files are not yet loaded onto the device. The Config Agent also updates the eSocket.POS database to contain the update parameter string.

Applying the update
  1. The next time eSocket.POS starts up (this is controlled by the retailer or the POS environment), the eSocket.POS device integration code finds the update parameter string.

  2. The device integration class interprets the update parameter string and uses it to load the new firmware onto the device (this step depends on how updates are implemented for this specific device.)

  3. After updating the device, eSocket.POS might determine that a Java Virtual Machine (JVM) restart is required to load the new patch classes for this update. If so, it refuses to start and the error message indicates that a restart is required. Restarting is under the control of the retailer or the POS application.

  4. eSocket.POS flags the update as complete (using the esp_update table) so the update is only applied once, and not once each time eSocket.POS restarts.

Follow-up
  1. Eventually the customer can remove the update_params entry in the ConfigServer database or replace it with another update.

  2. The update files remain on the eSocket.POS point-of-sale system or store server where they provide an audit trail. They are not cleaned out, as in a store server environment it is not possible to determine whether other terminals must still apply the update.

5.8.2. Limitations and special considerations

Note that, depending on the device integration, it is usually not possible for a failed update to be rolled back to the earlier version; eSocket.POS does not possess detailed information about the firmware on the device before the update. If an update fails, the device might be left in an unusable state.

In extreme cases, for instance where the update is incorrect, or where the update is interrupted by a power outage or communication error, certain devices might interpret this as an attempt to tamper with the device. This might trigger a security procedure on the device which can lead to the clearing of the device RAM. When this happens, the device becomes unusable and might have to be returned to the manufacturer or agent to be reloaded.

For these reasons, it is essential that the possible impact of a failed device update is fully understood by the retailer, and that device updates are carefully tested before being deployed.

5.9. Device File Download Management

eSocket.POS provides a way of tracking what file downloads were applied for the configured devices. The file download update process can involve updating the firmware version on the device by loading a new/updated application to the device. These file downloads are tracked in the eSocket.POS database in the form of a terminal file record for each file that had been loaded to the device. These records (called the file record information) ensure that a device would not apply the file to the device again, if already applied, but only when required, for example, when a file name record does not match what is already stored in the database for a terminal and is suggested to be new configuration.

Note
Device file download management must be implemented by the device driver to be functional.

5.9.1. File record information

  • Timestamp of the configuration set

  • Serial Number of the device that the file got applied to

  • MD5 Hash of the file

  • Terminal Id

A file will not be reloaded to the device should the file record information not have changed from the previous file download.

See the esp_device_updates page for more information about the file records that will be stored for file downloads.

5.10. Serial number validation

5.10.1. Overview

eSocket.POS provides a framework for the validation of device serial numbers. Note that the information given here must be read in conjunction with the eSocket.POS Developer Guide for details of the events and callbacks mentioned below.

Serial number validation is configured against the device class in esp_classes, and the serial numbers themselves are configured in esp_device_serials.

Devices such as card readers have a unique and fixed serial number. If this number can be retrieved from the device it can be used to identify the individual device. Serial number validation aims to prevent devices from being replaced or tampered with by verifying this serial number and by flagging when the device is disconnected. Serial number validation can be applied to any of the logical devices.

If serial number validation fails, then access to the device for processing financial data is denied. Access to the device is controlled using a serial number validation status stored against the device. The validation status can be UNKNOWN, ALLOWED, or DENIED. Access is allowed as long as the validation status is UNKNOWN or ALLOWED.

Serial number validation can be initiated by the POS using the DEVICE_SERIAL_NR_VALIDATE event and/or can be configured to occur at fixed intervals. Configuration at intervals is controlled through the esp_snv_interval device parameter.

There are two modes of serial number validation. If the POS is registered for the DEVICE_SERIAL_NR_AUTHORIZE callback then POS authorization is possible. Otherwise, a default decision is made by eSocket.POS.

The differences in functionality between the POS- and eSocket.POS-authorization modes are as follows:

  • If POS authorization is possible then the POS (or POS operator) makes the decision about whether to allow access to a device with an unrecognized (that is, non-configured) serial number pattern*. Otherwise, this is determined by the serial number validation type configuration option.

  • If POS authorization is possible, then the POS (or POS operator) makes the decision about whether to allow access to a new** or replaced** device. Otherwise, a default decision is taken based on whether the serial number is recognized and (if not) whether unrecognized serial numbers are allowed (as determined by the serial number validation type configuration option).

  • If POS authorization is possible then the POS (or POS operator) can take the decision about whether to allow access to a device which is disconnected. Otherwise, disconnects are ignored.

  • Serial number patterns can be specific serial numbers or patterns in SQL syntax (or a mixture of both). The value can also be defined in terms of ranges (A-B) with the use of the PatternMatcher system property. They can be specified per store, store revision, lane profile, and terminal ID pattern. See esp_device_serials for further details.

** A 'new' device refers to a device configured in eSocket.POS for which the serial number is successfully retrieved for the purpose of serial number validation for first time. A 'replaced' device refers to a device configured in eSocket.POS for which a change in serial number is detected since the last time the serial number was successfully validated.

5.10.2. Serial number validation steps

eSocket.POS authorization mode

If the POS is not registered for the DEVICE_SERIAL_NR_AUTHORIZE callback then each time that the serial number is validated the following steps are taken:

  1. If serial number retrieval is not supported by the device and device driver then the validation status is changed to UNKNOWN. None of the following steps are taken. Otherwise, validation continues with the next step.

  2. The serial number is retrieved from the device, through the device driver.

  3. If the device is currently disconnected then an event is logged and none of the following steps are taken.

  4. If the serial number has not changed and is already validated then serial number validation has completed successfully and none of the following steps are taken. If the serial number is not validated then the following steps are taken.

  5. The serial number is checked against the configured allowed serial number patterns for the terminal.

  6. A decision is made about how to set the validation status, as follows. If the serial number was retrieved successfully and matches an allowed serial number pattern then the validation status is set to ALLOWED. If the serial number was retrieved successfully, but does not match an allowed value, then the esp_snv_type for the device is checked. If this value allows validation of unrecognized serial numbers then the validation status is set to ALLOWED; otherwise, it is set to DENIED. If the serial number was not retrieved successfully (for example due to a device disconnect) then the validation status remains unchanged.

  7. If, as a result of the previous steps, the validation status changed, then a DEVICE_SERIAL_NR_STATUS event is raised to inform the POS of the validation result.

  8. If, as a result of the previous steps, the validation status changes from UNKNOWN/DENIED to APPROVED, then an informational event is logged. If the validation status changes from UNKNOWN/APPROVED to DENIED then a warning is logged.

POS authorization mode

If the POS is registered for the DEVICE_SERIAL_NR_AUTHORIZE callback, then each time that the serial number is validated the following steps are taken:

  1. If serial number retrieval is not supported by the device and device driver, then the validation status is changed to UNKNOWN. None of the following steps are taken. Otherwise, validation continues with the next step.

  2. The serial number is retrieved from the device through the device driver.

  3. If the device is currently disconnected, then an event is logged and none of the following steps are taken.

  4. If the serial number has not changed and is already validated and no disconnects are detected since the last serial number validation, then serial number validation has completed successfully and none of the following steps are taken. If the serial number is not validated, or a disconnect has occurred, then the following steps are taken.

  5. The serial number is checked against the configured allowed serial number patterns for the terminal.

  6. The DEVICE_SERIAL_NR_AUTHORIZE callback is raised with the serial number status information. The status information includes whether the serial number is for a new or replaced device, whether the serial number is configured and whether any device disconnects are detected since the last time the serial number was successfully validated. The response to the callback is used to set the validation status of the device to ALLOWED or DENIED. If a timely response to the callback is not received then the validation status of the device is set to DENIED. See the event description in the eSocket.POS Developer Guide for further details.

  7. A DEVICE_SERIAL_NR_STATUS event is raised to inform the POS of the validation result.

  8. If, as a result of the previous steps, the validation status changes from UNKNOWN/DENIED to APPROVED then an informational event is logged. If the validation status changes from UNKNOWN/APPROVED to DENIED then a warning is logged.

If the DEVICE_SERIAL_NR_AUTHORIZE callback is raised, then the POS might, at a later time, raise a DEVICE_SERIAL_NR_AUTHORIZE event as a delayed response to this callback. It might do this, for example, if store manager intervention is required to authorize a device. In the meantime, the callback must return a denial response, but this response is superseded by the authorization response provided in the DEVICE_SERIAL_NR_AUTHORIZE event. Therefore, this event can result in the validation state being updated. After processing this event, eSocket.POS raises the DEVICE_SERIAL_NR_STATUS event (as described in step 7). If this event results in a change in the validation status of the device, then an event or warning is logged (as described in step 8).

5.10.3. Steps for checking if access is allowed

Each time that access is required to a device for processing financial data the following steps are taken:

  1. The validation status of the device is checked. If set to DENIED, then access to the device is denied. Note that if access to the smartcard reader is denied then this does not mean that access to the card reader and keypad are denied if they are separate physical devices; therefore, a financial transaction might be able to proceed using the card’s magnetic stripe or manual entry of card data. If the validation status is APPROVED then the following steps are taken.

  2. If the esp_sn_dependency parameter for the device is set to true then the validation statuses of the other logical devices configured for the terminal are checked. If the validation status of any of these devices is set to DENIED then access to the device is denied. Otherwise, access to the device is allowed.

Note that while access to a device is denied for processing financial data, access might still be allowed for some basic functions. These include the display of the welcome message and the transaction outcome on a smartcard reader.

5.10.4. POS callback device

eSocket.POS provides a callback mechanism which allows it to request information from the POS while a transaction is being processed. It can be used in place of a physical device, so that instead of implementing an interface to a physical device in the device driver the POS Callback Device uses callback events to retrieve the required data from the POS. It therefore provides a 'logical device.'

This is useful where eSocket.POS does not have access to a device capable of clear text entry. Even if a PIN pad is present, many PIN pads do not allow clear text entry because of security concerns.

It is also useful where the POS drives the swipe reader used to read the magnetic stripe.

Note that using the POS callback device requires that the POS application supports these callback messages and returns the relevant value to eSocket.POS.

Logical devices implemented
  • Keypad

  • PIN pad

  • Card Reader

Configuring to use the POS callback device

To configure eSocket.POS to use the POS callback device, configure the following class under any or all of the KEYPAD, PINPAD, and CARDREADER tags as required:

  • postilion.esocketpos.devicemanager.PosCallbackDevice

This class does not require a parameter string.

Event IDs supported

All the callbacks raised by the POS Callback Device are with the Event ID 'DATA_REQUIRED,' and the event data is used to define the data that is required.

The only other event raised by the POS Callback Device is the 'CANCEL_CARD_SWIPE' event (if the POSCallbackDevice is configured as the card reader).

Note that the POS application must register for these events/callbacks to be notified of them.

See the Event ID page of the eSocket.POS Developer Guide for detailed information about these events/callbacks.

5.10.5. AID selection

eSocket.POS provides a mechanism which allows device driver implementations to select the application identifier (AID) during EMV transactions.

The way in which this functionality occurs is affected by the following parameter for a terminal profile:

Parameter name Description

AID selection method

Select the method of AID selection that should occur. These methods vary between AID selection occurring on the PED, and AID selection occurring through eSocket.POS.

This table lists the function of each AID selection method:

AID selection method Description

Default

eSocket.POS will not perform AID selection, and will delegate to the device to perform the AID selection.

US Common Debit prioritized

If multiple AIDs exist on the card, the US Common Debit AID with the highest priority on the card is selected.

Note
This option will allow the cardholder to select PIN or Signature, which will change the Terminal Capabilities applied to the request.

International AID prioritized

If multiple AIDs exist on the card, the International AID with the highest priority on the card is selected.

Debit/Credit selection

If multiple AIDs exist on the card, the customer is prompted to select between Credit and Debit. Selecting Credit indicates that the International AID with the highest priority on the card is selected. Selecting Debit indicates that the US Common Debit AID with the highest priority on the card is selected.

Highest-priority AID selection

eSocket.POS selects the highest priority AID, unless the card has multiple AIDs with the same priority. In this case, the device driver implementation determines the AID selection method.

Merchant-prioritized customer AID selection

If multiple AIDs exist on the card, the customer will be prompted to select an option from the list of AIDs on the card. This list will be ordered based on the priority of the AIDs configured in the Cards console, ignoring the priority of the AID indicated by the card. Selecting this option allows compliance with the MIF Network Selection Mandate.

Configuring the AID selection method for a terminal profile
  1. Log in to the Store and Terminal Configuration console (if not already logged in).

  2. Select the Profiles page.

  3. Select the Terminal Profiles subpage.

  4. Add a new terminal profile by selecting the Add New edit option or clicking the Add New button.

  5. Select the Terminal Configuration page on the New Terminal Profile dialog box that opens.

  6. Enter configuration information that includes the AID selection method.

Forcing of automatic AID selection

Forcing of automatic AID selection can be applied to certain configured Cards. When this occurs, the highest priority AID will be selected without any prompt for selection. Configure the FORCE_AUTO_AID_SELECTION terminal parameter to specify which cards require forcing of automatic AID selection.

Note
This parameter might not function when using a custom class, and is overridden when the AID selection method forces customer selection.
Tag Description

FORCE_AUTO_AID_SELECTION_<suffix>

This parameter lists several conditions where, if all are fulfilled by an AID present on a card, automatic AID selection will occur. This parameter is configured with a value of <tag>=<value1>|<value2> where an EMV tag <tag> must match one of the <value>s, delimited by a pipe-character (|), to fulfill the condition. If multiple conditions need to apply, delimit each condition with a comma (,).

Example: <tag>=<value>,<tag>=<value>

<suffix> should be set to 1. If multiple lists of conditions are required to specify multiple cards that require automatic AID selection, add more FORCE_AUTO_AID_SELECTION parameters with incremental suffixes.

Example: FORCE_AUTO_AID_SELECTION_2 If an AID fulfills all conditions in any of the FORCE_AUTO_AID_SELECTION parameters, automatic AID selection will occur.

Note: If the tags being compared are not returned by the device before application selection consult the appropriate device driver and integrator specification for a method to return additional tags.

Configure the terminal to enable forced automatic AID selection:

For the required terminal profile, configure the FORCE_AUTO_AID_SELECTION_1 value as a custom parameter by completing the following two tasks.

Add a parameter definition:

  1. From the Software Components Configuration console, select the Parameter Definition tab, and click the Add New button. The New Custom Parameter window appears and prompts for information.

  2. Enter the Tag value as FORCE_AUTO_AID_SELECTION_1.

  3. Enter the Name value as Force auto selection conditions, or any other identifiable value.

  4. Select an from the Format drop-down list.

  5. Specify a Length that is long enough for the conditions you wish to create.

  6. Click Save + Exit when done.

Add a new parameter:

  1. From the Store and Terminal Configuration console, select the Profiles > Components tab.

  2. Select the required Terminal Profile from the drop-down list.

  3. From the Parameter Values tab, click the Add New button to add a new parameter.

  4. Search for the FORCE_AUTO_AID_SELECTION_1 tag created before, and then select it.

  5. Specify the desired value in the Value field.

  6. Click Save + Exit when done.

Custom AID selection class

By default, a base AID selector class is used to select the correct AID. However, a custom class can be configured to be used instead.

Configure the custom class with the following details:

Variable Setting

Name

Enter a name identifying the custom AID selection class. This name will appear in the ConfigServer Store and Terminal console when including a custom class in a terminal profile.

Class

Enter the full Java class name of the custom AID selection class. This class must extend the postilion.esocketpos.devicemanager.AAidSelector class. See the custom AID selection class documentation for details on what this value must be.

Default Parameters

Leave this empty.

Tag

Enter AID_SELECTOR as the Tag value.

See the eSocket.POS Configuration Server User Guide for more information about how to configure a custom class.

5.10.6. Device Polling Parameters Configuration

eSocket.POS provides the following list of parameters which can be configured to control the poll interval after the device is disconnected while operating in TCP/IP mode.

  • DeviceDisconnectPollInterval

    This parameter specifies the time interval (in seconds) for polling the device after the device is found to be disconnected by polling failure. The device will be polled after every time interval specified in this parameter until maximum back off time (specified in the DeviceMaxBackoffTime parameter) is reached after disconnection. After DeviceMaxBackoffTime, the device will be polled every 30 seconds. The default value is 30 seconds.

    Note
    Although eSP will try to reconnect every x seconds, there might be a delay of 3-7 seconds added by the OS, when a network cable is unplugged and plugged back.
  • DeviceMaxBackoffTime

    This parameter specifies the maximum time (in seconds) for which the device will be polled using time interval specified in the DeviceDisconnectPollInterval parameter before resetting the poll interval to 30 seconds. The default value is 360 seconds.

  • CONN_TIMEOUT=<A positive integer>

    This is a device connection parameter which indicates the number of seconds to wait for device to be connected before connection timeout. The default value for this parameter is 15 seconds. For example, CONN_TIMEOUT=5.

Configuring parameters DeviceDisconnectPollInterval and DeviceMaxBackoffTime:
  1. Open the ConfigServer Software Components console, select the Parameter Definition tab and add a new entry.

  2. Set the Tag field to DeviceDisconnectPollInterval or DeviceMaxBackoffTime.

  3. Enter any descriptive Name. For example, Device Disconnect Poll Interval or Device Maximum Backoff Time.

  4. Set Format to n.

  5. The parameter Length is dependent on the number of seconds to be configured. Set the length up to a value large enough to store the required seconds.

  6. Open the ConfigServer Store and Terminal console and under the Profiles tab, select the Components tab.

  7. Select the relevant Terminal Profile from the drop-down list. If the terminal profile has not been created yet, it can be configured on the Terminal Profiles tab under the Profiles tab.

  8. Select the Parameter Values tab and add a new parameter value.

    The New Parameter Value dialog box prompts for the required information.

  9. Set the Tag field to the DeviceDisconnectPollInterval or DeviceMaxBackoffTime parameter definition previously added. The Name field is automatically updated.

  10. In the Value field, set the parameter value as required.

Configuring parameters CONN_TIMEOUT :
  1. Open the ConfigServer Store and Terminal console.

  2. Add a new entry to the Profiles > Connection Types tab in the ConfigServer Store and Terminal console.

  3. On the New Connection Type dialog box, enter the following information:

    • A descriptive name for the Type field, for example, Verifone FormAgent TCP/IP.

    • Set the Protocol as required. Note that CONN_TIMEOUT should only be set when using TCP/IP protocol.

    • Set the Filter Class to appropriate value.

    • Set the Device Tag to appropriate value.

    • If a TCP/IP was selected for the Protocol, configure optional connection parameter CONN_TIMEOUT in Parameters which indicates the number of seconds to wait for the device to be connected before connection timeout. The default value for this parameter is 15 seconds. For example, CONN_TIMEOUT=5.

    Note
    See the "Configure connection types" page in the eSocket.POS Configuration Server User Guide for more details.

5.10.7. Generic Device Driver Transaction Processing Decisions

eSocket.POS provides a mechanism which allows device driver implementations to record progress when processing a transaction.

Device drivers that implement this feature can set decisions into structured data under the "TPR:DeviceDriver" key. The decisions are made during a transaction based on the following available decisions:

Name Byte Bit Description

Card Inserted

1

8

A card has been inserted into the device (the chip is read).

Card Swiped

1

7

A card has been swiped on the device (the magnetic stripe is read).

Card Tapped

1

6

A card has been tapped on the device (contactless tap was performed).

Manual PAN

1

5

PAN was entered manually.

Candidate List Selection using PSE

1

4

Candidate list was obtained from the card’s Payment System Environment (PSE).

Candidate List Selection using List of AIDs

1

3

Candidate list was obtained by the terminal iterating through its AID list, asking the card whether it supports each individual AID.

AID Selection

1

2

Completed selection of a single AID.

Application Initialization

1

1

EMV application initialization is performed on the device.

Script Processing before 2nd ICC

2

8

The device performs script processing before the second generation of the application cryptogram.

Script Processing after 2nd ICC

2

7

The device performs script processing after the second generation of the application cryptogram.

5.11. Database

The eSocket.POS Information Server is an internal entity within eSocket.POS that provides access to information from a SQL database.

Information in the database includes:

  • Configuration parameters

  • Names of custom classes

  • State information

  • Card and account data

  • Hotcards

  • Transaction records

Transactions are stored to provide stand-in capability, retrieve original data elements for linked transactions, and to provide persistence in case of system failure.

For a list of databases supported by eSocket.POS, see Supported platforms.

5.11.1. HSQL database

HSQL database engine

The HSQL Database Engine (HSQLDB) is an open source 100% Java SQL database engine. HSQLDB is not shipped as part of the eSocket.POS distribution, but can be used as part of the POS integration when a lightweight database is required. The following notes are intended as a guideline to running HSQLDB as part of eSocket.POS, but for full details see the documentation supplied with HSQLDB.

Note that HSQLDB requires Java versions jdk1.3.0 or later.

When HSQLDB is used with eSocket.POS, certain copyright and license notices apply.

Installing HSQLDB

The latest version of HSQLDB can be downloaded from http://hsqldb.org.

The distribution zip file contains the jar file hsqldb.jar. This file must then be placed in your classpath.

HSQLDB modes

HSQLDB can be run in various modes. eSocket.POS supports the following modes:

Standalone mode: The database is run within the same Java VM as the application.

Note
When in standalone-mode, only one process is allowed to access the database at the time. It is required to use the -ca and -um directives in the eSocket.POS service to merge all 3 eSocket.POS services into the same process to prevent database access issues.

Server mode: The database is run in a separate application. This can be done in one of two ways:

  • As a Windows service

  • Using the command line <java> <classpath> org.hsqldb.Server -database <db_filename>

Note
eSocket.POS does not support running HSQLDB in embedded mode.
eSocket.POS database

For notes on installing, uninstalling, and upgrading, see HSQL and the eSocket.POS database.

HSQLDB script file size

HSQLDB creates a file <db_filename>.script which contains the full list of SQL transactions on the database. This file grows in size until it reaches the size in megabytes specified by the hsqldb.log_size property in the <db_filename>.properties file, at which stage it is checkpointed or compacted. The value for hsqldb.log_size is set to 200 MB when the database is created, but can be altered by editing the text file.

HSQLDB database manager

HSQLDB provides a graphical tool to view and update the database manually. Run the following command to start the HSQLDB database manager:

<java> <classpath> org.hsqldb.util.DatabaseManager

The database manager can’t be used if HSQLDB is currently running in standalone-mode.

HSQLDB Database settings

The following settings are recommended for HSQLDB. Note that these typically must be configured before starting eSocket.POS.

Setting Reason

Configure LOB SCALE to be 8 or less.

Prevent HSQL lobs file from growing too large.

Enable LOB compression

Prevent HSQL lobs file from growing too large.

Configure LOG SIZE to be 5MB.

Encourage more frequent database checkpoints, which cleanup both the log and log files from growing too large.

HSQLDB Windows service

On a Microsoft Windows platform, the HSQL database can be run in server mode within one of the Windows services provided with eSocket.POS.

This is done by specifying HSQLDB as a custom application, using the following parameter as part of the command line for the eSocket.POS or Config Agent service:

-cust postilion.esocketpos.util.HsqldbRun

In addition to this, the following eSocket.POS property must be configured:

postilion.esocketpos.hsqldb_params = -database <db_filename>

For example, the database file can be C :\\postilion\\eSocket.POS\\esp_db. These values are used as the command line arguments to run the org.hsqldb.Server class, and further options are contained in the HSQLDB documentation.

See the eSocket.POS Windows services page for more information about configuring this service.

Note that the file hsqldb.jar must be included in the classpath when running this service.

HSQLDB license

The HSQL Database Engine (HSQLDB) is an open source 100% Java SQL database engine. HSQLDB is not shipped as part of the eSocket.POS distribution.

When HSQLDB is used with eSocket.POS, the following copyrights and licenses apply:

This product includes Hypersonic SQL.

ORIGINAL LICENSE (also known as the "hypersonic_lic.txt"):

For content, code, and products originally developed by Thomas Mueller and the Hypersonic SQL Group:

Copyright (c) 1995-2000 by the Hypersonic SQL Group. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes Hypersonic SQL."

  • Products derived from this software may not be called "Hypersonic SQL" nor may "Hypersonic SQL" appear in their names without prior written permission of the Hypersonic SQL Group.

  • Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes Hypersonic SQL."

This software is provided "as is" and any expressed or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the Hypersonic SQL Group or its contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption), however caused any on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

This software consists of voluntary contributions made by many individuals on behalf of the Hypersonic SQL Group.

For content, code, and products subsequently developed by the hsqldb Development Group:

Copyright (c) 2001-2002, The HSQL Development Group
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer, including earlier license statements (above) and comply with all above license conditions.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution, including earlier license statements (above) and comply with all above license conditions.

Neither the name of the HSQL Development Group nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG, OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

5.11.2. DB2 Express-C database

DB2 Express-C

IBM DB2 Express-C is a no-charge community edition of the DB2 database server. You can visit the IBM website for further details on obtaining DB2 Express-C. Creation of an eSocket.POS database on DB2 Express-C is beyond the scope of this user guide. Contact your primary support provider for further information.

Installing the eSocket.POS database tables

See the Installation and Upgrades section for more information about installing the eSocket.POS database tables. When installing on DB2 Express-C, "CLOB" must be specified for the JDBC text data type. The property postilion.esocketpos.JdbcTextDatatype must be set to "CLOB". See Upgrade Manager properties.

5.11.3. Table definitions

Table definitions - overview

eSocket.POS uses a database to store all configuration parameters. This includes application configuration, card and account configuration, persistent state information, and a transaction store.

Information is stored in a SQL database which is updated by Configuration Agent. The Configuration Agent is external to the main eSocket.POS application. API developers do not have to concern themselves with the Configuration Agent.

Timestamp

eSocket.POS configuration is stored with a timestamp recording when this information was configured. The timestamp determines whether data is old (no longer active), active, or loading (activated once the load is complete). Only information in the active timestamp is retrieved by eSocket.POS.

The following table defines which timestamp is active:

Categories

Individual terminals are associated with a terminal category and processing category. These categories define configuration information, which is common to sets or categories of terminals, so that this configuration is not duplicated if the database is shared by more than one terminal. If this distinction is not required, only one category needs to be defined.

Terminal Configuration

Terminal Configuration is the information that varies from one terminal to the next. This is stored under the terminal ID.

The following tables define the configuration of an individual terminal. Associate that terminal with a terminal category and a processing category, and define properties which are unique to that terminal:

The following tables define dynamic state information, and a transaction store for a specific terminal:

The esp_merchandise_tran table is no longer in use, and is deprecated.

Terminal data

Terminal data includes all information that is defined once for all the terminals in a terminal category.

If the eSocket.POS database is shared by a number of terminals, this allows the integrator to differentiate between different sets of terminals.

The following tables define the configuration within a terminal category:

Processing data

Processing data includes all information about the cards and accounts that can be used across a set of terminals, as well as the merchandise products (such as prepay) available at those terminals. For this purpose, terminals are grouped into processing categories.

If the eSocket.POS database is shared by a number of terminals, this allows the integrator to differentiate between the different sets of cards and merchandise products to be allowed at different sets of terminals.

The following tables define the configuration within a processing category:

Hotcards

Hotcards are stored without a terminal ID, terminal category, or processing category and are therefore accessible to any eSocket.POS terminal using the database. They are not grouped into terminal or processing categories.

The following table stores hotcards:

Commands

Commands sent by the database-driven command mechanism are stored in the following table:

Oney

Information relating to Oney-specific functionality is stored in the following table:

Extended parameters

The extended parameters column present in a number of eSocket.POS tables provides support for associating parameters with key eSocket.POS entities (for example, cards and accounts). The extended parameters column contains a value formatted as a name/value hash table message string (which is the same format as is used in field 127.22 (structured data) of the eSocket.POS ISO8583 implementation).

Naming convention

The extended parameters naming convention is as follows:

  • <product-name-prefix>_<parameter-name>

where …​

<product-name-prefix> = the name of the product

<parameter-name> = a short parameter name

If the extended parameter value being used is part of the standard eSocket.POS installation, then the <product-name-prefix> is esp.

Formatting example

Extended Parameters: 219extended_param_name220extended_param_value221extended_param_name_b222extended_param_value_b where:

2 is the length of the length indicator of the extended parameter name;

19 is the length indicator of the extended parameter name;

extended_param_name is the extended parameter name;

2 is the length of the length indicator of the extended parameter value;

20 is the length indicator of the extended parameter value;

extended_param_value is the extended parameter value;

and so forth.

esp_account_types

esp_account_types contains English names for each of the two-digit account type codes.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..255

acc_type

The account type

n2

name

The name of the account type

ans..20

The following values are typically configured:

  • 00 - Default

  • 10 - Savings

  • 20 - Check

  • 30 - Credit

  • 40 - Transmission

esp_accounts

esp_accounts contains each attached account on each card type.

Field Notes Format

timestamp

The timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..20

bin

The bank identification number (BIN) for this card

n..13

acc_type

The account type:
10 - Savings
20 - Check
30 - Credit
40 - Transmission

n2

pin_req

Defines whether PIN entry is required:
3 - PIN entry is required, except for manual PAN entry transactions.
2 - PIN entry is not required.
1 - PIN entry is required.
0 - PIN entry is based on the service code, if check entire service code is selected.

n1

sign_req

Defines whether the cardholder’s signature is required:
1 - A signature is required.
0 - Other

n1

manual_pan_allowed

Defines whether manual PAN entry is allowed:
1 - Manual PAN entry is allowed.
0 - Other

n1

cashback_allowed

Defines whether cashback is allowed:
1 - Cashback is allowed.
0 - Other

n1

budget_allowed

Defines whether an extended payment (budget) option is allowed:
1 - An extended payment is allowed.
0 - Other

n1

min_budget_amount

The minimum amount in minor units for which an extended payment is allowed

n..12

manual_pan_standin

Defines whether an acquirer stand-in is allowed for manual PAN entry:
1 - Acquirer stand-in is allowed for manual PAN entry.
0 - Other

n1

offline_limit_purchase

The maximum transaction amount (including cashback) in minor units for which offline stand-in is allowed

Amounts above this limit must be declined if eSocket.POS is offline. Amounts above the floor limit but below the offline limit can only be approved on stand-in if eSocket.POS is offline.

n..12

floor_limit_purchase

The maximum transaction amount (including cashback) in minor units for which online stand-in is allowed

Amounts below this limit can be approved on stand-in, even if eSocket.POS is online.

n..12

offline_limit_cash

The maximum cashback amount in minor units for which offline stand-in is allowed

n..12

floor_limit_cash

The maximum cashback amount in minor units for which online stand-in is allowed

n..12

max_purchase_amount

The maximum purchase amount allowed on this account (in minor units)

A value of 0 indicates that no maximum applies.

n..12

max_cash_amount

The maximum amount allowed for cashback on this account (in minor units)

A value of 0 indicates that no maximum applies.

n..12

max_tran_amount

The maximum transaction amount allowed on this account (in minor units)

n..12

icc_fallback_allowed

Defines whether fallback from chip to magstripe is allowed:
1 - Fallback from chip to magstripe is allowed.
0 - Other

n1

card_acceptor_id

A code identifying the card acceptor for this card and account

ans15

pan_length

The PAN length for this card, used to distinguish between cards with the same BIN

This value might be zero if the PAN length is unknown or varies.

n2

generate_referral

Defines whether a referral should be generated:
1 - A referral should be generated when eSocket.POS is not connected, and the transaction amount is above the offline limit.
0 - Other

n1

acquirer_name

Identifies the acquirer for this card

ans..30

custom_data

Account data for use by custom components Suggested format:
name1='value1', name2='value2'…​

ans..

accept_issuer_decision

Indicates whether the online approval overrides device failure or not

n1

rps_type

The first digit can have the following values:
0 - Not valid for RPS
1 - Force RPS online
2 - Stand-in

The second digit can have the following values to indicate the RPS program:
1 - MasterCard
2 - Visa

n2

rps_limit

The maximum purchase amount allowed on this account (in minor units) for an RPS transaction

n..12

intervene_action

The action that a cashier must take when acquirer intervention is required on a transaction

This field usually contains a telephone number to prompt the cashier to contact the acquirer call center for voice authorization.

n..20

ext_params

The extended parameters associated with the accounts entity

The extended parameters are formatted as a name/value hashtable message string. For more information, see the Extended Parameters page.

ans..

card_name

The name of the card product that this account is attached to

ans..20

binset_category

The calculated name for the set of BINs that is associated with the attached account

ans..20

acquiring_inst_id

The acquiring institution ID associated with the totals group of the attached account

ans..11

cvm_required_lim_ctls

The maximum transaction amount (including cashback) in minor units for which cardholder verification is not required

Transactions with amounts above this limit will require cardholder verification, if it is configured for this account.

Note
This limit applies to contactless transactions.

n..12

floor_lim_ctls

The maximum transaction amount (including cashback) in minor units for which online stand-in is allowed

Amounts below this limit can be approved offline, even if eSocket.POS is online.

Note
This limit applies to contactless transactions.

n..12

receiving_inst_id

The receiving institution ID code (field 100) of the ISO 8583 message, defining which sink node the payments system must route the transaction to

n..11

additional_signature_cvm_limit

The minimum transaction amount in minor units for which signature requests will always occur

Amounts below or equal to this limit might not require signature capture.

n..12

technologies

The technologies (as a comma-separated field) used with this mapping

This field is a required field, with xx as the default. These values should map to PAN entry modes as defined in the ISO 8583 message field 22.

ans..100

disallow_reversals

Indicates whether reversals should be allowed or not:
1 - Reversals are not allowed.
0 - Reversals are allowed.

n1

disallow_refunds

Indicates whether refunds should be allowed or not:
1 - Refunds are not allowed.
0 - Refunds are allowed.

n1

esp_acq_ca_map

esp_acq_ca_map contains the store’s card acceptor mappings for acquirers.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

acq_ca_map_category

The calculated name for the set of acquirer and card acceptor mappings used by various other entities

ans..20

acquirer_name

The name of the acquirer used with this mapping

ans..30

mapped_ca_id

The code identifying the card acceptor used with this mapping

ans15

intervene_action

The action that a cashier must take when acquirer intervention is required on a transaction

This field usually contains a telephone number to prompt the cashier to contact the acquirer call center for voice authorization.

ans..20

technologies

The technologies as a comma-separated field used with this mapping

This field is a required field, with xx as default. These values should map to PAN entry modes as defined in ISO8583 message field 22.

ans..100

esp_bins

esp_bins contains all the configured BINs, together with other relevant information, grouped by category. This is used by other entities to identify which group of BINs should be associated with that entity.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

binset_category

The calculated name for the set of BINs that other entities will reference

ans..20

card_name

A name identifying the card product this set of BINs is associated with

ans..20

bin

The bank identification number (BIN) is the first part of the primary account number (PAN). When retrieving the card record for a given PAN, eSocket.POS returns the record with the longest BIN which matches the card’s PAN and PAN length.

n..13

pan_length

The PAN length for a card this BIN will be associated with

eSocket.POS uses the PAN length to distinguish between cards with the same BIN. This value might be zero if the PAN length varies or is unknown.

n2

exclude

A flag to indicate whether this BIN and PAN length combination should be excluded from the card product matching

Values:
0 - Do not exclude (default)
1 - Exclude

Note
If the same BIN ranges are configured for the same card products and one of the BIN is set to value 1 (exclude), then it excludes the entire card product from BIN matching.

n1

description

The name of the card product as it must be printed on transaction slips

This field is optional and if not specified, then the card product name itself is printed.

ans..20

esp_ca_public_key

esp_ca_public_key contains EMV Certifying Authority Public Keys.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..255

rid

The Registered Application Provider ID (RID) for the Certifying Authority (CA) which issues this public key

Contains the hexadecimal expansion of the binary RID

n..13

key_index

CA public key index for this key

ans2

modulus

Modulus for this key

Contains the hexadecimal expansion of the binary modulus

ans..

exponent

Exponent for this key
2 = 2
3 = 3
1 = 216 + 1

n1

check_sum

Check sum for this key

Contains the hexadecimal expansion of the binary check sum

ans40

activation_date

Activation date for this key (YYYYMMdd)

n8

expiration_date

Expiration date for this key (YYYYMMdd)

n8

custom_data

Additional data for this application, for use by custom components

n8

esp_cards

esp_cards contains information on all supported card types.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..20

bin

The bank identification number (BIN) for this card

This is the first part of the primary account number (PAN). When retrieving the card record for a given PAN, eSocket.POS returns the record with the longest BIN which matches the card’s PAN and PAN length.

n..13

name

A name identifying the card product.

ans..20

timeout_proc

Reserved for future use.

ans1

pan_verify

1 if the PAN must be checked using the Luhn algorithm, 0 otherwise.

n1

pan_length

The PAN length for this card

eSocket.POS uses the PAN length to distinguish between cards with the same BIN. This value might be zero if the PAN length varies or is unknown.

n2

check_exp_date

1 if the expiry date must be checked, 0 otherwise

n1

check_svc_code

0 if the service code on the card must not be checked
1 if the service code on the card must be checked
2 if the first digit of the service code must be checked

n1

svc_code_offset

Reserved for future use.

INT

check_v_period

1 if the effective date must be checked, 0 otherwise

n1

v_period_offset

Location of effective date after the separator on Track 2 (or 0 if not present)

INT

v_period_format

One of the following effective date formats in Track 2:
1: YYMM
2: MMYY
3: MM (valid period in months prior to expiration)

n1

card_seq_nr_offset

Location of the card sequence number after the separator on Track 2 (or 0 if not present)

INT

card_seq_nr_length

Length of the card sequence number on Track 2

INT

check_inq_allowed

1 if this card supports inquiries for check verification, 0 otherwise

n1

referral_telephone

Contains a telephone number to be returned in referral responses

ans..20

offline_limit_check

Check verification requests below this limit are automatically approved if eSocket.POS is offline.

n..12

floor_limit_check

Check verification requests below this limit are automatically approved if eSocket.POS is online.

n..12

cvv2_required

1 if a CVV2 value must be entered, 0 otherwise

n1

cvv2_length

The length of the CVV2 or equivalent value

n1

custom_data

Card data for use by custom components

Suggested format:
name1='value1', name2='value2'…​

ans..

mask_sensitive_data

1 if the PAN, Track 1, Track 2, and Service Restriction Code returned to the POS Application must be masked, 0 if otherwise

n1

check_embossed_pan

0 if the last four digits of the PAN must not be compared to the PAN
1 if the digits must be compared but cancel is acceptable
2 if the digits must be compared and cancel is considered to be a failure

n1

ext_params

The extended parameters associated with the cards entity

The extended parameters are formatted as a name/value hashtable message string. For more information, see the Extended Parameters page.

ans..

binset_category

The calculated name for the set of BINs that is associated with this card product

ans..20

opc_selection_mandatory

1 OPC processing should be mandatory for this card profile, 0 otherwise.

n1

default_opc_value

This is the value of the default OPC which should be used in a scenario where there are no OPC options configured. This is an optional field and if left empty, no default OPC will be assigned.

an..5

loyalty_brand

Used to identify the brand of this Loyalty Card

ans..141

loyalty_id_prefix

This is used to determine whether a Loyalty card’s identifier was correctly retrieved and starts with this configured prefix.

an..3

loyalty_id_offset

Offset within Discretionary data of ISO Track1 where Loyalty identifier exists

n..2

loyalty_id_length

Length of the Loyalty identifier

n..2

esp_classes

The esp_classes table contains information about all configured classes used by eSocket.POS.

Field Notes Format

timestamp

The timestamp identifies the configuration set for this entry, with format YYMMddHHmmss.

n12

term_category

The terminal category for the terminals where this entry is configured

ans..255

class_tag

The class tag identifies the class being configured.

ans..80

rank

The rank specifies the order of the component in the pipeline. The rank must be sequential, starting from 1. If a gap is left, ranks after the gap are ignored.

INT

class_name

The fully qualified name of the class

ans..255

params

A parameter string specific to the class chosen

ans..255

update_params

An update parameter string specific to the class chosen

It can be used to indicate a firmware update to be applied to a device.

ans..255

ext_params

The Extended Parameters associated with the class entity

See the Supported extended parameters section for more details.

ans..

Configure exactly one class for each of the following:

  • Source entity (class_tag = SOURCE)

  • Sink entity (class_tag = SINK)

  • Card reader (class_tag = CARDREADER)

  • Display (class_tag = DISPLAY)

  • Keypad (class_tag = KEYPAD)

  • PIN pad (class_tag = PINPAD)

The following devices are optional and default to NullDevice if no class is configured:

  • Smart card reader (class_tag = SMARTCARDREADER)

  • Check reader (class_tag = CHECKREADER)

  • Signature capture device (class_tag = SIGNATURECAPTURE)

  • Operator display device (class_tag = OPERATORDISPLAY)

  • Barcode reader display device (class_tag = BARCODEREADER)

Zero or more classes can be configured for the following, using a rank to indicate the order in which the components are configured in the pipeline:

  • Request pipeline components (class_tag = REQ_PIPELINE)

  • Response pipeline components (class_tag = RSP_PIPELINE)

Supported extended parameters

The following device class extended parameters are supported for esp_classes.

  • esp_snv_type - Specifies whether the device serial number must be configured in esp_device_serials for access to be allowed to the device for processing financial data.

    • 1 = true

    • 0 = false

      The default value is false.

      Note
      This parameter is only used if serial number validation is conducted in eSocket.POS authorization mode.
  • esp_snv_dependency - Specifies whether a device is blocked for processing financial data if serial number validation fails for another device associated with the same terminal. For example, it can stipulate whether a magnetic stripe reader is blocked if serial number validation fails for the smartcard reader, where the two readers are provided by separate physical devices.

    • 1 = true

    • 0 = false

      The default value is false.

  • esp_snv_interval - The interval, in minutes, at which serial number validation must occur.

    • A value of "0" indicates that serial number validation must be performed only once, at startup.

    • A value greater than zero indicates that serial number validation must occur at startup and at fixed intervals thereafter.

    • If the value is not set, then serial number validation only occurs if the DEVICE_SERIAL_NR_VALIDATE event is raised by the POS application.

esp_command_requests

The esp_command_requests table stores commands sent using the database driven command mechanism.

Field Notes Format

id

Identifier that is unique for all requests originating from the same VM

n..

source

Name of the entity sending the command

This value is unique across VMs. The following values are allowed:

  • eSocket.POS

  • eSocket.POS Configuration Agent

  • eSocket.POS Upgrade Manager

as..50

destination

Name of the entity receiving this command

as..50

command

The command string

ans..255

parameters

The command parameters

ans..255

date_logged

The timestamp, in YYYYMMddHHmmss format, showing the time that this command was sent

n14

term_id

Terminal ID

ans8

status

The command status can be set to:

  • 0 - request

  • 1 - response

n1

response

The command response

ans..255

esp_config

The esp_config table includes configuration of general parameters for eSocket.POS.

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

term_category

The terminal category for the terminals where this entry is configured

ans..255

cardswipe_init

NO LONGER USED

n1

esp_currency_countries

The esp_currency_countries table stores a static mapping from a currency code to the countries using that currency. This table is populated for multi-country currencies, like the euro (EUR) or US dollar (USD).

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..255

currency_code

The 3-digit numeric currency code

For example, 978 for the euro.

a3

country_code_numeric

The numeric country code, expressed as an integer value

For example, 840 for the USA.

n3

esp_device_config

The esp_device_config table includes configuration of device parameters for eSocket.POS. Each line represents a physical device connection at a POS terminal.

Note that this table allows either serial or TCP/IP communication to be configured. One or the other must be included in the table, but not both.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

term_id

The terminal ID

ans8

device_tag

A tag identifying the device

See the device-specific user guide for details on the device-tag and filter classes.

ans..80

remote_ip_address

The remote host name or IP address at which to connect to the device (TCP/IP connections only)

ans..15

remote_port

The remote port at which to connect to the device (TCP/IP connections only)

n..5

serial_port

Not used

See the sap_address field description for details.

ans..12

baud_rate

The baud rate at which to communicate with the device, for example, 9600 or 19200 (serial connections only).

n..5

data_bits

The number of data bits, for example, 7 or 8 (serial connections only).

n1

stop_bits

The number of stop bits, for example, 1 or 0 (serial connections only).

n1

parity

The parity of the connection: 0=none, 1=odd, 2=even (serial connections only).

n1

filter_class

The name of a class to act as a filter to handle communications with the device

See the user guide page for the specific device.

ans..255

params

A list of space-separated parameters for communication with the device

Values can be included in any order.

For serial connections, the following optional values can be included to specify flow control:

  • RTSCTS_IN (hardware flow control on communication from the device)

  • RTSCTS_OUT (hardware flow control on communication to the device)

  • XONXOFF_IN (software flow control on communication from the device)

  • XONXOFF_OUT (software flow control on communication to the device)

Hardware and software flow control cannot be used simultaneously.

For serial connections, the following optional value can be specified for error handling:

  • NOTIFY_FAILURE (Notify serial port failure on error): This option enables throwing a Device Failure exception (as a failure notification) on the serial port if I/O errors occur during serial communication. To enable the setting it must be set to 1. For example, NOTIFY_FAILURE=1. This option is disabled by default.

For serial connections, the following optional value can be specified:

  • SERIAL_LIB (Serial Port Connectivity Library): This setting can be used to configure a specific serial port connectivity library. The following libraries may be selected using this setting:

    • SERIAL_LIB=0 (Oracle Java Communication Implementation) - This is the default library

    • SERIAL_LIB=1 (RXTX Communication Implementation) - This is an alternate library that can be used in a Linux environment.

For TCP/IP connections, the following optional values can be included:

  • CONN_TIMEOUT (Connection Timeout): This indicates the number of seconds to wait for the device to be connected before a connection timeout. The default value for this parameter is 15 seconds. For example, CONN_TIMEOUT=5.

ans..80

custom_sap_factory

The postespos.core.node.ASapFactory implementation that must be used by DeviceConnection to establish the connection to the device

ans..255

sap_address

The remote address of the device

For example, the name of the serial port to which the device is connected, such as COM1 (serial connections only).

ans..128

setup_data

The setup data required by the Custom Sap Factory to set up a SAP connected to the device.

ans..100

rank

The device group (rank) of the device.

n..4

sap_protocol

Indicates the protocol used for the device’s connection

Valid values are:

  • 1 - TCP/IP Client

  • 2 - Serial

  • 3 - Custom

  • 4 - TCP/IP Server

n1

custom_data

Terminal physical device data for use by custom components

Suggested format:
key1=value1, key2=value2…​

ans..

esp_device_serials

The esp_device_serials table stores allowed serial number patterns which can be used for validating a peripheral device (such as a smartcard reader).

The serial number defines an allowed serial number pattern for the specified timestamp, rollout group, store ID, lane profile and terminal ID.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

rollout_group

A revision of store data

It currently only stores a set of allowed serial numbers. An example of where this can be used is to distinguish pilot terminals from stable terminals. It matches a value in esp_term_config.

ans..20

store_id

A consistent and unique identifier for the store

Note
This is distinct from the MerchantId property value which is assigned by the acquirer and for which there can be more than one value per store.

A value of % indicates that this entry applies to all stores.

ans..25

lane_prof

The lane profile which identifies a type of lane, for example a food or a self-service lane

A value of % indicates that this entry applies to all lane profiles.

ans..20

term_id

A filter for terminal IDs

This may be an actual terminal ID, a pattern using SQL syntax, or a terminal range. A value of % indicates that this entry applies to all terminals.

ans..255

serial_number

A filter for serial numbers This may be an actual serial number, a pattern using SQL syntax, or a serial range. A value of % indicates that all serial numbers are valid.

ans..255

The pattern-matching algorithm used for matching term_id and serial_number values is configured using the PatternMatcher system property.

esp_device_updates

The esp_device_updates table stores information about the file downloads for device drivers.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

term_id

The terminal ID

ans8

filename

The name of the file

ans…​255

md5

The md5 hash of the file data

ans..32

result

The result of the file send

ans8

serial_number

The serial number of the device

ans..255

esp_emv_aid

The esp_emv_aid table contains information on all EMV applications supported by the terminal.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..20

aid

The application identifier (AID) for this terminal application

It contains the hexadecimal expansion of the binary EMV value.

ans10..32

app_ver_nr

Application Version Number from a card

It contains the hexadecimal expansion of the binary EMV value.

ans4

ddol

Default DDOL (Dynamic Data Authentication Data Object List)

It contains the hexadecimal expansion of the binary EMV value.

ans..

tdol

Default TDOL (Transaction Certificate Data Object List)

It contains the hexadecimal expansion of the binary EMV value.

ans..

partial_match

1 if the application can be selected using a partial match to the card application
0 otherwise

n1

custom_data

Additional data for this application, for use by custom components

Values entered in this field can be either space- or semi-colon-separated.

ans..

latest_app_ver_nr

The latest application version number for this application

ans4

scheme_name

The descriptive name for the EMV scheme, for example, VISA

ans..20

floor_limit_chip

Floor limit for ICC transactions on this AID

n..12

term_act_code_default

Terminal Action Code - Default

ans10

term_act_code_denial

Terminal Action Code - Denial

ans10

term_act_code_online

Terminal Action Code - Online

ans10

target_percent

Target percent for random selection

n2

max_target_percent

Maximum target percent for biased random selection

n2

threshold_value

Threshold value for biased random selection

n..12

cvm_required_limit_ctls

The maximum transaction amount for which cardholder verification will not be required

This limit applies to contactless transactions.

n..12

floor_limit_ctls

The maximum transaction amount for which online stand-in will occur

This limit applies to contactless transactions.

n..12

tran_limit_ctls

The maximum transaction amount for contactless transactions

n..12

term_act_code_default_ctls

Contactless Terminal Action Code - Default

ans10

term_act_code_denial_ctls

Contactless Terminal Action Code - Denial

ans10

term_act_code_online_ctls

Contactless Terminal Action Code - Online

ans10

tran_limit_ctls_dcv

The maximum transaction amount for DCV(on-Device Cardholder Verification) contactless transactions

n..12

priority

Ranks the list of AIDs attached to an AID class

n2

aid_type

The type of the AID:
1 - International
2 - Domestic
3 - US

n1

cvm_required_limit

The maximum transaction amount for which cardholder verification will not be required

This limit applies to contact transactions.

n..12

ext_params

Additional data for this application stored in a structured data format, for use by custom components

ans..

loyalty_bic

Bank Identifier Code

an..11

loyalty_brand

Used to identify the brand of this Loyalty Card

ans..141

loyalty_id_tag

The configured EMV tag holding the Loyalty identifier

ans..19

loyalty_id_length

Length of the Loyalty identifier

n..2

esp_emv_bin

esp_emv_bin contains information on all BINs for which EMV parameters are configured.

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..20

bin

The BIN for the record

n..13

floor_limit_chip

Floor limit for ICC transactions on this BIN

n..12

tac_denial

Terminal Action Code - Denial

ans10

tac_online

Terminal Action Code - Online

ans10

tac_default

Terminal Action Code - Default

ans10

target_percent

Target percent for random selection

n2

max_target_percent

Maximum target percent for biased random selection

n2

threshold_value

Threshold value for biased random selection

n..12

custom_data

Additional data for this BIN, for use by custom components

ans..

pan_length

The PAN length for this BIN record

eSocket.POS uses the PAN length to distinguish between records with the same BIN. This value can be zero if the PAN length varies or is unknown.

n2

esp_hotcards

esp_hotcards contains information on all cards marked as hot.

Field Notes Format

timestamp

Identifies which hotcard set this belongs to

YYMMddHHmmss

ans12

pan

The card number (PAN) of the hotcard

n..19

rsp_code

The hold response code to be returned

n2

auth_id_rsp

The authorization ID response to be returned

ans6

seq_nr

The card sequence number

n3

tel_nr

Combination of the telephone number of someone at the card issuer and the hotcard category, in the following format:

<tel nr>|<hc cat>

Note
If there is no hotcard category, then the pipe character is not required. Otherwise, it is required.

ans..25

ans..20|an..2

entry_date

The date this hotcard was entered

date

hashed_pan

The hash value of the PAN as a hexadecimal string

an..512

hash_algorithm

The indicator of the algorithm used to create the PAN hash value

n1

esp_merchandise_config

The esp_merchandise_config table stores merchandise configuration details for a specific network and product.

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..255

pos_product_id

The product ID as specified by the EPOS

ans..50

network_id

The network ID for this merchandise product

ans..12

product_id

Not used

See the product_id_long field for details.

ans..12

network_name

The network name for this merchandise product

ans..50

product_name

The product name for this merchandise product

ans..50

merchandise_type

Identify the type of merchandise associated with this merchandise product

The following values are currently supported:

  • TELEPHONE PREPAY

  • ELECTRICITY

  • OTHER

ans..30

receiving_inst_id

This is used in Postilion to route the merchandise transaction to the correct Sink Node.

ans..11

obtain_user_id

Set this to true (1) if the user must be prompted for the User ID (for example, mobile phone number).

n1

confirm_user_id

Set this to true (1) if the user must be prompted to confirm the User ID (for example, mobile phone number).

n1

obtain_card_swipe

Set this to true (1) if the user must be prompted to swipe a merchandise card.

n1

product_id_long

The product ID for this merchandise product

ans..50

esp_merchant

The esp_merchant table includes configuration of merchant parameters.

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

term_category

The terminal category for the terminals where this entry is configured.

ans..255

merchant_type

4-digit classification of the merchant’s type of business product or service.

Codes to be developed within each country

n4

card_acceptor_id_code

A 15-character code identifying the merchant

ans15

card_acceptor_name_loc

The name and location of the merchant

This is a fixed length field consisting of 4 data elements:

  • The location information (positions 1 - 23), exclusive of city, state and country

  • The city (positions 24 - 36) in which the Point-of-Service is located

  • The state (positions 37 - 38) in which the Point-of-Service is located

  • The country (positions 39 - 40) in which the Point-of-Service is located

ans40

esp_package_feedback

The esp_package_feedback table stores the information about the package download feedbacks sent to the Config Server.

Field Notes Format

package_id

The package ID of the file received from the Config Server

n12

filename

The name of the file

ans…​255

type

The package type

This can have one of the following values:

  • ZIP

  • WHITELIST

  • DEV_PARAMS

  • DEV_SOFTWARE

  • OTHER

ans…​50

device_serial_number

The device serial number of the PED on which the package is attempted to install

and…​255

status

The feedback status sent to Config Server

This can have one of the following values:

  • RECEIVED

  • INSTALLED

  • FAILED

  • IGNORED

ans…​20

status_timestamp

The timestamp, in YYMMddHHmmss format, indicating when the status was delivered to Config Server

n12

esp_opc_list

This table stores information about the possible Operation Codes (OPCs) that can be displayed for a configured card.

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..20

payment_option_code

The value of the OPC, when selected

ans..5

short_label

The short label for this OPC

ans..100

long_label

The long label for this OPC (to be used in receipts)

ans..100

opc_type

0 - OPC to select by Cardholder on the PED
1 - OPC to select by Merchant on the POS
2 - Cash Advance
3 - Balance inquiry
4 - Activation
6 - Deactivation

n1

start_date

The start date for the duration of this OPC’s operating time

CCYYMMDD

end_date

The end date for the duration of this OPC’s operating time This date includes the configured day.

CCYYMMDD

offline_standin_limit

The maximum transaction amount in minor units for which offline stand-in is allowed

n12

esp_opc_bin_map

This table stores information about the possible Operation Codes (OPCs) that are mapped to a configured card.

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

proc_category

The processing category for the terminals where this entry is configured

ans..20

bin

The BIN that the OPC is being mapped to

n..12

payment_option_code

The value of the OPC, when selected

ans..5

opc_display_order

The display order for this OPC

n2

code_support

Used for filtering to obtain the right group of OPCs associated with this card

an..5

code_support_label

The Code Support Label is unique for each Code Support value.

ans..40

ext_params

The extended parameters associated with this mapping entity

The extended parameters are formatted as a name/value hashtable message string. For more information, see the Extended Parameters page.

ans..

esp_opc_list_online

This table stores dynamic information about the possible Operation Codes (OPCs) that can be displayed for a configured card.

Field Notes Format

opc_id

The ID for this OPC

n2

payment_option_code

The value of the OPC, when selected

ans..5

short_label

The short label for this OPC

ans..100

long_label

The long label for this OPC (to be used in receipts)

ans..100

acquirer_id

The acquirer ID identifying the configuration set for this entry

ans..30

version

The configuration version associated with this OPC

ans..12

opc_type

0 - OPC to select by cardholder on the PED
1 - OPC to select by merchant on the POS
2 - Cash advance
3 - Balance inquiry
4 - Activation
6 - Deactivation

n1

start_date

The start date for the duration of this OPC’s operating time

CCYYMMDD

end_date

The end date for the duration of this OPC’s operating time

This date includes the configured day.

CCYYMMDD

offline_standin_limit

The maximum transaction amount in minor units for which offline stand-in is allowed

n12

esp_opc_bin_map_online

This table stores dynamic information about the possible Operation Codes (OPCs) that are mapped to a configured card.

Field Notes Format

bin

The BIN that the OPC is being mapped to

n..12

opc_id

The ID for the OPC being mapped

n2

opc_display_order

The display order for this OPC

n2

version

The configuration version associated with this OPC

ans..12

acquirer_id

The acquirer ID identifying the configuration set for this entry

ans..30

code_support

Used for filtering to obtain the right group of OPCs associated with this card

an..5

code_support_label

The Code Support label is unique for each Code Support value.

ans..40

ext_params

The extended parameters associated with this mapping entity

The extended parameters are formatted as a name/value hashtable message string. For more information, see the Extended Parameters page.

ans..

pan_length

The length of the PAN used in the mapping algorithm when considering an OPC for selection

n..11

card_wording

The card wording associated with this BIN

This can be printed on the receipt.

ans..40

esp_params

The esp_params table includes configuration of custom terminal category parameters (tag-value pairs).

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

term_category

The terminal category for the terminals where this entry is configured

ans..20

tag

The tag identifying the parameter

ans..255

value

The parameter value

ans..

esp_pos_config

The esp_pos_config table includes configuration of POS parameters.

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

term_category

The terminal category for the terminals where this entry is configured

ans..20

pin_entry_capability

1 Terminal can accept PINs
2 Terminal cannot accept PINs

n1

pos_pin_capture_code

The maximum number of PIN characters that can be accepted by the Point-of-Service device
Values are 04 to 12.

n2

currency_code_transaction

The default currency code of the transaction amount

n3

card_data_input_capability

0 Unknown
1 Manual, no terminal
2 Magnetic stripe read
3 Bar code
4 OCR
5 Magnetic stripe, key entry and integrated circuit card (ICC)
6 Key entry
7 Magnetic stripe and key entry
8 Magnetic stripe and integrated circuit card (ICC)
9 Integrated circuit card (ICC)
A Contactless integrated circuit card (ICC)
B Contactless magnetic stripe

n1

cardholder_auth_capability

0 No electronic authentication
1 PIN
2 Electronic signature analysis
3 Biometrics
4 Biographic
5 Electronic authentication inoperative
6 Other

n1

card_capture_capability

0 None
1 Capture

n1

operating_environment

1 On premises of card acceptor, attended
2 On premises of card acceptor, unattended
3 Off premises of card acceptor, attended
4 Off premises of card acceptor, unattended
5 On premises of cardholder, unattended

n1

cardholder_presence

0 Cardholder present
1 Cardholder not present, unspecified
2 Cardholder not present, mail order
3 Cardholder not present, telephone
4 Cardholder not present, standing authorization

n1

card_data_output_capability

1 None
2 Magnetic stripe write
3 Integrated circuit card (ICC)

n1

terminal_output_capability

1 None
2 Printing
3 Display
4 Printing and display

n1

pin_capture_capability

0 No PIN capture capability
1 Device PIN capture capability unknown
4 Four characters
5 Five characters
6 Six characters
7 Seven characters
8 Eight characters
9 Nine characters
A Ten characters
B Eleven characters
C Twelve characters

n1

terminal_operator

0 Customer operated
1 Card acceptor operated
2 Administrative

n1

terminal_type

Values are specified in the Transaction Manager Interface Specification. Refer to the Terminal Type subfield of POS Data Code (field 123).

n2

terminal_owner

The name of the merchant where the POS terminal is located

ans..25

pos_geographic_data

This contains a series of codes to identify the state, county, postal service code and country code where the POS device is physically located. This data element is defined in ANSI X9.2 (1988).

The layout is as follows:

  • The numeric state code (positions 1 - 2)

  • The numeric county code (positions 3 - 5)

  • The alphanumeric postal service code (positions 6 - 14)

  • The numeric country code (positions 15 - 17)

If any of the sub-fields is not used, it must be set to spaces.

ans17

sponsor_bank

This identifies the institution sponsoring the card acceptor POS terminal.

ans8

term_country_code

Terminal country code

n3

term_capabilities

EMV terminal capabilities

It contains the hexadecimal expansion of the binary EMV value.

ans6

add_term_cap

EMV additional terminal capabilities

It contains the hexadecimal expansion of the binary EMV value.

ans10

emv_term_type

EMV terminal type. Typically '22'

n2

auto_aid_selection

This indicates if automatic selection of an application for a multi-application card is enabled.
1 - True
0 - False

The default is 0.

n1

supported_languages

The list of supported languages

The 2-character language codes are concatenated to form this list.

a60

prompt_language

A two-character language code used during EMV transactions when the list of supported languages does not contain the cardholder’s preferred language

It is also used to retrieve the resource bundle to use for non-EMV prompts.

a2

customer_lang_selection

This indicates if manual language selection is enabled.
1 - True
0 - False

The default is 0. Manual language selection is disabled.

n1

aid_selection_method

The method used to select the application identifier (AID) during EMV transactions:

0 - Default
1 - US Common Debit AID prioritized
2 - International AID prioritized
3 - Debit/Credit selection
4 - Highest-priority AID selection
5 - Merchant prioritized customer AID selection

n1

acquirer

Identifies the default Acquirer

ans..30

acquiring_inst_id

Identifies the default acquiring institution ID Code

n..11

receiving_inst_id

Identifies the default receiving institution ID Code

n..11

esp_properties

The esp_properties table stores the eSocket.POS properties that were remotely configured, typically via Configuration Server, and loaded by eSocket.POS. The property configuration in this table is given preference over the eSocket.POS properties file.

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set for this entry

n12

property_name

The name of the property

ans..255

property_value

The value of this property that was configured remotely

ans..255

Note
If a property is included in this table with a blank property_value, eSocket.POS will ignore this property - regardless of how it is configured in the properties file.
esp_state

The esp_state table stores persistent state information internal to eSocket.POS. Note that this table does not contain a timestamp column and is not updated during configuration.

Field Notes Format

term_id

The terminal ID

ans8

sys_trace

Initial value is 0

Thereafter, the value is incremented each time eSocket.POS initiates a message to Realtime (for example, a key exchange message).

n..5

tran_nr

Initial value is 0

Thereafter, the value is incremented each time eSocket.POS assigns a Transaction Number to a message.

n..6

tran_sequence_counter

Initial value is 1

Thereafter, the value of the transaction sequence counter is incremented for each new transaction.

n..8

custom_state

This column stores additional custom state information about the terminal. This data is accessed by device drivers and custom pipeline components using the eSocket.POS InformationServer class. The format is internal to eSocket.POS and this data must not be modified manually.

ans..

esp_support_events

The esp_support_events table stores events for the purpose of reporting them centrally at the Realtime system.

Field Notes Format

term_id

Terminal ID

ans..8

event_id

Event ID

n..

severity

0-Informational, 1-Warning, 2 - Error

n1

description

A description of the event

ans..

date_logged

The date when the event was logged

ans23

delivery_status

0-Undelivered to the central monitoring system

1-In flight
2-Delivered to the central monitoring system

n1

esp_term_config

The esp_term_config table stores information about a specific terminal.

This table associates a terminal ID with a terminal category and processing category. These categories define configuration information, which is common to sets or categories of terminal. The table also defines values which may vary from one terminal to another.

Field Notes Format

timestamp

Timestamp in YYMMddHHmmss format identifying the configuration set for this entry

n12

term_id

The terminal ID

ans8

term_category

The terminal category to which this terminal belongs

ans..20

proc_category

The processing category to which this terminal belongs

ans..20

command_port

Port for UDP or TCP commands to the terminal, if a dedicated port is required per terminal

This must be set to 0 if there is a command port configured in eSocket.POS properties, or if no command port is required.

n..5

pos_seq_num

The POS terminal sequence number

ans6

terminal_name

A descriptive name for the terminal

ans..40

card_acceptor_id_code

A 15-character code identifying the merchant

ans15

card_acceptor_name_loc

The name and location of the merchant

This is a fixed length field consisting of 4 data elements:

  • The location information (positions 1 - 23), exclusive of city, state and country

  • The city (positions 24 - 36) in which the Point-of-Service is located

  • The state (positions 37 - 38) in which the Point-of-Service is located

  • The country (positions 39 - 40) in which the Point-of-Service is located

ans40

custom_data

Terminal data for use by custom components

Suggested format:
name1='value1', name2='value2'…​

ans..

rollout_group

A revision of store data

This currently only stores a sets of allowed serial numbers (see also esp_device_serials). An example of where this can be used is to distinguish pilot terminals from stable terminals.

ans..20

store_id

A consistent and unique identifier for the store

Note
This is distinct from the MerchantId property value which is assigned by the acquirer and for which there can be more than one value per store.

ans..25

lane_prof

A lane profile which identifies a type of lane, for example a food or self-service lane

ans..20

ext_params

The extended parameters associated with the terminal entity

The extended parameters are formatted as a name/value hash table message string. For more information see the Extended Parameters page.

ans..

interrupt_eligible_cards

The card products eligible for payment interrupts associated with the terminal entity

The card products are formatted as a string-separated by commas.

ans..1000

binset_category

The calculated name for the set of BINs that this terminal is configured to recognize

ans..20

acq_ca_map_category

The calculated name for the set of acquirer and card acceptor mappings that the retailer, which this terminal is part of, is configured to recognize

ans..20

dcc_support

Indicates whether dynamic currency conversion (DCC) is supported:

  • null - unknown / not set

  • 0 - not supported

  • 1 - supported

n1

terminal_blocked

Indicates whether the terminal is blocked:

  • null - not blocked

  • 0 - not blocked

  • 1 - blocked

n1

esp_timestamp

The esp_timestamp table stores information about which configuration in the database is active. This is to facilitate loading a new configuration set without disrupting the current configuration during the load.

Field Notes Format

timestamp

The timestamp, in YYMMddHHmmss format, identifying the configuration set

n12

status

  • active if this is the active configuration set

  • loading if this set is currently loading and is not yet active

  • drop if this set is marked for deletion

  • old if this set is no longer in use and is marked for deletion

ans..8

type

The configuration type to which this timestamp applies

Can be one of TERM_CONFIG, TERM_DATA, PROC_DATA, or HOTCARD

ans..12

esp_trans

The esp_trans table stores transaction request and response fields and is used to provide persistence and integrity of transactions.

Field Notes Format

tran_nr

Unique Transaction Number

n6

sys_trace

Systems Trace Audit Number (Transaction ID)

n6

term_id

Terminal ID

ans8

state

Records the state the transaction was in when last saved

10 RECEIVED_BY_SOURCE
The request message is received at the eSocket.POS source.

20 TRAN ENGINE PROCESSING REQ
The request message is being processed by the pipeline components.

25 RECEIVED BY SINK
The request message is received at the eSocket.POS sink.

28 SAF ENQUEUE
The message is placed on the store and forward queue.

30 SENT TO REMOTE
The request/advice message is sent to the remote entity.

50 RECEIVED FROM REMOTE
A response message is received from the remote entity.

60 GENERATED BY SINK
A response message was generated by the eSocket.POS sink.

70 REJECTED BY ESP
A request message was rejected by eSocket.POS.

75 ABANDONED ADVICE
An advice was abandoned after several attempts to send it to an active upstream entity without a response.

80 PROCESSING RESPONSE
The response message is being processed by the pipeline components.

90 RETURNED BY SOURCE
The response message is sent back to the source of the original transaction.

n2

msg_type

ISO 8583 message type

n4

pan

PAN (Card Number)

n..19

processing_code

Processing Code, consisting of Transaction Type, Account From and Account To

n6

amount_tran_requested

Transaction Amount from the request

n..12

amount_tran_approved

Transaction Amount approved in the response

n..12

transmission_date_time

The transmission date and time, expressed in Coordinated Universal Time (UTC), format MMddHHmmss

n12

time_local

Local time in format HHmmss

n6

date_local

Local date in format MMDD

n4

expiry_date

Expiration Date of the card in format YYMM

n4

merchant_type

Code classifying the merchant’s type of business product or service

n4

pan_entry_mode

PAN Entry Mode

n2

card_seq_nr

Card Sequence Number of the card

n3

pos_condition_code

POS Condition Code

n2

fee_tran

Transaction fee (reserved)

n..12

fee_tran_proc

Transaction fee (reserved)

n..12

track2_data

Track 2 Data of the card.

z..37

ret_ref_no

Retrieval Reference Number

an12

auth_id_rsp

Authorization ID Response

an6

rsp_code

Response Code

n2

rsp_code_rev

Response Code sent in Reversal message

n2

service_restriction_code

Service Restriction Code of the card

n3

card_acceptor_id_code

Card Acceptor ID Code

ans15

card_acceptor_name_loc

Card Acceptor Name and Location

ans40

additional_rsp_data

Contains the Referral Telephone Number

ans..25

additional_data

note

ans..

currency_code_tran

Currency Code of the acquirer

n3

amount_cash_requested

Cashback Amount in the request

n..12

amount_cash_approved

Cashback Amount approved in the response

n..12

msg_reason_code

Message Reason Code

n4

auth_life_cycle_code

Authorization Life-cycle Code

n3

authorizing_inst

Authorizing Agent Institution

n..11

echo_data

(reserved)

ans..255

extended_payment_code

Extended Payment Period in months

n2

orig_data_elements

(reserved)

n42

replacement_amounts

May contain the Final Amount

an42

payee

(reserved)

ans25

receiving_inst

(reserved)

n..11

account_id_1

(reserved)

ans..28

account_id_2

(reserved)

ans..28

pos_data_code

POS Data Code

n15

switch_key

Switch Key used to match transactions by Postilion

ans..32

pos_operator_id

POS Operator ID

ans8

service_station_data

(reserved)

ans73

auth_profile

Authorization Profile

n2

check_data

Check Data

ans..50

retention_data

(reserved)

ans..

additional_node_data

(reserved)

ans..

original_key

Original key used to link to a previous transaction

ans..32

address_verification_data

Address Verification Data

ans..29

address_verification_result

Address Verification Result

ans1

validation_data

(reserved)

ans..50

bank_details

(reserved)

ans31

structured_data

Structured Data, excluding fields with the 'do not persist' flag set

ans..

payee_name_and_address

(reserved)

ans253

payer_account_id

(reserved)

ans..28

icc_data_req

ICC Request Data. This is the ICC Data constructed during the request leg of the message and contains the first cryptogram.

ans..

icc_data_rsp

ICC Response Data. This is the ICC Data constructed during the response leg of the message and contains the second cryptogram.

ans..

structured_data_rsp

Structured Data Response, excluding fields with the "do not persist" flag set

ans..

extended_tran_type

The Extended Transaction Type

n4

date_settlement

Settlement Date

n4

bin

The bank identification number (references esp_cards)

n..13

pan_length

The PAN length (references esp_cards)

n2

custom_data

esp_trans data for use by custom_components

ans..

rsp_code_req

The response code of the request message

n2

msg_reason_code_req

The message reason code of the request message

n4

linked_tran_seq_nr

The sequence number of a linked transaction in a list of chained transactions

n…​4

dcc_status_code

The DCC Status Code set during the request leg of dynamic currency conversion (DCC) message flow

ans..10

pos_data

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

  • The POS terminal ID (positions 1 - 8) identifying the POS terminal, for example, a cash register, on which the transaction was performed.

  • The POS sequence number (positions 9 - 14) specifying the POS terminal sequence number.

  • The POS operator ID (positions 15 - 22) specifying the cashier that performed the transaction.

ans22

dcc_status_code_rsp

The DCC Status Code set during the response leg of dynamic currency conversion (DCC) message flow.

ans..10

encrypted_pan

The encrypted PAN (Encrypted value of Card Number)

an..512

encrypted_track2_data

Encrypted value of Track 2 Data of the card

By default, this is not saved to comply with Visa Cardholder Information Security Program (CISP) requirements.

an..512

encrypted_account_id1

Encrypted value of account_id_1

an..512

encrypted_account_id2

Encrypted value of account_id_2

an..512

encrypted_payer_account_id

Encrypted value of payer_account_id

an..512

key_alias

Key alias used to encrypt the data

ans..24

extended_auth_id_rsp

(reserved)

ans..8

acquiring_inst

(reserved)

n..11

esp_update

The esp_update table stores information about updates that are applied by eSocket.POS. Note that this table does not contain a timestamp column and is not updated during configuration.

Field Notes Format

term_id

The terminal ID

ans8

class_tag

The tag of the class which applied the update

This corresponds to the class_tag column in esp_classes.

ans..80

update_params

The parameters of the update

This corresponds to the update_params column in esp_classes.

ans..255

oney_opc_config

This table stores information about the possible Oney Operating Codes (OPCs) that can be displayed for a configured card.

Field Notes Format

mid

The merchant identifier code for this entry

ans..15

extended_bin

The BIN that the OPC is being mapped to

n..10

code_support

Used for filtering to obtain the right group of OPCs associated with this card

an..5

code_support_label

The Code Support Label is unique for each Code Support value.

ans..40

pin_code_flag

0 = Giftcard (no PIN ever, N/A)
1 = Yes
2 = No

n1

allow_cancellations

0 = No
1 = Yes

n1

allow_refunds

0 = No
1 = Yes

n1

opc_code

The value of the OPC, when selected

ans..5

short_label

The short label for this OPC

ans..10

long_label

The long label for this OPC (to be used in receipts)

ans..40

opc_type

0 = OPC to select by Cardholder on the PED
1 = OPC to select by Merchant on the POS
2 = Cash Advance
3 = Balance Enquiry
4 = Activation
6 = Deactivation

n1

start_date

The start date for the duration of this OPC’s operating time

CCYYMMDD

end_date

The end date for the duration of this OPC’s operating time

This date includes the configured day.

CCYYMMDD

opc_display_order

The display order for this OPC

n2

standin_amount

The maximum transaction amount in minor units for which offline stand-in is allowed

n12

esp_capks_online

esp_capks_online contains a set of online EMV Certifying Authority (CA) Public Keys.

Field Notes Format

emv_file_version

The file version received in the file download for the CA public keys

ans..255

rid

The Registered Application Provider ID (RID) for the Certifying Authority (CA) which issues this public key

Contains the hexadecimal expansion of the binary RID

n..10

key_index

CA public key index for this key

ans2

modulus

Modulus for this key

Contains the hexadecimal expansion of the binary modulus

ans..

exponent

Exponent for this key
2 = 2
3 = 3
1 = 2 16 + 1

n1

check_sum

Check sum for this key

Contains the hexadecimal expansion of the binary check sum

ans40

activation_date

Activation date for this key (YYYYMMdd)

n8

expiration_date

Expiration date for this key (YYYYMMdd)

n8

custom_data

Additional data for this application, for use by custom components

ans..

Pattern syntax

A pattern is a string of characters with optional wild cards included that matches a set of strings. The available wild cards and examples of their usage are listed below.

Wildcard character Description Example

%

Any string of zero or more characters

'%computer%' matches all strings with the word 'computer' anywhere in the string.

_ (underscore)

Any single character

'_ean' matches all four letter strings that end with ean (Dean, Sean, and so on).

[ ]

Any single character within the specified range ([a-f]) or set ([abcdef])

Alternatively, this is used to escape any single character that would otherwise be interpreted as a special character (that is, ^-_%[]).

'[C-P]arsen' matches strings ending with arsen and beginning with any single character between C and P, for example Carsen, Larsen, Karsen, and so on.

'100[%]' matches the string '100%'.

[^]

Any single character not within the specified range ([^a-f]) or set ([^abcdef])

'de[^l]%' matches all strings beginning with de and where the following letter is not l.

5.12. Config Agent

5.12.1. Configuration Agent

The eSocket.POS Configuration Agent is the gateway used to upload configuration information into the eSocket.POS Database. Although it is an integral part of the eSocket.POS solution, it runs independently of the main eSocket.POS application. This allows for configuration changes to be made even if the POS application is not running.

Configuration, hotcard, and update files

Five types of files are processed by the Configuration Agent:

  • Update files, in zip format. These can contain device firmware updates or other file updates, and are unzipped to a location specified by a file root_dir.txt inside the zip file.

  • Configuration files, in XML format. Three separate files are supported: Terminal Configuration, Terminal Data and Processing Data, and each of these may be either a full or an incremental file.

  • Hotcard files, in hotcard file format. Full or incremental hotcard files are supported.

  • Custom SQL data scripts, in SQL format. These can be used to deliver configuration data for custom eSocket.POS components that have their own database tables.

  • File Upload Requests, in XML format. These can be used to cause eSocket.POS to upload requested files to Config Server.

    The types of files that can be uploaded to Config Server are: Terminal Traces eSocket.POS Traces Config Agent Traces eSocket.POS Log

These files are generated using the central eSocket.POS Configuration Server (ConfigServer). See the eSocket.POS Configuration Server User Guide for details.

NOTE::Update files are processed before any configuration files.

Loading new files

At configurable intervals or via a system command, the Configuration Agent polls a specified directory for new configuration files of the types specified above. Files may transferred from the ConfigServer into this directory by one of two methods:

  • The Configuration Agent can be configured to download them from the ConfigServer using HTTP.

  • The files may be delivered to the Configuration Agent directory via a third-party mechanism.

When new files become available, the Configuration Agent first validates the files and then loads them into the eSocket.POS database.

Once the load is successfully completed, the new configuration comes into effect in the eSocket.POS application. If a Config ID is configured, a timestamp file called <config_id>.ts is created containing the timestamps that have just become active.

The Configuration Agent can be configured to maintain a certain number of past configuration sets in the eSocket.POS database.

Failed software updates

If a software update consists of more than one file, all files must be processed for the software update to succeed. If a failure occurs with any of these files, then all update files that are processed during the update are rolled back. In addition, any configuration files accompanying the failed update files are ignored.

ConfigAgent Dependency Validation

If the postilion.esocketpos.ConfigAgentEnableSoftwareValidation property is enabled, then the ConfigAgent checks for the presence of the required class files before applying configuration updates. The ConfigAgent compares the class name values found in the Terminal Data configuration file with the currently-installed class files. If there are any inconsistencies in the class files required and the class files currently installed, then the ConfigAgent does not apply the configuration update (that is, Terminal Data, Terminal Config, Processing Config and so on). Missing class files are reported by ConfigAgent in the ConfigAgent trace, in PackageFeedback sent to ConfigServer, and by logging an CONFIG_AGENT_CLASS_FILES_MISSING event.

5.12.2. Configuration Agent Using Internet Connectivity

Connections over the public internet are inherently less secure than using a private network or VPN connection. Therefore the overall best practice for configuration distribution is to use a private network or VPN connection. If you have assessed the risks associated with using the public Internet and deemed them acceptable, this page documents some best practices that should be adhered to in addition to your own organization’s security best practices.

Configuration over the public internet is only supported in conjunction with the terminal activation sequence enabled by the activation pipeline component.

Best practices when connecting over the public internet
  • Set the configuration property that indicates connections are made over the public internet.

  • Provide an initial TLS key pair and client certificate and configure the alias in the properties file. This should only be used for initial configuration rollout when the terminal does not have an activated TLS key pair. Once it is activated, ConfigAgent will make use of the activated TLS key pair instead of the initial TLS key pair that has been provided.

  • Avoid using the same initial key pair for all eSocket.POS instances. This is especially important if your ConfigServer configuration allows the initial key pair to access most or all configuration, software and files. If your ConfigServer is locked down to only allow configuration required for activation (see ConfigServer user guide), you can consider using the same initial key pair for all eSocket.POS instances. You will need to have a strategy for revoking a single key pair if it becomes compromised so that it can be replaced for future rollouts.

  • Limit the validity of any initial public key certificate to as short as possible. Ideally, just enough time to allow a successful configuration download which would allow activation.

  • Make use of configuration signing and verification.

  • Consider loading initial configuration in a secure location before a terminal is deployed. This would allow the terminal to activate with the EFT switch and subsequently retrieve configuration from ConfigServer using the activated key pair. It therefore reduces the risk of needing a preconfigured TLS key pair to be able to distribute configuration to eSocket.POS.

5.12.3. Running the Configuration Agent

Running Config Agent as part of the eSocket.POS service

The Config Agent service is no longer installed by default during the installation as all its features can now be achieved using the main eSocket.POS service.

In order to run the Config Agent service as part of the eSocket.POS service, you have to use the -ca option in the parameters for that service.

If that is done, Config Agent must not be run simultaneously as the eSocket.POS service will achieve everything Config Agent does.

Refer to the page on The new Service for details on how to update the settings for the service.

Running the Configuration Agent as a separate Windows service

If you choose to run Config Agent as a separate service from the main eSocket.POS service, you have to first create the Config Agent service as this is no longer created during the installation. The Service Util tool helps easily create the service.

Once created, the Config Agent service may then be started and stopped from the Windows Services manager.

Running the Configuration Agent separately from the eSocket.POS service has the advantage that these services can be stopped and started independently, while running them in the same service has the advantage of reducing overall system requirements, as only one Java VM is run.

Refer to the page on Running eSocket.POS as a Windows service for details on how to update the settings for the service.

Running the Configuration Agent from the command line

The Configuration Agent may be started using the following command line:

<java> <classpath> postilion.esocketpos.config.ConfigAgent <command_line_parameters>

where <java> <classpath> is the invocation of the Java virtual machine with classpath parameters.

The <command_line_parameters> are discussed below.

Command line parameters
Field Notes Format

properties_file

The fully qualified path of the eSocket.POS properties file.

eg: c:\eSocket.POS\esp_properties.txt

ans..255

The Configuration Agent is a long-running application that, for maximum benefit, must never be terminated. Once started, it polls a user specified directory at configurable intervals for new upload files. It may also be configured to poll once at a configurable time or at startup, and then quit.

Running the Configuration Agent from the eSocket.POS API

A POS developer using the eSocket.POS API can start the Configuration Agent from within their own application, using the startConfigAgent method. Refer to the eSocket.POS Developer Guide for more information.

eSocket.POS properties

The Configuration Agent reads its own configuration from the eSocket.POS properties. Please see the Configuration Agent Properties page for more information on the required properties.

5.12.4. Configuration Agent commands

CommandUtil

The CommandUtil command line tool can be used to send a command to the Configuration Agent to trigger an immediate configuration download from the Configuration Server. The CommandUtil tool can be used as follows:

<jvm> <classpath> postilion.esocketpos.util.CommandUtil <command_line_parameters>

where <jvm> <classpath> is the invocation of the Java virtual machine with classpath parameters.

e.g. java -cp C:\WINDOWS\java\classes;C:\postilion\eSocket.POS\bin\postespos-sdk.jar postilion.esocketpos.util.CommandUtil 192.168.232.131 60007 CONFIG_NOW

The <command_line_parameters> are discussed below.

Command line parameters
Field Notes Format

host/ip

The host/ip of the machine running Configuration Agent

eg: 192.168.0.1

an

port

The port at which the Configuration Agent service is running.

eg: 60007

n..1-65535

command

The command which should be sent to the Configuration Agent service.

Currently, ' CONFIG_NOW ' is the only supported command. This command triggers Configuration Agent to begin an immediate configuration download from Configuration Server.

eg: *CONFIG_NOW*

an

5.12.5. Configuration Agent properties

The Configuration Agent reads the configuration parameters from eSocket.POS properties. Further details on the Configuration Agent-specific options are listed below. In addition, the Configuration Agent requires the PropertiesFilePath, JDBC, LogDriver, and Log4J properties as described in the eSocket.POS properties documentation.

If connecting via the public internet, the TLS key store and TLS trust store related properties need to be configured. See Configuring the SSL keystore and Configuring the SSL truststore respectively for the relevant properties.

NOTE

Properties that are not remotely configurable are marked as such with an *.

Property Description

postilion.esocketpos.ConfigAgentTracePath

Specifies the path where trace files for Config Agent are stored.

postilion.esocketpos.ConfigAgentTrace

Specifies the Trace behavior at startup.

  • 'ON' or '<entity> <entity>…​ <entity> ON' turns tracing on (globally or for the specified entities) when eSocket.POS starts,

  • 'CLEAR' or '<entity> <entity>…​ <entity> CLEAR' turns tracing on and clears the trace file.

See tracing settings for further details.

postilion.esocketpos.ConfigAgentTraceStyle

Specifies the Trace Style at startup. Possible values include

  • NORMAL

  • CASCADE

    NOTE

    If this property is not specified, the Trace Style chosen is CASCADE

postilion.esocketpos.ConfigAgentTraceNrLines

Specifies the maximum number of lines that the detailed trace file may contain.

NOTE

The default is 100000 if this property is not configured.

postilion.esocketpos.ConfigAgentTraceNrFiles

Specifies the maximum number of Configuration Agent trace files that the trace viewer can contain (default is 5 if this property is not configured)

postilion.esocketpos.IncomingConfigPath

The directory that the Configuration Agent must monitor for incoming upload files, and where the timestamp file is created after files are successfully loaded.

For example,
Windows: "c:\\postilion\\esocket.pos\\incoming"
Linux: "/usr/etc/esocketpos/upload/"

*This property cannot be configured remotely.

postilion.esocketpos.ConfigPollStartTime

The time at which the Configuration Agent must begin polling for incoming configuration files. This value is only used when the Configuration Agent starts up. Since all subsequent polls are performed relative to this first one, this 'start time' provides some mechanism for effecting a poll at a specific time. This value is modified by ConfigDownloadJitterTime property.

For example, configuring the Configuration Agent to start at 00:00 with a poll interval of 24 hours results in a poll once a day at midnight.

The value for this property must be a 4-digit 24 hour time. A value of "9999" indicates that the file must be read at startup.

For example,
"1500" (3pm)

postilion.esocketpos.ConfigPollOnStartUp

Indicates that Configuration Agent must check for new processing data and terminal data downloads immediately on startup. This value is modified by ConfigDownloadJitterTime property or ConfigStartupJitterTime property depending upon the configuration.

For example, "True" check for new processing data and terminal data downloads.

postilion.esocketpos.ConfigDownloadJitterTime

The time interval (in minutes) after the polling start time, within which Configuration Agent must select a random time when to start polling for configuration files. This property affects the behaviour of ConfigPollStartTime and ConfigPollOnStartUp.

postilion.esocketpos.ConfigStartupJitterTime

The time interval (in minutes) after the polling start time, within which Configuration Agent must select a random time when to start polling for configuration files. If this value is not set, it will default to the ConfigDownloadJitterTime. This property affects ConfigPollOnStartUp property. Also if this property is configured, it overrides the ConfigDownloadJitterTime property only for startup.

postilion.esocketpos.HotcardPollStartTime

The time at which the Configuration Agent must begin polling for incoming hotcard files. This value is only used when the Configuration Agent starts up. Since all subsequent polls are performed relative to this first one, this 'start time' provides some mechanism for effecting a poll at a specific time.

For example, configuring the Configuration Agent to start at 00:00 with a poll interval of 24 hours results in a poll once a day at midnight.

The value for this property must be a 4-digit 24 hour time. A value of "9999" indicates that the file must be read at startup.

For example, "1500" (3pm)

postilion.esocketpos.HotcardPollOnStartUp

Indicates that Configuration Agent must check for new hotcard configuration downloads immediately upon startup.

For example, "True" check for new hotcard downloads.

postilion.esocketpos.DisableHotcardDownload

Indicates that Configuration Agent must not download hotcard files. Note that Configuration Agent still polls for, and applies hotcard files.

For example, "True" do not attempt to download hotcard files.

postilion.esocketpos.HotcardDownloadJitterTime

The time interval (in minutes) after the hotcard polling time, within which Configuration Agent must select a random time when to start polling for hotcard files.

postilion.esocketpos.ConfigPollInterval

The time (in minutes) the Configuration Agent must wait between polls for configuration files. If set to "0", the load is only attempted once. If both this and the hotcard poll interval are set to "0", the Configuration Agent quits after both loads are attempted once.

postilion.esocketpos.HotcardPollInterval

The time (in minutes) the Configuration Agent must wait between polls for hotcard files. If set to "0", the load is only attempted once. If both this and the config poll interval are set to "0", the Configuration Agent quits after both loads are attempted once.

postilion.esocketpos.ConfigDownloadNrRetries

The maximum number of times Configuration Agent retries configuration and hotcard file downloads from the HTTP server when a download failure occurs during a poll interval. If this property is not specified, then a failed download is retried 3 times. A value of "0" disables this functionality (failed downloads are not retried).

NOTE

Configuration Agent waits a random amount of time between 25 and 30 seconds between retry attempts.

postilion.esocketpos.ConfigDownloadNrRetriesPerFile

The maximum number of times Configuration Agent retries downloading a particular file from the HTTP server when a download failure occurs. These per-file retry attempts will occur within each download attempt described for the property above. If this property is not specified, then a failed download of a file is retried 3 times. A value of "0" disables this functionality (failed downloads are not retried on a per-file basis).

NOTE

Configuration Agent waits 30 seconds between per-file retry attempts.

postilion.esocketpos.ConfigHistorySize

The number of old configuration sets which the Configuration Agent must maintain. This an optional property and its value can be any non-negative number.

Note that:

  • If this property is not set, the Configuration Agent does not delete old configuration sets.

Important
In this case the database grows indefinitely, so this is not recommended in production.
  • If this property is set to 0, the Configuration Agent does not maintain any old configuration sets, i.e. it deletes old configuration data as soon as new configuration data is successfully activated.

  • If this property is set to a numeric value larger than 0, the Configuration Agent maintains as many old configuration sets in the eSocket.POS database as the specified number.

  • If the postilion.esocketpos.ApplyConfigurationOnResync property is set, old configuration sets that are still in use by terminals may still exist, and may not be deleted. The number of old configuration sets specified by this property to be maintained is therefore in addition to those marked as currently in use by one or more terminals.

postilion.esocketpos.ConfigId

ConfigServer uses this property to determine which configuration files are required for this instance of eSocket.POS.

It is constructed as follows:

< Retailer ID >_< Configuration Set >

The specified retailer ID and configuration set must be configured in the ConfigServer database, or no configuration files will download. See the ConfigServer User Guide for more details about the retailer ID and configuration set.

By convention, if eSocket.POS is installed on each cash register, then the Configuration Set must be the Terminal ID.

For example:

MyStore_12345678

  • This property cannot be configured remotely.

postilion.esocketpos.StoreId

ConfigServer uses this property to identify the store.

  • This property cannot be configured remotely.

postilion.esocketpos.MachineId

If the eSocket.POS machine ID is not automatically determined, the Machine ID can be manually configured in the eSocket.POS properties file using this property. This must be a text string up to 24 characters drawn from the alphabet (A-Z), digits (0-9) and minus sign (-). No blank or space characters are permitted as part of a name. The first character must be an alpha character. The last character must not be a minus sign.

Default: the default value for this property is the eSocket.POS machine’s hostname.

  • This property cannot be configured remotely.

postilion.esocketpos.ConfigHttpServer

The name of the HTTP server from which the Configuration Agent must download new configuration and hotcard files. This may either be an IP address such as 137.1.2.34 or else the name of the server such as bob.com.

If this property is set, then the Configuration Agent attempts to connect to the server and retrieve new files whenever the poll intervals have run out. If this property is not set, then the Configuration Agent monitors the IncomingConfigPath directory for new files.

  • This property cannot be configured remotely.

postilion.esocketpos.ConfigServerPort

The port number of the HTTP server. This must only be set if the ConfigHttpServer property is set.

  • This property cannot be configured remotely.

postilion.esocketpos.ProxyHttpServer

The name of an optional HTTP Proxy Server through which the Config Agent sends requests for new configuration and hotcard files. This may either be an IP address, such as 123.1.2.3, or the name of the server, such as bob.com.

If this property is set, then caching of configuration files occurs at the HTTP proxy server. If this property is not set, then a direct connection is established to the server, and new files are downloaded directly from the server. This property only has an effect if the postilion.esocketpos.ConfigHttpServer property is set.

  • This property cannot be configured remotely.

postilion.esocketpos.ProxyServerPort

The port number of the HTTP Proxy server. This must only be set if the ProxyHttpServer property is set.

  • This property cannot be configured remotely.

postilion.esocketpos.MaxFeedbackUploadSize

Specifies the maximum size of a single upload of feedback files to ConfigServer. Config Agent attempts to minimize uploads by packaging feedback files into a single upload, up to the maximum set with this property. A value of 0 (zero) forces Configuration Agent to deliver only one feedback file at a time. Similarly, if the maximum size is smaller than a single feedback file, only one file is uploaded. If the maximum is larger than one file, Configuration Agent packages the feedback files into the upload until the maximum size is reached. The remaining feedback files are uploaded at the next attempt.

Default: The default is 2048 (KB) if this property is not configured.

NOTE

The size is in kilobytes (KB) and only integer values are valid. If this property value is greater than 195 KB and IIS is integrated with Config Server then it is required to update IIS configuration also by adding IIS Configuration property maxRequestEntityAllowed. For more details about how to update IIS Configuration property maxRequestEntityAllowed see the IIS page of the ConfigServer User Guide.

postilion.esocketpos.ScriptName

This must only be set if the ConfigHttpServer property is set.

If ConfigServer is using IIS, then this property is the location and name of the script file to use when contacting the HTTP server. The location refers to the script files virtual directory, which is /webserver/config.asp.

If the ConfigServer HTTP server is used, this property must be /configserver/fileserver.

If configuration is retrieved over the public internet (see Configuration Agent Using Internet Connectivity) then ConfigServer or IIS must be accessed via a proxy server. This property must then be set to the URL that the proxy server is expecting configuration requests at. For example, /config

  • This property cannot be configured remotely.

postilion.esocketpos.ConfigSapFactory

Optional. The fully qualified Java class name of a custom Service Access Point (SAP) factory class that Configuration Agent’s HTTP client must use. This may be required in some cases to handle client-specific network issues or new functionality.

  • This property cannot be configured remotely.

postilion.esocketpos.ConfigAgentModuleProcessors

Optional. A comma (,) separated fully qualified Java class names of custom config module processors classes that Configuration Agent’s should use to download additional configs into eSocket.POS database.

  • This property cannot be configured remotely.

postilion.esocketpos.ConfigSapFactorySetupData

The setup data required by the SAP factory class, if one is configured. Refer to the documentation delivered with the SAP factory class.

  • This property cannot be configured remotely.

postilion.esocketpos.ConfigShouldResync

Boolean value indicating that Configuration Agent must send a RESYNC command to eSocket.POS when new terminal data configuration is loaded.

For example, "True" or "False"

postilion.esocketpos.ConfigShouldAbortFailedFetch

Boolean value indicating that Configuration Agent must abort the config load operation should the fetch operation fail to download new files from the HTTP Server. This prevents loading configuration that may be present in the incoming configuration directory.

NOTE

The default is True.

If this property is configured to 'False' config may still be applied from the incoming configuration directory if it was present and valid. This property only has effect if the postilion.esocketpos.ConfigHttpServer property is set.

  • This property cannot be configured remotely.

postilion.esocketpos.UpgradeRestartTime

Configuration Agent is able to send a RESTART command to eSocket.POS after new software updates or upgrades are downloaded. This property specifies the time after an update or upgrade at which the RESTART command must be sent.

The value for this property must be a 4-digit 24 hour time. A value of AfterDownload indicates that the RESTART command must be sent as soon as new updates or upgrades are downloaded.

postilion.esocketpos.VerifyDistributionFiles

Boolean value indicating if file verification must be enabled. If it is set to true Configuration Agent loads only signed files, and it only loads them if it successfully verifies both the integrity and authenticity of the files.

NOTE

When file verification is enabled the property postilion.esocketpos.SecuredConfigPath is required for both the Configuration Agent and for the Upgrade Manager.

  • This property cannot be configured remotely.

postilion.esocketpos.SecuredConfigPath

A directory on the file system with security privileges that only allows the Configuration Agent, Upgrade Manager and other 'trusted processes' write access.

Note: This property is required when file verification is enabled, otherwise it may not be present. If present, it must be configured with the same value as in Upgrade Manager properties.

  • This property cannot be configured remotely.

postilion.esocketpos.install.KeyStore

Required if sensitive properties in eSocket.POS properties are encrypted.

  • This property cannot be configured remotely.

postilion.esocketpos.JceKeyStoreType

Required if sensitive properties in eSocket.POS properties are encrypted.

  • This property cannot be configured remotely.

postilion.esocketpos.JceProvider

Required if sensitive properties in eSocket.POS properties are encrypted.

  • This property cannot be configured remotely.

postilion.esocketpos.ConfigAgentCommandPort

If configured, Configuration Agent will listen on this port for a command to trigger an immediate config download.

NOTE

In addition to this property being configured, Configuration Agent also needs to be configured to poll for new configs at a configured interval i.e. the property 'postilion.esocketpos.ConfigPollInterval' must be configured with a value greater than 0.

postilion.esocketpos.ConfigAgentCommandPortHost

If configured, Configuration Agent will only listen for commands on this host/ip address. If this property is not configured, Configuration Agent will listen on all configured ip addresses.

postilion.esocketpos.ConfigAgentCommandPortTrustedHosts

A semi-colon(;) separated list of trusted hosts/ip’s from which commands will be accepted by Configuration Agent. If this property is not configured, commands will be accepted from any host.

NOTE

If you only want to allow connections from the machine on which Configuration Agent is running then use the host name or the network interface configured ip address. Do not use localhost/127.0.0.1.

postilion.esocketpos.ConfigAgentSqlQueryOutputDir

The directory that the Configuration Agent must use to output the results of SQL queries. The results of those queries will be output to the file "ConfigAgent_SqlQuery.log" in this directory. This file will be overwritten during each poll but only when new queries need to be run. The queries referred to here are any "SELECT" statement(s) defined in ".sql" files which are added to the Terminal Profile in the ConfigServer Store and Terminal console and which are downloaded and run by Configuration Agent.

NOTE

The user/account under which the Configuration Agent runs must have write access to this directory. If not specified, the queries will still run but results will not be saved to disk.

postilion.esocketpos.ConfigAgentSoftwareUpdateBatchSize

A positive integer, indicating the number of software update files that Config Agent should process in an update before deleting these processed files. This feature is disabled when the property is not configured.

NOTE

Any processed files that are not deleted during the processing phase will be deleted the next time Config Agent performs an update. For example, if the property is configured to delete every 5 files, but there are 2 files left, these files will not be deleted in that update session.

postilion.esocketpos.ConfigAgentConnectOverInternet

Indicates that ConfigAgent will be connecting over the public internet to retrieve configuration.

Should be set to TRUE if connecting over the public internet.

Accessing configuration over the public internet is not without risk and a careful risk assessment should be completed before connecting over the public internet. Refer to Best Practices.

If configured, ConfigAgent will attempt to use an activated client certificate (see Pipeline component - Activation) for TLS negotiation. If there is no terminal activated on this eSocket.POS machine, then it will attempt to use the certificate alias configured with postilion.esocketpos.UnactivatedClientCertAlias. If it is not configured or there is not a valid certificate at that alias in the TLS key store, then no client certificate will be presented during TLS negotiation.

  • This property cannot be configured remotely.

postilion.esocketpos.UnactivatedClientCertAlias

The default client certificate alias to use from the TLS key store (see Configuring the SSL keystore). This certificate is used if postilion.esocketpos.ConfigAgentConnectOverInternet is configured and a terminal has not yet been activated. This certificate can be used by ConfigServer to authenticate the client (eSocket.POS machine) before there are activated terminals on this machine.

  • This property cannot be configured remotely.

postilion.esocketpos.ConfigServerPortUnactivated

This is an alternate port on which ConfigServer listens for connections. eSocket.POS machines that do not yet have an activated terminal connects to this port instead of the port configured using property postilion.esocketpos.ConfigServerPort. This port at ConfigServer can then be locked down to only serve the configuration needed to activate as opposed to all configuration.

This property only applies when postilion.esocketpos.ConfigAgentConnectOverInternet is configured.

  • This property cannot be configured remotely.

postilion.esocketpos.ConfigAgentSendPedInstallFeedback

This property indicates whether Config Server should be notified of the whitelist file install status on the PED. This can be set to "True" or "False".

For example, "True" Notify Config Server of the whitelist file install status on the PED.

NOTE

The default is "False" if this property is not configured.

postilion.esocketpos.FileUploadPollStartTime

The time at which the Configuration Agent must begin polling for incoming upload request files. This value is only used when the Configuration Agent starts up. Since all subsequent polls are performed relative to this first one, this 'start time' provides some mechanism for effecting a poll at a specific time.

For example, configuring the Configuration Agent to start at 00:00 with a poll interval of 24 hours results in a poll once a day at midnight.

The value for this property must be a 4-digit 24 hour time. A value of "9999" indicates that the file must be read at startup.

postilion.esocketpos.FileUploadPollInterval

The time (in minutes) the Configuration Agent must wait between polls for upload request files. If set to "0", the load is only attempted once.

postilion.esocketpos.FileUploadPollOnStartUp

Indicates that Configuration Agent must check for new upload requests immediately on startup.

For example, "True" check for new upload requests.

postilion.esocketpos.FileUploadJitterTime

The time interval (in minutes) after the polling start time, within which Configuration Agent must select a random time when to start polling for upload request files.

postilion.esocketpos.ConfigAgentEnableSoftwareValidation

A Boolean value indicating whether ConfigAgent Dependency Validation must be enabled. This can be set to "TRUE" or "FALSE".

NOTE

The default is "False" if this property is not configured.

5.13. Upgrade Manager

5.13.1. Upgrade Manager - overview

Major and minor upgrades, service packs, and patches can be delivered to the eSocket.POS deployment from a central location by using eSocket.POS Upgrade Manager. The upgrades are applied during the POS or Store Server’s boot process, before any eSocket.POS application starts up. This is because updates to the database, class file, and JAR file cannot be made while any dependent application is already running. The Upgrade Manager is also used for deploying and upgrading custom Pipeline Components and Device Integrations.

For remote upgrades to be processed, the Upgrade Manager must be run during the boot process. Please refer here for instructions on running the Upgrade Manager. The Upgrade Manager is configured using eSocket.POS properties. Refer to Upgrade Manager properties for details.

Upgrade manager can update eSocket.POS properties file if the upgrade requires it.

Upgrade delivery

The Upgrade Manager uses the same delivery mechanism as the Config Agent. Each time it is run, it polls the Config Agent’s IncomingConfigPath for new upgrades. Any files conforming to the following naming convention are processed as upgrades: setup_<app_name>_<version>_build<build_nr>_r<SDK_version>.jar. See the Naming convention page for more details about the Config Agent file naming convention.

Files may be transferred from the ConfigServer into this directory by one of two methods:

  • The Config Agent can be configured to download them from the ConfigServer using HTTP.

  • The files may be delivered directly to the Config Agent directory via a third-party mechanism.

In both cases, upgrades are scheduled for the next reboot. If multiple upgrades are delivered simultaneously, they are applied in timestamp order. Other Config Agent files that are delivered at the same time or later - such as configuration files - are not applied by the Config Agent until the upgrade is successfully run.

Failed upgrades

The Upgrade Manager tags all files that are successfully processed by appending "_processed_<TIMESTAMP>". However, if an error occurred during an upgrade, any changes made during the upgrade are rolled back. The offending file is tagged by appending "_failed_<TIMESTAMP>". Other upgrades or Config Agent files delivered with the upgrade are rolled back if they have already been applied, or are ignored if they have not been applied yet.

Unsupported Java virtual machines

To configure a different Java virtual machine please refer to the eSocket.POS Windows services topic.

Troubleshooting

The Upgrade Manager cannot make use of the standard eSocket.POS error reporting channel (Event Log or Log4J), since it may need to upgrade this functionality. Instead, informational and error events are recorded in a log file in the incoming directory: esp_upgrade.log. The following problems are common with upgrades:

  • Database access problems: an upgrade may require access to the eSocket.POS database. Make sure that the database is accessible when the Upgrade Manager is run. Refer to the Database upgrades topic for more details (especially if the deployment of eSocket.POS uses HSQLDB).

  • JAR file access problems: an upgrade may need to update a JAR file used by eSocket.POS. JAR files that are in use may be locked on some operating systems (including, Microsoft Windows). Make sure that no other eSocket.POS application is running when the Upgrade Manager is run. In addition, make sure that no JAR files are on the CLASSPATH when the Upgrade Manager is run (some Java VMs lock JARs on the classpath, even if the application is not using them).

Rollback

Any changes that are applied by a standard eSocket.POS version upgrade (major, minor or service pack) or patch from eSocket.POS v2.2 onwards can be undone by executing a rollback for the upgrade or patch from the command line. It is possible to rollback the last successful or unsuccessful version upgrade to its previous version and it is also possible to rollback (uninstall) any of the patches on the installed version.

The rollback mechanism is intended to allow clients to perform an upgrade and immediately undo the upgrade if a problem is encountered. Care must be taken not to attempt a rollback to a previous version of an application once a configuration change that relies on the new application version is applied.

Note
The rollback is supported for upgrades that are installed using the self-executing JAR installer or the upgrade manager, but it is not possible to rollback upgrades that are installed manually or with the setup.exe.

If the patch or upgrade was delivered directly to the Config Agent directory via a third-party mechanism, a rollback is performed from the command line.

  • Stop all eSocket.POS services before attempting a rollback.

  • In the case of a major, minor or service pack version rollback, first rollback all of the installed patches by following the rollback instructions distributed with each patch.

  • Locate the rollback executable JAR which is installed to the rollback sub-directory of the applications installation directory, e.g. C:\Postilion\eSocket.POS\rollback. The rollback executable for a standard eSocket.POS upgrade is named as follows: rollback_<app_name>_<version>_build<build_nr>_r<SDK_version>.jar

  • Run the rollback executable JAR from the command line, with the following parameters: -p < properties_file> , where < properties_file> is the location of the Upgrade Manager properties , e.g. the following command-line rollback version 1.1 of an application called "DeviceDriverX", which was built on eSocket.POS v2.5.

    java -jar rollback_DeviceDriverX_v1.1_build_12345_r2.5.jar -p C:\Postilion\eSocket.POS\properties.txt

If the patch or upgrade was downloaded from the ConfigServer using HTTP, ConfigServer must be updated. This involves removing the patch or upgrade from the Software Profiles under the ConfigServer Remote Software Deployment console. Thereafter, a rollback is performed on eSocket.POS from the command line as described above.

Note
Although standard eSocket.POS upgrades support rollback, rollback support is dependent on the application being upgraded or patched. See the documentation distributed with the application or patch for detailed information.
Rollback of eSocket.POS from v2.7 or later, back to eSocket.POS v2.6 or earlier

The normalized processing data introduced in eSocket.POS v2.7 is not compatible with any version of eSocket.POS earlier than v2.7. Therefore, if normalized data exists in the database prior to a rollback, the rollback will fail.

To rollback eSocket.POS from v2.7 or later, back to v2.6 or earlier, the database must be cleared of all normalized data. This can be done by manually deleting the content of the esp_cards and esp_accounts tables. Following the rollback, a full download of configuration data is required for eSocket.POS to continue operation.

Uninstall

To uninstall a manual installation of eSocket.POS, the user has to manually perform the following steps:

  • Drop the eSocket.POS database. See installation on using the DatabaseInstaller to DROP the database.

  • Manually delete the eSocket.POS installation directory.

To uninstall an automatic installation of eSocket.POS, perform the steps as documented in eSocket.POS Java installation utility - Uninstalling eSocket.POS section of the user guide on steps for uninstallation of the application.

Note
When upgrading eSocket.POS using the self-executing JAR installer or the upgrade manager, and then uninstalling eSocket.POS using the uninstaller, some upgraded content may remain, as the uninstaller is not packaged with the self-executing JAR installer. This content may be deleted manually.

5.13.2. Running the Upgrade Manager

The Upgrade Manager must be started or run each time the POS or Store Server is booted up, before any eSocket.POS applications are started.

Running the Upgrade Manager as part of the eSocket.POS service

The Upgrade Manager service is no longer installed by default during the installation as all its features can now be achieved using the main eSocket.POS service.

In order to run the Upgrade Manager service as part of the eSocket.POS service, you have to use the -um option in the parameters for that service.

If that is done, Upgrade Manager must not be run simultaneously as the eSocket.POS service will achieve everything the Upgrade Manager does.

Refer to the page on The new Service for details on how to update the settings for the service.

Running upgrade manager as a separate Windows Service

If you choose to run the Upgrade Manager as a separate service from the main eSocket.POS service, you have to first create the Upgrade Manager service as this is no longer created during the installation. The Service Util tool helps easily create the service.

Once created, the Upgrade Manager service may then be started and stopped from the Windows Services manager. It is recommended that other eSocket.POS services are defined as dependent on the Upgrade Manager service.

Important note: When starting the Upgrade Manager Windows service from the command line, the command

sc start EspUpgrManager

must be used instead of

net start EspUpgrManager

This is because Upgrade Manager installs patches/upgrades during startup, which means it can be in the "starting" state for an extended period of time. However, the net start command is synchronous and waits for a service to start up (i.e. enter the "started" state) before terminating. If a service does not start up in less than 30 seconds, it is considered a failure and the service is terminated. This could result in Upgrade Manager not installing all the available patches or not completing an upgrade. The sc start command does not have this problem as it is asynchronous and does not wait for the service to enter the "started" state.

When using sc start , the sc query command can be issued afterwards to check when the service has started up. The STATE value in the output will be 2 (START_PENDING) while it is still starting up. The STATE value will be 4 (RUNNING) once it has started.

Running the Upgrade Manager from the command line

From the command line, the Upgrade Manager is a short-lived process, starting up, looking for and applying available upgrades, and then terminating. It is not a long-running service \ daemon process like eSocket.POS or the Config Agent.

The Upgrade Manager may be run using the following command line:

<java> <classpath> postilion.esocketpos.upgrade.UpgradeManager <command_line_parameters>

where <java> <classpath> is the invocation of the Java virtual machine with classpath parameters.

The <command_line_parameters> are discussed below.

Command line parameters
Field Notes Format

-p <properties_file>

The fully qualified path of the eSocket.POS properties file.

eg: c:\eSocket.POS\esp_properties.txt

ans..255

eSocket.POS properties

The Upgrade Manager reads its own configuration from the eSocket.POS properties. Please see the Upgrade Manager properties page for more information on the required properties.

5.13.3. Upgrade Manager properties

The Upgrade Manager reads configuration parameters from eSocket.POS properties. Below are more details on the options that are specific to the Upgrade Manager. In addition, the Upgrade Manager requires the PropertiesFilePath and JDBC properties, described in the eSocket.POS properties documentation, and the IncomingConfigPath property, described in the Configuration Agent properties documentation.

If a non-mandatory property does not have a value configured, the default value is used. If the default values are not satisfactory, they must be explicitly configured.

NOTE

Properties that are not remotely configurable are marked as such with an *.

Property Mandatory Description

postilion.esocketpos.install.HomeDir

Yes

The root directory of the eSocket.POS installation.

e.g. Windows: "c:\\postilion\\eSocket.POS"
Linux: "/opt/postilion/eSocket.POS"

*This property is not remotely configurable.

postilion.esocketpos.install.ClassPath

Yes

This must contain the full eSocket.POS classpath, including all eSocket.POS JAR files and additional JAR files (for example, JDBC drivers). Please see here for details.

*This property is not remotely configurable.

postilion.esocketpos.install.SupportRollback

No

eSocket.POS upgrades records all installation steps to the database and installs an executable JAR file that can be used to rollback any changes made by the upgrade. This property can be set to false to disable rollback support in environments where disk space is an issue.

Default value: true

postilion.esocketpos.JdbcTextDatatype

No

The SQL data type to use for TEXT data in the eSocket.POS database. This depends on the database platform that eSocket.POS is installed on. This must be set to the same value as was used during the database installation.

Default value: TEXT

postilion.esocketpos.install.ClassDir

No

The eSocket.POS class file root directory.

e.g. Windows: "c:\\WINNT\\java\\classes"
Linux: "/opt/postilion/eSocket.POS/classes"

Default value: The location of the postilion.esocketpos. Version class file on the ClassPath property.

*This property is not remotely configurable.

postilion.esocketpos.install.JarDir

No

The eSocket.POS jar file directory.

e.g. Windows: "c:\\postilion\\eSocket.POS\\bin"
Linux: "/opt/postilion/eSocket.POS/classes"

Default value: The location of the esocket-tools.jar file. This is <home_dir>\\bin on a Windows deployment, or <home_dir>/classes on a manual deployment. Both locations are tested and the first that contains the JAR file is used.

*This property is not remotely configurable.

postilion.esocketpos.ConfigId

No

Required to create a feedback file.

*This property is not remotely configurable.

postilion.esocketpos.install.KeyStore

No

Required if sensitive properties in the eSocket.POS properties file are encrypted - see eSocket.POS properties.

*This property is not remotely configurable.

postilion.esocketpos.JceKeyStoreType

No

Required if sensitive properties in the eSocket.POS properties file are encrypted - see eSocket.POS properties.

*This property is not remotely configurable.

postilion.esocketpos.JceProvider

No

Required if sensitive properties in the eSocket.POS properties file are encrypted - see eSocket.POS properties.

*This property is not remotely configurable.

postilion.esocketpos.JdbcDriver

No

See eSocket.POS properties

postilion.esocketpos.JdbcUrl

Yes

See eSocket.POS properties

postilion.esocketpos.JdbcUser

Yes

See eSocket.POS properties

postilion.esocketpos.JdbcUserPassword

Yes

See eSocket.POS properties

postilion.esocketpos.hsqldb_params

No

This is required if eSocket.POS uses HSqlDB in server-mode as an eSocket.POS Windows Service.

*This property is not remotely configurable.

postilion.esocketpos.IncomingConfigPath

Yes

See Configuration Agent properties.

postilion.esocketpos.SecuredConfigPath

No

A directory on the file system with security privileges that only allows the Configuration Agent, Upgrade Manager and other 'trusted processes' write access.

NOTE

This property is required when File Verification is enabled and it must be configured with the same value in Configuration Agent properties.

*This property is not remotely configurable.

5.13.4. Database upgrades

The eSocket.POS Upgrade Manager may require database access during an upgrade, to apply database upgrade scripts to the eSocket.POS database. Database access is achieved using the JDBC properties. Additionally, any JAR or class files required to load the JDBC driver must be included in the ClassPath property (refer to eSocket.POS properties for more information).

It is also important that the database server is running when the Upgrade Manager is run.

HSQLDB support

For most database platforms, standard JDBC access is used. However some special processing may be done for deployments using HSQLDB.

  • If HSQLDB is being used in standalone-mode (the JDBC URL is of the form j dbc:hsqldb:file:<file_path> ):

    • a SHUTDOWN command is sent to the database when the upgrade is complete. This ensures that all changes are applied.

  • If HSQLDB is being used in server-mode (the JDBC URL is of the form j dbc:hsqldb:hsql://<ip_address> ), and is embedded in an eSocket.POS Windows Service (the postilion.esocketpos.hsqldb_params property is configured):

    • the embedded HSQLDB server is started as a separate thread within Upgrade Manager;

    • and, a SHUTDOWN command is sent to the database when the upgrade is complete. This ensures that all changes are applied and the server thread terminates.

5.13.5. Properties file upgrades

eSocket.POS Upgrade Manager provides a framework for eSocket.POS extensions and plugins to update the default properties file during their installation/upgrade. This is achieved by providing a properties.actions file in the root directory of the installation jar. Each line of this file should have an action that the Upgrade Manager should perform on the properties file. The following actions are supported :

Action Description

add

This action is used to add a new entry in the properties file.

Usage: add <property_name> = <property_value>

where property_name is the property to be added and property_value is its value. This action is used to add a new entry in the properties file.

If the property is already defined in the properties file, it will not be updated. In order to force an update of the value even if the property is already set, the -f or --force switch must be used as follow:

add -f <property_name> = <property_value> or add --force <property_name> = <property_value>

To include the value of an existing property as part value of the property being added, you have to put the property inside double braces {{ property_name }} .

Examples

  • add postilion.esocketpos.itk.fixed.nodePort = 40000

  • add -f postilion.esocketpos.mfe.class.name = postilion.espitk.posinterface.ItkFrontEnd

  • add --force postilion.esocketpos.itk.fixed.nodePort = 40000

  • add -f postilion.esocketpos.service.EspRun.Parameters=-p {{postilion.esocketpos.PropertiesFilePath}} -xml

remove

Deletes the specified property and its value from the properties file if found.

Usage: remove <property_name>

with <property_name> being the name of the property to be removed from the properties file. If the property is not found, the action will be ignored.

Example

  • remove postilion.esocketpos.xmlinterface.eSocketPosSchemaFile

NOTE

Those properties file actions are case-sensitive

5.14. Structured Receipt Scripting Language (SRSL)

5.14.1. About SRSL

The Structured Receipt Scripting Language (SRSL) is a compact scripting language used to define the format of receipts.

Refer to the commands reference for more detailed information.

Basic concepts

A scripting language behaves in the following way:

  • The scripts are read and parsed top-down, one line at a time.

  • The scripts consist of various statements and commands that tell the printer driver how to display text on the receipts.

  • More than one statement and command can be written on one line, and the white space (such as spaces, tabs, and line-feeds) do not influence the result.

5.14.2. Getting started: Receipt printing

Receipt printing overview

Receipt printing in eSocket.POS is provided by the following components:

  • A Receipt Printer pipeline component

  • SRSL - the Structured Receipt Scripting Language used by the Receipt Printer pipeline component to produce receipts

An example receipt definition is provided as a starting point. This definition is configured to cater for the following:

  • A customer receipt

  • A merchant copy of the receipt

  • A merchant batch totals receipt

  • A merchant batch totals receipt

  • A signature line when no digital signature verification was performed

Note
The example makes use of the SRSL printer names that are supported by the Receipt Printer pipeline component.
{
Printer types:

all: All printers

cust_approved: Customer receipt for an approved transaction.
cust_declined: Customer receipt for a declined transaction.
cust_reprint_approved: Customer receipt reprint (approved transaction).
cust_reprint_declined: Customer receipt reprint (declined transaction).

merch_approved: Merchant receipt for an approved transaction.
merch_declined: Merchant receipt for a declined transaction.
merch_reprint_approved: Merchant receipt reprint (approved transaction).
merch_reprint_declined: Merchant receipt reprint (declined transaction).

merch_totals_approved: Merchant batch totals receipt (approved).
merch_totals_declined: Merchant batch totals receipt (declined).

signature: Receipt that requires a signature.
}

{REPRINT Merchant receipts}
printer(merch_reprint_approved)
printer(merch_reprint_declined)

  [uppercase("merchant reprint")]c24 @eol

{REPRINT Customer receipts}
printer(cust_reprint_approved)
printer(cust_reprint_declined)

  [uppercase("customer reprint")]c24 @eol

{Customer copy}
printer(cust_approved)
printer(cust_declined)

    [uppercase("customer's receipt")]c24 @eol

{Merchant copy}
printer(merch_approved)
printer(merch_declined)

    [uppercase("merchant's receipt")]c24 @eol

{Customer welcome message}
printer(cust_approved)
printer(cust_declined)
printer(cust_reprint_approved)
printer(cust_reprint_declined)

     ["Welcome to the Store!"]c24 @eol @eol

{ALL receipts}
printer(all)

    [#terminal_owner]c24 @eol @eol
    "Terminal ID: " #term_id @eol
    format(#time,"dd/MM/yyyy") ^ format(#time,"HH:mm:ss") @eol @eol

printer(cust_approved)
printer(cust_declined)
printer(cust_reprint_approved)
printer(cust_reprint_declined)
printer(merch_approved)
printer(merch_declined)
printer(merch_reprint_approved)
printer(merch_reprint_declined)

  {The card details are only printed if they are available.}

  optional(#pan,
    undef: "" |
    default : "Card number: " #pan @eol)

  optional(#card_seq_nr,
    undef : "" |
    default : "Seq nr: " #card_seq_nr @eol)

  optional(#emv_tag_ApplicationIdentifier,
    undef : "" |
    default : "AID: " #emv_tag_ApplicationIdentifier @eol)

  optional(#emv_tag_TerminalVerificationResult,
   undef : "" |
   default : "TVR: " #emv_tag_TerminalVerificationResult @eol)

  @eol

  "Tran type: " optional(#tran_type,
                           "00" : "PURCHASE" |
                           "20" : "REFUND" |
                           default  : "Other") @eol @eol

{MERCHANT receipts}
printer(merch_approved)
printer(merch_declined)
printer(merch_reprint_approved)
printer(merch_reprint_declined)

  "From account: " #from_account @eol
  "To account: " #to_account @eol @eol

{APPROVED receipts}
printer(cust_approved)
printer(merch_approved)
printer(cust_reprint_approved)
printer(merch_reprint_approved)
printer(merch_totals_approved)

  ["Approved"]c24 @eol @eol
  optional(#auth_nr, "???" : "" | default: "Auth nr: " #auth_nr @eol @eol)

{DECLINED receipts}
printer(cust_declined)
printer(merch_declined)
printer(cust_reprint_declined)
printer(merch_reprint_declined)
printer(merch_totals_declined)

  {Message reason code also required for declined transactions.}
  ["Declined"]c24 @eol @eol
  "Msg Reason Code: " #msg_reason_code @eol @eol

printer(cust_approved)
printer(cust_declined)
printer(cust_reprint_approved)
printer(cust_reprint_declined)
printer(merch_approved)
printer(merch_declined)
printer(merch_reprint_approved)
printer(merch_reprint_declined)

  ["Total amount: "]l13 [format(#amount, %symbol %major "." %minor)]r11 @eol
  "Response code: " #rsp_code @eol @eol

{Receipts requiring a SIGNATURE}
printer(signature)

  @eol @eol @eol
  "Signature: _____________________" @eol @eol

{CUSTOMER receipts}
printer(cust_approved)
printer(cust_declined)

  ["Thanks for visiting!"]c24 @eol

{BATCH TOTALS receipts}
printer(merch_totals_approved)

    "Credits, number: " #credits_nr @eol
    "Credits, reversal number: " #credits_rev_nr @eol
    "Debits, number: " #debits_nr @eol
    "Debits, reversal number: " #debits_rev_nr @eol
    "Transfers, number: " #transfers_nr @eol
    "Transfers, reversal number: " #transfers_rev_nr @eol
    "Inquiries, number: " #inquiries_nr @eol
    "Authorizations, number: " #auths_nr @eol
    "Credits, processing fee amount: " #credits_proc_fee_amount @eol
    "Credits, transaction fee amount: " #credits_tran_fee_amount @eol
    "Debits, processing fee amount: " #debits_proc_fee_amount @eol
    "Debits, transaction fee amount: " #debits_tran_fee_amount @eol
    "Credits, amount: " #credits_amount @eol
    "Credits, reversal amount: " #credits_rev_amount @eol
    "Debits, amount: " #debits_amount @eol
    "Debits, reversal amount: " #debits_rev_amount @eol
    "Amount, net settlement: " #amount_net_settle @eol
    "Payments, number: " #payments_nr @eol
    "Payments, reversal number: " #payments_rev_nr @eol

{ALL receipts}
printer(all)
@cut

5.14.3. SRSL commands

SRSL commands overview

This section serves as a SRSL command reference.

SRSL provides the following commands:
Display field description

Maps name_string using a locale-based resource bundle.

Display field value

Inserts the value of a field

Insert blank space

^

Inserts blank space

Insert comment

Comment text (not displayed)

Insert text

Inserts unparsed text

String operations

Left-aligns, right-aligns, or centers text, with or without truncation

Character duplication

Inserts n copies of char

Format string

Inserts the value of a field, formatted

Formatting statement

Format object s according to SRSL

Optional statement

Depending on the value of object, process the SRSL indicated by option

Select printer(s)

Selects a conceptual printer

Control characters

Inserts printer control characters

Set to uppercase

Convert string to uppercase

Move down

Move the printer head down n lines

Locale statement

Changes the active locale for all subsequent calls to lookup

The locale is changed to the value of locale_text, which is expected to be a valid locale designator.

Lookup statement

Looks up lookup_text from the ReceiptMessages resource bundle family, using the current active locale

Optionally, resolves to SRSL if lookup_text has no resource bundle message configured.

Block receipt

Insert SRSL

If SRSL occupies fewer than n lines, fill with blank lines.

Convert hex to binary

Converts hextext from a string of hex-ASCII characters to a string of bytes, where a byte is represented by two hex digits (0-9, A-F)

Block receipt
SRSL: block command

Symbol

block

Syntax

block (n, SRSL)

Function

Ensures that printing ends at least n lines from its current position, while printing the second parameter

If the SRSL definition in the second parameter finishes past n lines, then printing will resume from that position. This command can be used in the following situations:

  1. A conditional statement was used and depending on the outcome of the condition, n number of lines was printed, where n is not known.

  2. A message will be printed, but the message length is unknown.

  3. n number of lines are to be reserved for the header.

Example

block ( 5, “HELLO†) “BYE†- parses the second parameter as an SRSL definition, then ensures that printing of BYE begins at least 5 lines after HELLO has been printed. This is typically used for pre-printed receipts, and alignment needs to be maintained. See ('Example).

Character duplication
SRSL: & (repeat character)

Symbol

&

Syntax

& char

n

Function

Inserts n copies of char. Note that n < 100.

Examples

&X5 prints XXXXX

&b2 prints bb

&s3 &o3 &s3 prints sssooosss

Control characters
SRSL: \ (control characters)

Symbol

\

Syntax

Function

Inserts a control character.

Control characters can be device-dependent. Ensure that any control characters that are used in receipt definitions are supported by the devices.

Note
The hex command

is used for inserting strings of arbitrary binary data, such as graphics.

Examples

The following SRSL fragment:

"This is an" \QUOTE "example" \QUOTE

outputs:

This is an "example"

\FF form-feeds the receipt.

\VT % changes the character set ( \VT ) and prints the £ symbol from that set (%).

Convert hex to binary
SRSL: hex command

Symbol

hex

Syntax

hex("hextext")

Function

Converts hextext from a string of hex-ASCII characters to a string of bytes, where a byte is represented by two hex digits (0-9, A-F)

Example

SRSL: hex("414349")

Output: a string of bytes of value 65, 67, and 73, corresponding to the ASCII characters ACI

Display field description
SRSL: @ (map name using a locale-based resource bundle)

Symbol

@

Syntax

@ name_string (no spaces between @ and name_string)

Function

Uses the resource bundle family named ReceiptMessages to map name_string to a value

The resource bundle is queried using the current active locale (which is set using the locale command).

Refer to PipelineComponentReceiptPrinter - Resource Bundles for an overview of how resource bundles are used with SRSL.

Examples

Assuming that there is a ReceiptMessages resource bundle with the following mappings:
@footer=Thank you for visiting
@footer will produce: Thank you for visiting

Additionally, eSocket.POS provides the following list of names for device driver implementations to map to device-specific values:

SRSL Name Default value Description

@bold

<Empty string>

Denotes bold text

@center

<Empty string>

Centers the text

@cut

\n\n\n\n

Advances the receipt so that it may be cut or torn

@double_height

<Empty string>

Denotes text printed with a double-height font

@double_width

<Empty string>

Denotes text printed with a double-width font

@eol

\n

Advances the receipt to the next line

@inverted

<Empty string>

Denotes inverted text

@landscape

<Empty string>

Denotes text printed in landscape mode

@large

<Empty string>

Denotes large text

@right

<Empty string>

Denotes right-justified text

@underline

<Empty string>

Denotes underlined text

Display field value
SRSL: # (display field value)

Symbol

#

Syntax

# value_string (no spaces between # and value_string ) or # record.sub_record

Function

Insert the value of the field identified by value_string

For a listing of all accessible fields, see value strings.

Fields can be records, which are referenced in terms of their subfields. The record is separated from the subfield by a period (".").

Sensitive fields will be masked on receipts, provided that eSocket.POS is configured to protect sensitive data.

Example

#term_id- prints Term0001 (assuming that is the terminal’s ID)

#additional_amount.02 - prints the value of Additional Amount (field 054), subfield 2 (Available balance)

Formatting statement
SRSL: format command

Symbol

format

Syntax

format( object, SRSL )

Function

Inserts object, formatted according to the script SRSL

Within a format command, the values of fields in object may be referenced using the % (display formatted field value) command.

If object is a DateTime object, the script specifies the format in which the date and time are displayed.

If object is an amount, it will be formatted according to the default currency format for the amount.

A format_count field is also provided, referenced as %format_count, which indicates the line number being processed (starting at 1).

Amounts can be used as a standard #value when standard formatting rules are used. If a different formatting is required, however, the format command can be used on the amount to change the format rules for that specific amount.

Example

format(#time, "HH:mm:ss") : inserts 14:56:31

format (#full_amount, %symbol %major "." %minor) : inserts $12.34 (assuming that the amount is 00001234 and the currency is 840 (USD).

Format string
SRSL: % (display formatted field value)

Symbol

%

Syntax

% value_string (no spaces between % and value_string )

Function

Only within a format command, insert the value of the field identified by value_string. The % command is available to format commands displaying DateTime and Amount objects.

Each tag of the relevant object will be used as a Format String.

Example

%major prints the digits preceding the decimal symbol for an Amount object.

%minor prints the digits following the decimal symbol for an Amount object.

%symbol prints the currency symbol for an Amount object.

Insert blank space
SRSL: ^ (insert blank space)

Symbol

^

Syntax

^

Function

Inserts one space character

Example

^^^ - prints three spaces

Insert comment
SRSL: {…​} (insert comment)

Symbol

{ …​ }

Syntax

{ comment }

Function

Include a comment in the script

Comments are not parsed and do not print or display. They can be nested.

Examples

{ This is a comment line and is not part of the script }

{ This is a {nested} comment line and is not part of the script }

Insert text
SRSL: "…​" (insert text)

Symbol

" …​ "

Syntax

" text "

Function

Inserts text into the receipt without parsing it

Control characters are not recognized within text strings.

Example

" {this is text in curly brackets} and these are special symbols \@#$^*() "

This prints as:

{this is text in curly brackets} and these are special symbols \@#$^*()

Lookup statement
SRSL: lookup command

Symbol

Lookup

Syntax

lookup( lookup_string)

or

lookup( lookup_string, SRSL)

Function

Performs a lookup using the ReceiptMessages resource bundle family

The resource bundle is queried using the current active locale (which is set using the locale command).

If there is no match for a description of lookup_string in resource bundle family, this function will return the value of the second parameter, SRSL.

Refer to PipelineComponentReceiptPrinter - Resource Bundles for an overview of how resource bundles are used with SRSL.

Example

Assuming that there is a ReceiptMessages resource bundle with the following mappings: thankyou=Thank you for visiting lookup("thankyou") will produce: Thank you for visiting

lookup("nonexistentkey", "Message not found") will produce: Message not found

Move down
SRSL: down command

Symbol

down

Syntax

down( n)

Function

Ensures that printing starts n lines from its current position (default 1) by inserting n \LF (linefeed) characters

Example

This SRSL fragment:

"This is line 1"

down (5)

"This is line 6"

outputs:

1 This is line 1

2

3

4

5

6 This is line 6

Optional statement
SRSL: optional command

Symbol

Optional

Syntax

optional ( object,
option1 : SRSL |
option2 : SRSL |
[…​]
optionN : SRSL)

Function

Insert the SRSL definition Indicated by the option selected by the value of object

Example

optional (#tran_type,
"1" : "WITHDRAWAL" |
"2" : "DEPOSIT" |
undef : "Does not exist" |
unprint : "Contains an ASCII unprintable character (character code 0 to 31 or  greater than 127)" |
default : "Other")

Inserts WITHDRAWAL for a transaction type of 1, and DEPOSIT for a transaction type of 2, with fallthroughs for other transaction types and errors

Select printer(s)
SRSL: printer command

Symbol

printer

Syntax

printer( printer_name)

Function

Indicates to the SRSL parser that all SRSL statements that follow the printer command apply to printer_name

Multiple printers can be defined for any SRSL statement, or group of statements. If the printer name matches the name in any of the printer commands, the SRSL statement (or group of statements) will be applied.

Example

Given the following SRSL definition:

{-------------------------------------------}
printer(merch_reprint_approved)
printer(merch_reprint_declined)
   "Merchant reprint: "

printer(cust_reprint_approved)
printer(cust_reprint_declined)
   "Customer reprint: "

printer(merch_reprint_approved)
printer(cust_reprint_approved)
   "Approved"

printer(merch_reprint_declined)
printer(cust_reprint_declined)
   "Declined"
{-------------------------------------------}

If a receipt is printed for printer merch_reprint_approved, the output is: Merchant reprint: Approved

If a receipt is printed for printer merch_reprint_declined, the output is: Merchant reprint: Declined

If a receipt is printed for printer cust_reprint_approved, the output is: Customer reprint: Approved

If a receipt is printed for printer cust_reprint_declined, the output is: Customer reprint: Declined

Set to uppercase
SRSL: uppercase command

Symbol

uppercase

Syntax

uppercase( SRSL )

Function

Converts SRSL to uppercase

Example

uppercase("Cash") produces: CASH

String operations
SRSL: […​] (alignment)

Syntax

[ SRSL ] a n (no spaces between " ] ", " a ", and " n ").

" a " = alignment; " n " = length. " SRSL " is any valid sequence of commands.

Function

Strings can be aligned in four ways:

Align right: The string to be right-aligned is trimmed of whitespace. If the string is longer than n and truncation is allowed, the rightmost n characters are displayed. If truncation is not allowed, the entire string is displayed. If the string is shorter than n, it is padded with spaces to the left.

Align left: The string to be left-aligned is trimmed of whitespace. If the string is longer than n and truncation is allowed, the leftmost n characters are displayed. If truncation is not allowed, the entire string is displayed. If the string is shorter than n, it is padded with spaces to the right.

Center: The string to be centered is trimmed of whitespace. If the string is longer than n and truncation is allowed, the n centermost characters are displayed. If truncation is not allowed, the entire string is displayed. If the string is shorter than n, it is padded with spaces on either side. If the number of spaces is uneven, the right-hand side will have one more space than the left-hand side.

Trimming: The string is trimmed of whitespace. Trimming requires no length value.

5.14.4. References

SRSL reference: Value strings

Value strings

Value strings are used to reference values related to a transaction. Value strings are preceded with a # symbol in the SRSL receipt definition, for example, #rsp_code.

Value strings that reference sensitive fields, for example #pan, will print masked values on receipts, if the eSocket.POS system is configured to protect sensitive data.

The following simple value strings are supported. Where more than one value is defined, either can be used interchangeably.

Value Description

additional_amount

The value of Additional Amounts (field 054) in the Iso8583Post message

Individual amounts within this field can be accessed using the 2-digit Amount Type of the amount.

For example, to reference the Available Balance (amount type 02), use #additional_amount.02.

additional_node_data

The value of Additional Node Data (field 127.9) in the Iso8583Post message

amount

The value of Amount Transaction (field 004) in the Iso8583Post message

app_name

The application name

Its value can be any one of the following:

  • Application Preferred Name: As obtained from EMV tag 9F16,

  • Application Label: As obtained from EMV tag 50,

  • Card Product Name: As obtained from the value of the tag CardProductName of Structured Data (field 127.22) in the Iso8583Post message. If the structured data tag is not present, then the value is the name of the card product, as configured in the database.

auth_nr

The value of Authorization ID Response (field 038) in the Iso8583Post message

auth_profile

The value of Authorization Profile (field 127.6) in the Iso8583Post message

cardholder_authentication_capability

cardholder_auth_cp

The value of the Cardholder Authentication Capability subfield of POS Data Code (field 123) in the Iso8583Post message

card_acc_id_code

The value of Card Acceptor ID Code (field 042) in the Iso8583Post message

card_capture_capability

The value of the Card Capture Capability subfield of POS Data Code (field 123) in the Iso8583Post message

card_data_input_capability

card_input_cp

The value of the Card Data Input Capability subfield of POS Data Code (field 123) in the Iso8583Post message

card_data_input_mode

The value of the Card Data Input Mode subfield of POS Data Code (field 123) in the Iso8583Post message

card_data_output_capability

card_output_cp

The value of the Card Data Output Capability subfield of POS Data Code (field 123) in the Iso8583Post message

card_present

The value of the Card Present subfield of POS Data Code (field 123) in the Iso8583Post message

card_product_name

The value of the tag CardProductName of Structured Data (field 127.22) in the Iso8583Post message

If the structured data tag is not present, then the value is the name of the card product, as configured in the database.

card_seq_nr

The value of Card Sequence Number (field 023) in the Iso8583Post message

cardholder_authentication_entity

cardholder_auth_ety

The value of the Cardholder Authentication Entity subfield of POS Data Code (field 123) in the Iso8583Post message

cardholder_authentication_method

cardholder_auth_method

The value of the Cardholder Authentication Method subfield of POS Data Code (field 123) in the Iso8583Post message

cardholder_present

The value of the Cardholder Present subfield of POS Data Code (field 123) in the Iso8583Post message

city

The value of the city subfield of Card Acceptor Name Location (field 043) in the Iso8583Post message

country

The value of the country subfield of Card Acceptor Name Location (field 043) in the Iso8583Post message

currconv_conv_date

The value of Date, Conversion (field 016) in the Iso8583Post message

currency_code

The value of Currency Code, Transaction (field 049) in the Iso8583Post message

emv_app_label

The value of the tag EmvApplicationLabel of Structured Data (field 127.22) in the Iso8583Post message

emv_tsi

The value of the tag EmvTransactionStatusInformation of Structured Data (field 127.22) in the Iso8583Post message

expiry_date

The value of Date Expiration (field 014) in the Iso8583Post message

extended_tran_type

The value of Extended Transaction Type (field 127.33) in the Iso8583Post message

from_account

The value of the subfield from_account of Processing Code (field 003) in the Iso8583Post message

from_account_id

The value of Account Identification 1 (field 102) in the Iso8583Post message

gratuity_amount

The gratuity amount from the tag GratuityAmount of Structured Data (field 127.22), or from the field Additional Amounts (field 054) in the Iso8583Post message, whichever is set

is_approved

This resolves to a 1 if the Iso8583Post message has an approved Response Code (field 039). Otherwise, resolves to a 0.

is_approved_offline

This resolves to a 1 if the Iso8583Post message has an approved Response Code (field 039) and has not been sent to an upstream entity.Otherwise, resolves to a 0.

is_approved_online

This resolves to a 1 if the Iso8583Post message has an approved Response Code (field 039) and has been sent to an upstream entity.Otherwise, resolves to a 0.

is_declined_offline

This resolves to a 1 if the Iso8583Post message has a declined Response Code (field 039) and has not been sent to an upstream entity. Otherwise, resolves to a 0

is_declined_online

This resolves to a 1 if the Iso8583Post message has a declined Response Code (field 039) and has been sent to an upstream entity. Otherwise, resolves to a 0.

is_online

This resolves to a 1 if the Iso8583Post message has been sent to an upstream entity. Otherwise, resolves to a 0.

is_signature

This resolves to a 1 if PIN is not required, and the CVM results for ICC transactions, or the account configuration, indicates a signature is required. Otherwise, resolves to a 0.

issuer_network_id

The value of Issuer Network ID (field 127.31) in the Iso8583Post message

location

The value of the location subfield of Card Acceptor Name Location (field 043) in the Iso8583Post message

msg_reason_code

The value of Message Reason Code (field 056) in the Iso8583Post message

msg_type

The ISO 8583 message type of the message.

network_label

The value of the tag NetworkLabel of Structured Data (field 127.22) in the Iso8583Post message

operating_environment

The value of the Operating Environment subfield of POS Data Code (field 123) in the Iso8583Post message

pan

The card number in the Iso8583Post message

pan_len

The number of digits in the card number

pin_capture_capability

The value of the PIN Capture Capability subfield of POS Data Code (field 123) in the Iso8583Post message

pos_entry_mode

The value of POS Entry Mode (field 022) in the Iso8583Post message

pos_geographic_data_country_code

pos_geo_country_code

The value of the country subfield of POS Geographic Data (field 127.13) in the Iso8583Post message

pos_geographic_data_county_code

pos_geo_county_code

The value of the county subfield of POS Geographic Data (field 127.13) in the Iso8583Post message

pos_geographic_data_postal_service_code

pos_geo_postal_code

The value of the postal service code subfield of POS Geographic Data (field 127.13) in the Iso8583Post message

pos_geographic_data_state_code

pos_geo_state_code

The value of the state code subfield of POS Geographic Data (field 127.13) in the Iso8583Post message

receiving_inst

The value of Receiving Institution ID Code (field 100) in the Iso8583Post message

retrieval_ref_nr

The value of Retrieval Reference Number (field 037) in the Iso8583Post message

rsp_code

The value of Response Code (field 039) in the Iso8583Post message

settlement_day

The value of Originator/Authorizer date settlement (field 127.20) in the Iso8583Post message

sink_node

The value of the sink node subfield of Routing Information (field 127.3) in the Iso8583Post message

stan

The value of Systems Trace Audit Number (field 011) in the Iso8583Post message

start_date

The value of the tag StartDate (effective date) of Structured Data (field 127.22) in the Iso8583Post message

state

The value of the state subfield of Card Acceptor Name Location (field 043) in the Iso8583Post message

term_id

The value of Card Acceptor Terminal ID (field 041) in the Iso8583Post message

terminal_operator

The value of the Terminal Operator subfield of POS Data Code (field 123) in the Iso8583Post message

terminal_owner

The value of Terminal Owner (field 127.12) in the Iso8583Post message

terminal_output_capability

term_output_cp

The value of the Terminal Output Capability subfield of POS Data Code (field 123) in the Iso8583Post message

terminal_type

The value of the Terminal Type subfield of POS Data Code (field 123) in the Iso8583Post message

time

The Iso8583Post transaction time

The format of the date/time string can be changed in two ways:

  • SRSL Print Strategy: The format can be changed by using the SRSL Formatting statement.

  • PED/HTML Print Strategy: The format can be changed by using a receipt message bundle entry time_format=<date/time format>.

tm_settlement_date

The value of Date, Settlement (field 015) in the Iso8583Post message

to_account

The value of the subfield to_account of Processing Code (field 003) in the Iso8583Post message

to_account_id

The value of Account Identification 2 (field 103) in the Iso8583Post message

tran_type

The value of the subfield tran_type of Processing Code (field 003) in the Iso8583Post message

verification_method

Indicates the method of cardholder verification used

Its value can either be PIN, SIGNATURE, CONSUMER DEVICE, or NONE.

dcc_Indicator

Indicates the DCC status of the transaction

Its value can either be:

  • 1 : The cardholder was offered currency conversion and accepted it

  • 2 : The cardholder was offered currency conversion and declined it

  • NONE

dcc_DCCExchangeRate

In the case the DCC offer was accepted, this is the rate used for the currency conversion.

dcc_SrcAmount

In the case the DCC offer was accepted, this is the amount (including currency) before the conversion.

dcc_SrcAlphaCode

The alphabetic code of the currency being converted from

dcc_TgtAmount

In the case the DCC offer was accepted, this is the amount (including currency) after the conversion.

dcc_TgtAlphaCode

The alphabetic code of the currency being converted to

dcc_DisclaimerText

The disclaimer text for the DCC offer, that can have values: DisclaimerText_1 = The first disclaimer text, DisclaimerText_2 = The 2nd disclaimer text

opi_SiteId

This is an Oracle Payment Interface (OPI) specific value that returns the site ID.

opi_WsNo

This is an Oracle Payment Interface (OPI) specific value that returns the workstation number for the terminal.

opi_Operator

This is an Oracle Payment Interface (OPI) specific value that returns the operator ID.

opi_GuestNo

This is an Oracle Payment Interface (OPI) specific value that returns the guest number for the transaction if applicable.

opi_IndustryCode

This is an Oracle Payment Interface (OPI) specific value that returns the industry code.

opi_ProxyInfo

This is an Oracle Payment Interface (OPI) specific value that returns the proxy info.

opi_POSInfo

This is an Oracle Payment Interface (OPI) specific value that returns the POS info.

opi_TransType

This is an Oracle Payment Interface (OPI) specific value that returns the OPI transaction type.

The following complex value strings are supported:

Value Description

iso_field_<field_nr>

The result of retrieving the field_nr from the Iso8583Post message

iso_field_127_<private_field_nr>

The result of retrieving the private_field_nr from the Iso8583Post message

emv_tag_<IccData DTD element>

The value of an ICC Data XML element, for example #emv_tag_ApplicationIdentifier

In its simplest form, the first element that matches <IccData DTD element> will be printed.

Alternatively, the EMV tag can used, for example #emv_tag_4F instead of #emv_tag_ApplicationIdentifier, however this is limited to the equivalent elements found in the ICC Data XML data, or the tags found in Structured Data (field 127.22), under the key TlvIccDataExtended (See the SET_EXT_ICC_DATA parameter in pipeline component EMV).

A more specific version of this value string is also supported:
#emv_tag_[IccRequest|IccResponse]_<IccData DTD element>

This version of the value string will only consider either IccRequest or IccResponse, accordingly.

ICC Data elements that contain sensitive or cryptographic information will not be printed on receipts. Please refer to forbidden EMV tags for a list of disallowed elements.

tip_<percentage>

Applies the percentage to Amount, Transaction (field 004)

This string can be used to print tip recommendations on a receipt.

For example, for a (minor denomination) transaction amount of 200: tip_10 will print 20 tip_110 will print 220.

Date/time formatting

To specify the format for the #time Value String use a time pattern string (for example, "HH:mm:ss") in the Format statement. In such a pattern, all ASCII letters are reserved as pattern letters, which are defined as the following:

Symbol Meaning Presentation Example

G

era designator

Text

AD

y

year

Number

1996

M

month in year

Text & Number

July & 07

d

day in month

Number

10

h

hour in AM/PM (1~12)

Number

12

H

hour in day (0~23)

Number

0

m

minute in hour

Number

30

s

second in minute

Number

55

S

millisecond

Number

978

E

day in week

Text

Tuesday

D

day in year

Number

189

F

day of week in month

Number

2 (2nd Wed in July)

w

week in year

Number

27

W

week in month

Number

2

a

AM/PM marker

Text

PM

k

hour in day (1~24)

Number

24

K

hour in AM/PM (0~11)

Number

0

z

time zone

Text

Pacific Standard Time

'

escape for text

''

single quote

'

The number of pattern letters (from the table above) in the time pattern string determines the format:

  • Text: 4 or more pattern letters: use full form; less than 4: use short or abbreviated form if one exists.

  • Number: the minimum number of digits to display/print. Shorter numbers are zero-padded (on the left) to this amount. Year is handled specially; that is, if the count of 'y' is 2, the Year will be truncated to 2 digits.

  • Text & Number: 3 or more, use text, otherwise use number.

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even if they are not contained within single quotes.

eSocket.POS Windows services

On a Microsoft Windows platform, each of the eSocket.POS applications may be run as a Windows service. These services may be started and stopped from the Windows Services manager.

Three services are installed with eSocket.POS: these are the eSocket.POS service, the eSocket.POS Configuration Agent service, and the eSocket.POS Upgrade Manager service.

Service parameters

The three eSocket.POS services take parameters as described below. These are contained in the properties file under the property postilion.esocketpos.service.<service_name>.Parameters, where <service_name> is EspRun, EspConfigAgent, or EspUpgrManager.

Note: If a different service name was configured for any of the services during the installation/upgrade, please use the configured service name instead.

eSocket.POS service
Parameter Notes

<service_class>

postilion.esocketpos.util.EspRun

-p <properties>

Specifies the fully qualified path of the eSocket.POS properties file.

-um

Run the Upgrade Manager as part of this service.

-ca

Run the Configuration Agent as part of this service.

-xml

Run the XML interface as part of this service. May not be specified together with -mfe option.

-mfe <params>

Run the Message Front-end as part of this service. May not be specified together with -xml option. The parameters are the same as those required to run the Message Front-end from the command line, except that the properties file is omitted since it is already specified using the -p parameter.

-msfe

Run the Multi-Source Front-end as part of this service. May not be specified together with -mfe or -xml option. Any additional parameters needed should be specified in the properties file.

-cust <custom_class>

Run a custom application where <custom_class> specifies the fully qualified class name. Custom classes must extend the base class postilion.esocketpos.util.ACustomApp.

Custom applications for this service may also be specified in the eSocket.POS properties file.

By default, the eSocket.POS service is installed with the -xml option and specifies the properties file using -p <esp_dir>\properties.txt, where <esp_dir> is the eSocket.POS installation directory, for example C:\postilion\eSocket.POS.

eSocket.POS Configuration Agent service
Parameter Notes

<service_class>

postilion.esocketpos.util.ConfigAgentRun

-p <properties>

Specifies the fully qualified path of the eSocket.POS properties file.

-cust <custom_class>

Run a custom application where <custom_class> specifies the fully qualified class name. Custom classes must extend the base class postilion.esocketpos.util.ACustomApp.

By default, the eSocket.POS Configuration Agent service is installed with the -ca option and specifies the properties file using -p <esp_dir>\properties.txt , where <esp_dir> is the eSocket.POS installation directory, for example C:\postilion\eSocket.POS.

eSocket.POS Upgrade Manager service
Parameter Notes

<service_class>

postilion.esocketpos.util.UpgrManagerRun

-p <properties>

Specifies the fully qualified path of the eSocket.POS properties file.

By default, the eSocket.POS Upgrade Manager service specifies the properties file using -p <esp_dir>\properties.txt, where <esp_dir> is the eSocket.POS installation directory, for example C:\postilion\eSocket.POS. In addition, the other eSocket.POS services are dependent on the Upgrade Manager - the Upgrade Manager service must be started before them.

Limitations

When eSocket.POS is run as a service, the service must not use mapped drive letters, because Windows stores these mappings per user, and they may not match those of the account used to run the service. UNC paths must be used instead. Unfortunately, Java does not support UNC names in the classpath, so any classpath entries must refer to a local drive.

Running the services using various Java Virtual Machines

The eSocket.POS and Configuration Agent services are installed to run using the Java Virtual Machine (VM) specified during installation. However, another Java VM may be used if required, by specifying the following properties in the registry using regedit.exe.

postilion.portability.jvm_dll

The value HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/<service_name>/Parameters/Properties/postilion.portability.jvm_dll can be used to specify the desired Java VM.If this value does not exist, create it by adding a Properties key to the Parameters key, and adding the value postilion.portability.jvm_dll to this key.

The data portion of this value defines the DLL to use when launching the Java virtual machine (VM). Determining which DLL is usually relatively straightforward, certainly for Java 2 virtual machines. Typically the DLL is called jvm.dll and lives in the bin directory of the Java platform in question. Another name commonly used for this DLL is javai.dll.

java.endorsed.dirs

If you are using the Sun Java (1.4 or above) VM, then you must specify the following value in the registry for the EspRun and EspConfigAgent services (note that this must not be configured for the EspUpgrManager service):

HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/< service_name >/Parameters/Properties/java.endorsed.dirs

If this value does not exist, create it by adding a Properties key to the Parameters key, and adding the value java.endorsed.dirs to this key.

The system property java.endorsed.dirs specifies the directory that the Java runtime environment searches in for JAR files that contain classes implementing newer versions of endorsed standards. The data portion of this value must be set to c:\postilion\eSocket.POS\bin\endorsed.

JavaClassPath

For most Java VMs, it is necessary to specify the classpath to use when launching the service. This is done using the value HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/<service_name>/Parameters/JavaClassPath. If the JavaClassPath value does not exist, it must be created under the Parameters key.

The data portion of this value specifies the classpath where the eSocket.POS classes and jar files may be found. This must typically include <WINNT>\java\classes, the fully qualified paths of the jar files esocket-tools.jar and any other classes required to run eSocket.POS.Note that jar files must appear after the location of the eSocket.POS class files in the classpath. For the Upgrade Manager service, the classpath must only contain the class files, and none of the JAR files.

Service terminates unexpectedly following logoff

Logging off from a machine running an eSocket.POS service using the Sun VM (1.3 and later) or JRockit VM results in the service stopping. The reason is that the Windows logoff event is not processed correctly by these JVM’s.

To solve this problem a parameter must be prepended at the start of the value HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/<service_name>/Parameters/CommandLine in the registry. For the Sun VM use -Xrs and for the JRockit VM use -Xnohup.

Other System Properties supported by the eSocket.POS Services

com.vsi.xml.preserve_whitespace_padding

false

A boolean value indicating whether or not whitespaces should be preserved in XML data elements.

Classpath

The classes and jar files installed by eSocket.POS must be specified in the classpath for the Java VM when the application is run. Specifically, ensure that the following is included:

  • eSocketpos Java class files - usually located in C:\WINNT\java\classes, depending on the operating system installed

  • esocket-tools.jar - located in C:\Postilion\eSocket.POS\bin after an automatic installation

Note
The jar files must appear after the location of the eSocket.POS Java class files in the classpath.
CommAPI Serial Communication

If eSocket.POS must connect to a device using a serial port using the Java CommAPI (javax.comm) package, then you must include the following jar file:

  • comm.jar

Note
The CommAPI implementation is not shipped with eSocket.POS. There are various implementations for different platforms.
RXTX Serial Communication

If eSocket.POS must connect to a device using a serial port using the RXTX Communication Implementation on a Linux platform, then you must include the following jar file:

  • RXTXcomm.jar

Note
The RXTXcomm implementation is not shipped with eSocket.POS. There are various implementations for different platforms.
HSQLDB

When HSQLDB is used with eSocket.POS, the following jar file must be in the classpath:

  • hsqldb.jar

Note
HSQLDB is not shipped with eSocket.POS. The latest release of HSQLDB can be found at http://hsqldb.org .
Strong data protection

If the system is configured for strong data protection, two additional jar files are required.

  • bcprov-jdk15.jar and bcpkix-jdk15.jar

Note
These jar files are required regardless of whether the system is configured for strong data protection or not.
Example

The following is a typical example of the classpath:

C:\Windows\java\classes;C:\Postilion\eSocket.POS\bin\endorsed\xercesImpl.jar;C:\Postilion\eSocket.POS\bin\endorsed\xml-apis.jar;C:\Postilion\eSocket.POS\bin\esocket-tools.jar;C:\Postilion\eSocket.POS\bin\bcprov-jdk15.jar;C:\Postilion\eSocket.POS\bin\bcpkix-jdk15.jar;C:\Postilion\eSocket.POS\bin\jai_codec.jar;C:\Postilion\eSocket.POS\bin\jai_core.jar;C:\HSQL\hsqldb.jar;C:\Postilion\eSocket.POS\bin\comm.jar;C:\Postilion\eSocket.POS\bin\jakarta.xml.bind-api-2.3.2.jar;C:\Postilion\eSocket.POS\bin\jaxb-runtime-2.3.2.jar;C:\Postilion\eSocket.POS\bin\istack-commons-runtime-3.0.8.jar;C:\Postilion\eSocket.POS\bin\jakarta.activation-api-1.2.1.jar

a in [SRSL] a n
  • - right align, without removing excess characters

  • - right align, removing excess characters

  • L - left align, without removing excess characters

  • l - left align, removing excess characters

  • C - center, without removing excess characters

  • c - center, removing excess characters

  • t - trim spaces on both ends

Example Currencies Symbols SRSL for OPI Implementations

840=USD

978=EUR

192=CUP

710=ZAR

826=GBP

Receipt Structure Example for OPI Implementations
{

This receipt profile definition is used by default for OPI implementations.

Printer types:

all: All printers

cust_approved: Customer receipt for an approved transaction.

cust_declined: Customer receipt for a declined transaction.

cust_reprint_approved: Customer receipt reprint (approved transaction).

cust_reprint_declined: Customer receipt reprint (declined transaction).

merch_approved: Merchant receipt for an approved transaction.

merch_declined: Merchant receipt for a declined transaction.

merch_reprint_approved: Merchant receipt reprint (approved transaction).

merch_reprint_declined: Merchant receipt reprint (declined transaction).

merch_totals_approved: Merchant batch totals receipt (approved).

merch_totals_declined: Merchant batch totals receipt (declined).

signature: Receipt that requires a signature.

}

{Customer language}

printer(cust_approved)

printer(cust_declined)

printer(cust_reprint_approved)

printer(cust_reprint_declined)

locale("en")

{REPRINT Merchant receipts}

printer(merch_approved)

printer(merch_declined)

printer(merch_reprint_approved)

printer(merch_reprint_declined)

printer(merch_totals_approved)

printer(merch_totals_declined)

locale("en")

{PART I: TITLE DEFINITION }

{REPRINT Merchant receipts}

printer(merch_reprint_approved)

printer(merch_reprint_declined)

lookup("merchant_reprint_title") @eol

{REPRINT Customer receipts}

printer(cust_reprint_approved)

printer(cust_reprint_declined)

lookup("cardholder_reprint_title") @eol

{Customer copy}

printer(cust_approved)

printer(cust_declined)

lookup("cardholder_receipt_title") @eol

{Merchant copy}

printer(merch_approved)

printer(merch_declined)

lookup("merchant_receipt_title") @eol

{Customer welcome message}

printer(cust_approved)

printer(cust_declined)

printer(cust_reprint_approved)

printer(cust_reprint_declined)

lookup("customer_welcome_message") @eol

{ PART II: HEADER DEFINITION - Merchant and Terminal Information }

optional(#terminal_owner, "???" : "" | default : #terminal_owner @eol)

lookup("ws_no_label")": " #opi_WSNo ^^^lookup("terminal_id_label")": " #term_id @eol

optional(#iso_field_43, "???" : "" | default : #iso_field_43 @eol)

optional(#opi_SiteId, "???" : "" | default : lookup("site_id_label")": " #opi_SiteId @eol)

optional(#opi_POSInfo, "???" : "" | default : lookup("pos_info_label")": "#opi_POSInfo @eol)

lookup("city_label")": " #city @eol

lookup("country_label")": " #country @eol

format(#time,"dd/MM/yyyy") ^ format(#time,"HH:mm:ss") @eol @eol

{

PART III: TRANSACTION DATA 1/2 - CARD DETAILS

The card details are only printed if they are available.

}

printer(cust_approved)

printer(cust_declined)

printer(cust_reprint_approved)

printer(cust_reprint_declined)

printer(merch_approved)

printer(merch_declined)

printer(merch_reprint_declined)

lookup("stan_label")": " #stan @eol

lookup("rrn_label")": " #retrieval_ref_nr @eol @eol

optional(#pan, "???" : "" | default : lookup("pan_label")": " #pan @eol)

optional(#card_seq_nr, "???" : "" | default : lookup("seq_number_label")": " #card_seq_nr @eol)

optional(#expiry_date, "???" : "" | default : lookup("expiry_date_label")": " #expiry_date @eol)

optional(#card_acc_id_code, "???" : "" | default : lookup("card_acceptor_id_label")": " #card_acc_id_code @eol)

optional(#verification_method, "???" : "" | default : lookup("verification_method_label")": " #verification_method @eol)

optional(#card_product_name, "???" : "" | default : @eol #card_product_name @eol@eol)

optional(#gratuity_amount, "???" : "" | default : lookup("gratuity_amount_label")": " format(#gratuity_amount, %symbol " " %major "." %minor) @eol)

optional(#additional_amount.40, "???" : "" | default : lookup("cashback_amount_label")": " format(#additional_amount.40, %symbol " " %major "." %minor) @eol @eol)

optional(#dcc_DccIndicator,

"1" : lookup("accepted_dcc_offer_label") @eol |

"2" : lookup("declined_dcc_offer_label") @eol|

default :)

optional(#dcc_DCCExchangeRate, "???" : "" | default : lookup("dcc_exchange_rate_label")": " #dcc_DCCExchangeRate @eol)

optional(#dcc_SrcAmount, "???" : "" | default : lookup("src_amount_label")": " format(#dcc_SrcAmount, %symbol " " %major "." %minor)) ^^

optional(#dcc_TgtAmount, "???" : "" | default : lookup("tgt_amount_label")": " format(#dcc_TgtAmount, %symbol " " %major "." %minor)) ^^ @eol

@eol

optional(#opi_TransType,

"01" : "PAYMENT" |

"50" : "READ NON PCI CARD" |

default : "OTHER") @eol @eol

{MERCHANT receipts need account information}

printer(merch_approved)

printer(merch_declined)

printer(merch_reprint_approved)

printer(merch_reprint_declined)

"From account: " #from_account @eol

"To account: " #to_account @eol @eol

{APPROVED receipts should have auth code}

printer(cust_approved)

printer(merch_approved)

printer(cust_reprint_approved)

printer(merch_reprint_approved)

printer(merch_totals_approved)

lookup("transaction_outcome_approved") @eol @eol

optional(#auth_nr, "???" : "" | default: lookup("auth_nr_label")": " #auth_nr @eol @eol)

{DECLINED receipts}

printer(cust_declined)

printer(merch_declined)

printer(cust_reprint_declined)

printer(merch_reprint_declined)

printer(merch_totals_declined)

{Message reason code also required for declined transactions.}

lookup("transaction_outcome_declined") @eol @eol

optional(#msg_reason_code, "???" : "" | default: lookup("msg_reason_code_label")": " #msg_reason_code @eol @eol)

printer(cust_approved)

printer(cust_declined)

printer(cust_reprint_approved)

printer(cust_reprint_declined)

printer(merch_approved)

printer(merch_declined)

printer(merch_reprint_approved)

printer(merch_reprint_declined)

lookup("amount_label")": " format(#amount, %symbol " " %major "." %minor) @eol

{EMV Values if set}

printer(cust_approved)

printer(cust_declined)

printer(cust_reprint_approved)

printer(cust_reprint_declined)

printer(merch_approved)

printer(merch_declined)

printer(merch_reprint_approved)

printer(merch_reprint_declined)

optional(#emv_tag_ApplicationIdentifier, "???" : "" | default : "AID: " #emv_tag_ApplicationIdentifier @eol)

optional(#emv_tag_TerminalVerificationResult, "???" : "" | default : "TVR: " #emv_tag_TerminalVerificationResult @eol)

optional(#emv_tag_AuthorizationResponseCode, "???" : "" | default : "ARC: " #emv_tag_AuthorizationResponseCode @eol)

optional(#emv_tag_CvmResults, "???" : "" | default : "CVM Results: " #emv_tag_CvmResults @eol)

optional(#emv_tag_TerminalCapabilities , "???" : "" | default : "TermCap: " #emv_tag_TerminalCapabilities @eol)

{Receipts requiring a SIGNATURE}

printer(signature)

@eol @eol

"Signature: _____________________" @eol @eol

{CUSTOMER receipts}

printer(cust_approved)

printer(cust_declined)

lookup("footer_text_label") @eol

{BATCH TOTALS receipts}

printer(merch_totals_approved)

printer(merch_totals_declined)

"Credits, number: " #credits_nr @eol

"Credits, reversal number: " #credits_rev_nr @eol

"Debits, number: " #debits_nr @eol

"Debits, reversal number: " #debits_rev_nr @eol

"Transfers, number: " #transfers_nr @eol

"Transfers, reversal number: " #transfers_rev_nr @eol

"Inquiries, number: " #inquiries_nr @eol

"Authorizations, number: " #auths_nr @eol

"Credits, processing fee amount: " #credits_proc_fee_amount @eol

"Credits, transaction fee amount: " #credits_tran_fee_amount @eol

"Debits, processing fee amount: " #debits_proc_fee_amount @eol

"Debits, transaction fee amount: " #debits_tran_fee_amount @eol

"Credits, amount: " #credits_amount @eol

"Credits, reversal amount: " #credits_rev_amount @eol

"Debits, amount: " #debits_amount @eol

"Debits, reversal amount: " #debits_rev_amount @eol

"Amount, net settlement: " #amount_net_settle @eol

"Payments, number: " #payments_nr @eol

"Payments, reversal number: " #payments_rev_nr @eol

{ALL receipts}

printer(all)

@cut
Example resource bundles SRSL for OPI Implementations
merchant_reprint_title=Merchant Reprint Receipt

cardholder_reprint_title = Cardholder Reprint Receipt

merchant_receipt_title=Merchant Receipt

cardholder_receipt_title=Customer Receipt

customer_welcome_message=Welcome to Xstore

terminal_id_label=Terminal ID

city_label=City

ws_no_label=WS No

country_label=Country

card_acceptor_id_label=Card Acc ID

pan_label=Card Number

seq_number_label=Card Seq. No

stan_label=Seq. No

rrn_label=RRN

amount_label=Amount

expiry_date_label=Expiry date

verification_method_label=CVM

card_product_name_label=Card Product

gratuity_amount_label=Gratuity Amount

cashback_amount_label=CashBack Amount

auth_nr_label=Auth Code

msg_reason_code_label=Msg Reason Code

footer_text_label=Thanks for Visiting !

site_id_label=Site ID

pos_info_label=POS Info

unknown_tran_type_label=UNKNOWN TRANSACTION TYPE

tran_type_01=PAYMENT

transaction_outcome_approved=APPROVED

transaction_outcome_declined=DECLINED

accepted_dcc_offer_label=DCC OFFER ACCEPTED

declined_dcc_offer_label=DCC OFFER DECLINED

dcc_exchange_rate_label=EXCHANGE RATE

src_currency_label=FROM

tgt_currency_label=TO

src_amount_label=FROM

tgt_amount_label=TO
Forbidden EMV tags

To avoid exposing sensitive or cryptographic data, AtmApp will not allow the following EMV tags to be printed:

IccData Tag

ApplicationTransactionCounter (9F36)

Cryptogram (9F26)

CryptogramInformationData (9F27)

IssuerAuthenticationData (91)

UnpredictableNumber (9F37)

n in down(n): This parameter represents an integer that indicates the number of linefeeds to perform in the receipt at the current position. If n is not specified it defaults to 1.

n in [SRSL]a n: This integer represents the total length assigned to the text. It should be in the range 1 to 99.

SRSL

Consists of a piece of text or a full script.

SRSL: align left

Text can be aligned with or without truncation.

Syntax

[SRSL] a n (no spaces between " ] ", " a ", and " n ").

" a " = alignment; " n " = length. " SRSL " is any valid sequence of commands.

Specify l to truncate, and L to preserve the entire string. Amounts should never be truncated. Use truncation if rigid formatting constraints need to be observed, such as when using preprinted receipt paper.

In the examples, blank spaces are indicated by "·" signs that do not appear in the output.

Example SRSL statement Output

No spaces, n < text length

["Hello"]l2

He

No spaces, n < text length

["Hello]L2

Hello

No spaces, n > text length

["Hello"]l10

Hello·····

No spaces, n > text length

["Hello"]L10

Hello·····

Spaces, n < text length

["···Hello···"]l2

He

Spaces, n > text length

["···Hello···"]l10

Hello·····

SRSL: align right

Text may be aligned with or without truncation.

Syntax

[SRSL] a n (no spaces between " ] ", " a ", and " n ").

" a " = alignment; " n " = length. " SRSL " is any valid sequence of commands.

Specify to truncate, and to preserve the entire string. Amounts should never be truncated. Use truncation if rigid formatting constraints need to be observed, such as when using preprinted receipt paper.

In the examples, blank spaces are indicated by "·" signs that do not appear in the output.

Example SRSL command Output

No spaces, n < text length

["Hello"]r2

lo

No spaces, n < text length

["Hello"]R2

Hello

No spaces, n > text length

["Hello"]r10

·····Hello

No spaces, n > text length

["Hello"]R10

·····Hello

Spaces, n < text length

["···Hello···"]r2

lo

Spaces, n > text length

["···Hello···"]r10

·····Hello

Block example
  1. HELLO

  2. {blank}

  3. {blank}

  4. {blank}

  5. {blank}

  6. BYE

SRSL: centering

Text may be centered with or without truncation.

Syntax

[SRSL] a n (no spaces between " ] ", " a ", and " n ").

" a " = alignment; " n " = length. " SRSL " is any valid sequence of commands.

Specify c to truncate, and C to preserve the entire string. Amounts should never be truncated. Use truncation if rigid formatting constraints need to be observed, such as when using preprinted receipt paper.

In the examples, blank spaces are indicated by "·" signs that do not appear in the output.

Example SRSL statement Output

No spaces, n < text length

["Hello"]c3

ell

No spaces, n < text length

["Hello"]C3

Hello

No spaces, n > text length

["Hello"]c10

··Hello···

No spaces, n > text length

["Hello"]C10

··Hello···

Spaces, n < text length

["···Hello···"]c3

ell

Spaces, n > text length

["···Hello···"]c10

··Hello···

Locale statement
SRSL: locale command

Symbol

Locale

Syntax

locale( locale_string)

Function

Changes the active locale to locale_string

A valid locale_string consists of either:

  • The empty string: ""

  • A valid ISO 639 2-character language code

  • A valid ISO 639 2-character language code, followed by an underscore, followed by a valid ISO 3166 2-character country code.

The active locale affects all resource bundle lookups.

The active locale will remain active until another locale command is encountered in the receipt.

Example

locale("") will set the active locale to an empty locale value.

This will cause resource bundle lookups to use the default bundle, instead of a locale-specific bundle.

locale("en") will set the active locale to English.

locale("en_US") will set the active locale to English (US).

Standard control characters

The following control characters catered for and can be referred to by name.

Text ASCII code (decimal) ASCII code (hex)

BS

8

08

Backspace

LF

10

0A

Linefeed

VT

11

0B

Vertical Tab

FF

12

0C

Form-feed

CR

13

0D

Carriage return

HT

9

09

Horizontal Tab

ESC

27

1B

Escape

SI

15

0F

SO

14

0E

QUOTE

34

22

Double quote (")

Transaction receipt
SRSL Script Comments

uppercase(

{Print everything on the receipt in upper case - **: The last bracket to close this statement at the end}

definition ("Header")

{Print the header portion}

lookup ("transaction", #tran_type)

{Print the transaction type after retrieving it from the relevant table}

[optional(#amount, default: #amount)]r20 \LF

\{If an amount value exists, then print the amount right aligned within 20 characters} {Linefeed}

optional( #from_account, default: [ @from]t ^ lookup("account", #from_account) ^ )

{If a from-account exists, then print the from label (trimmed), then a space, then the actual from-account retrieved from the relevant table, and lastly a space}

optional( #to_account, default: [ @to]t ^ lookup("account", #to_account) ) \LF

{If a to-account exists, then print the to label (trimmed), then a space, then the actual to-account retrieved from the relevant table, and lastly a space}

optional ( #ministatement, default: \LF format (#ministatement, format ( %DATE_TIME , "yy MMM dd hh:mm") ^^ lookup("isotran",%TRAN) \LF optional(%ACC_ID1,"" :

default:[ @from]t ^ % ACC_ID1 ^^) optional(%ACC_ID2, "" :

default:[ @to]t ^ % ACC_ID2 ^^) %TRAN_AMT \LF) \LF)

{If mini-statement exists, then print Linefeed followed by formatted mini-statement information for each transaction therein: the date and time; the transaction type retrieved from the relevant table; if a from account is present, then print its label (trimmed) and itself followed by two spaces; if a to account is present, then print its label (trimmed) and itself followed by two spaces; the amount of the transaction; Linefeed} {LineFeed}. See Mini-Statement Example for values.

optional ( #fee, default: [ @fee]t ":" ^ [ #fee]r20 \LF)

{If a value exists for the fee, then print the fee label, followed by char ":", then a space, then the value of the fee right aligned within 20 characters, and lastly a Linefeed}

optional ( #message, default: \LF #message\LF)

{If message exists then print Linefeed, then message and another Linefeed}

optional ( #ledger_balance_from, default: \LF [ @ledger_balance]l8 [ #ledger_balance_from]r15)

{If the ledger balance exists then print a Linefeed, then the ledger balance label left aligned within 8 characters, followed by the ledger balance itself right aligned within 15 characters}

optional ( #amount_available_from, default: \LF [ @avail_balance

]r15)

\{If the available balance exists then print a Linefeed, then the available balance label left aligned within 8 characters, followed by the available balance itself right aligned within 15 characters}

\LF &-40 \FF

{Linefeed} \{Print char "-" 40 times} {Formfeed}

)

\{close uppercase statement at beginning}

For more information, please see cardholder Receipt and Journal Receipt.

Transaction receipt - cardholder
Line Output (withdrawal) Output (mini-statement)

º º º º º º ºS1º º º º º º º

º º º º º º ºS1º º º º º º º

ºººººººººººººººWATERFRONTººººººººººººººº

ºººººººººººººººWATERFRONTººººººººººººººº

ºººººCAPE TOWNºººWCºººSOUTH AFRICAºººººº

ºººººCAPE TOWNºººWCºººSOUTH AFRICAºººººº

ººººººDATEººººººººTIMEººººººººATMººººººº

ººººººDATEººººººººTIMEººººººººATMººººººº

ºººº12\01\98ººººº12:35ººººººXYZ123

ºººº12\01\98ººººº12:35ººººººXYZ123

CARD NUMBERººººººººº…​…​…​…​7890

CARD NUMBERººººººººº…​…​…​…​7890

----------------------------------------

----------------------------------------

SEQ NUMBºººººººººººººººººººººº1234567890

SEQ NUMBºººººººººººººººººººººº1234567890

AUTH NUMººººººººººººººººººººººººººººº999

AUTH NUMººººººººººººººººººººººººººººº999

WITHDRAWALººººººººººººº$500.00

MINISTATEMENT

FROMºSAVINGSº

SURCHARGE:ºººººººººººººººº$1.00

LEDGERºººººººº$13500.00

98ºSepº03ººººº14:32ººDEPOSIT

AVAILººººººººº$11000.00

TOºSAVINGSºº$555,50

----------------------------------------

98ºSepº14ººººº08:17ººWITHDRAW

FROMºCHECKºº$200,00

98ºSepº17ººººº11:43ººTRANSFER

23

FROMºCREDITººTOºCHECKºº$196,85

24

21

SURCHARGE:ºººººººº$1.00

25

LEDGERºººººººº$13500.00

26

AVAILººººººººº$11000.00

27

----------------------------------------

Transaction receipt - journal
Output (withdrawal) Output (mini-statement)

ºººº12\01\98ººººº12:35ººººººXYZ123

ºººº12\01\98ººººº12:35ººººººXYZ123

1234567890ºººº999

1234567890ºººº999

WITHDRAWALººººººººººººº$500.00

MINISTATEMENT

FROMºSAVINGSº

SURCHARGE:ºººººººººººººººº$1.00

LEDGERºººººººº$13500.00

98ºSepº03ººººº14:32ººDEPOSIT

AVAILººººººººº$11000.00

TOºSAVINGSºº$555,50

----------------------------------------

98ºSepº14ººººº08:17ººCASH WITHDRAWAL

FROMºCHECKºº$200,00

98ºSepº17ººººº11:43ººTRANSFER

FROMºCREDITººTOºCHECKºº$196,85

SURCHARGE:ºººººººº$1.00

LEDGERºººººººº$13500.00

AVAILººººººººº$11000.00

----------------------------------------

Trimming

Blank spaces are illustrated by the º sign. This makes it easier to map the script to the output. In a live environment, these would not be present.

Since trimming only strips spaces from the ends of a string, it is unnecessary to provide a length parameter.

Example SRSL statement Output

No spaces

["Hello"]t

Hello

Spaces

["ºººHelloººº"]t

Hello

6. Operation

6.1. Monitor eSocket.POS

You can use event logging, tracing, and monitoring to help manage eSocket.POS.

6.1.1. Event logging

You must configure the eSocket.POS properties file for event logging. Refer to the following pages for more information about event logging:

6.1.2. Tracing

eSocket.POS provides information via tracing. You must configure the eSocket.POS properties file for various options of tracing.

You can also use Configuration Agent for tracing - see Configuration Agent properties for more information.

6.1.3. Monitoring

Monitoring information from eSocket.POS is available centrally via the Realtime Terminals Monitor or ConfigServer Query Console. Additionally, you can monitor eSocket.POS locally or remotely by sending monitoring commands via TCP or UDP.

The Realtime Terminals Monitor indicates the overall status of each eSocket.POS terminal (OK, suspect, or critical) and provides details on entities within eSocket.POS.

Similarly, the ConfigServer Query Console provides a view of the current deployment status of packages and physical eSocket.POS terminals. It provides the following details:

  • The date and time of the last contact with ConfigServer

  • The terminal’s overall status (OK, suspect, or critical)

  • The terminal’s pending rollout status

  • A list of the installed software

To use the monitoring capabilities of eSocket.POS centrally, you must:

  • Configure the Monitoring pipeline component, otherwise no monitoring information or support events (for central event logging) will be sent upstream. Enabling the Monitoring pipeline component can have a negative impact on performance on low-end hardware or on a store server servicing a large number of terminals under heavy load.

  • Use PosConnect as the node interface instead of PostTerm, because PosConnect does not require extra configuration for monitoring to work.

eSocket.POS sends monitoring information and support events upstream as described in Monitoring pipeline component.

Note
The Realtime Terminals Monitor and ConfigServer Query Console may have restricted access. Contact your head office or service provider to gain access or to retrieve the information from these consoles. See the eSocket.POS Configuration Server User Guide and Realtime Framework User Guide for details about these applications.

6.2. Monitoring using commands

The status of a terminal can be monitored with UDP or TCP commands sent to the eSocket.POS command port, which is specified via eSocket.POS properties. The command to retrieve status information is:

  • STATUS <terminal ID> PTFORMAT

The response to this command contains 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, a valid response to the STATUS <terminal ID> PTFORMAT command would be:

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 that the PIN pad was disconnected (position 8, value of "03").

Note
If a certain entity is not present in the current terminal setup, the status code for that entity will be 00 - OK. Status entries may 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 UDP/TCP commands.

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

Terminal Monitor histogram example

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), excluding the last dequeued transaction that is being delivered upstream (if applicable)

    • The "SAFQ not clearing" indicator, for example, 0 (SAFQ is clearing), 1 (SAFQ is not clearing)

    • If the SAFQ is not clearing, the approximate time in minutes since a transaction was last dequeued from the SAFQ in order to be sent upstream

      In the example response above, this contains the value:

      2|1|243|

      That is, there are currently two transactions in the store and forward queue (SAFQ), the SAFQ is currently not clearing and has been stuck for 243 minutes (for example, 4 hours and 3 minutes).

      An example of when the SAFQ is clearing would be:

      3|0|

      That is, there are currently three transactions in the SAFQ, and the SAFQ is clearing.

      Note
      In future, further miscellaneous values may be added, separated by pipe characters.
  • <condition> contains a single digit representing the overall status of the terminal. It has one of the following values:

    Value Condition Description

    0

    OK

    The terminal is operating normally.

    2

    Suspect

    The terminal has encountered a number of errors but is still successfully processing transactions.

    1

    Critical

    The terminal is no longer able to process transactions.

    In the example response above, this contains the value:

    1

    That is, the status of the terminal is Critical.

6.3. TCP and UDP commands

eSocket.POS can process a number of commands via a TCP\UDP Command Port (see Tracing, Monitoring using Commands and Resyncing and Restarting eSocket.POS). The recommended configuration is a single command port per installation, configured in the eSocket.POS properties. The configuration key is 'postilion.esocketpos.CommandPort'.

Note that for backwards compatibility, a separate command port can be specified for each terminal in the esp_term_config table. However, this port is only used if the global command port is not configured in eSocket.POS properties.

6.3.1. TCP message header

TCP commands sent to the eSocket.POS command port must begin with a two byte header to indicate the length of the data segment of the message. This header must precede all TCP commands sent to eSocket.POS and precedes the command response from eSocket.POS.

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

Note
The 2-byte header does not apply to UDP commands.

6.3.2. Commands to a device group

When running eSocket.POS with multiple device groups (see Devices), it may be necessary to run a command against a specific device group. Commands to eSocket.POS usually take the following form:

<command>_<parameter>

If DeviceManager receives a command in the form shown above, it will run it against all device groups. To run a command against a specific device group, the command must take the following form:

<rank>_<command>_<parameter>

The rank is the rank as it is configured in ConfigServer.

6.4. Resyncing and restarting

6.4.1. Resyncing

eSocket.POS can resynchronize configuration data maintained in memory with the database. This is done by closing and re-initializing the terminal. The terminal is unable to process transactions during a resync. An event is logged for any transactions received during this time.

eSocket.POS can be resynchronized by means of UDP or TCP commands sent to the eSocket.POS command port. The syntax for the command is as follows:

RESYNC < terminal_ID >

The terminal ID parameter must be the terminal identifier of an active eSocket.POS terminal, or can be set to "ALL" if all active terminals must be resynchronized. Depending on the values set for the Config Agent properties, the Configuration Agent sends a RESYNC command to eSocket.POS when new configuration data becomes available.

6.4.2. Restarting

On receiving the RESTART command, eSocket.POS sends the RESTART_REQUIRED event to the POS. When running inside of the POS application it is the responsibility of the POS to restart itself. When running using the XML interface or the Message Front-end eSocket.POS is able to restart itself, depending on the configuration specified in the eSocket.POS properties.

Depending on the values set for the Config Agent properties, the Configuration Agent sends a RESTART command to eSocket.POS when new software updates and upgrades are applied.

6.5. Tracing

Transactions within eSocket.POS can be traced to an HTML file at a location specified in the eSocket.POS properties.

Trace information is appended to the HTML file until it reaches 100000 lines in size, after which a new file is created. As many as five files are stored, after which the oldest file is deleted whenever a new file is created.

Sensitive data is obfuscated in the trace file to meet PCI compliance requirements. This is done for the following fields as described:

  • Primary Account Number (field 2): The first six digits and the last four digits are shown. Remaining digits are replaced with stars.

  • Track 2 (field 35): The first six digits and the last four digits of the PAN and the entire expiry date (if present) are shown. Remaining digits are replaced with stars.

All the characters of the following fields (if present) are replaced with stars.

  • Track 3 (field 36)

  • Service Restriction Code (field 40)

  • Track 1 (field 45)

  • PIN Data (field 52)

  • CVV2 (field 127.10)

  • American Express Card Identifier (CID) (field 127.28)

6.5.1. Tracing impact in a live environment

Because of the amount of data generated, it is not recommended to use tracing for long periods in a production environment.

Tracing can negatively impact performance on low-end hardware or on a store server servicing many terminals under heavy load.

A trace file containing transactions from a live system can include sensitive information such as magnetic stripe data and PIN blocks. In the US, this may violate security requirements such as Visa CISP (Cardholder Information Security Program). Consult your acquirer if in doubt.

6.5.2. Tracing using UDP or TCP commands

Tracing can be controlled by means of commands sent to the eSocket.POS command port, specified in the eSocket.POS properties. The following commands are supported:

  • TRACE <terminal ID> ON

  • TRACE <terminal ID> OFF

  • TRACE <terminal ID> CLEAR

  • TRACE <terminal ID> <entity> ON

  • TRACE <terminal ID> <entity> OFF

The terminal ID parameter must be the terminal identifier of an active eSocket.POS terminal, or can be set to "ALL" if the command must be sent to all active terminals at this installation. If a separate port is configured for each terminal in the database, then this parameter must not be sent.

6.5.3. Trace settings using eSocket.POS properties

Tracing is off by default, but may be turned on automatically when eSocket.POS starts, by setting the property 'postilion.esocketpos.Trace' in the eSocket.POS properties. Possible values for this property include:

  • ON

  • CLEAR

  • <entity> <entity> …​ <entity> ON

  • <entity> <entity> …​ <entity> CLEAR

Note that CLEAR also has the effect of turning tracing on at startup when specified in the eSocket.POS properties. When TCP or UDP commands are used, TRACE CLEAR does not turn tracing on.

If specifying which entities are to be traced the options include those specified under the Tracing Entities below. E.g.

  • postilion.esocketpos.Trace=PIPELINE_MSG_UPDATES SOURCE SINK EVENT STARTUP PROPERTIES CLEAR

If trace entities are not specified then all entities are traced. For example:

  • postilion.esocketpos.Trace=ON

6.5.4. Trace styles

eSocket.POS supports two styles of tracing:

  • NORMAL - A verbose text view of all the information being traced.

  • CASCADE - A user-friendly summarized version. Clicking an item in the trace expands it to display the full details for that item. This setting assumes that Internet Explorer or the Trace Viewer is being used to view the trace file.

The trace style is set to CASCADE by default, but may be changed to NORMAL when eSocket.POS starts, by setting the property 'postilion.esocketpos.TraceStyle' in the eSocket.POS properties. The trace style can’t be changed using TCP or UDP commands.

6.5.5. Trace size

The maximum size of the eSocket.POS trace file is configurable by setting the property 'postilion.esocketpos.TraceNrLines' in the eSocket.POS properties.

6.5.6. Number of trace files

The maximum number of trace files for eSocket.POS is configurable by setting the property 'postilion.esocketpos.TraceNrFiles' in the eSocket.POS properties.

6.5.7. Trace entities

  • STARTUP - parameters used in initialization of the loaded esp_classes - for example, pipeline components or devices

  • PROPERTIES - properties used in initialization of eSocket.POS

  • EVENT - events and callbacks used for communication between the POS application, pipeline components and device driver

  • SOURCE - transaction messages between the terminal and the transaction pipeline source end

  • SINK - transaction messages between the transaction pipeline sink end and the remote entity, and connection related messages

  • XML - XML interface messages

  • PIPELINE - transaction messages through the pipeline

  • PIPELINE_MSG_UPDATES - updates to transaction messages through the pipeline (for example, field insertions, deletions and updates made by each component)

  • MSGENCRYPT - encrypted transaction messages

  • SSL - SSL handshake completion messages

  • DEVICE_MANAGER - device-related behavior implemented within the SDK, including serial number validation

Communication with devices is also traced, typically using the manufacturer name as the identifier. The following identifiers are used:

  • DIONE

  • HYPERCOM

  • INGENICO

  • MAGTEK

  • VERIFONE

6.6. Event Logging

A number of informational and error events are logged by eSocket.POS. Events can be logged to a text file when the postilion.esocketpos.util.Log4j LogDriver property is set.

See the example in the eSocket.POS property section.

Additional properties must be set when using Log4j.

Refer to the Third party licensing section for Log4j package licensing details.

6.6.1. Central event logging

eSocket.POS has additional event logging available. The central event log writes locally generated support event log entries to the support events database table, esp_support_events. The events are stored in the table until they have been delivered to PosConnect by means of the Monitoring pipeline component. The central event log is configured as a custom class with a class tag of LOG_DRIVER and with the following class name:

  • postilion.esocketpos.log.CentralSupportLog

For central event logging to support event aggregation, configure the following named parameters:

Name Default Description

ENABLED

1

Indicates whether event aggregation should be enabled or disabled: 0 = disabled 1 = enabled

CRITERIA

2

Specifies the event aggregation criteria: 1 = event ID only 2 = event ID and terminal ID

STARTUP_PERIOD

30

The time period, in seconds, at startup-up during which no event aggregation occurs. This caters for typical high volumes of events that occur at start-up.

HIGH_VOL_THRESHOLD

4

As events per aggregation time period are measured, when this threshold is reached then a high volume of events is being experienced.

TIME_PERIOD

60

The time period in seconds that is used to measure the aggregation period lengths

PERIOD_LENGTHS

1,10,60

A comma-separated list of period lengths used to calculate the aggregation time-period (TIME_PERIOD x PERIOD_LENGTHS)

DISABLE_EVENT_IDS

Empty

A comma-separated list of event IDs that should not be aggregated

Note
The support events database table is cleaned out by either the Transaction Cleaner pipeline component or the Store Cleaner component. If the central event log is enabled, then it is essential that either of these cleaning components are enabled and configured to clean old or undelivered events.
Event aggregation

The central event log can efficiently handle high volumes (up to thousands) of support events with the same event ID by aggregating these events before writing to the database table, esp_support_events. So in the case of a flood of the same event from a downstream entity, aggregating these events helps prevent the eSocket.POS database from filling up and reduces the number of events being sent upstream to PosConnect. Ultimately this helps reduce the impact on system resources.

For example, if a PIN entry device (PED) within the eSocket.POS terminal population malfunctions it may generate high volumes of error and warning events. At the start of such a high volume period, the central event log records the first few occurrences of the event and an aggregate event at the end of the aggregate time period. The aggregate event represents all the events during that aggregation time period with the same event ID, and is written to the database table.

While the high volume of events is sustained, the central event log gradually increases the length of the aggregation time period. By default, the aggregation time period changes from 60 seconds, to 600 seconds, and finally to 3600 seconds each. The final period length is repeated as long as the high volume of events persists. By default, the first four occurrences of the event are recorded in the first aggregation period and written to the database table. Only one occurrence of the event will be recorded in subsequent periods if a high volume of events is sustained.

Note
Currently, the central event log is the only eSocket.POS functionality that supports event aggregation.

6.6.2. Events

Each of the events that eSocket.POS or one of its components can log to the Windows Event Log, Tracing or the Postilion Support Framework is described in this section.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

6.6.150. Event 10147

Severity:

Warning

Symbolic Name:

SECURITY_PROVIDER_LOAD_FAILED

Message:

Text:

The security provider class that is required for PCI DSS 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 DSS compliancy and an attempt to make use of the PCI DSS features may result in an error.

Action:

No action required. See the eSocket.POS user guide for more information on PCI Data Security Standards.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Action:

o action required.

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

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

6.6.253. 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, the certificate issued during activation 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. There is also no default certificate configured (using configuration property postilion.esocketpos.UnactivatedClientCertAlias), the certificate configured is not present in the key store or it is not valid.

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, the certificate issued during activation will be used to connect to ConfigServer.

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

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

6.6.256. Event 10253

Severity:

Warning

Symbolic Name:

INCORRECT_USER_PARAM

Message:

Text:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

6.6.282. Event 10279

Severity:

Error

Symbolic Name:

HSQLDB_SERVER_LOG_ERROR_MESSAGE

Message:

Text:

HSQLDB Error Message: %1

Parameter %1:

The error message logged by the HSQLDB server

Description:

This event encapsulates HSQLDB server log 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 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:

Review the error message logged by the HSQLDB server to determine the action to take to rectify

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

6.7. Verifying version information

6.7.1. Displaying the installed eSocket.POS software versions

eSocket.POS provides a Version command-line utility that may be used to display and verify the installed version of eSocket.POS or one its plugin applications. The utility also lists all installed patches for the application, and validates that the file updates provided by those patches are present on the system and correct. If a patch is not listed, or problems are indicated, then that patch was not successfully applied.

To use this utility, run the following command at the command prompt:

<java> <classpath> <javapackage>.Version

Where:

  • <java> <classpath> is the invocation of the Java virtual machine with classpath parameters.

  • <javapackage> is the base Java package of eSocket.POS or a plugin application.

For example, to display the version of the base eSocket.POS deployment and all its installed patches, run:

java -cp c:\windows\java\classes postilion.esocketpos.Version

6.7.2. Displaying additional version information

In addition to the above, a VersionInfo command-line utility is provided to display auxiliary versioning information about the eSocket.POS system. This utility provides the same output as the Version utility, but reports the following additional information:

  • The installation checksum(s) for the eSocket.POS installation. This checksum may be used to uniquely identify a particular eSocket.POS software distribution.

Note
The VersionInfo utility is only available for the base eSocket.POS installation. It is not shipped with eSocket.POS plugins.

To use this utility, run the following command at the command prompt:

<java> <classpath> postilion.esocketpos.VersionInfo [<parameters>]

Where:

  • <java> <classpath> is the invocation of the Java virtual machine with classpath parameters.

  • <parameters> is a list of one or more command-line parameters defined in the table below.

    Parameter Description

    -c

    Displays the eSocket.POS installation checksum(s) only. If not specified, the eSocket.POS version and installed patches are listed in addition to the installation checksum(s).

    The eSocket.POS properties file also needs to be specified using the -p parameter.

    -p <properties-file>

    The fully-qualified path to the eSocket.POS properties file.

    Required when the installation checksums need to be displayed. If not specified, the installation checksums will not be shown.

For example, to only display the installation checksum(s) of the base eSocket.POS systems:

java -cp c:\windows\java\classes postilion.esocketpos.VersionInfo -c -p c:\postilion\eSocket.POS\properties.txt

7. eSocket.POS ServiceUtil

7.1. Overview

The eSocket.POS ServiceUtil application modifies the installed services on Windows and Linux. It is used to apply configuration resulting from updates to the eSocket.POS properties file, which can be updated with parameters required for the eSocket.POS services.

7.2. Running the utility

The following steps must be carried out to run the utility:

  1. Open a command or shell prompt.

  2. Run the following command:

    java -classpath <eSocket.POS class path> postilion.esocketpos.util.ServiceUtil <command> <properties file>

    Where <command> specifies the action to apply to the services and can be one of the following:

    • -updateservice - The update service action recreates all of the eSocket.POS services with any updates to parameters defined in the eSocket.POS properties file

    • -createservice - The create service action creates all of the eSocket.POS services with the parameters defined in the eSocket.POS properties file.

      Note
      This is only available on Windows and must be used if services are not installed on the system, or if the services were previously corrupted on the system.

Examples for running the utility:

  • Windows

    java -classpath c:\Program Files\Postilion\eSocket.POS\java;c:\Program Files\Postilion\eSocket.POS\bin\bcpkix-jdk15.jar;c:\Program Files\Postilion\bin\bcprov-jdk15.jar postilion.esocketpos.util.ServiceUtil -updateservice c:\Program Files\Postilion\eSocket.POS\properties.txt

  • Linux

    java -classpath /opt/Postilion/eSocket.POS/java:/opt/Postilion/eSocket.POS/bin/bcpkix-jdk15.jar:/opt/Postilion/eSocket.POS/bin/bcprov-jdk15.jar postilion.esocketpos.util.ServiceUtil -updateservice /opt/Postilion/eSocket.POS/properties.txt

Note
You must stop all running eSocket.POS services when running this utility so that the services can be recreated.

The following parameters can be updated from the properties file:

Windows
  • Classpath for the services

    Note
    This is configured from the postilion.esocketpos.install.ClassPath property.
  • Service log level

  • Service log prefix

  • JVM parameters, including Maximum memory pool size, Initial memory pool size, and the path to the JVM DLL

  • Service startup mode

  • Service dependencies

Linux
  • Classpath for the services

    Note
    This is configured from the postilion.esocketpos.install.ClassPath property
  • Enabling or disabling debugging

  • Path to the JSVC application used by the services

  • JVM parameters including Maximum memory pool size, Initial memory pool size, and the path to the JVM DLL

For more information, refer to the eSocket.POS installation utility - Manifest file page.

Note
  • The service will not be modified if services exist on the system and the "createservice" option is used.

  • Additional logging for this utility will be produced in the eSocket.POS trace file.

8. Troubleshooting

9. NullPointerException raised while processing ICC_DATA

This section addresses a JRE 8 compatibility issue when using eSocket.POS v2.8. In the release of JRE 8, the following APIs were deprecated:

  • The Java Endorsed Standards Override Mechanism

  • The Extension Mechanism for Support of Optional Packages

Therefore, applications using these mechanisms must migrate away from them. See the steps below to resolve this issue by removing the endorsed dirs registry option. Steps are also provided to revert this change if required.

Note
This change only applies when using JRE 8.

To resolve this issue, follow these steps to remove the endorsed dirs registry option:

  1. Stop the eSocket.POS service.

  2. Move the following jar files to: C:\Postilion\eSocket.POS\bin

    • xeresImpl.jar

    • xml-apis.jar

  3. Remove the "endorsed" folder from C:\Postilion\eSocket.POS\bin.

  4. Update the value of the JavaClassPath registry parameter for EspRun (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\EspRun\Parameters) to add the following entries:

    • C:\Postilion\eSocket.POS\bin\xercesImpl.jar;

    • C:\Postilion\eSocket.POS\bin\xml-apis.jar;

  5. Remove the java.endorsed.dirs key from the registry for the EspRun service (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\EspRun\Parameters\Properties).

  6. Start the eSocket.POS service.

To revert the previous instructions, follow these steps to add the endorsed dirs registry option:

  1. Stop the eSocket.POS service.

  2. Create a folder named "endorsed" in the C:\Postilion\eSocket.POS\bin folder.

  3. Move the jar files below to: C:\Postilion\eSocket.POS\bin\endorsed

    • xeresImpl.jar

    • xml-apis.jar

  4. Add the java.endorsed.dirs key from the registry for the EspRun service (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\EspRun\Parameters\Properties).

  5. Remove the following entries from the JavaClassPath registry (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\EspRun\Parameters)

    • C:\Postilion\eSocket.POS\bin\xercesImpl.jar;

    • C:\Postilion\eSocket.POS\bin\xml-apis.jar;

  6. Start the eSocket.POS service.

10. DTDs

10.1. TerminalData description

The XML elements described below are used to modify the contents of the eSocket.POS datastore. Each element typically corresponds to an operation on a specific database table. The DTD TerminalData.dtd is installed along with eSocket.POS and can be viewed with a text editor. The conditions associated with each element or attribute are indicated in parantheses

Element conditions:

Element Definition

<NONE>

The absence of a condition indicator means that that element is mandatory and that only one instance is permitted within the enclosing element.

?

This element is optional, but may only occur once within the enclosing element

*

The element is optional and there are no restrictions on the number of times it can occur within its parent element.

+

The element may be occur many times within its enclosing element, but it must occur at least once.

Attribute conditions:

Attribute Definition

#IMPLIED

This attribute is optional. These are typically used in update sub-elements of TerminalData

#REQUIRED

This attribute is mandatory in the enclosing element. Such attributes typically identify the information that is used to uniquely identify elements .

  • TerminalData ()

    • This element encapsulates all operations that may affect the terminal information in the datastore. All contained elements and data are related to a specific terminal

    • TerminalDataUpdate (*)

      • This element encapsulates all the information that is used to update an existing terminal category in the eSocket.POS datastore.

      • TerminalCategory (#REQUIRED)

        • description:The category of terminal to be updated.

        • input:ans..20

      • IsCardswipeInitSupported (#IMPLIED)

        • description:NO LONGER USED.

      • MerchantUpdate (*)

        • This element encapsulates the information needed to update the details of a merchant that already exists in the eSocket.POS datastore

        • MerchantType (#IMPLIED)

          • description:The classification of the merchant’s type of business product or service. Codes to be developed within each country.

          • input:n4

        • CardAcceptorIdCode (#IMPLIED)

          • description:A code identifying the card acceptor/merchant.

          • input:ans15

        • CardAcceptorNameLocation (#IMPLIED)

          • description:The name and location of the card acceptor.

          • input:ans40

      • PosDataUpdate (*)

        • This element encapsulates the information needed to update the terminal attributes that already exist in the eSocket.POS datastore

        • PinEntryCapability (#IMPLIED)

          • description:Indicates whether the terminal is capable of accepting PINs

          • input options:

            • 1 : if the terminal can accept PINs

            • 2 : if the terminal can not accept PINs

        • PosPinCaptureCode (#IMPLIED)

          • description:The maximum number of PIN characters that can be accepted by the Point-of-Service device.

          • input:"04" to "12"

        • CurrencyCodeTransaction (#IMPLIED)

          • description:The local currency of the acquirer or source location of the transaction

          • input:n3

        • CardDataInputCapability (#IMPLIED)

          • description:Indicates the mechanism by which card data was captured

          • input options:

            • 1 : manual data input (if the terminal has no mechanism for reading card data)

            • 2 : magnetic stripe read

            • 3 : bar code

            • 4 : for optical character recognition (OCR)

            • 5 : for integrated circuit card (ICC)

            • 6 : for key entry

        • CardholderAuthCapability (#IMPLIED)

          • description:Indicates the mechanism by which the cardholder’s identity was confirmed

          • input options:

            • 0 : if no electronic authentication can be perfomed

            • 1 : PIN

            • 2 : electronic signature analysis

            • 3 : biometrics

            • 4 : biographics

            • 5 : electronic authentication inoperative

            • 6 : other

        • CardCaptureCapability (#IMPLIED)

          • description:Indicates whether the terminal has the ability to retain cards

          • input options:

            • 0 : terminal cannot retain cards

            • 1 : terminal can capture cards

        • OperatingEnvironment (#IMPLIED)

          • description:Identifies the environment in which the terminal is being operated

          • input options:

            • 1 : on premises of card acceptor, attended

            • 2 : on premises of card acceptor, unattended

            • 3 : off premises of card acceptor, attended

            • 4 : off premises of card acceptor, unattended

            • 5 : on premises of card holder, unattended

        • CardholderPresence (#IMPLIED)

          • description:Indicated whether the cardholder was present at the time of the transaction

          • input options:

            • 0 : cardholder present

            • 1 : cardholder not present, unspecified

            • 2 : cardholder not present, mail order

            • 3 : cardholder not present, telephone

            • 4 : cardholder not present, standing authorization

        • CardDataOutputCapability (#IMPLIED)

          • description:Indicates the ability of the terminal to output data to the card

          • input options:

            • 1 : none

            • 2 : magnetic stripe write

            • 3 : integrated circuit card (ICC)

        • TerminalOutputCapability (#IMPLIED)

          • description:Indicates what output mechanisms the terminal has available

          • input options:

            • 1 : none

            • 2 : printing

            • 3 : display

            • 4 : printing and display

        • PinCaptureCapability (#IMPLIED)

          • description:Indicates the number of characters that the terminal is capable of capturing for PIN entry

          • input options:

            • 0 : no pin capture capability

            • 1 : unknown

            • 4 : four characters

            • 5 : five characters

            • 6 : six characters

            • 7 : seven characters

            • 8 : eight characters

            • 9 : nine characters

            • A : ten characters

            • B : eleven characters

            • C : twelve characters

        • TerminalOperator (#IMPLIED)

          • description:Identifies the entity that was operating the terminal at the time of the transaction

          • input options:

            • 0 : customer operated

            • 1 : card acceptor operated

            • 2 : administrative

        • TerminalType (#IMPLIED)

          • description:Code identifying the type of the terminal. Values are defined in the Postilion Interface Specification for the Terminal Type subfield of POS Data Code (field 123)

          • input:n2

        • TerminalOwner (#IMPLIED)

          • description:The name of the merchant at which this terminal is located

          • input:ans25

        • PosGeographicData (#IMPLIED)

          • description:A series of codes that identify the the state (positions 1-2), country (positions 3-5), postal service code (positions 6-14) and country code (positions 15-17) at the terminal’s physical location. The postal code may be alphanumeric, but all others are numeric. Any unused positions must be space filled

          • input:ans17

        • SponsorBank (#IMPLIED)

          • description:Identified the institution sponsoring the card acceptor’s POS terminal

          • input:ans8

        • TerminalCountryCode (#IMPLIED)

          • description:The ISO Terminal Country Code

          • input:n3

        • EmvTerminalCapabilities (#IMPLIED)

          • description:The EMV Terminal Capabilities. Contains the hexadecimal expansion of the binary EMV value.

          • input:ans6

        • EmvAddTermCapabilities (#IMPLIED)

          • description:The EMV Additional Terminal Capabilities. Contains the hexadecimal expansion of the binary EMV value.

          • input:ans10

        • EmvTerminalType (#IMPLIED)

          • description:The EMV Terminal Type. Typically '22'.

          • input:n2

        • AutoAidSelection (#IMPLIED)

          • description:Indicates whether the automatic selection of an application for multi-application cards is enabled.

          • input options:

            • 0 : Automatic selection is not enabled

            • 1 : Automatic selection is enabled

        • SupportedLanguages (#IMPLIED)

          • description:The list of supported languages. The 2-character language codes are concatenated to form this list.

          • input:a60

        • PromptLanguage (#IMPLIED)

          • description:A 2-character language code used during EMV transactions when the list of supported languages does not contain the cardholder’s preferred language. It is also used to retrieve the resource bundle to use for non-EMV prompts.

          • input:a2

        • CustomerLangSelection (#IMPLIED)

          • description:Indicates if manual language selection is enabled.

          • input options:

            • 0 : Disabled

            • 1 : Enabled

        • AidSelectionMethod (#IMPLIED)

          • description:The method used to select the Application Identifier during EMV transactions.

          • input options:

            • 0 : Disabled (Auto Aid Selection deactivated)

            • 1 : US Common Debit AID prioritized

            • 2 : International AID prioritized

            • 3 : Customer selection

            • 4 : Auto Aid Selection activated

      • CustomClassUpdate (*)

        • This element is used to update information about the processing and device integration classes that are used by eSocket.POS

        • PipelineClassUpdate (*)

          • This element is used to update the information for a class in one of the eSocket.POS transaction processing pipelines.

          • PipelineTag (#REQUIRED)

            • description:Indicates the pipeline for which the class to be updated has been configured

            • input options:

              • REQ_PIPELINE : if the class to be updated is in the request pipeline

              • RSP_PIPELINE : if the class to be updated is in the response pipeline

          • Rank (#REQUIRED)

            • description:Indicates the current ranking of the class that is to be updated. Ranks must be sequential, starting from 1. Note that class rankings are used to uniquely identify pipeline classes and thus cannot be updated. To change the rank of a class, it must be deleted and re-inserted with the required rank

            • input:INTEGER

          • Classname (#IMPLIED)

            • description:The fully qualified Java class name of the component

            • input:ans..255

          • ParamString (#IMPLIED)

            • description:Additional configuration information that may be required by the component. Please consult the specific component’s documentation for details

            • input:ans..255

          • UpdateParams (#IMPLIED)

            • description:A parameter indicating an update to be applied, for instance a device firmware update. Refer to the specific component’s documentation for details.

            • input:ans..255

        • PipelineClassDelete (*)

          • This element is used to remove a class from one of the eSocket.POS processing pipelines.

          • PipelineTag (#REQUIRED)

            • description:Indicates the pipeline for which the class to be deleted has been configured

            • input options:

              • REQ_PIPELINE : if the class to be deleted is in the request pipeline

              • RSP_PIPELINE : if the class to be deleted is in the response pipeline

          • Rank (#REQUIRED)

            • description:Indicates the current ranking of the class that is to be deleted. When removing a class, it is important to keep in mind that the ranks of the remaining classes are not adjusted in any way. They must be updated separately, because ranks must remain sequential without gaps. This has the effect of making it a simple matter to replace a class of a specific rank. On the other hand, if classes are frequently removed and new ones inserted with new ranks (i.e. not with the same rank of a removed class) then it may become difficult to keep track of the ranks of the pipeline classes.

            • input:INTEGER

        • PipelineClassInsert (*)

          • This element is used to insert a processing class into one of the eSocket.POS transaction processing pipelines.

          • PipelineTag (#REQUIRED)

            • description:Indicates the processing pipeline into which the component is to be inserted

            • input options:

              • REQ_PIPELINE : if the class is being inserted into the request pipeline

              • RSP_PIPELINE : if the class is being inserted into the response pipeline

          • Rank (#REQUIRED)

            • description:The rank with which the class must be inserted. The rank of a class defines its position in the processing pipeline. Ranks must be sequential, starting from 1.

            • input:INTEGER

          • Classname (#REQUIRED)

            • description:The fully qualified Java class name of the component

            • input:ans..255

          • ParamString (#IMPLIED)

            • description:Additional configuration information that may be required by the component. Please consult the specific component’s documentation for details

            • input:ans..255

          • UpdateParams (#IMPLIED)

            • description:A parameter indicating an update to be applied, for instance a device firmware update. Refer to the specific component’s documentation for details.

            • input:ans..255

        • TaggedClassUpdate (*)

          • This element encapsulates the information required to update a tagged (i.e. non-pipeline class) integration class. If eSocket.POS is configured for multiple device groups then this element affects the default or first device group.

          • Tag (#REQUIRED)

            • description:The tag that uniquely identifies the class.

            • input:ans..80

          • Classname (#IMPLIED)

            • description:The fully qualified Java class name of the integration class.

            • input:ans..255

          • ParamString (#IMPLIED)

            • description:Additional configuration information that may be required by the component. Please consult the specific component’s documentation for details

            • input:ans..255

          • UpdateParams (#IMPLIED)

            • description:A parameter indicating an update to be applied, for instance a device firmware update. Refer to the specific component’s documentation for details.

            • input:ans..255

          • ExtendedParameters (#IMPLIED)

            • description:A field for adding multiple extended parameters.

            • input:ans..

        • TaggedClassDelete (*)

          • This element is used to remove an existing tagged class from the eSocket.POS datastore. If eSocket.POS is configured for multiple device groups then this element affects the default or first device group.

          • Tag (#REQUIRED)

            • description:The tag that uniquely identifies the class.

            • input:ans..80

        • TaggedClassInsert (*)

          • This element is used to insert a new tagged class into the eSocket.POS datastore. If eSocket.POS is configured for multiple device groups then this element affects the default or first device group.

          • Tag (#REQUIRED)

            • description:The tag that uniquely identifies the class.

            • input options:

              • SOURCE : If this is the integration class that is to be used for the source entity.

              • SINK : If this is the integration class that is to be used for the sink entity.

              • CARDREADER : If this if the cardreader integration class.

              • DISPLAY : If this is the display integration class.

              • KEYPAD : If this is the keypad integration class.

              • PINPAD : If this is the pinpad integration class.

              • SMARTCARDREADER : If this is the integration class for the smart card/ICC reader.

              • CHECKREADER : If this is the integration class for the check reader.

              • SIGNATURECAPTURE : If this is the integration class for the signature capture device.

              • OPERATORDISPLAY : If this is the integration class for the operator display device.

          • Classname (#REQUIRED)

            • description:The fully qualified Java class name of the integration class.

            • input:ans..255

          • ParamString (#IMPLIED)

            • description:Additional configuration information that may be required by the component. Please consult the specific component’s documentation for details

            • input:ans..255

          • UpdateParams (#IMPLIED)

            • description:A parameter indicating an update to be applied, for instance a device firmware update. Refer to the specific component’s documentation for details.

            • input:ans..255

          • ExtendedParameters (#IMPLIED)

            • description:A field for adding multiple extended parameters.

            • input:ans..

        • DeviceClassUpdate (*)

          • This element encapsulates the information required to update a device (i.e. non-pipeline class) integration class. If eSocket.POS is configured for multiple device groups then this element affects the specified device group.

          • Tag (#REQUIRED)

            • description:The tag that uniquely identifies the class.

            • input:ans..80

          • Classname (#IMPLIED)

            • description:The fully qualified Java class name of the integration class.

            • input:ans..255

          • Rank (#REQUIRED)

            • description:Indicates the current ranking of the class that is to be updated. Note that class rankings are used to uniquely identify device classes and thus cannot be updated. To change the rank of a device class, it must be deleted and re-inserted with the required rank

            • input:INTEGER

          • ParamString (#IMPLIED)

            • description:Additional configuration information that may be required by the component. Consult the specific component’s documentation for details

            • input:ans..255

          • UpdateParams (#IMPLIED)

            • description:A parameter indicating an update to be applied, for instance a device firmware update. Refer to the specific component’s documentation for details.

            • input:ans..255

          • ExtendedParameters (#IMPLIED)

            • description:A field for adding multiple extended parameters.

            • input:ans..

        • DeviceClassDelete (*)

          • This element is used to remove an existing tagged class from the eSocket.POS datastore. If eSocket.POS is being configured for multiple device groups then this element affects the specified device group.

          • Tag (#REQUIRED)

            • description:The tag that uniquely identifies the class.

            • input:ans..80

          • Rank (#REQUIRED)

            • description:The rank of the class which must be removed. The rank of a class indicates the device group that it has been assigned to.

            • input:INTEGER

        • DeviceClassInsert (*)

          • This element is used to insert a new tagged class into the eSocket.POS datastore. If eSocket.POS is being configured for multiple device groups then this element affects the specified device group.

          • Tag (#REQUIRED)

            • description:The tag that uniquely identifies the class.

            • input options:

              • SOURCE : If this is the integration class that is to be used for the source entity.

              • SINK : If this is the integration class that is to be used for the sink entity.

              • CARDREADER : If this if the cardreader integration class.

              • DISPLAY : If this is the display integration class.

              • KEYPAD : If this is the keypad integration class.

              • PINPAD : If this is the pinpad integration class.

              • SMARTCARDREADER : If this is the integration class for the smart card/ICC reader.

              • CHECKREADER : If this is the integration class for the check reader.

              • SIGNATURECAPTURE : If this is the integration class for the signature capture device.

              • OPERATORDISPLAY : If this is the integration class for the operator display device.

          • Classname (#REQUIRED)

            • description:The fully qualified Java class name of the integration class.

            • input:ans..255

          • Rank (#REQUIRED)

            • description:The rank with which the class must be inserted. The rank of a class indicates the device group that it has been assigned to.

            • input:INTEGER

          • ParamString (#IMPLIED)

            • description:Additional configuration information that may be required by the component. Please consult the specific component’s documentation for details

            • input:ans..255

          • UpdateParams (#IMPLIED)

            • description:A parameter indicating an update to be applied, for instance a device firmware update. Refer to the specific component’s documentation for details.

            • input:ans..255

          • ExtendedParameters (#IMPLIED)

            • description:A field for adding multiple extended parameters.

            • input:ans..

    • TerminalDataDelete (*)

      • This element is used used to delete an existing terminal category from the eSocket.POS datastore.

      • TerminalCategory (#REQUIRED)

        • description:The category of terminal to be deleted.

        • input:ans..20

    • TerminalDataInsert (*)

      • This element encapsulates all the information that is used to insert a new terminal category into the eSocket.POS datastore.

      • TerminalCategory (#REQUIRED)

        • description:The category of terminal to be inserted.

        • input:ans..20

      • IsCardswipeInitSupported (#REQUIRED)

        • description:NO LONGER USED. Set to 0.

      • MerchantInsert ()

        • This element is used to insert the merchant information for a new terminal.

        • MerchantType (#REQUIRED)

          • description:The classification of the merchant’s type of business product or service. Codes to be developed within each country.

          • input:n4

        • CardAcceptorIdCode (#REQUIRED)

          • description:A code identifying the card acceptor/merchant.

          • input:ans15

        • CardAcceptorNameLocation (#REQUIRED)

          • description:The name and location of the card acceptor.

          • input:ans40

      • PosDataInsert ()

        • This element is used to insert the POS configuration information for a new terminal into the eSocket.POS datastore.

        • PinEntryCapability (#REQUIRED)

          • description:Indicates whether the terminal is capable of accepting PINs

          • input options:

            • 1 : if the terminal can accept PINs

            • 2 : if the terminal can not accept PINs

        • PosPinCaptureCode (#REQUIRED)

          • description:The maximum number of PIN characters that can be accepted by the Point-of-Service device.

          • input:"04" to "12"

        • CurrencyCodeTransaction (#REQUIRED)

          • description:The local currency of the acquirer or source location of the transaction

          • input:n3

        • CardDataInputCapability (#REQUIRED)

          • description:Indicates the mechanism by which card data was captured

          • input options:

            • 1 : manual data input (if the terminal has no mechanism for reading card data)

            • 2 : magnetic stripe read

            • 3 : bar code

            • 4 : for optical character recognition (OCR)

            • 5 : for integrated circuit card (ICC)

            • 6 : for key entry

        • CardholderAuthCapability (#REQUIRED)

          • description:Indicates the mechanism by which the cardholder’s identity was confirmed

          • input options:

            • 0 : if no electronic authentication can be perfomed

            • 1 : PIN

            • 2 : electronic signature analysis

            • 3 : biometrics

            • 4 : biographics

            • 5 : electronic authentication inoperative

            • 6 : other

        • CardCaptureCapability (#REQUIRED)

          • description:Indicates whether the terminal has the ability to retain cards

          • input options:

            • 0 : terminal cannot retain cards

            • 1 : terminal can capture cards

        • OperatingEnvironment (#REQUIRED)

          • description:Identifies the environment in which the terminal is being operated

          • input options:

            • 1 : on premises of card acceptor, attended

            • 2 : on premises of card acceptor, unattended

            • 3 : off premises of card acceptor, attended

            • 4 : off premises of card acceptor, unattended

            • 5 : on premises of card holder, unattended

        • CardholderPresence (#REQUIRED)

          • description:Indicated whether the cardholder was present at the time of the transaction

          • input options:

            • 0 : cardholder present

            • 1 : cardholder not present, unspecified

            • 2 : cardholder not present, mail order

            • 3 : cardholder not present, telephone

            • 4 : cardholder not present, standing authorization

        • CardDataOutputCapability (#REQUIRED)

          • description:Indicates the ability of the terminal to output data to the card

          • input options:

            • 1 : none

            • 2 : magnetic stripe write

            • 3 : integrated circuit card (ICC)

        • TerminalOutputCapability (#REQUIRED)

          • description:Indicates what output mechanisms the terminal has available

          • input options:

            • 1 : none

            • 2 : printing

            • 3 : display

            • 4 : printing and display

        • PinCaptureCapability (#REQUIRED)

          • description:Indicates the number of characters that the terminal is capable of capturing for PIN entry

          • input options:

            • 0 : no pin capture capability

            • 1 : unknown

            • 4 : four characters

            • 5 : five characters

            • 6 : six characters

            • 7 : seven characters

            • 8 : eight characters

            • 9 : nine characters

            • A : ten characters

            • B : eleven characters

            • C : twelve characters

        • TerminalOperator (#REQUIRED)

          • description:Identifies the entity that was operating the terminal at the time of the transaction

          • input options:

            • 0 : customer operated

            • 1 : card acceptor operated

            • 2 : administrative

        • TerminalType (#REQUIRED)

          • description:Code identifying the type of the terminal. Values are defined in the Postilion Interface Specification for the Terminal Type subfield of POS Data Code (field 123)

          • input:n2

        • TerminalOwner (#REQUIRED)

          • description:The name of the merchant at which this terminal is located

          • input:ans25

        • PosGeographicData (#REQUIRED)

          • description:A series of codes that identify the the state (positions 1-2), country (positions 3-5), postal service code (positions 6-14) and country code (positions 15-17) at the terminal’s physical location. The postal code may be alphanumeric, but all others are numeric. Any unused positions must be space filled

          • input:ans17

        • SponsorBank (#REQUIRED)

          • description:Identified the institution sponsoring the card acceptor’s POS terminal

          • input:ans8

        • TerminalCountryCode (#IMPLIED)

          • description:The ISO Terminal Country Code

          • input:n3

        • EmvTerminalCapabilities (#IMPLIED)

          • description:The EMV Terminal Capabilities. Contains the hexadecimal expansion of the binary EMV value.

          • input:ans6

        • EmvAddTermCapabilities (#IMPLIED)

          • description:The EMV Additional Terminal Capabilities. Contains the hexadecimal expansion of the binary EMV value.

          • input:ans10

        • EmvTerminalType (#IMPLIED)

          • description:The EMV Terminal Type. Typically '22'.

          • input:n2

        • AutoAidSelection (#IMPLIED)

          • description:Indicates whether the automatic selection of an application for multi-application cards is enabled.

          • input options:

            • 0 : Automatic selection is not enabled

            • 1 : Automatic selection is enabled

        • SupportedLanguages (#IMPLIED)

          • description:The list of supported languages. The 2-character language codes are concatenated to form this list.

          • input:a60

        • PromptLanguage (#IMPLIED)

          • description:A 2-character language code used during EMV transactions when the list of supported languages does not contain the cardholder’s preferred language. It is also used to retrieve the resource bundle to use for non-EMV prompts.

          • input:a2

        • CustomerLangSelection (#IMPLIED)

          • description:Indicates if manual language selection is enabled.

          • input options:

            • 0 : Disabled

            • 1 : Enabled

        • AidSelectionMethod (#IMPLIED)

          • description:The method used to select the Application Identifier during EMV transactions.

          • input:n1

          • input options:

            • 0 : Disabled (Auto Aid Selection deactivated, default)

            • 1 : US Common Debit AID prioritized

            • 2 : International AID prioritized

            • 3 : Customer selection

            • 4 : Auto Aid Selection activated

      • CustomClassInsert (?)

        • This element is used to update information about the processing and device integration classes that are used by eSocket.POS

        • PipelineClassInsert (*)

          • This element is used to insert a processing class into one of the eSocket.POS transaction processing pipelines.

          • PipelineTag (#REQUIRED)

            • description:Indicates the processing pipeline into which the component is to be inserted

            • input options:

              • REQ_PIPELINE : if the class is being inserted into the request pipeline

              • RSP_PIPELINE : if the class is being inserted into the response pipeline

          • Rank (#REQUIRED)

            • description:The rank with which the class must be inserted. The rank of a class defines its position in the processing pipeline. Ranks must be sequential, starting from 1.

            • input:INTEGER

          • Classname (#REQUIRED)

            • description:The fully qualified Java class name of the component

            • input:ans..255

          • ParamString (#REQUIRED)

            • description:Additional configuration information that may be required by the component. Please consult the specific component’s documentation for details

            • input:ans..255

        • TaggedClassInsert (*)

          • This element is used to insert a new tagged class into the eSocket.POS datastore.

          • Tag (#REQUIRED)

            • description:The tag that uniquely identifies the class.

            • input options:

              • SOURCE : If this is the integration class that is to be used for the source entity.

              • SINK : If this is the integration class that is to be used for the sink entity.

              • CARDREADER : If this if the cardreader integration class.

              • DISPLAY : If this is the display integration class.

              • KEYPAD : If this is the keypad integration class.

              • PINPAD : If this is the pinpad integration class.

              • SMARTCARDREADER : If this is the integration class for the smart card/ICC reader.

          • Classname (#REQUIRED)

            • description:The fully qualified Java class name of the integration class.

            • input:ans..255

          • ParamString (#IMPLIED)

            • description:Additional configuration information that may be required by the component. Please consult the specific component’s documentation for details

            • input:ans..255

10.2. TerminalConfig description

The XML elements described below are used to modify the contents of the eSocket.POS datastore. Each element typically corresponds to an operation on a specific database table. The DTD TerminalConfig.dtd is installed along with eSocket.POS and can be viewed with a text editor. The conditions associated with each element or attribute are indicated in parantheses

Element conditions:

Element Definition

<NONE>

The absence of a condition indicator means that that element is mandatory and that only one instance is permitted within the enclosing element.

?

This element is optional, but may only occur once within the enclosing element

*

The element is optional and there are no restrictions on the number of times it can occur within its parent element.

+

The element may be occur many times within its enclosing element, but it must occur at least once.

Attribute conditions:

Attribute Definition

#IMPLIED

This attribute is optional. These are typically used in update sub-elements of TerminalConfig

#REQUIRED

This attribute is mandatory in the enclosing element. Such attributes typically identify the information that is used to uniquely identify elements .

  • TerminalConfig ()

    • Parent aggregate for eSocket.POS terminal configuration information. It may contain information for adding, removing or updating the terminal information in the eSocket.POS datastore.

    • TerminalUpdate (*)

      • This aggegate contains information that will be used to update an existing terminal. The terminal to be updated is identified by the required terminal ID.

      • TerminalId (#REQUIRED)

        • description:The ID number of the terminal to be updated.

        • input:an8

      • TerminalCategory (#IMPLIED)

        • description:This information determines the set of terminal specific data (such as merchant ID, etc) that will be applied to this terminal.

        • input:ans..20

      • ProcessingCategory (#IMPLIED)

        • description:The processing category of a terminal determines the set of processing data that will be used by the terminal. Processing data is card information, account information, etc.

        • input:ans..20

      • CommandPort (#IMPLIED)

        • description:The TCP port on which the eSocket.POS instance that is controlling this terminal must listen for commands. Use 0 if no command port is required.

        • input:INT

      • PosSequenceNumber (#IMPLIED)

        • description:The Sequence Number of the terminal

        • input:ans6

      • TerminalName (#IMPLIED)

        • description:A descriptive name for the terminal

        • input:ans..40

      • CardAcceptorIdCode (#IMPLIED)

        • description:A code identifying the card acceptor/merchant).

        • input:ans15

      • CardAcceptorNameLocation (#IMPLIED)

        • description:The name and location of the card acceptor.

        • input:ans40

      • CustomData (#IMPLIED)

        • description:Additional data for this terminal, for use by custom components.

        • input:ans..

      • RolloutGroup (#IMPLIED)

        • description:A revision of the store configuration. Currently only used to define separate sets of allowed serial numbers. An example of how this might be used is to distinguish pilot terminals from stable terminals.

        • input:ans..20

      • StoreID (#IMPLIED)

        • description:A consistent and unique store identifier. Note that this is distinct from the MerchantId property value (which is assigned by the acquirer and for which there may be more than one value per store).

        • input:ans..25

      • LaneProfile (#IMPLIED)

        • description:The type of lane, for example a food lane or a self-service lane.

        • input:ans..20

      • InterruptEligibleCards (#IMPLIED)

        • description:The card products eligible for payment interrupts.

        • input:ans..1000

      • BinSetCategory (#IMPLIED)

        • description:The BIN set category of a terminal determines the set of BINs that will be used by the terminal. This field should only be populated if the configuration makes use of the normalized file format.

        • input:ans..20

      • AcquirerCardAcceptorMappingCategory (#IMPLIED)

        • description:The Acquirer Card Acceptor Mapping category of a terminal determines the set of card acceptor mappings that will be used by the terminal. This field should only be populated if the configuration makes use of the normalized file format.

        • input:ans..20

      • DccSupport (#IMPLIED)

        • description:Indicates whether dynamic currency conversion (DCC) is supported by a terminal.

        • input:n1

        • input options:

          • ** : not set

          • 0 : not supported

          • 1 : supported

      • DeviceUpdate (*)

        • This aggregate is used to update existing information for a particular device

        • Tag (#REQUIRED)

          • description:This identifies the particular device that is to be updated.

          • input:ans..80

        • RemoteIPAddress (#IMPLIED)

          • description:The IP Address or name of the machine to which the device is connected.

          • input:ans..15

        • RemotePort (#IMPLIED)

          • description:The TCP port on which the device, or its TCP to serial bridge, is listening.

          • input:INT

        • SerialPort (#IMPLIED)

          • description:The identifier of the serial port to which the device is connected (used if eSocket.POS communicates with the device via a serial connection) NOTE: Replaced by SapAddress

          • input:ans..12

        • BaudRate (#IMPLIED)

          • description:The baud rate at which the device communicates (used if eSocket.POS communicates with the device via a serial connection)

          • input:n..5

        • DataBits (#IMPLIED)

          • description:The number of data bits used by the device (used if eSocket.POS communicates with the device via a serial connection)

          • input:n1

        • StopBits (#IMPLIED)

          • description:The number of stop bits used by the device (used if eSocket.POS communicates with the device via a serial connection)

          • input:n1

        • Parity (#IMPLIED)

          • description:The parity used by the device (used if eSocket.POS communicates with the device via a serial connection)

          • input options:

            • NONE : if no parity is used

            • EVEN : if the device uses an even parity scheme

            • ODD : if the device uses an odd parity scheme

        • FilterClass (#IMPLIED)

          • description:The Filter Class required by the device. Please consult the documentation for the device integration software for this value.

        • Params (#IMPLIED)

          • description:A list of space-separated parameters for communication with the device. Please consult the documentation for the device integration software for this value.

        • CustomSapFactory (#IMPLIED)

          • description:The name of the CustomSapFactory class that will be used to establish a connection with the device.

          • input:ans..255

        • SapAddress (#IMPLIED)

          • description:The address of the device. eg SerialPort or CustomSapFactory address NOTE: the SapAddress is used to specify the SerialPort.

          • input:ans..128

        • SetupData (#IMPLIED)

          • description:The setup data used by the CustomSapFactory.

          • input:ans..100

      • DeviceDelete (*)

        • This element is used to remove a device that is associated with a particular terminal.

        • Tag (#REQUIRED)

          • description:This identifies the particular device that is to be removed.

          • input:ans..80

      • DeviceInsert (*)

        • This aggregate is used to associate a new device with a terminal

        • Tag (#REQUIRED)

          • description:This identifies the particular device that is to be added.

          • input:ans..80

        • RemoteIPAddress (#REQUIRED)

          • description:The IP Address or name of the machine to which the device is connected. This value should only be specified if eSocket.POS is to use a TCP/IP connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. RemoteIPAddress="") in the configuration file.

          • input:ans..15

        • RemotePort (#REQUIRED)

          • description:The TCP port on which the device, or its TCP to serial bridge, is listening. This value should only be specified if eSocket.POS is to use a TCP/IP connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. RemotePort="") in the configuration file.

          • input:INT

        • SerialPort (#REQUIRED)

          • description:The identifier of the serial port to which the device is connected. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. SerialPort="") in the configuration file.

          • input:ans..12

        • BaudRate (#REQUIRED)

          • description:The baud rate at which the device communicates. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. BaudRate="") in the configuration file.

          • input:n..5

        • DataBits (#REQUIRED)

          • description:The number of data bits used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. DataBits="") in the configuration file.

          • input:n1

        • StopBits (#REQUIRED)

          • description:The number of stop bits used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. StopBits="") in the configuration file.

          • input:n1

        • Parity (#REQUIRED)

          • description:The parity used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. Parity="") in the configuration file.

          • input options:

            • NONE : if no parity is used

            • EVEN : if the device uses an even parity scheme

            • ODD : if the device uses an odd parity scheme

        • FilterClass (#REQUIRED)

          • description:The Filter Class required by the device. Please consult the documentation for the device integration software for this value.

        • Params (#REQUIRED)

          • description:A list of space-separated parameters for communication with the device. Please consult the documentation for the device integration software for this value.

        • CustomSapFactory (#IMPLIED)

          • description:The name of the CustomSapFactory class that will be used to establish a connection with the device.

          • input:ans..255

        • SapAddress (#IMPLIED)

          • description:The address of the device. eg SerialPort or CustomSapFactory address NOTE: the SapAddress is used to specify the SerialPort.

          • input:ans..128

        • SetupData (#IMPLIED)

          • description:The setup data used by the CustomSapFactory.

          • input:ans..100

      • RankedDeviceUpdate (*)

        • This aggregate is used to update existing information for a particular device

        • Tag (#REQUIRED)

          • description:This identifies the particular device that is to be updated.

          • input:ans..80

        • RemoteIPAddress (#IMPLIED)

          • description:The IP Address or name of the machine to which the device is connected.

          • input:ans..15

        • RemotePort (#IMPLIED)

          • description:The TCP port on which the device, or its TCP to serial bridge, is listening.

          • input:INT

        • SerialPort (#IMPLIED)

          • description:The identifier of the serial port to which the device is connected (used if eSocket.POS communicates with the device via a serial connection) NOTE: Replaced by SapAddress

          • input:ans..12

        • BaudRate (#IMPLIED)

          • description:The baud rate at which the device communicates (used if eSocket.POS communicates with the device via a serial connection)

          • input:n..5

        • DataBits (#IMPLIED)

          • description:The number of data bits used by the device (used if eSocket.POS communicates with the device via a serial connection)

          • input:n1

        • StopBits (#IMPLIED)

          • description:The number of stop bits used by the device (used if eSocket.POS communicates with the device via a serial connection)

          • input:n1

        • Parity (#IMPLIED)

          • description:The parity used by the device (used if eSocket.POS communicates with the device via a serial connection)

          • input options:

            • NONE : if no parity is used

            • EVEN : if the device uses an even parity scheme

            • ODD : if the device uses an odd parity scheme

        • FilterClass (#IMPLIED)

          • description:The Filter Class required by the device. Please consult the documentation for the device integration software for this value.

        • Params (#IMPLIED)

          • description:A list of space-separated parameters for communication with the device. Please consult the documentation for the device integration software for this value.

        • CustomSapFactory (#IMPLIED)

          • description:The name of the CustomSapFactory class that will be used to establish a connection with the device.

          • input:ans..255

        • SapAddress (#IMPLIED)

          • description:The address of the device. eg SerialPort or CustomSapFactory address NOTE: the SapAddress is used to specify the SerialPort.

          • input:ans..128

        • SetupData (#IMPLIED)

          • description:The setup data used by the CustomSapFactory.

          • input:ans..100

        • Rank (#REQUIRED)

          • description:The device group(rank) of the device.

          • input:n..4

      • RankedDeviceDelete (*)

        • This element is used to remove a device that is associated with a particular terminal.

        • Tag (#REQUIRED)

          • description:This identifies the particular device that is to be removed.

          • input:ans..80

        • Rank (#REQUIRED)

          • description:The device group(rank) of the device.

          • input:n..4

      • RankedDeviceInsert (*)

        • This aggregate is used to associate a new device with a terminal

        • Tag (#REQUIRED)

          • description:This identifies the particular device that is to be added.

          • input:ans..80

        • RemoteIPAddress (#REQUIRED)

          • description:The IP Address or name of the machine to which the device is connected. This value should only be specified if eSocket.POS is to use a TCP/IP connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. RemoteIPAddress="") in the configuration file.

          • input:ans..15

        • RemotePort (#REQUIRED)

          • description:The TCP port on which the device, or its TCP to serial bridge, is listening. This value should only be specified if eSocket.POS is to use a TCP/IP connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. RemotePort="") in the configuration file.

          • input:INT

        • SerialPort (#REQUIRED)

          • description:The identifier of the serial port to which the device is connected. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. SerialPort="") in the configuration file.

          • input:ans..12

        • BaudRate (#REQUIRED)

          • description:The baud rate at which the device communicates. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. BaudRate="") in the configuration file.

          • input:n..5

        • DataBits (#REQUIRED)

          • description:The number of data bits used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. DataBits="") in the configuration file.

          • input:n1

        • StopBits (#REQUIRED)

          • description:The number of stop bits used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. StopBits="") in the configuration file.

          • input:n1

        • Parity (#REQUIRED)

          • description:The parity used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. Parity="") in the configuration file.

          • input options:

            • NONE : if no parity is used

            • EVEN : if the device uses an even parity scheme

            • ODD : if the device uses an odd parity scheme

        • FilterClass (#REQUIRED)

          • description:The Filter Class required by the device. Please consult the documentation for the device integration software for this value.

        • Params (#REQUIRED)

          • description:A list of space-separated parameters for communication with the device. Please consult the documentation for the device integration software for this value.

        • CustomSapFactory (#IMPLIED)

          • description:The name of the CustomSapFactory class that will be used to establish a connection with the device.

          • input:ans..255

        • SapAddress (#IMPLIED)

          • description:The address of the device. eg SerialPort or CustomSapFactory address NOTE: the SapAddress is used to specify the SerialPort.

          • input:ans..128

        • SetupData (#IMPLIED)

          • description:The setup data used by the CustomSapFactory.

          • input:ans..100

        • Rank (#REQUIRED)

          • description:The device group(rank) of the device.

          • input:n..4

    • TerminalDelete (*)

      • This aggregate is used to remove an existing terminal from the eSocket.POS datastore.

      • TerminalId (#REQUIRED)

        • description:The ID number of the terminal that is to be removed

        • input:an8

    • TerminalInsert (*)

      • This aggregate contains the information necessary to add a new terminal to the eSocket.POS datastore.

      • TerminalId (#REQUIRED)

        • description:The ID number of the terminal to be updated.

        • input:an8

      • TerminalCategory (#REQUIRED)

        • description:This information determines the set of terminal specific data (such as merchant ID, etc) that will be applied to this terminal.

        • input:ans..20

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of a terminal determines the set of processing data that will be used by the terminal. Processing data is card information, account information, etc.

        • input:ans..20

      • CommandPort (#REQUIRED)

        • description:The TCP port on which the eSocket.POS instance that is controlling this terminal must listen for commands. Use 0 if no command port is required.

        • input:INT

      • PosSequenceNumber (#REQUIRED)

        • description:The Sequence Number of the terminal

        • input:ans6

      • TerminalName (#IMPLIED)

        • description:A descriptive name for the terminal

        • input:ans..40

      • CardAcceptorIdCode (#IMPLIED)

        • description:A code identifying the card acceptor/merchant).

        • input:ans15

      • CardAcceptorNameLocation (#IMPLIED)

        • description:The name and location of the card acceptor.

        • input:ans40

      • CustomData (#IMPLIED)

        • description:Additional data for this terminal, for use by custom components.

        • input:ans..

      • RolloutGroup (#IMPLIED)

        • description:A revision of the store configuration. Currently only used to define separate sets of allowed serial numbers. An example of how this might be used is to distinguish pilot terminals from stable terminals.

        • input:ans..20

      • StoreID (#IMPLIED)

        • description:A consistent and unique store identifier. Note that this is distinct from the MerchantId property value (which is assigned by the acquirer and for which there may be more than one value per store).

        • input:ans..25

      • LaneProfile (#IMPLIED)

        • description:The type of lane, for example a food lane or a self-service lane.

        • input:ans..20

      • InterruptEligibleCards (#IMPLIED)

        • description:The card products eligible for payment interrupts.

        • input:ans..1000

      • BinSetCategory (#IMPLIED)

        • description:The BIN set category of a terminal determines the set of BINs that will be used by the terminal. This field should only be populated if the configuration makes use of the esp_bins database table (i.e. Normalized file format).

        • input:ans..20

      • AcquirerCardAcceptorMappingCategory (#IMPLIED)

        • description:The Acquirer Card Acceptor Mapping category of a terminal determines the set of card acceptor mappings that will be used by the terminal. This field should only be populated if the configuration makes use of the normalized file format.

        • input:ans..20

      • DccSupport (#IMPLIED)

        • description:Indicates whether dynamic currency conversion (DCC) is supported by a terminal.

        • input:n1

        • input options:

          • 0 : not supported

          • 1 : supported

      • DeviceInsert (*)

        • This aggregate is used to associate a new device with a terminal

        • Tag (#REQUIRED)

          • description:This identifies the particular device that is to be added.

          • input:ans..80

        • RemoteIPAddress (#REQUIRED)

          • description:The IP Address or name of the machine to which the device is connected. This value should only be specified if eSocket.POS is to use a TCP/IP connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. RemoteIPAddress="") in the configuration file.

          • input:ans..15

        • RemotePort (#REQUIRED)

          • description:The TCP Port on which the device, or its TCP to serial bridge, is listening. This value should only be specified if eSocket.POS is to use a TCP/IP connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. RemotePort="") in the configuration file.

          • input:INT

        • SerialPort (#REQUIRED)

          • description:The identifier of the serial port to which the device is connected. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. SerialPort="") in the configuration file.

          • input:ans..12

        • BaudRate (#REQUIRED)

          • description:The baud rate at which the device communicates. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. BaudRate="") in the configuration file.

          • input:n..5

        • DataBits (#REQUIRED)

          • description:The number of data bits used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. DataBits="") in the configuration file.

          • input:n1

        • StopBits (#REQUIRED)

          • description:The number of stop bits used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. StopBits="") in the configuration file.

          • input:n1

        • Parity (#REQUIRED)

          • description:The parity used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. Parity="") in the configuration file.

          • input options:

            • NONE : if no parity is used

            • EVEN : if the device uses an even parity scheme

            • ODD : if the device uses an odd parity scheme

        • FilterClass (#REQUIRED)

          • description:The Filter Class required by the device. Please consult the documentation for the device integration software for this value.

        • Params (#REQUIRED)

          • description:A list of space-separated parameters for communication with the device. Please consult the documentation for the device integration software for this value.

      • RankedDeviceInsert (*)

        • This aggregate is used to associate a new device with a terminal

        • Tag (#REQUIRED)

          • description:This identifies the particular device that is to be added.

          • input:ans..80

        • RemoteIPAddress (#REQUIRED)

          • description:The IP Address or name of the machine to which the device is connected. This value should only be specified if eSocket.POS is to use a TCP/IP connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. RemoteIPAddress="") in the configuration file.

          • input:ans..15

        • RemotePort (#REQUIRED)

          • description:The TCP port on which the device, or its TCP to serial bridge, is listening. This value should only be specified if eSocket.POS is to use a TCP/IP connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. RemotePort="") in the configuration file.

          • input:INT

        • SerialPort (#REQUIRED)

          • description:The identifier of the serial port to which the device is connected. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. SerialPort="") in the configuration file.

          • input:ans..12

        • BaudRate (#REQUIRED)

          • description:The baud rate at which the device communicates. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. BaudRate="") in the configuration file.

          • input:n..5

        • DataBits (#REQUIRED)

          • description:The number of data bits used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. DataBits="") in the configuration file.

          • input:n1

        • StopBits (#REQUIRED)

          • description:The number of stop bits used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. StopBits="") in the configuration file.

          • input:n1

        • Parity (#REQUIRED)

          • description:The parity used by the device. This value should only be specified if eSocket.POS is to use a serial connnection to communicate with the device. If this is not the case, then it should be set to null (i.e. Parity="") in the configuration file.

          • input options:

            • NONE : if no parity is used

            • EVEN : if the device uses an even parity scheme

            • ODD : if the device uses an odd parity scheme

        • FilterClass (#REQUIRED)

          • description:The Filter Class required by the device. Please consult the documentation for the device integration software for this value.

        • Params (#REQUIRED)

          • description:A list of space-separated parameters for communication with the device. Please consult the documentation for the device integration software for this value.

        • CustomSapFactory (#IMPLIED)

          • description:The name of the CustomSapFactory class that will be used to establish a connection with the device.

          • input:ans..255

        • SapAddress (#IMPLIED)

          • description:The address of the device. eg SerialPort or CustomSapFactory address NOTE: the SapAddress is used to specify the SerialPort.

          • input:ans..128

        • SetupData (#IMPLIED)

          • description:The setup data used by the CustomSapFactory.

          • input:ans..100

        • Rank (#REQUIRED)

          • description:The device group(rank) of the device.

          • input:n..4

    • StoreRevisionUpdate (*)

      • This aggregate contains the information necessary to add a store revision to the eSocket.POS datastore. An example of how store revisions may be used is to distinguish stable terminals from pilot terminals.

      • RolloutGroup (#REQUIRED)

        • description:A revision of the store configuration. Currently only used to define separate sets of allowed serial numbers.

        • input:ans..20

      • Revision (#REQUIRED)

        • description:An identifier for the Config Server revision.

        • input:ans..

      • AllowedSerialsUpdate (*)

        • This aggregate is used to define a list of allowed serial numbers for devices associated with the store ID, lane profile and terminal ID.

        • StoreID (#REQUIRED)

          • description:A consistent and unique store identifier. Note that this is distinct from the MerchantId property value (which is assigned by the acquirer and for which there may be more than one value per store). A value of % includes all stores.

          • input:ans..25

        • LaneProf (#REQUIRED)

          • description:The lane profile which identifies the type of lane. For example a food lane or a self-service lane. A value of % includes all lane profiles.

          • input:ans..20

        • TerminalID (#REQUIRED)

          • description:A filter for terminal IDs. It may be an actual terminal ID or a pattern using SQL syntax. A value of % includes all terminal IDs.

          • input:ans..255

        • SerialNumberList (#REQUIRED)

          • description:A list of serial number patterns separated by the new line character. Each pattern may be an actual serial number or a pattern using SQL syntax. A entry of % indicates that all serial numbers are allowed.

          • input:ans..255

      • AllowedSerialsDelete (*)

        • This aggregate is used to clear a the set of allowed serial numbers for devices associated with the store ID, lane profile and terminal ID

        • StoreID (#REQUIRED)

          • description:A consistent and unique store identifier. Note that this is distinct from the MerchantId property value (which is assigned by the acquirer and for which there may be more than one value per store). A value of % includes all stores.

          • input:ans..25

        • LaneProf (#REQUIRED)

          • description:The lane profile which identifies the type of lane. For example a food lane or a self-service lane. A value of % includes all lane profiles.

          • input:ans..20

        • TerminalID (#REQUIRED)

          • description:A filter for terminal IDs. It may be an actual terminal ID or a pattern using SQL syntax. A value of % includes all terminal IDs.

          • input:ans..25

    • StoreRevisionDelete (*)

      • This aggregate contains the information necessary to remove data associated with a particular store revision from the eSocket.POS datastore.

      • RolloutGroup (#REQUIRED)

        • description:A revision of the store configuration. Currently only used to define separate sets of allowed serial numbers.

        • input:ans..20

    • RemotePropertyUpdate (*)

      • This aggregate contains the information necessary to update data associated with a particular remotely configured property revision from the eSocket.POS datastore.

      • PropertyName (#REQUIRED)

        • description:A unique name for each remotely configured property.

        • input:ans..255

      • PropertyValue (#IMPLIED)

        • description:The configured value for the property.

        • input:ans..255

    • RemotePropertyDelete (*)

      • This aggregate contains the information necessary to delete data associated with a particular remotely configured property revision from the eSocket.POS datastore.

      • PropertyName (#REQUIRED)

        • description:A unique name for each remotely configured property.

        • input:ans..255

    • RemotePropertyInsert (*)

      • This aggregate contains the information necessary to insert data associated with a particular remotely configured property revision into the eSocket.POS datastore.

      • PropertyName (#REQUIRED)

        • description:A unique name for each remotely configured property.

        • input:ans..255

      • PropertyValue (#REQUIRED)

        • description:The configured value for the property.

        • input:ans..255

10.3. ProcessingData description

The XML elements described below are used to modify the contents of the eSocket.POS datastore. Each element typically corresponds to an operation on a specific database table. The DTD ProcessingData.dtd is installed along with eSocket.POS and can be viewed with a text editor. The conditions associated with each element or attribute are indicated in parantheses

Element conditions:

Element Definition

<NONE>

The absence of a condition indicator means that that element is mandatory and that only one instance is permitted within the enclosing element.

?

This element is optional, but may only occur once within the enclosing element

*

The element is optional and there are no restrictions on the number of times it can occur within its parent element.

+

The element may be occur many times within its enclosing element, but it must occur at least once.

Attribute conditions:

Attribute Definition

#IMPLIED

This attribute is optional. These are typically used in update sub-elements of ProcessingData

#REQUIRED

This attribute is mandatory in the enclosing element. Such attributes typically identify the information that is used to uniquely identify elements .

  • ProcessingData ()

    • This encapsulates the operations on data that is not related to a specific terminal.

    • AccountTypeUpdate (*)

      • This element is used to update an existing account type.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the account type to be updated

        • input:ans..20

      • Type (#REQUIRED)

        • description:The 2-digit account type to be updated

        • input:n2

      • Name (#REQUIRED)

        • description:The name of the specified account type

        • input:ans..20

    • AccountTypeDelete (*)

      • This element is used to remove an existing account type from the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the account type to be deleted

        • input:ans..20

      • Type (#REQUIRED)

        • description:The 2-digit account type to be deleted

        • input:n2

    • AccountTypeInsert (*)

      • This element is used to insert a new account type into the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the account type to be inserted

        • input:ans..20

      • Type (#REQUIRED)

        • description:The 2-digit account type to be inserted

        • input:n2

      • Name (#REQUIRED)

        • description:The name of the specified account type

        • input:ans..20

    • AccountUpdate (*)

      • This element is used to update an existing account in the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the account to be updated

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The BIN with which this account is associated. Set to NIL if normalized file format is used.

        • input:n..13

      • AccountType (#REQUIRED)

        • description:The type of this account.

        • input:n2

      • PanLength (#REQUIRED)

        • description:The PAN length of the cards with which this account is associated. Set to 0 (zero) if normalized file format is used.

        • input:n..2

      • IsPinEntryRequired (#IMPLIED)

        • description:Indicates whether a PIN must be entered when using this account.

        • input options:

          • 0 : if PIN entry is not required

          • 1 : if PIN entry is required for this account

      • IsSignatureRequired (#IMPLIED)

        • description:Indicates whether a signature is required when using this account.

        • input options:

          • 0 : if a signature is not required

          • 1 : if a signature is required for this account

      • IsManualPanEntryAllowed (#IMPLIED)

        • description:Indicates whether the PAN on the card may be entered manually (instead of being read from the card) when using this account.

        • input options:

          • 0 : if the PAN may not be entered manually

          • 1 : if manual PAN entry is allowed

      • IsCashbackAllowed (#IMPLIED)

        • description:Indicates whether a cashback transaction may be performed from this account.

        • input options:

          • 0 : if this account may not be used for performing cashback transactions

          • 1 : if cashback transactions may be performed from this account

      • IsBudgetAllowed (#IMPLIED)

        • description:Indicates whether this account may be used for extended payment transactions (i.e. payment is spread over a number of periods).

        • input options:

          • 0 : if this account may not be used for extended payment transactions

          • 1 : if extended payment transactions are permitted from this account.

      • MinBudgetAmount (#IMPLIED)

        • description:The minimum amount (in the minor currency denomination) for which extended payment transactions are permitted from this account.

        • input:n..12

      • IsStandinOnManualPanEntryAllowed (#IMPLIED)

        • description:Indicates whether acquirer standin is permitted for transactions from this account where the PAN has been entered manually.

        • input options:

          • 0 : if acquirer standin is not permitted

          • 1 : if acquirer standin is permitted

      • OfflineLimitPurchase (#IMPLIED)

        • description:The maximum transaction amount (in the minor currency denomination) for which acquirer stand-in may be performed when the upstream authorizing host is not available.

        • input:n..12

      • FloorLimitPurchase (#IMPLIED)

        • description:The maximum transaction amount (in the minor currency denomination) for which acquirer stand-in may be performed when the upstream authorizing host is available.

        • input:n..12

      • OfflineLimitCash (#IMPLIED)

        • description:The maximum cash amount (in the minor currency denomination) for which acquirer stand-in may be performed when the upstream authorizing host is not available.

        • input:n..12

      • FloorLimitCash (#IMPLIED)

        • description:The maximum cash amount (in the minor currency denomination) for which acquirer stand-in may be performed when the upstream authorizing host is available.

        • input:n..12

      • MaxPurchaseAmount (#IMPLIED)

        • description:The maximum purchase amount (in the minor currency denomination) allowed for a transaction using this account. A value of zero means no maximum applies.

        • input:n..12

      • MaxCashAmount (#IMPLIED)

        • description:The maximum cash amount (in the minor currency denomination) allowed for a transaction using this account. A value of zero means no maximum applies.

        • input:n..12

      • MaxTranAmount (#IMPLIED)

        • description:The maximum transaction amount (in the minor currency denomination) allowed for a transaction using this account. A value of zero means no maximum applies.

        • input:n..12

      • IsIccFallbackAllowed (#IMPLIED)

        • description:Indicates whether this account allows fallback from chip to magstripe.

        • input options:

          • 0 : if fallback is not allowed

          • 1 : if fallback is allowed

      • CardAcceptorIdCode (#IMPLIED)

        • description:A code identifying the card acceptor for this card and account

        • input:ans15

      • GenerateReferral (#IMPLIED)

        • description:Indicates whether a referral needs to be generated if eSocket.POS is disconnected, and the transaction amount is above the offline limit.

        • input:n1

        • input options:

          • 1 : if a referral needs to be generated if eSocket.POS is not connected, and the transaction amount is above the offline limit.

          • 0 : if this functionality is not required.

      • AcquirerName (#IMPLIED)

        • description:The name of the acquirer for this card and account

        • input:ans15..30

      • CustomData (#IMPLIED)

        • description:Custom data for this card and account, for use by custom components. Suggested format is "name1='value1', name2='value2'"

        • input:ans..

      • AcceptIssuerDecision (#IMPLIED)

        • description:Accept Issuer Decision indicates whether the online approval overrides device failure or not.

        • input:n1

      • RPSType (#IMPLIED)

        • description:The first digit can have the value of 0 - not valid for RPS, 1 - force RPS online or 2 - Stand-in. The second digit can have the value of 1 - Mastercard or 2 - Visa to indicate the RPS program.

        • input:n2..

      • RPSLimit (#IMPLIED)

        • description:The maximum cash amount (in the minor currency denomination) for an RPS transaction.

        • input:n..12

      • InterveneAction (#IMPLIED)

        • description:The action that a cashier should take when acquirer intervention is required on a transaction. This field usually contains a telephone number to prompt the cashier to contact the acquirer call center for voice authorization. .

        • input:ans..20

      • ExtendedParameters (#IMPLIED)

        • description:The extended parameters associated with the accounts entity.

        • input:ans..

      • CardName (#IMPLIED)

        • description:The name of the card product that this account is attached to.

        • input:ans..20

      • BinSetCategory (#IMPLIED)

        • description:The calculated name for the set of BINs that is associated with this attached account.

        • input:ans..20

      • AcquiringInstitutionID (#IMPLIED)

        • description:The acquiring institution ID associated with the totals group of this attached account.

        • input:ans..11

      • CVMRequiredLimitCtls (#IMPLIED)

        • description:The maximum transaction amount (including cashback) in minor units for which cardholder verification is not required. Transactions with amounts above this limit must require cardholder verification if it is configured for this account. This limit applies to contactless transactions.

        • input:n..12

      • FloorLimitCtls (#IMPLIED)

        • description:The maximum transaction amount (including cashback) in minor units for which online stand-in is allowed. Amounts below this limit may be approved offline even if eSocket.POS is online. This limit applies to contactless transactions.

        • input:n..12

    • AccountDelete (*)

      • This element is used to remove an existing account from the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the account to be deleted

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The BIN with which this account is associated. Set to NIL if normalized file format is used.

        • input:n..13

      • AccountType (#REQUIRED)

        • description:The type of the account to be deleted

        • input:n2

      • PanLength (#REQUIRED)

        • description:The PAN length of the cards with which this account is associated. Set to 0 (zero) if normalized file format is used.

        • input:n..2

    • AccountInsert (*)

      • This element is used to insert a new account into the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the account to be inserted

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The BIN with which this account is associated. Set to NIL if normalized file format is used.

        • input:n..13

      • AccountType (#REQUIRED)

        • description:The type of this account.

        • input:n2

      • PanLength (#REQUIRED)

        • description:The PAN length of the cards with which this account is associated. Set to 0 (zero) if normalized file format is used.

        • input:n..2

      • IsPinEntryRequired (#REQUIRED)

        • description:Indicates whether a PIN must be entered when using this account.

        • input options:

          • 0 : if PIN entry is not required

          • 1 : if PIN entry is required for this account

      • IsSignatureRequired (#REQUIRED)

        • description:Indicates whether a signature is required when using this account.

        • input options:

          • 0 : if a signature is not required

          • 1 : if a signature is required for this account

      • IsManualPanEntryAllowed (#REQUIRED)

        • description:Indicates whether the PAN on the card may be entered manually (instead of being read from the card) when using this account.

        • input options:

          • 0 : if the PAN may not be entered manually

          • 1 : if manual PAN entry is allowed

      • IsCashbackAllowed (#REQUIRED)

        • description:Indicates whether a cashback transaction may be performed from this account.

        • input options:

          • 0 : if this account may not be used for performing cashback transactions

          • 1 : if cashback transactions may be performed from this account

      • IsBudgetAllowed (#REQUIRED)

        • description:Indicates whether this account may be used for extended payment transactions (i.e. payment is spread over a number of periods).

        • input options:

          • 0 : if this account may not be used for extended payment transactions

          • 1 : if extended payment transactions are permitted from this account.

      • MinBudgetAmount (#REQUIRED)

        • description:The minimum amount (in the minor currency denomination) for which extended payment transactions are permitted from this account.

        • input:n..12

      • IsStandinOnManualPanEntryAllowed (#REQUIRED)

        • description:Indicates whether acquirer standin is permitted for transactions from this account where the PAN has been entered manually.

        • input options:

          • 0 : if acquirer standin is not permitted

          • 1 : if acquirer standin is permitted

      • OfflineLimitPurchase (#REQUIRED)

        • description:The maximum transaction amount (in the minor currency denomination) for which acquirer stand-in may be performed when the upstream authorizing host is not available.

        • input:n..12

      • FloorLimitPurchase (#REQUIRED)

        • description:The maximum transaction amount (in the minor currency denomination) for which acquirer stand-in may be performed when the upstream authorizing host is available.

        • input:n..12

      • OfflineLimitCash (#REQUIRED)

        • description:The maximum cash amount (in the minor currency denomination) for which acquirer stand-in may be performed when the upstream authorizing host is not available.

        • input:n..12

      • FloorLimitCash (#REQUIRED)

        • description:The maximum cash amount (in the minor currency denomination) for which acquirer stand-in may be performed when the upstream authorizing host is available.

        • input:n..12

      • MaxPurchaseAmount (#REQUIRED)

        • description:The maximum purchase amount (in the minor currency denomination) allowed for a transaction using this account. A value of zero means no maximum applies.

        • input:n..12

      • MaxCashAmount (#REQUIRED)

        • description:The maximum cash amount (in the minor currency denomination) allowed for a transaction using this account. A value of zero means no maximum applies.

        • input:n..12

      • MaxTranAmount (#REQUIRED)

        • description:The maximum transaction amount (in the minor currency denomination) allowed for a transaction using this account. A value of zero means no maximum applies.

        • input:n..12

      • IsIccFallbackAllowed (#REQUIRED)

        • description:Indicates whether this account allows fallback from chip to magstripe.

        • input options:

          • 0 : if fallback is not allowed

          • 1 : if fallback is allowed

      • CardAcceptorIdCode (#REQUIRED)

        • description:A code identifying the card acceptor for this card and account

        • input:ans15

      • GenerateReferral (#IMPLIED)

        • description:Indicates whether a referral needs to be generated if eSocket.POS is disconnected, and the transaction amount is above the offline limit.

        • input:n1

        • input options:

          • 1 : if a referral needs to be generated if eSocket.POS is not connected, and the transaction amount is above the offline limit.

          • 0 : if this functionality is not required.

      • AcquirerName (#REQUIRED)

        • description:The name of the acquirer for this card and account

        • input:ans..30

      • CustomData (#REQUIRED)

        • description:Custom data for this card and account, for use by custom components. Suggested format is "name1='value1', name2='value2'"

        • input:ans..

      • AcceptIssuerDecision (#IMPLIED)

        • description:Accept Issuer Decision indicates whether the online approval overrides device failure or not.

        • input:n1

      • RPSType (#IMPLIED)

        • description:The first digit can have the value of 0 - not valid for RPS, 1 - force RPS online or 2 - Stand-in. The second digit can have the value of 1 - Mastercard or 2 - Visa to indicate the RPS program.

        • input:n2..

      • RPSLimit (#IMPLIED)

        • description:The maximum cash amount (in the minor currency denomination) for an RPS transaction.

        • input:n..12

      • InterveneAction (#IMPLIED)

        • description:The action that a cashier should take when acquirer intervention is required on a transaction. This field usually contains a telephone number to prompt the cashier to contact the acquirer call center for voice authorization.

        • input:ans..20

      • ExtendedParameters (#IMPLIED)

        • description:The extended parameters associated with the accounts entity.

        • input:ans..

      • CardName (#IMPLIED)

        • description:The name of the card product that this account is attached to.

        • input:ans..20

      • BinSetCategory (#IMPLIED)

        • description:The calculated name for the set of BINs that is associated with this attached account.

        • input:ans..20

      • AcquiringInstitutionID (#IMPLIED)

        • description:The acquiring institution ID associated with the totals group of this attached account.

        • input:ans..11

      • CVMRequiredLimitCtls (#IMPLIED)

        • description:The maximum transaction amount (including cashback) in minor units for which cardholder verification is not required. Transactions with amounts above this limit must require cardholder verification if it is configured for this account. This limit applies to contactless transactions.

        • input:n..12

      • FloorLimitCtls (#IMPLIED)

        • description:The maximum transaction amount (including cashback) in minor units for which online stand-in is allowed. Amounts below this limit may be approved offline even if eSocket.POS is online. This limit applies to contactless transactions.

        • input:n..12

    • AcqCaMapUpdate (*)

      • This element is used to update an existing acquirer card acceptor mapping in the eSocket.POS datastore.

      • AcqCaMapCategory (#REQUIRED)

        • description:The calculated name for the set of acquirer and card acceptor mappings used by various other entities.

        • input:ans..20

      • AcquirerName (#REQUIRED)

        • description:The name of the acquirer used with this mapping.

        • input:ans..30

      • MappedCardAcceptorId (#IMPLIED)

        • description:The code identifying the card acceptor used with this mapping.

        • input:ans15

      • InterveneAction (#IMPLIED)

        • description:The action that a cashier must take when acquirer intervention is required on a transaction. This field usually contains a telephone number to prompt the cashier to contact the acquirer call center for voice authorization.

        • input:ans..20

    • AcqCaMapDelete (*)

      • This element is used to remove an existing acquirer card acceptor mapping from the eSocket.POS datastore.

      • AcqCaMapCategory (#REQUIRED)

        • description:The calculated name for the set of acquirer and card acceptor mappings used by various other entities.

        • input:ans..20

      • AcquirerName (#REQUIRED)

        • description:The name of the acquirer used with this mapping.

        • input:ans..30

    • AcqCaMapInsert (*)

      • This element is used to insert a new acquirer card acceptor mapping into the eSocket.POS datastore.

      • AcqCaMapCategory (#REQUIRED)

        • description:The calculated name for the set of acquirer and card acceptor mappings used by various other entities.

        • input:ans..20

      • AcquirerName (#REQUIRED)

        • description:The name of the acquirer used with this mapping.

        • input:ans..30

      • MappedCardAcceptorId (#IMPLIED)

        • description:The code identifying the card acceptor used with this mapping.

        • input:ans15

      • InterveneAction (#IMPLIED)

        • description:The action that a cashier must take when acquirer intervention is required on a transaction. This field usually contains a telephone number to prompt the cashier to contact the acquirer call center for voice authorization.

        • input:ans..20

    • BinUpdate (*)

      • This element is used to update an existing BIN in the eSocket.POS datastore.

      • BinSetCategory (#REQUIRED)

        • description:The calculated name for the set of BINs that other entities will reference.

        • input:ans..20

      • CardName (#IMPLIED)

        • description:A name identifying the card product this set of BINs is associated with.

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The bank identification number (BIN) is the first part of the primary account number (PAN). When retrieving the card record for a given PAN, eSocket.POS returns the record with the longest BIN that matches the card’s PAN and PAN length.

        • input:n..13

      • PanLength (#REQUIRED)

        • description:The PAN length for a card this BIN will be associated with. eSocket.POS uses the PAN length to distinguish between cards with the same BIN. This value may be zero if the PAN length varies or is unknown.

        • input:n2

      • Exclude (#IMPLIED)

        • description:A flag to indicate whether this BIN and PAN length combination should be excluded from the card product matching.

        • input:n1

      • Description (#IMPLIED)

        • description:The name of the card product as it must be printed on transaction slips. This field is optional and if not specified, then the card product name itself is printed.

        • input:ans..20

    • BinDelete (*)

      • This element is used to remove an existing BIN from the eSocket.POS datastore.

      • BinSetCategory (#REQUIRED)

        • description:The calculated name for the set of BINs that other entities will reference.

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The bank identification number (BIN) is the first part of the primary account number (PAN). When retrieving the card record for a given PAN, eSocket.POS returns the record with the longest BIN that matches the card’s PAN and PAN length.

        • input:n..13

      • PanLength (#REQUIRED)

        • description:The PAN length for a card this BIN will be associated with. eSocket.POS uses the PAN length to distinguish between cards with the same BIN. This value may be zero if the PAN length varies or is unknown.

        • input:n2

    • BinInsert (*)

      • This element is used to insert a new BIN into the eSocket.POS datastore.

      • BinSetCategory (#REQUIRED)

        • description:The calculated name for the set of BINs that other entities will reference.

        • input:ans..20

      • CardName (#IMPLIED)

        • description:A name identifying the card product this set of BINs is associated with.

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The bank identification number (BIN) is the first part of the primary account number (PAN). When retrieving the card record for a given PAN, eSocket.POS returns the record with the longest BIN that matches the card’s PAN and PAN length.

        • input:n..13

      • PanLength (#REQUIRED)

        • description:The PAN length for a card this BIN will be associated with. eSocket.POS uses the PAN length to distinguish between cards with the same BIN. This value may be zero if the PAN length varies or is unknown.

        • input:n2

      • Exclude (#IMPLIED)

        • description:A flag to indicate whether this BIN and PAN length combination should be excluded from the card product matching.

        • input:n1

      • Description (#IMPLIED)

        • description:The name of the card product as it must be printed on transaction slips. This field is optional and if not specified, then the card product name itself is printed.

        • input:ans..20

    • CardUpdate (*)

      • This element is used to update a card already configured in the eSocket.POS datastore

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the card to be updated

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The BIN of the card to be updated. Set to NIL if normalized file format is used.

        • input:n..13

      • Name (#IMPLIED)

        • description:The name that has been assigned to the card

        • input:ans..20

      • TimeoutProcessing (#IMPLIED)

        • description:This feature has been reserved for future use in eSocket.POS

        • input:0

      • IsPanVerificationRequired (#IMPLIED)

        • description:Indicates whether the PAN should be validated using the Luhn validation algorithm.

        • input options:

          • 0 : if Luhn validation should not be performed

          • 1 : if validation should be performed.

      • PanLength (#REQUIRED)

        • description:The expected length of the PAN for this card type, or 0 if the length varies. Set to 0 (zero) if normalized file format is used.

        • input:n..2

      • IsExpiryDateCheckRequired (#IMPLIED)

        • description:Indicates whether the expiry date on the card should be checked to determine if the card is still valid.

        • input options:

          • 0 : do not check the expiry date

          • 1 : check that card is valid

      • IsServiceRestrictionCodeCheckRequired (#IMPLIED)

        • description:Indicates whether the attempted transaction should be validated against the service restriction code on the card.

        • input options:

          • 0 : do not check the service restriction code

          • 1 : check the service restriction code

      • ServiceRestrictionCodeOffset (#IMPLIED)

        • description:The offset of the service restriction code in Track 2 data. The offset is measured from the separator after the PAN. If the service restriction code is not present or is not being checked (see "IsServiceRestrictionCodeCheckRequired") then this value should be set to "0"

        • input:INT

      • IsValidPeriodCheckRequired (#IMPLIED)

        • description:Some cards may, in addition to expiry date, have an effective date from which the card is considered valid. This option indicates whether it is necessary to check if the transaction has been performed on a date that falls within this valid period.

        • input options:

          • 0 : the valid period check need not be performed

          • 1 : perform the valid period check.

      • ValidPeriodOffset (#IMPLIED)

        • description:The offset of the valid period indicator of the card in Track 2 data. The offset is measured from the separator after the PAN.

        • input:INT

      • ValidPeriodFormat (#IMPLIED)

        • description:A code indicating the format of the valid period on Track 2 of the card

        • input options:

          • 1 : Effective date in YYMM format

          • 2 : Effective date in MMYY format

          • 3 : Number of months in MM format prior to expiry date

      • CardSequenceNumberOffset (#IMPLIED)

        • description:The offset of the sequence number of the card in Track 2 data. The offset is measured from the separator after the PAN.

        • input:INT

      • CardSequenceNumberLength (#IMPLIED)

        • description:The length of the card sequence number as present in the Track 2 data on the card.

        • input:INT

      • IsCheckInquiryAllowed (#IMPLIED)

        • description:Indicates whether this card supports inquiries for check verification.

        • input options:

          • 0 : check verification is not supported.

          • 1 : check verification is supported.

      • ReferralTelephoneNumber (#IMPLIED)

        • description:The number to be called for transactions that have been referred.

        • input:ans..20

      • OfflineLimitCheck (#IMPLIED)

        • description:The maximum amount (in the minor currency denomination) for which acquirer stand-in may be performed on check verifications when the upstream authorizing host is not available.

        • input:n2

      • FloorLimitCheck (#IMPLIED)

        • description:The maximum amount (in the minor currency denomination) for which acquirer stand-in may be performed on check verifications when the upstream authorizing host is available.

        • input:n2

      • IsCvv2Required (#IMPLIED)

        • description:Indicates whether a CVV2 or equivalent value is required for this card.

        • input options:

          • 0 : CVV2 is not required

          • 1 : CVV2 is required

      • Cvv2Length (#IMPLIED)

        • description:The length of the CVV2 or equivalent value for this card. If CVV2 is not required (see "IsCvv2Required") then this value should be set to "0"

        • input:n1

      • CustomData (#IMPLIED)

        • description:Custom data for this card, for use by custom components. Suggested format is "name1='value1', name2='value2'"

        • input:ans..

      • MaskSensitiveData (#IMPLIED)

        • description:Indicates whether sensitive data (PAN, Track1, Track2, and Service Restriction Code) sent to the POS should be masked.

        • input:n1

        • input options:

          • 1 : if the sensitive data should be masked.

          • 0 : if the sensitive data should not be masked.

      • CheckEmbossedPan (#IMPLIED)

        • description:Indicates whether to check the last four digits of the Pan embossed on the card against the Pan or not.

        • input:n1

        • input options:

          • 0 : do not check the embossed pan.

          • 1 : Optional check, cancel accepted.

          • 2 : Mandatory check, cancel rejected.

    • CardDelete (*)

      • This element is used to remove an existing card from the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the card to be deleted

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The BIN of the card to be deleted. Set to NIL if normalized file format is used.

        • input:n..13

      • PanLength (#REQUIRED)

        • description:The expected length of the PAN for this card type, or 0 if the length varies. Set to 0 (zero) if normalized file format is used.

        • input:n..2

    • CardInsert (*)

      • This element is used to insert a new card record into the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the card to be inserted

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The BIN of the card to be inserted. Set to NIL if normalized file format is used.

        • input:n..13

      • Name (#REQUIRED)

        • description:The name that has been assigned to the card

        • input:ans..20

      • TimeoutProcessing (#REQUIRED)

        • description:This feature has been reserved for future use in eSocket.POS

        • input:0

      • IsPanVerificationRequired (#REQUIRED)

        • description:Indicates whether the PAN should be validated using the Luhn validation algorithm.

        • input options:

          • 0 : if Luhn validation should not be performed

          • 1 : if validation should be performed.

      • PanLength (#REQUIRED)

        • description:The expected length of the PAN for this card type, or 0 if the length varies. Set to 0 (zero) if normalized file format is used.

        • input:n..2

      • IsExpiryDateCheckRequired (#REQUIRED)

        • description:Indicates whether the expiry date on the card should be checked to determine if the card is still valid.

        • input options:

          • 0 : do not check the expiry date

          • 1 : check that card is valid

      • IsServiceRestrictionCodeCheckRequired (#REQUIRED)

        • description:Indicates whether the attempted transaction should be validated against the service restriction code on the card.

        • input options:

          • 0 : do not check the service restriction code

          • 1 : check the service restriction code

      • ServiceRestrictionCodeOffset (#REQUIRED)

        • description:The offset of the service restriction code in Track 2 data. The offset is measured from the separator after the PAN. If the service restriction code is not present or is not being checked (see "IsServiceRestrictionCodeCheckRequired") then this value should be set to "0"

        • input:INT

      • IsValidPeriodCheckRequired (#REQUIRED)

        • description:Some cards may, in addition to expiry date, have an effective date from which the card is considered valid. This option indicates whether it is necessary to check if the transaction has been performed on a date that falls within this valid period.

        • input options:

          • 0 : the valid period check need not be performed

          • 1 : perform the valid period check.

      • ValidPeriodOffset (#REQUIRED)

        • description:The offset of the valid period indicator of the card in Track 2 data. The offset is measured from the separator after the PAN.

        • input:INT

      • ValidPeriodFormat (#REQUIRED)

        • description:A code indicating the format of the valid period on Track 2 of the card

        • input options:

          • 1 : Effective date in YYMM format

          • 2 : Effective date in MMYY format

          • 3 : Number of months in MM format prior to expiry date

      • CardSequenceNumberOffset (#REQUIRED)

        • description:The offset of the sequence number of the card in Track 2 data. The offset is measured from the separator after the PAN.

        • input:INT

      • CardSequenceNumberLength (#REQUIRED)

        • description:The length of the card sequence number as present in the Track 2 data on the card.

        • input:INT

      • IsCheckInquiryAllowed (#REQUIRED)

        • description:Indicates whether this card supports inquiries for check verification.

        • input options:

          • 0 : check verification is not supported.

          • 1 : check verification is supported.

      • ReferralTelephoneNumber (#REQUIRED)

        • description:The number to be called for transactions that have been referred.

        • input:ans..20

      • OfflineLimitCheck (#REQUIRED)

        • description:The maximum amount (in the minor currency denomination) for which acquirer stand-in may be performed on check verifications when the upstream authorizing host is not available.

        • input:n2

      • FloorLimitCheck (#REQUIRED)

        • description:The maximum amount (in the minor currency denomination) for which acquirer stand-in may be performed on check verifications when the upstream authorizing host is available.

        • input:n2

      • IsCvv2Required (#REQUIRED)

        • description:Indicates whether a CVV2 or equivalent value is required for this card.

        • input options:

          • 0 : CVV2 is not required

          • 1 : CVV2 is required

      • Cvv2Length (#REQUIRED)

        • description:The length of the CVV2 or equivalent value for this card. If CVV2 is not required (see "IsCvv2Required") then this value should be set to "0"

        • input:n1

      • CustomData (#REQUIRED)

        • description:Custom data for this card, for use by custom components. Suggested format is "name1='value1', name2='value2'"

        • input:ans..

      • MaskSensitiveData (#IMPLIED)

        • description:Indicates whether sensitive data (PAN, Track1, Track2, and Service Restriction Code) sent to the POS should be masked.

        • input:n1

        • input options:

          • 1 : if the sensitive data should be masked.

          • 0 : if the sensitive data should not be masked.

      • CheckEmbossedPan (#IMPLIED)

        • description:Indicates whether to check the last four digits of the Pan embossed on the card against the Pan or not.

        • input:n1

        • input options:

          • 0 : do not check the embossed pan.

          • 1 : Optional check, cancel accepted.

          • 2 : Mandatory check, cancel rejected.

    • EmvAidUpdate (*)

      • This element is used to update an EMV application already configured in the eSocket.POS datastore

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the application to be updated

        • input:ans..20

      • Aid (#REQUIRED)

        • description:The AID of the application to be updated. Contains the hexadecimal expansion of the binary AID.

        • input:ans..32

      • ApplicationVersionNumber (#REQUIRED)

        • description:The Application Version Number of the application to be updated. Contains the 4-character hexadecimal expansion of the 2-byte value.

        • input:ans4

      • Ddol (#IMPLIED)

        • description:The Default Dynamic Data Authentication Data Object List (DDOL) for this application. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans..

      • Tdol (#IMPLIED)

        • description:The Default Transaction Certificate Data Object List (TDOL) for this application. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans..

      • PartialMatch (#IMPLIED)

        • description:Indicates whether the terminal application can be selected based on a partial match with the card AID.

        • input options:

          • 0 : the application cannot be selected using a partial match

          • 1 : the application can be selected using a partial match

      • CustomData (#IMPLIED)

        • description:Additional data for this application, for use by custom components.

        • input:ans..

      • LatestApplicationVersionNumber (#IMPLIED)

        • description:The latest application version number of the Application to be updated. Contains the 4-character hexadecimal expansion of the 2-byte value.

        • input:ans4

      • SchemeName (#IMPLIED)

        • description:The scheme name, e.g. VISA, to be updated.

        • input:ans..20

      • FloorLimitChip (#IMPLIED)

        • description:Floor limit for ICC transactions on this AID.

        • input:n..12

      • TacDefault (#IMPLIED)

        • description:Terminal Action Code - Default

        • input:ans10

      • TacDenial (#IMPLIED)

        • description:Terminal Action Code - Denial

        • input:ans10

      • TacOnline (#IMPLIED)

        • description:Terminal Action Code - Online

        • input:ans10

      • TargetPercent (#IMPLIED)

        • description:The target percent for random selection for cards using this application.

        • input:n2

      • MaxTargetPercent (#IMPLIED)

        • description:The maximum target percent for biased random selection for cards using this application.

        • input:n2

      • ThresholdValue (#IMPLIED)

        • description:The threshold value for biased random selection for cards using this application. The value is given in the minor denomination.

        • input:n..12

      • CVMRequiredLimitCtls (#IMPLIED)

        • description:The maximum transaction amount for which cardholder verification will not be required. This limit applies to contactless transactions.

        • input:n..12

      • FloorLimitCtls (#IMPLIED)

        • description:The maximum transaction amount for which online stand-in will occur. This limit applies to contactless transactions.

        • input:n..12

      • TranLimitCtls (#IMPLIED)

        • description:The maximum transaction amount for contactless transactions.

        • input:n..12

      • TacDefaultCtls (#IMPLIED)

        • description:Contactless Terminal Action Code - Default

        • input:ans10

      • TacDenialCtls (#IMPLIED)

        • description:Contactless Terminal Action Code - Denial

        • input:ans10

      • TacOnlineCtls (#IMPLIED)

        • description:Contactless Terminal Action Code - Online

        • input:ans10

      • TranLimitCtlsDCV (#IMPLIED)

        • description:The maximum transaction amount for DCV(on-Device Cardholder Verification) contactless transactions.

        • input:n..12

      • Priority (#IMPLIED)

        • description:The rank of this AID among the list of assigned AIDs.

        • input:n2

      • AidType (#IMPLIED)

        • description:The type of the AID.

        • input:n1

        • input options:

          • 1 : International

          • 2 : Domestic

          • 3 : US

      • CVMRequiredLimit (#IMPLIED)

        • description:The maximum transaction amount for which cardholder verification will not be required. This limit applies to contact transactions.

        • input:n..12

    • EmvAidDelete (*)

      • This element is used to remove an existing EMV application from the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the application to be deleted

        • input:ans..20

      • Aid (#REQUIRED)

        • description:The AID of the application to be deleted

        • input:ans..32

      • ApplicationVersionNumber (#REQUIRED)

        • description:The Application Version Number of the application to be deleted.

        • input:n2

    • EmvAidInsert (*)

      • This element is used to insert a new EMV application into the eSocket.POS datastore

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the application to be inserted

        • input:ans..20

      • Aid (#REQUIRED)

        • description:The AID of the application to be inserted. Contains the hexadecimal expansion of the binary AID.

        • input:ans..32

      • ApplicationVersionNumber (#REQUIRED)

        • description:The Application Version Number of the application to be inserted. Contains the 4-character hexadecimal expansion of the 2-byte value.

        • input:ans4

      • Ddol (#REQUIRED)

        • description:The Default Dynamic Data Authentication Data Object List (DDOL) for this application. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans..

      • Tdol (#REQUIRED)

        • description:The Default Transaction Certificate Data Object List (TDOL) for this application. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans..

      • PartialMatch (#REQUIRED)

        • description:Indicates whether the terminal application can be selected based on a partial match with the card AID.

        • input options:

          • 0 : the application cannot be selected using a partial match

          • 1 : the application can be selected using a partial match

      • CustomData (#REQUIRED)

        • description:Additional data for this application, for use by custom components.

        • input:ans..

      • LatestApplicationVersionNumber (#IMPLIED)

        • description:The latest application version number of the Application. Contains the 4-character hexadecimal expansion of the 2-byte value.

        • input:ans4

      • SchemeName (#IMPLIED)

        • description:The scheme name, e.g. VISA.

        • input:ans..20

      • FloorLimitChip (#IMPLIED)

        • description:Floor limit for ICC transactions on this AID.

        • input:n..12

      • TacDefault (#IMPLIED)

        • description:Terminal Action Code - Default

        • input:ans10

      • TacDenial (#IMPLIED)

        • description:Terminal Action Code - Denial

        • input:ans10

      • TacOnline (#IMPLIED)

        • description:Terminal Action Code - Online

        • input:ans10

      • TargetPercent (#IMPLIED)

        • description:The target percent for random selection for cards using this application.

        • input:n2

      • MaxTargetPercent (#IMPLIED)

        • description:The maximum target percent for biased random selection for cards using this application.

        • input:n2

      • ThresholdValue (#IMPLIED)

        • description:The threshold value for biased random selection for cards using this application. The value is given in the minor denomination.

        • input:n..12

      • CVMRequiredLimitCtls (#IMPLIED)

        • description:The maximum transaction amount for which cardholder verification will not be required. This limit applies to contactless transactions.

        • input:n..12

      • FloorLimitCtls (#IMPLIED)

        • description:The maximum transaction amount for which online stand-in will occur. This limit applies to contactless transactions.

        • input:n..12

      • TranLimitCtls (#IMPLIED)

        • description:The maximum transaction amount for contactless transactions.

        • input:n..12

      • TacDefaultCtls (#IMPLIED)

        • description:Contactless Terminal Action Code - Default

        • input:ans10

      • TacDenialCtls (#IMPLIED)

        • description:Contactless Terminal Action Code - Denial

        • input:ans10

      • TacOnlineCtls (#IMPLIED)

        • description:Contactless Terminal Action Code - Online

        • input:ans10

      • TranLimitCtlsDCV (#IMPLIED)

        • description:The maximum transaction amount for DCV(on-Device Cardholder Verification) contactless transactions.

        • input:n..12

      • Priority (#IMPLIED)

        • description:The rank of this AID among the list of assigned AIDs .

        • input:n2

      • AidType (#IMPLIED)

        • description:The type of the AID.

        • input:n1

        • input options:

          • 1 : International

          • 2 : Domestic

          • 3 : US

      • CVMRequiredLimit (#IMPLIED)

        • description:The maximum transaction amount for which cardholder verification will not be required. This limit applies to contact transactions.

        • input:n..12

    • EmvBinUpdate (*)

      • This element is used to update an EMV BIN already configured in the eSocket.POS datastore

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the EMV BIN to be updated

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The BIN of the EMV BIN record to be updated.

        • input:n..13

      • PanLength (#REQUIRED)

        • description:The PAN length of the EMV BIN record to be updated

        • input:n..2

      • FloorLimitChip (#IMPLIED)

        • description:The floor limit (in the minor denomination) for ICC transactions on cards with this BIN. Transaction amounts above this limit should be sent online for authorisation.

        • input:n..12

      • TacDenial (#IMPLIED)

        • description:The Terminal Action Codes - Denial for cards with this BIN. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans10

      • TacOnline (#IMPLIED)

        • description:The Terminal Action Codes - Online for cards with this BIN. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans10

      • TacDefault (#IMPLIED)

        • description:The Terminal Action Codes - Default for cards with this BIN. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans10

      • TargetPercent (#IMPLIED)

        • description:The target percent for random selection for cards with this BIN.

        • input:n2

      • MaxTargetPercent (#IMPLIED)

        • description:The maximum target percent for biased random selection for cards with this BIN.

        • input:n2

      • ThresholdValue (#IMPLIED)

        • description:The threshold value for biased random selection for cards with this BIN. The value is given in the minor denomination.

        • input:n..12

      • CustomData (#IMPLIED)

        • description:Additional data for this BIN, for use by custom components.

        • input:ans..

    • EmvBinDelete (*)

      • This element is used to remove an existing EMV BIN from the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the EMV BIN to be deleted

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The BIN of the EMV BIN record to be deleted

        • input:n..13

      • PanLength (#REQUIRED)

        • description:The PAN length of the EMV BIN record to be deleted

        • input:n..2

    • EmvBinInsert (*)

      • This element is used to insert a new EMV BIN into the eSocket.POS datastore

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the EMV BIN to be inserted

        • input:ans..20

      • Bin (#REQUIRED)

        • description:The BIN of the EMV BIN record to be inserted

        • input:n..13

      • PanLength (#REQUIRED)

        • description:The PAN length of the EMV BIN record to be inserted

        • input:n..2

      • FloorLimitChip (#REQUIRED)

        • description:The floor limit (in the minor denomination) for ICC transactions on cards with this BIN. Transaction amounts above this limit should be sent online for authorisation.

        • input:n..12

      • TacDenial (#REQUIRED)

        • description:The Terminal Action Codes - Denial for cards with this BIN. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans10

      • TacOnline (#REQUIRED)

        • description:The Terminal Action Codes - Online for cards with this BIN. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans10

      • TacDefault (#REQUIRED)

        • description:The Terminal Action Codes - Default for cards with this BIN. Contains the hexadecimal expansion of the binary EMV value.

        • input:ans10

      • TargetPercent (#REQUIRED)

        • description:The target percent for random selection for cards with this BIN.

        • input:n2

      • MaxTargetPercent (#REQUIRED)

        • description:The maximum target percent for biased random selection for cards with this BIN.

        • input:n2

      • ThresholdValue (#REQUIRED)

        • description:The threshold value for biased random selection for cards with this BIN. The value is given in the minor denomination.

        • input:n..12

      • CustomData (#REQUIRED)

        • description:Additional data for this BIN, for use by custom components.

        • input:ans..

    • CAPublicKeyUpdate (*)

      • This element is used to update a Certification Authority public key already configured in the eSocket.POS datastore

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the key to be updated

        • input:ans..20

      • Rid (#REQUIRED)

        • description:The Registered Application Provider Identifier (RID) of the Certification Authority for this key. Contains the 10-character hexadecimal expansion of the 5-byte RID.

        • input:ans10

      • Index (#REQUIRED)

        • description:The index of this key. Contains the 2-character hexadecimal expansion of the 1-byte index.

        • input:ans2

      • Modulus (#IMPLIED)

        • description:The modulus for this key. Contains the hexadecimal expansion of the binary modulus.

        • input:ans..

      • Exponent (#IMPLIED)

        • description:The exponent for this key.

        • input:ans..

        • input options:

          • 1 : 2^16 + 1

          • 2 : 2

          • 3 : 3

      • CheckSum (#IMPLIED)

        • description:The check sum for this key. Contains the hexadecimal expansion of the binary check sum.

        • input:ans40

      • ActivationDate (#IMPLIED)

        • description:The activation date for this key (YYYYMMdd).

        • input:n8

      • ExpirationDate (#IMPLIED)

        • description:The expiration date for this key (YYYYMMdd).

        • input:n8

      • CustomData (#IMPLIED)

        • description:Additional data for this key, used by custom components.

        • input:ans..

    • CAPublicKeyDelete (*)

      • This element is used to remove an existing Certification Authority public key from the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the key to be deleted

        • input:ans..20

      • Rid (#REQUIRED)

        • description:The Registered Application Provider Identifier (RID) of the Certification Authority for this key. Contains the 10-character hexadecimal expansion of the 5-byte RID.

        • input:ans10

      • Index (#REQUIRED)

        • description:The index of this key. Contains the 2-character hexadecimal expansion of the 1-byte index.

        • input:ans2

    • CAPublicKeyInsert (*)

      • This element is used to insert a new Certification Authority public key into the eSocket.POS datastore

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the key to be inserted

        • input:ans..20

      • Rid (#REQUIRED)

        • description:The Registered Application Provider Identifier (RID) of the Certification Authority for this key. Contains the 10-character hexadecimal expansion of the 5-byte RID.

        • input:ans10

      • Index (#REQUIRED)

        • description:The index of this key. Contains the 2-character hexadecimal expansion of the 1-byte index.

        • input:ans2

      • Modulus (#REQUIRED)

        • description:The modulus for this key. Contains the hexadecimal expansion of the binary modulus.

        • input:ans..

      • Exponent (#REQUIRED)

        • description:The exponent for this key.

        • input:ans..

        • input options:

          • 1 : 2^16 + 1

          • 2 : 2

          • 3 : 3

      • CheckSum (#REQUIRED)

        • description:The check sum for this key. Contains the hexadecimal expansion of the binary check sum.

        • input:ans40

      • ActivationDate (#REQUIRED)

        • description:The activation date for this key (YYYYMMdd).

        • input:n8

      • ExpirationDate (#REQUIRED)

        • description:The expiration date for this key (YYYYMMdd).

        • input:n8

      • CustomData (#IMPLIED)

        • description:Additional data for this key, used by custom components.

        • input:ans..

    • MerchandiseConfigUpdate (*)

      • This element is used to update a merchandise product already configured in the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the merchandise product to be updated

        • input:ans..20

      • PosProductID (#REQUIRED)

        • description:The POS product ID of the merchandise product to be updated

        • input:ans..50

      • NetworkID (#IMPLIED)

        • description:The network ID of the merchandise product to be updated. A special value of NIL indicates that this value was not specified in Config Server.

        • input:ans..12

      • ProductID (#IMPLIED)

        • description:The product ID of the merchandise product to be updated

        • input:ans..50

      • NetworkName (#IMPLIED)

        • description:The network name of the merchandise product to be updated

        • input:ans..50

      • ProductName (#IMPLIED)

        • description:The product name of the merchandise product to be updated

        • input:ans..50

      • MerchandiseType (#IMPLIED)

        • description:The merchandise type of the merchandise product to be updated

        • input:ans..30

        • input options:

          • TELEPHONE PREPAY : telephone prepay service

          • OTHER : reserved for future use

      • ReceivingInstID (#IMPLIED)

        • description:Used in Postilion to route the merchandise transaction to the correct Sink Node.

        • input:ans..11

      • ObtainUserID (#IMPLIED)

        • description:Determines whether to prompt for the User ID (e.g. Mobile phone number).

        • input options:

          • 0 : if the User ID is not required

          • 1 : if the User ID is required

      • ConfirmUserID (#IMPLIED)

        • description:Determines whether the user is required to confirm the User ID (e.g. Mobile phone number).

        • input options:

          • 0 : if the user does not need to confirm the User ID

          • 1 : if the user needs to confirm the User ID

      • ObtainCardSwipe (#IMPLIED)

        • description:Determines whether to prompt for a merchandise card to be swiped.

        • input options:

          • 0 : if the user should not be prompted to swipe a merchandise card

          • 1 : if the user should be prompted to swipe a merchandise card

    • MerchandiseConfigDelete (*)

      • This element is used to remove a merchandise product from the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the merchandise product to be deleted

        • input:ans..20

      • PosProductID (#REQUIRED)

        • description:The POS product ID of the merchandise product to be deleted

        • input:ans..50

    • MerchandiseConfigInsert (*)

      • This element is used to insert a merchandise product into the eSocket.POS datastore.

      • ProcessingCategory (#REQUIRED)

        • description:The processing category of the merchandise product to be inserted

        • input:ans..20

      • PosProductID (#REQUIRED)

        • description:The POS product ID of the merchandise product to be inserted

        • input:ans..50

      • NetworkID (#REQUIRED)

        • description:The network ID of the merchandise product to be inserted. A special value of NIL indicates that this value was not specified in Config Server.

        • input:ans..12

      • ProductID (#REQUIRED)

        • description:The product ID of the merchandise product to be inserted

        • input:ans..50

      • NetworkName (#REQUIRED)

        • description:The network name of the merchandise product to be inserted

        • input:ans..50

      • ProductName (#REQUIRED)

        • description:The product name of the merchandise product to be inserted

        • input:ans..50

      • MerchandiseType (#REQUIRED)

        • description:The merchandise type of the merchandise product to be inserted

        • input:ans..30

        • input options:

          • TELEPHONE PREPAY : telephone prepay service

          • OTHER : reserved for future use

      • ReceivingInstID (#REQUIRED)

        • description:Used in Postilion to route the merchandise transaction to the correct Sink Node.

        • input:ans..11

      • ObtainUserID (#REQUIRED)

        • description:Determines whether to prompt for the User ID (e.g. Mobile phone number).

        • input options:

          • 0 : if the User ID is not required

          • 1 : if the User ID is required

      • ConfirmUserID (#REQUIRED)

        • description:Determines whether the user is required to confirm the User ID (e.g. Mobile phone number).

        • input options:

          • 0 : if the user does not need to confirm the User ID

          • 1 : if the user needs to confirm the User ID

      • ObtainCardSwipe (#REQUIRED)

        • description:Determines whether to prompt for a merchandise card to be swiped.

        • input options:

          • 0 : if the user should not be prompted to swipe a merchandise card

          • 1 : if the user should be prompted to swipe a merchandise card