Migrating from a previous Cardlink integration

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

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.

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’ Android Card TerminalsLinux Card Terminals
msgType 3 ‘810’ ‘810’ Android Card TerminalsLinux Card Terminals
msgCode 2 ‘00’ ‘00’ Android Card TerminalsLinux Card Terminals
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’ Android Card TerminalsLinux Card Terminals

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’ Android Card TerminalsLinux Card Terminals
sessionId String 6 A unique number to control integrity of session sequence. ‘002690’ Android Card TerminalsLinux Card Terminals
msgType String 3 ‘200’ ‘200’ Android Card TerminalsLinux Card Terminals
msgCode String 2 ‘00’ ‘00’ Android Card TerminalsLinux Card Terminals
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’ Android Card TerminalsLinux Card Terminals
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’ Android Card TerminalsLinux Card Terminals
msgOpt String 4 ‘0000’ ‘0000’ Android Card TerminalsLinux Card Terminals
Reserved String 0 Empty " Android Card TerminalsLinux Card Terminals
Reserved String 0 Empty " Android Card TerminalsLinux Card Terminals
Reserved String 0 Empty " Android Card TerminalsLinux Card Terminals
Reserved String 0 Empty " Android Card TerminalsLinux Card Terminals
ISV_amount String Variable up to 13 ISV fee amount always including 2 decimal digits following the decimal point. A dot must always be used as a decimal point. '123.00' Android Card TerminalsLinux Card Terminals
ISV_clientId String 200 The id of the ISV client.
Refer to note below.
'qwerty123456' Android Card TerminalsLinux Card Terminals
ISV_clientSecret String 200 The secret of the ISV client.
Refer to note below.
'qwerty123456' Android Card TerminalsLinux Card Terminals
ISV_sourceCode String 20 The reseller source code of the ISV.
Important: Should not be empty. Use “Default“ if no custom value.
Refer to note below.
'qwerty123456' Android Card TerminalsLinux Card Terminals

ISV parameter info:

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|||||0.10|qwerty123456|qwerty123456|qwerty123456

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

Notes

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||||629914XXXXXXXXX6770|629914XXXXXXXXX6770|qwerty123456|qwerty123456|my name|2212|1010

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|||||||

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' Android Card TerminalsLinux Card Terminals
seqTxnId 6 A 6 digit number matching the value sent in seqTnxNum field of the preceding txReady message. '000032' Android Card TerminalsLinux Card Terminals
msgTypeResp 3 '210' '210' Android Card TerminalsLinux Card Terminals
msgCodeResp 2 '00' '00' Android Card TerminalsLinux Card Terminals
respCodeResp 2 Approval status. '00' indicates approval. All other values indicate failure codes. See failure code table at the end. '00' Android Card TerminalsLinux Card Terminals
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' Android Card TerminalsLinux Card Terminals
cardTypeResp variable A string indicating the card type. 'VISA' Android Card TerminalsLinux Card Terminals
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' Android Card TerminalsLinux Card Terminals
refNumResp 6 A 6-digit number indicating the transaction's STAN number. '833121' Android Card TerminalsLinux Card Terminals
authCodeResp 6 A 6-digit number indicating the transaction's Authorisation code provided by the host. '690882' Android Card TerminalsLinux Card Terminals
batchNumResp 6 A 6-digit number indicating the batch number. Not to be taken into account. '000001' Android Card TerminalsLinux Card Terminals
amountResp variable The transaction's amount. '123.00' Android Card TerminalsLinux Card Terminals
msgOptResp 4 Ignore '1010' Android Card TerminalsLinux Card Terminals
tipAmountResp 2 '00' (currently not used) '00' Android Card TerminalsLinux Card Terminals
foreignAmountResp 2 '00' (currently not used) '00' Android Card TerminalsLinux Card Terminals
foreignCurrencyCode 2 '00' (currently not used) '00' Android Card TerminalsLinux Card Terminals
exchangeRageInclMarkupResp 2 '00' (currently not used) '00' Android Card TerminalsLinux Card Terminals
dccMarkcupPercentage 2 '00' (currently not used) '00' Android Card TerminalsLinux Card Terminals
dccExchangeDateOfRateResp 2 '00' (currently not used) '00' Android Card TerminalsLinux Card Terminals
eftTidResp 12 A 12 character string indicating the terminal's TID number, padded with spaces if required. '16016684' Android Card TerminalsLinux Card Terminals
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' Android Card Terminals
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' Android Card Terminals
MerchantReceiptPAN variable up to 19 This field contains the value of the PAN (and additional clipping) that should be printed in merchant receipt. If is empty, then apply the default clipping '629914XXXXXXXXX6770' Linux Card Terminals
CardholderReceiptPAN variable up to 19 This field contains the value of the PAN (and additional clipping) that should be printed in customer receipt. If is empty, then apply the default clipping. '629914XXXXXXXXX6770' Linux Card Terminals
CardholderReceiptText variable up to 200 If is not empty then this value should be printed at the end of the customer receipt. 'qwerty123456' Linux Card Terminals
TransactionReceiptAcquirerZone variable up to 200 If it is not empty then this value should be printed at the end of the customer receipt. 'qwerty123456' Linux Card Terminals

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.

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

Failure reasons and ISO codes

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

