Migrating from a previous Cardlink integration

How to migrate to Viva Wallet from a Cardlink integration.

Overview

Migrating to the Viva Wallet POS API from a previous integration of POS terminals using the Cardlink API - using our generic Viva Wallet API, Viva Wallet 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.

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

sequenceDiagram participant ECR/ePOS application participant Viva Wallet POS participant Viva Wallet Host ECR/ePOS application->>Viva Wallet POS:1. Open socket Viva Wallet POS-->>ECR/ePOS application:2. txReady Note over ECR/ePOS application,Viva Wallet POS: Transaction request is sent
only once txReady is received ECR/ePOS application->>Viva Wallet POS:3. Transaction request Viva Wallet POS-->>Viva Wallet Host:4. Transaction request Viva Wallet Host->>Viva Wallet POS:5. Transaction response Note over ECR/ePOS application,Viva Wallet POS:Keep the socket open until step
6, below, has been performed. Viva Wallet POS-->>ECR/ePOS application:6. txResponse ECR/ePOS application->>Viva Wallet 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:

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 Wallet 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 Wallet POS app for Android Mini Card Reader, Pocket Card Terminal connected via Bluetooth or USB to the Viva Wallet POS app 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 Wallet, or if you have any queries about our products and solutions, please see our Get Support page to see how we can help!