POS terminals

Minimise customer serving times by integrating a cash register or ordering application with one of Viva Wallet’s POS terminals. Integration allows an application to initiate transactions on a Viva Wallet terminal and get informed on the result.

Overview

Viva Wallet 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 or S900 Prolin terminal with a software version 4.13 or later. Any A80 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 client 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

Transaction flow

Messages

Transactions are initiated with a txRequest message. The terminal responds with a txReady to indicate readiness for card presentment. The result of card presentment process is returned to the application with a txResponse message.

Overall the following messages are available:

  • A txSaleRequest originating from the application to initiate a request for a new Sale transaction
  • A txCancelRequest originating from the application to initiate a request for a Cancel transaction
  • A txReady originating from the terminal to indicate that the terminal is ready for card presentment.
  • A txSaleResponse originating from the terminal to return the result of a sale transaction.
  • A txCancelResponse originating from the terminal to return the result of a cancel transaction.

Message structure and format

txSaleRequest

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

Field Type Lengh (chars) Description Example
msgLength String 4 A 4 digit number padded with leading zeros indicating message length minus 4 (including any separators). ‘0063’
sessionId String 4 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.

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

txCancelRequest

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

Field Type Lengh (chars) Description Example
msgLength String 4 A 4 digit number padded with leading zeros indicating message length minus 4 (including any separators). ‘0061’
sessionId String 4 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. ‘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’

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.

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.

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

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 Lengh (chars) Description Example
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’

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:

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

The table below summarises the contents of the response.

Field Lengh (chars) Description Example
msgLength 4 A 4 digit number padded with leading zeros indicating message length minus 4 (including any separators). ‘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. See failure code table below. ‘00’
respMessageResp variable up to 60 A string containing information on how the transaction was made, the verification method used, the transaction RRN. ‘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 other 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’
exchangeRangeInclMarkupResp 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’

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.

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

Code Description
51 Declined By Host
UD Unsupported Card
UC User Cancelled
LC Lost Carrier (Communication Error)
TO Time Out (Communication Error)
CE Communication Error (Other)
ND Communication Error (Other)
NA Host Not Available
IM Invalid response by host
UN Error – Wrong Transaction
EC Expired Card
XC Transaction approved. EMV fail. Reversed
RC Error during card reading

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:

IsoCode Description
10001 Refer To Card Issuer
10003 Invalid Merchant
10004 Pickup Card
10005 Do Not Honor
10006 General Error
10012 Invalid Transaction
10013 Invalid Amount
10014 Invalid Account Number
10030 Format Error
10041 Lost Card
10043 Stolen Card
10051 Insufficient Funds
10054 Expired Card
10055 Incorrect Pin
10057 Transaction Not Permitted To Card Holder
10058 Transaction Not Permitted To Acquirer Or Terminal
10061 Activity Amount Limit Exceeded
10062 Restricted Card
10063 Security Violation
10065 Activity Count Limit Exceeded
10068 Late Response
10070 Call Issuer
10075 Pin Entry Tries Exceeded
10086 Pin Validation Not Possible
10087 Purchase Amount Only No Cash Back Allowed
10090 Cut Off In Progress
10094 Duplicate Transmission Detected
10096 System Malfunction
10199 Empty
10200 Unmapped
* Any other

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:

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

The table below summarises the contents of the response.

Field Lengh (chars) Description Example
msgLength 4 A 4 digit number padded with leading zeros indicating message length minus 4 (including any 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 ‘00’ ‘04’
respCodeResp 2 Approval status. ‘00’ indicates approval. All other values indicate failure. See failure code table below. ‘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 other digits are masked with stars. ‘537535******9999’
refNumResp 6 A 6-digit number indicating the transaction’s STAN number. ‘856749’
authCodeResp 6 ‘000000’ (No authorisation code available) ‘000000’
eftTidResp 12 A 12 character string indicating the terminal’s TID number, padded with spaces if required. ’ 16016684’

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

0081|000058|210|04|51|Declined|MASTERCARD|537534******0126|063768|000000|16000059

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.