Migrating from a previous Cardlink POS 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 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

sequenceDiagram participant Client application participant Viva Wallet POS participant Viva Wallet Host Note over Client application:Transaction init
message sent
to POS. Client application->>Viva Wallet POS:txRequest Note over Viva Wallet POS: READY message
triggered in card
presentment mode. Viva Wallet POS->>Client application:txReady Note over Client application: Card holder informed
that POS is
ready for card. Note over Viva Wallet POS: Card holder presents
card. POS executes
transaction with
payments host
(PIN requested
if needed). Viva Wallet POS->>Viva Wallet Host: Secure request Note over Viva Wallet Host: Transaction
executed and
response
returned. Viva Wallet Host->>Viva Wallet POS:Secure response Note over Viva Wallet POS:If POS is print
enabled, receipt is
printed and
response returned
to client app. Viva Wallet POS->>Client application:txResponse Note over Client application: Transaction result
received. Optional
receipt printed.

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:

Message structure and format

txSaleRequest

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

Field Type Length (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

txCancelRequest

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

Field Type Length (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

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
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 Length (chars) Description Example
msgLength 4 A 4-digit number padded with leading zeros indicating the character length of the message that follows (including 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 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'

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.

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

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

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.

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