Migrating from a previous Cardlink POS integration

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.

Table of contents:

• Requirements and limitations
• Transaction flow
• Messages

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 Linux terminal with a software version 4.13 or later. Any A80, A910 or A920 Android 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.

Transaction flow

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 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
• field msgLength should 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:

• 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 Preauth transaction.
• txPreauthResponse originating from the terminal to return the result of a Preath transaction.

Message structure and format

txReady

After receiving a txSaleRequest or a txCancelRequest message, the terminal will respond with a txReady message to indicate readiness for card presentment.

The response will look as follows:

0014|810|00|000032

The contents of the message are described below:

Field	Length (chars)	Description	Example	Card terminal support
msgLength	4	A 4 digit number padded with leading zeros indicating message length minus 4 (including any separators).	‘0014’
msgType	3	‘810’	‘810’
msgCode	2	‘00’	‘00’
seqTxnNum	6	A 6-digit number padded with leading zeros indicating the serial number of the transaction (or the count of transactions made so far).	‘000032’

txSaleRequest

For a typical sale request the client must provide the following information:

Field	Type	Length (chars)	Description	Example	Card terminal support
msgLength	String	4	A 4-digit number padded with leading zeros indicating message length minus 4 (including any separators). The request will be rejected if the correct message length is not provided.	‘0063’
sessionId	String	6	A unique number to control integrity of session sequence.	‘002690’
msgType	String	3	‘200’	‘200’
msgCode	String	2	‘00’	‘00’
uniqueTxnId	String	32	A unique transaction ID transmitted to the host for storage with the transaction. Note that this value will be provided in the MerchantTrns field provided in the sales export response.	‘12345678901234567890123456789012’
amount	String	variable up to 13	Amount always including 2 decimal digits following the decimal point. A dot must always be used as a decimal point.	‘123.00’
msgOpt	String	4	‘0000’	‘0000’
Reserved	String	5	Empty	"
Reserved	String	6	Empty	"
Reserved	String	8	Empty	"
Reserved	String	6	Empty	"

The above information elements must be joined into one single string using ‘|’ as a separator. i.e.

0063|002690|200|00|12345678901234567890123456789012|123.50|0000||||

If the resulting string gets appropriately transmitted to the terminal, the terminal will respond with a txResponse message.

Notes

• msgLength indicates the length of the message starting from the first separator. Since msgLength has always a length of 4, the value stored in msgLength is the total message length minus 4. The request will be rejected if the correct message length is not provided.

• uniqueTxnId must be exactly 32 characters, so padding (even with space characters) is required.

txSaleResponse

After executing a Sale transaction the terminal responds with a txSaleResponse to indicate if the transaction has been approved or not.

A txSaleResponse for an approved transaction looks as follows:

Linux Card Terminals:

0129|000032|210|00|00|CHIP/PIN~RRN:123456833121|VISA|479275******9999|833121|690882|000001|123.00|1010|00|00|00|00|00|00| 16016684

Android Card Terminals:

0141|000032|210|00|00|Contactless/None~RRN:934209567754|MASTERCARD|537489******1474|567754|Ar1s00|000001|3.33|1010|00|00|00|00|00|00| 16000098|1062160242000098|1062160242

The table below summarises the contents of the response.

Field	Length (chars)	Description	Example	Card terminal support
msgLength	4	A 4-digit number padded with leading zeros indicating the length of the message that follows (including separators). Note that this is the total number of bytes and not of characters (in some languages, some characters consist of 2 bytes).	'0129'
seqTxnId	6	A 6 digit number matching the value sent in seqTnxNum field of the preceding txReady message.	'000032'
msgTypeResp	3	'210'	'210'
msgCodeResp	2	'00'	'00'
respCodeResp	2	Approval status. '00' indicates approval. All other values indicate failure codes. See failure code table at the end.	'00'
respMessageResp	variable up to 60	A string containing information on how the transaction was made, the card holder verification method used, the RRN and the Auth.code provided by the host.	'CHIP/PIN~RRN:123456833121'
cardTypeResp	variable	A string indicating the card type.	'VISA'
accNumberResp	variable	A string indicating the card number. Note that only the 6 first and the 4 last digits are provided. All the rest digits are masked with stars.	'479275******9999'
refNumResp	6	A 6-digit number indicating the transaction's STAN number.	'833121'
authCodeResp	6	A 6-digit number indicating the transaction's Authorisation code provided by the host.	'690882'
batchNumResp	6	A 6-digit number indicating the batch number. Not to be taken into account.	'000001'
amountResp	variable	The transaction's amount.	'123.00'
msgOptResp	4	Ignore	'1010'
tipAmountResp	2	'00' (currently not used)	'00'
foreignAmountResp	2	'00' (currently not used)	'00'
foreignCurrencyCode	2	'00' (currently not used)	'00'
exchangeRageInclMarkupResp	2	'00' (currently not used)	'00'
dccMarkcupPercentage	2	'00' (currently not used)	'00'
dccExchangeDateOfRateResp	2	'00' (currently not used)	'00'
eftTidResp	12	A 12 character string indicating the terminal's TID number, padded with spaces if required.	'16016684'
orderCode	16	Optional. Can be provided instead of or together with a refNum number. If a txnDateFrom/txnDateTo is provided, then the returned transaction results are bound by these dates, otherwise the last three transactions are returned.	'1069120310000201'
shortOrderCode	10	Optional. Can be provided instead of or together with a refNum number. If a txnDateFrom/txnDateTo is provided, then the returned transaction results are bound by these dates, otherwise the last three transactions are returned.	'1069120310'

