ECR Protocol
How to migrate to Viva from a Cardlink integration.
- Overview
- Supported Devices
- Requirements and limitations
- Transaction flow
- Messages
- Key to card terminal product categories
- Get Support
Overview
Migrating to the Viva POS API from a previous integration of POS terminals using the Cardlink API - using our generic Viva API, Viva POS terminals can receive requests for initiating transactions from any device connected to the same local wired or wireless IP network.
Communication with the terminal is done through a simple TCP/IP connection, so to implement the integration, basic knowledge of socket programming is required.
Messages exchanged between the application and the terminal take the form of simple strings containing information elements separated by a simple separator character.
Supported Devices
This integration is supported by:
- Paydroid devices: IM30, A920/A920 Pro, A910, A80, A77, A55 (v1.6.0 or later)
- Prolin devices: Q30, IM20, S900, S800, D200 (v4.13 or later)
Requirements and limitations
Assuming that the terminal is active on a specific merchant, the following requirements apply:
The merchant account must be configured for ERP/ECR support - Check the settings menu of the terminal. If ERP/ECR setting is present the account is appropriately configured. If not, get in touch with our customer service to configure the account.
The ERP/ECR support must be enabled on the terminal - Navigate to terminal menu called Settings to enable the ERP/ECR setting. Note that the default port where the terminal listens for client requests is 8080.
When the ERP/ECR support gets enabled, the terminal displays on screen the IP address and the listening port. We strongly advise to configure the terminal with a static IP address, to ensure that the ECR/ePOS application will always be able to connect to the terminal. To avoid situations like this, upon feature enabling the terminal displays a warning if the address is configured via DHCP.
You can try sending the ECR command first through a TCP client like Hercules . By doing so you will understand better how the ECR feature works and what are the exact steps.
Transaction flow
only once txReady is received ECR/ePOS application->>Viva POS:3. Transaction request Viva POS-->>Viva Host:4. Transaction request Viva Host->>Viva POS:5. Transaction response Note over ECR/ePOS application,Viva POS:Keep the socket open until step
6, below, has been performed. Viva POS-->>ECR/ePOS application:6. txResponse ECR/ePOS application->>Viva POS:7. Close socket
Troubleshooting
If the ECR/ePOS sends a request and the transaction is not successfully initiated on the card terminal, check that:
- ECR/ePOS has been enabled on the Viva POS side
- correct IP and port have been set up on the ECR/ePOS side
- socket is opened and not closed before step 7
- field
msgLengthshould contain the correct length of the message
Messages
Transactions are initiated with a txRequest message. After receiving a txRequest message, the terminal will respond with a txReady message to indicate readiness for card presentment. Overall the following messages are available:
Sales-related requests
- txReady - originating from the terminal to indicate that the terminal is ready for card presentment
- txSaleRequest - originating from the application to initiate a request for a new sale transaction
- txPreauthRequest - originating from the application to initiate a request for a new pre-auth transaction
- txCancelRequest - originating from the application to initiate a request for a cancel transaction
- txAbort - originating from the application to indicate that the ongoing transaction should be aborted
- batchManagementRequest - originating from the application to initiate a batch management request
- getLastReceiptRequest - originating from the application to initiate a request to get the receipt data for the last transaction
- rePrintRequest - originating from the application to initiate a request to reprint the last transaction or the transaction with a given orderCode
Configuration-related requests
- setPrintingSettingsRequest - originating from the application to initiate a request to set the print receipt options
Viva reserves the right to add new fields to the end of the ECR/ePOS responses. For this reason, as a developer, you need to make sure that you do not limit the number of fields that can be handled. This is to avoid any future issues that may arise
Key to card terminal product categories
To understand the icons used on the above Messages pages, see the below table.
| Product category | Terminal models | Icon |
|---|---|---|
| Android Card Terminals | Android Card Terminal Ethernet, Android Card Terminal 4G, Mobile Card Terminal Plus, Mobile Card Terminal. |  |
| 'viva.com | Terminal' application for Android | Mini Card Reader, Pocket Card Terminal connected via Bluetooth or USB to the 'viva.com | Terminal' application for Android. |  |
| Linux Card Terminals | Countertop, IM20, S900, S800, D200. |  |
Get Support
If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!