CodeDescriptionEvent
51Declined By HostDeclined by the issuer
UDUnsupported CardCard is not supported
UCUser CancelledUser pressed cancel or the user failed to present card in due time
LCLost Carrier (Communication Error)No network
TOTime Out (Communication Error)Time out with host
CECommunication Error (Other)No connectivity
NDCommunication Error (Other)Request failed
NAHost Not AvailableHost is not unreachable
IMInvalid MAC received from host...
UNError – Wrong Transaction
ECExpired CardExpired Card
XCTransaction approved. EMV fail. AutoreversalTransaction approved but automatically canceled
RCError during card readingAn error occurred while reading the card.
NOError after void requestNo transactions found.
Notes
IsoCodeDescription
10001ReferToCardIssuer
10003InvalidMerchant
10004PickupCard
10005DoNotHonor
10006GeneralError
10012InvalidTransaction
10013InvalidAmount
10014InvalidAccountNumber
10030FormatError
10041LostCard
10043StolenCard
10051InsufficientFunds
10054ExpiredCard
10055IncorrectPin
10057TransactionNotPermittedToCardHolder
10058TransactionNotPermittedToAcquirerOrTerminal
10061ActivityAmountLimitExceeded
10062RestrictedCard
10063SecurityViolation
10065ActivityCountLimitExceeded
10068LateResponse
10070CallIssuer
10075PinEntryTriesExceeded
10086PinValidationNotPossible
10087PurchaseAmountOnlyNoCashBackAllowed
10090CutOffInProgress
10094DuplicateTransmissionDetected
10096SystemMalfunction
10199Empty
10200Unmapped
*Anyother

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’ Android Card TerminalsLinux Card Terminals
sessionId String 6 A unique number to control integrity of session sequence. ‘002690’ Android Card TerminalsLinux Card Terminals
msgType String 3 ‘200’ ‘200’ Android Card TerminalsLinux Card Terminals
msgCode String 2 ‘04’ ‘04’ Android Card TerminalsLinux Card Terminals
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’ Android Card TerminalsLinux Card Terminals
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’ Android Card TerminalsLinux Card Terminals
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’ Android Card TerminalsLinux Card Terminals
sourceTerminalId String 8 Optional. The terminal ID of the source with which the transaction is associated. ‘12345678’ Android Card TerminalsLinux Card Terminals
txnDateFrom

(NOT YET SUPPORTED)
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' Android Card Terminals
txnDateTo

(NOT YET SUPPORTED)
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' Android Card Terminals
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' Android Card Terminals
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' Android Card Terminals

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:

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:

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

Notes

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:

0073|000050|210|04|00||MASTERCARD|537535******1339|856749|000000|16016684|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' Android Card TerminalsLinux Card Terminals
seqTxnId 6 A 6-digit number matching the value sent in seqTnxNum field of the preceding txReady message. '000050' Android Card TerminalsLinux Card Terminals
msgTypeResp 3 '210' '210' Android Card TerminalsLinux Card Terminals
msgCodeResp 2 '04' '04' Android Card TerminalsLinux Card Terminals
respCodeResp 2 Approval status. '00' indicates approval. All other values indicate failure codes. See failure code table at the end. '00' Android Card TerminalsLinux Card Terminals
respMessageResp variable
up to 60
Empty '' Android Card TerminalsLinux Card Terminals
cardTypeResp variable A string indicating the card type. 'MASTERCARD' Android Card TerminalsLinux Card Terminals
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' Android Card TerminalsLinux Card Terminals
refNumResp 6 A 6-digit number indicating the transaction's STAN number. '856749' Android Card TerminalsLinux Card Terminals
authCodeResp 6 '000000' '000000' Android Card TerminalsLinux Card Terminals
eftTidResp 12 A 12-character string indicating the terminal's TID number, padded with spaces if required. '16016684' Android Card TerminalsLinux Card Terminals
orderCode 16 A 16-digit numeric string representing the order code. '1062160242000098' Android Card Terminals
shortOrderCode 10 A 10-digit numeric string representing the short order code. '1062160242' Android Card Terminals
MerchantReceiptPAN Variable up to 19 This field contains the value of the PAN (and additional clipping) that should be printed in merchant receipt. If is empty, then apply the default clipping. '629914XXXXXXXXX6770' Linux Card Terminals
CardholderReceiptPAN Variable up to 19 This field contains the value of the PAN (and additional clipping) that should be printed in customer receipt. If is empty, then apply the default clipping. '629914XXXXXXXXX6770' Linux Card Terminals
CardholderReceiptText Variable up to 200 If is not empty then this value should be printed at the end of the customer receipt. 'qwerty123456' Linux Card Terminals
TransactionReceiptAcquirerZone Variable up to 200 If it is not empty then this value should be printed at the end of the customer receipt. 'qwerty123456' Linux Card Terminals
CardholderName Variable up to 50 Name of the cardholder. 'CARDHOLDER NAME' Linux Card Terminals
CardExpirationDate 4 Expiration date of the card (YYMM). '2212' Linux Card Terminals
CardholderName&ExpirationDateFlags 4 Each char may be 0 (false) or 1 (true) and indicates if the cardholder name and the expiration date should be printed on the merchant/cardholder receipts).

1st char: if 1 then the Cardholder Name should be printed in the merchant's receipt. If 0, then it should not.

2nd char: if 1 then the Cardholder Name should be printed in the cardholder's receipt. If 0, then it should not.

3rd char: if 1 then the Expiration Date should be printed in the merchant's receipt. If 0, then it should not.

4th char: if 1 then the Expiration Date should be printed in the cardholder's receipt. If 0, then it should not.
'1062160242' Linux Card Terminals

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.

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 Pre-auths).

txPreauthRequest

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

For a typical pre-auth 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' Android Card Terminals

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.

txPreauthResponse

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

After executing a Pre-auth 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:

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’ Android Card Terminals
Failure reasons

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

txAbort

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

To abort an ongoing transaction the application should just drop the connection with the terminal. The following code line is an expected example:

socket.close()

When the application side drops the connection, the transaction gets aborted. If the transaction has been sent to the server an automatic system reversal of the aborted transaction will follow up.

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