Apex Payment Solutions Serial ECR & DLL Integration Apex SmartPOS December 20, 2020 2.00 Apex SmartPOS ECR Interface PROPRIETARY NOTICE AND LIABILITY DISCLAIMER The information disclosed in this document, including all designs and related materials are confidential and proprietary to Apex Payment Solutions. Apex Payment Solutions and the logo are registered trademarks of Apex Payment Solutions. Apex Payment Solutions reserve copyright and other proprietary rights to this document. This Document, or any part of this material, shall not be used, duplicated, reproduced, transmitted, published, or otherwise disclosed to anyone other than to whom this document is delivered without express written authorization from Apex Payment Solutions. This restriction is applicable to all pages of this document. www.apex.jo CONFIDENTIAL©2020 Page 2 of 23 Apex SmartPOS ECR Interface Table of Contents 1. Introduction ....................................................................................................................... 6 1.1. Purpose .............................................................................................................................................................. 6 1.2. Audience ............................................................................................................................................................ 6 1.3. Overview ............................................................................................................................................................ 6 2. Transport Protocol ............................................................................................................... 7 2.1. Interface Parameters ........................................................................................................................................ 7 2.2. Asynchronous Packet Framing ......................................................................................................................... 7 2.3. Retry & Timers................................................................................................................................................... 8 2.4. CRC Calculation ................................................................................................................................................. 8 2.5. Error Handling ................................................................................................................................................... 8 2.6. ECR Transaction Flow ....................................................................................................................................... 9 3. Application Protocol ............................................................................................................11 3.1. Protocol Field...................................................................................................................................................11 3.2. Length Field .....................................................................................................................................................11 3.3. Data Block Field...............................................................................................................................................11 3.3.1. JSON Data ...................................................................................................................................................11 4. Messages Specifications .......................................................................................................12 4.1. Start Session ....................................................................................................................................................12 4.2. Sale...................................................................................................................................................................13 4.3. Void ..................................................................................................................................................................14 4.4. Settlement .......................................................................................................................................................15 5. DLL Interface......................................................................................................................16 3.1 DLL Classes............................................................................................................................................................16 3.1.1 EcrConfig.....................................................................................................................................................16 3.1.2 ComPortSettings ........................................................................................................................................16 3.1.3 EcrRsp_StartSession...................................................................................................................................17 3.1.4 EcrRsp_Sale ................................................................................................................................................17 3.1.5 EcrRsp_Void................................................................................................................................................18 3.1.6 EcrRsp_Settle .............................................................................................................................................18 3.2 DLL Functions .......................................................................................................................................................19 3.2.1 General Functions ......................................................................................................................................19 3.2.2 Session Functions.......................................................................................................................................19 3.2.3 Financial Functions ....................................................................................................................................19 6. Appendix ..........................................................................................................................20 6.1. Response Codes...............................................................................................................................................20 www.apex.jo CONFIDENTIAL©2020 Page 3 of 23 Apex SmartPOS ECR Interface 6.2. Card Slot ..........................................................................................................................................................20 6.3. Sample Request (Low-Level)..........................................................................................................................20 6.4. Sample Code (C#) ............................................................................................................................................21 6.5. A90 COM Port configuration ..........................................................................................................................22 www.apex.jo CONFIDENTIAL©2020 Page 4 of 23 Apex SmartPOS ECR Interface Definitions Abbreviations ECR Electronic Cash Register POS Point of Sale\SmartPOS APDU Application Protocol Data Unit (Request or Response Data) CRC Cyclic Redundancy Check var Variable Length REQ Request RSP Response Special Character in Transfer Protocol: STX 0x02 Start of Text ETX 0x03 End of Text ACK 0x06 Acknowledgment NAK 0x15 Negative Acknowledgment ENQ 0x05 Enquiry EOT 0x04 End of transmission DLE 0x10 Data link escape www.apex.jo CONFIDENTIAL©2020 Page 5 of 23 Apex SmartPOS ECR Interface 1. Introduction 1.1. Purpose The purpose of this document is to provide a technical (message structure and data elements) and customization based on Apex-ECR protocol required for ECR-POS machine to integrate with Apex SmartPOS financial application. 1.2. Audience This document is primarily for the ECR-POS application developer for implementing Apex-ECR protocol to integrate with Apex SmartPOS financial application using Low-Level Serial protocol and\or using High-Level DLL. 1.3. Overview ECR machine will be integrated with A90 SmartPOS using Apex Low-Level ECR interface, to initiate different financial and inquiry transactions. A90 SmartPOS application will handle all transactions with the authorization Host. www.apex.jo CONFIDENTIAL©2020 Page 6 of 23 Apex SmartPOS ECR Interface 2. Transport Protocol The transport protocol defines the lower-level data link protocol that moves the messages\packets between ECR and Apex SmartPOS. The supported communication protocol is based on a standard asynchronous serial communication protocol (RS232 serial communication), to transfer packets (Application Protocol Data Unit-APDU) encoded as JSON data, the message format illustrates how the data (APDU) is encapsulated within the transport protocol. 2.1. Interface Parameters The data-transfer is carried-out according to RS232C with the following parameters (115200,8,N,1): • 115200 Baud Rate, asynchronous. • No Handshake. • 8 data-bits. • No parity-bit. • 1 Stop-bit. 2.2. Asynchronous Packet Framing Character-based framing, uses special communication control characters for idle fill and to indicate the beginning and ending of frames. Before transmission, sender should encapsulate the message inside framing control characters STX & ETX