Migrating from a previous Cardlink integration
How to migrate to Viva Wallet from a Cardlink integration.
- Requirements and limitations
- Transaction flow
- Key to card terminal product categories
- Get Support
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:
Terminal models supported - Any D200, S800, S900, Q30 or IM20 Prolin terminal with a software version 4.13 or later. Any Axxx (e.g. A80, A910 or A920) or IMxx series (e.g. IM30) Android card terminal with a software version 1.6.0 or later.
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. The ERP/ECR support setting allows you to configure another port.
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.
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
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 Wallet POS side
- correct IP and port have been set up on the ECR/ePOS side
- socket is opened and not closed before step 7
msgLengthshould contain the correct length of the message
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:
- 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.
- txSaleResponse - originating from the terminal to return the result of a sale transaction.
- txCancelRequest - originating from the application to initiate a request for a cancel transaction.
- txCancelResponse - originating from the terminal to return the result of a cancel transaction.
- txPreauthRequest - originating from the application to initiate a request for a new pre-auth transaction.
- txPreauthResponse - originating from the terminal to return the result of a pre-auth transaction.
- txAbort - originating from the application to indicate that the ongoing transaction should be aborted.
- getLastReceiptRequest - originating from the application to initiate a request to get the receipt data for the last transaction.
- getLastReceiptResponse - originating from the terminal to return the result of the receipt data for the last transaction.
- setPrintingSettingsRequest - originating from the application to initiate a request to set the print receipt options.
- setPrintingSettingsResponse - originating from the terminal to return the result of the set the print receipt options.
- batchManagementRequest - originating from the application to initiate a request to manage batch.
- batchManagementResponse - originating from the terminal to return the result of manage batch.
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.
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!