ECR Protocol

How to migrate to Viva from a Cardlink integration.

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:

Devices

Requirements and limitations

Assuming that the terminal is active on a specific merchant, the following requirements apply:

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

ECR/ePOS applicationViva POSViva Host1. Open socket2. txReadyTransaction request is sentonly once txReady is received3. Transaction request4. Transaction request5. Transaction responseKeep the socket open until step6, below, has been performed.6. txResponse7. Close socketECR/ePOS applicationViva POSViva Host

Troubleshooting

If the ECR/ePOS sends a request and the transaction is not successfully initiated on the card terminal, check that:

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:

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. Android Card Terminals
'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. Android Card Terminals
Linux Card Terminals Countertop, IM20, S900, S800, D200. Linux Card Terminals

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!