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, 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.
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
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:
- 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:
txSaleRequest
For a typical sale request the client must provide the following information:
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.
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.
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.
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.
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 |
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.