It is expected that certain transactions will fail for various reasons. A txSaleResponse for a failed transaction looks as follows:

0117|000040|210|00|UC|CANCELLED BY THE USER|||000000|000000|000001|0.50|1010|00|00|00|00|00|00|16016684

The structure of the message is the same as in the case of an approved transaction.

Differences are limited to two specific fields.

• respCodeResp field where a response code is returned indicating the reason the transaction failed.
• respMessageResp where a string is returned providing a textual description of the reason.

Obviously refNumResp and authCodeResp contain zeros since there is no STAN code available, nor an authorisation code.

txCancelRequest

txCancelRequest executes a typical transaction cancellation or refund. The operation depends on whether the Sale transaction to be cancelled/refunded was made on the same day (cancellation) or any day before that (refund). Please note the parameters below and how they apply to different cancellation/refund scenarios further down.

Field	Type	Length (chars)	Description	Example	Card terminal support
msgLength	String	4	A 4-digit number padded with leading zeros indicating message length minus 4 (including any separators). The request will be rejected if the correct message length is not provided.	‘0061’
sessionId	String	6	A unique number to control integrity of session sequence.	‘002690’
msgType	String	3	‘200’	‘200’
msgCode	String	2	‘04’	‘04’
uniqueTxnId	String	32	A unique transaction ID transmitted to the host for storage with the transaction. Note that this value will be provided in the MerchantTrns field provided in the sales export response.	‘12345678901234567890123456789012’
amount	String	variable up to 13	Amount always including 2 decimal digits following the decimal point. A dot must always be used as a decimal point. If the amount is less than the transaction's full amount and the transaction date is today, then an error is returned as only a void is possible and therefore a full amount must be given. In all other cases, the amount can be partial to enable partial refunds. If no amount is supplied, it is assumed that the transaction amount is to be returned.	‘123.00’
refNum	String	6	The STAN number of the transaction to be cancelled. Note that if the STAN value is unknown the application may provide the value ‘000000’. In that case, after card presentment, the terminal will provide a list of the last 3 transactions made with the presented card, allowing the user to select the transaction to be canceled.	‘826987’
txnDateFrom	String	24	Optional. If supplied and no orderCode or refNum is given, then the returned transactions are within the txnDateFrom and txnDateTo bounds. If it is not supplied, then the last three transactions are returned as is the case with the current protocol.	'2021-03-18T14:42:53.341Z'
txnDateTo	String	24	Optional. If supplied and no orderCode or refNum is given, then the returned transactions are within the txnDateFrom and txnDateTo bounds. If it is not supplied, then the last three transactions are returned as is the case with the current protocol. If a txnDateFrom is supplied and no txnDateTo is given, then the application assumes that txnDateTo is today's date. If a txnDateTo is supplied without a txnDateFrom, then an error must be returned.	'2021-03-20T14:42:53.341Z'
orderCode	String	16	Optional. Can be provided instead of or together with a refNum number. If a txnDateFrom/txnDateTo is provided, then the returned transaction results are bound by these dates, otherwise the last three transactions are returned.	'1069120310000201'
shortOrderCode	String	10	Optional. Can be provided instead of or together with a refNum number. If a txnDateFrom/txnDateTo is provided, then the returned transaction results are bound by these dates, otherwise the last three transactions are returned.	'1069120310'

The above information elements must be joined into one single string using ‘|’ as a separator. i.e.

0061|002690|200|04|12345678901234567890123456789012|123.00|826987

If the resulting string gets appropriately transmitted to the terminal, the terminal will respond with a txResponse message.

If only the amount is communicated during the refund and no order code is given:

• Show a list of transactions. Above the list show: Refund X EUR for which transaction?
• Each list item should contain the transaction ID, transaction date, original sale amount.
• Once a list item is chosen by the operator, show the refund confirmation (Are you sure you want to refund X EUR from the transaction with transaction ID A, transaction date B, original sale amount C?)
• Once confirmed, proceed with refund. No amount revalidation/entry necessary by terminal operator!

If the order code is communicated during the refund and no amount is given, then it is assumed that the entire amount is to be refunded:

• Proceed with refund. No amount revalidation/entry necessary by terminal operator!

If the order code is communicated during the refund and an amount is given:

• Proceed with refund. No revalidation/entry necessary by terminal operator!

