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
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
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. 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:
- txSaleRequest originating from the application to initiate a request for a new Sale transaction
- txCancelRequest originating from the application to initiate a request for a Cancel transaction
- txPreauthRequest originating from the application to initiate a request for a new Preauth transaction
- txReady originating from the terminal to indicate that the terminal is ready for card presentment.
- txSaleResponse originating from the terminal to return the result of a sale transaction.
- txCancelResponse originating from the terminal to return the result of a cancel transaction.
- txPreauthResponse originating from the terminal to return the result of a Preath transaction
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 | 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.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 | 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 | 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. | ‘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.
txPreauthRequest
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 |
---|---|---|---|---|
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.
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.
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.
Failure reasons and ISO codes
The table below summarises the failure reasons that can be provided by the terminal.
Code | Description | Event |
---|---|---|
51 | Declined By Host | Declined by the issuer |
UD | Unsupported Card | Card is not supported |
UC | User Cancelled | User pressed cancel or the user failed to present card in due time |
LC | Lost Carrier (Communication Error) | No network |
TO | Time Out (Communication Error) | Time out with host |
CE | Communication Error (Other) | No connectivity |
ND | Communication Error (Other) | Request failed |
NA | Host Not Available | Host is not unreachable |
IM | Invalid MAC received from host | ... |
UN | Error – Wrong Transaction | … |
EC | Expired Card | Expired Card |
XC | Transaction approved. EMV fail. Autoreversal | Transaction approved but automatically canceled |
RC | Error during card reading | An error occurred while reading the card. |
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 | ReferToCardIssuer |
10003 | InvalidMerchant |
10004 | PickupCard |
10005 | DoNotHonor |
10006 | GeneralError |
10012 | InvalidTransaction |
10013 | InvalidAmount |
10014 | InvalidAccountNumber |
10030 | FormatError |
10041 | LostCard |
10043 | StolenCard |
10051 | InsufficientFunds |
10054 | ExpiredCard |
10055 | IncorrectPin |
10057 | TransactionNotPermittedToCardHolder |
10058 | TransactionNotPermittedToAcquirerOrTerminal |
10061 | ActivityAmountLimitExceeded |
10062 | RestrictedCard |
10063 | SecurityViolation |
10065 | ActivityCountLimitExceeded |
10068 | LateResponse |
10070 | CallIssuer |
10075 | PinEntryTriesExceeded |
10086 | PinValidationNotPossible |
10087 | PurchaseAmountOnlyNoCashBackAllowed |
10090 | CutOffInProgress |
10094 | DuplicateTransmissionDetected |
10096 | SystemMalfunction |
10199 | Empty |
10200 | Unmapped |
* | 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.
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).
txPreauthResponse
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:
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
The contents of the response is the same as for txSaleResponse with the exception of the following:
Field | Type | Length (chars) | Description | Example |
---|---|---|---|---|
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).