Notes

• msgLength indicates the length of the message starting from the first separator. Since msgLength has always a length of 4, the value stored in msgLength is the total message length minus 4. The request will be rejected if the correct message length is not provided.

• uniqueTxnId must be exactly 32 characters, so padding (even with space characters) is required.

txCancelResponse

After executing a Cancel transaction the terminal responds with a txCancelResponse to indicate if the transaction has been approved or not.

A txCancelResponse for a successful cancel transaction looks as follows:

Linux Card Terminals:

0073|000050|210|04|00||MASTERCARD|537535******1339|856749|000000|16016684

Android Card Terminals:

0106|000022|210|04|51|Declined|||||000001|9.99|1010|00|00|00|00|00|00| 16000279|1069120310000279|1069120310

The table below summarises the contents of the response.

Field	Length (chars)	Description	Example	Card terminal support
msgLength	4	A 4-digit number padded with leading zeros indicating the character length of the message that follows (including separators).	'0073'
seqTxnId	6	A 6-digit number matching the value sent in seqTnxNum field of the preceding txReady message.	'000050'
msgTypeResp	3	'210'	'210'
msgCodeResp	2	'04'	'04'
respCodeResp	2	Approval status. '00' indicates approval. All other values indicate failure codes. See failure code table at the end.	'00'
respMessageResp	variable up to 60	Empty	''
cardTypeResp	variable	A string indicating the card type.	'MASTERCARD'
accNumberResp	variable	A string indicating the card number. Note that only the 6 first and the 4 last digits are provided. All the rest digits are masked with stars.	'537535******1339'
refNumResp	6	A 6-digit number indicating the transaction's STAN number.	'856749'
authCodeResp	6	'000000'	'000000'
eftTidResp	12	A 12-character string indicating the terminal's TID number, padded with spaces if required.	'16016684'
orderCode	16	A 16-digit numeric string representing the order code.	'1062160242000098'
shortOrderCode	10	A 10-digit numeric string representing the short order code.	'1062160242'

It is expected that certain transactions will fail for various reasons. A txSaleResponse for a failed transaction looks as follows:

0106|000022|210|04|51|Declined|||||000001|9.99|1010|00|00|00|00|00|00| 16000279|1069120310000279|1069120310

The structure of the message is the same as in the case of an approved transaction.

Differences are limited to two specific fields.

• respCodeResp field where a response code is returned indicating the reason the transaction failed. The table of values provided in txSaleResponse provides typical response codes that may be returned.
• respMessageResp where a string is returned providing a textual description of the reason.

Obviously authCodeResp contain zeros since there is no STAN code available, nor an authorisation code.

Failure reasons

See Failure reasons and ISO codes under txSaleResponse. These are the same for all transaction types (Sales, Cancellations and Preauths).

txPreauthRequest

Supported on PayDroid terminals only, not compatible with Linux devices.

For a typical preauth request the client must provide the same info as for txSaleRequest except for the following:

Field	Type	Length (chars)	Description	Example	Card terminal support
msgType	String	3	'100'	'100'

The above information elements must be joined into one single string using ‘|’ as a separator. i.e.

0063|002690|100|00|12345678901234567890123456789012|123.50|0000||||

If the resulting string gets appropriately transmitted to the terminal, the terminal will respond with a txResponse message.

Failure reasons and ISO codes

The table below summarises the failure reasons that can be provided by the terminal.

Notes

• The list of codes may differ slightly between different versions of the software. Therefore, it is strongly suggested to use the response code (as well as any informational text provided), merely for display or troubleshooting purposes, i.e. when reporting the issue to the customer service.

• In cases where the transaction gets declined by the Host (51), the terminal provides extra text on screen as well as a special code indicating the exact reason the transaction was declined by the host. The full list is described in the table below:

txPreauthResponse

Supported on PayDroid terminals only, not compatible with Linux devices.

After executing a Preauth transaction the terminal responds with a txPreauthResponse to indicate if the transaction has been approved or not.

A txPreauthResponse for an approved transaction looks as follows:

Linux Card Terminals:

0129|000032|110|00|00|CHIP/PIN~RRN:123456833121|VISA|479275******9999|833121|690882|000001|123.00|1010|00|00|00|00|00|00| 16016684

Android Card Terminals:

0166|000002|110|00|00|Contactless/None~RRN:109210030080|MASTERCARD|537488******9666|30080|006575|000001|1.23|00|00|00|00|00|00|00| 16022144|1092130081022143|1092130081

The contents of the response is the same as for txSaleResponse with the exception of the following:

Field	Type	Length (chars)	Description	Example	Card terminal support
msgTypeResp	String	3	‘110’	‘110’

Failure reasons

See Failure reasons and ISO codes under txSaleResponse. These are the same for all transaction types (Sales, Cancelations and Preauths).

Key to card terminal product categories

To understand the icons used in the above tables, 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.
Linux Card Terminals	Countertop, IM20, S900, S800, D200.