1 Wallee AG Local Till Interface (LTI)
Welcome to the Wallee AG Local Till Interface (LTI) documentation for version: 2.47, created on: 2024-07-03
2 Overview
The Local Till Interface (LTI) describes the interface between a till system and a Wallee terminal via a LAN network connection. The communication between the terminal and the Wallee Cloud or to the acquirer is out of scope.
2.1 Integration Variants
This document describes one out of three different interfaces which are available to integrate with a Wallee terminal.
Local Till Interface (LTI): The LTI is described in this document. Integrators should use the LTI if the till application connects to the terminal via a local area network. The most common use case is if the terminal and till are connected to the same LAN at the merchant’s site. The benefit is a fast connection as both, the till application and the terminal device, are in the same local network. One drawback is that the terminal’s IP address needs to be known. It is also possible to install till applications directly on the device and use LTI via localhost. Nevertheless, if a till application is installed on an Android terminal, then using the Android Till Interface (ATI) is recommended.
Android Till Interface (ATI): Integrators are recommended to use the Android Till Interface if their till application is installed directly on an Android based terminal. This way, the till app can directly talk to the terminal software (via android.os.Messenger). The benefit is that one can use our Android Till SDK to interact with the terminal. If the till app is not running on the terminal, then the Android Till Interface does not work.
Cloud Till Interface (CTI): By using the cloud interface, an integrator is using a public reachable API to interact with the terminal device. The benefit is that the till app does not need to know where the device is located and it works from any network. However there is a higher delay compared to other integration methods because the communication happens via a central server.
Note that there are also adaptors available for other protocols, like i.e: MDB which is commonly used on vending machines. For more information about adaptors, get in contact with Wallee’s customer support.
All integration options provide mechanisms for the same terminal features. Some of the features are as follows:
Request to perform payment transactions like Purchase, Load, Cashback, Reservation etc.
Activate and deactivate terminals (also called linking or unlinking).
Obtain surrogate PAN values (also called PAN hash or PAN token).
Trigger SI(CONFIG) and SI(INTI) procedures.
Receiving additional receipt or display information.
3 Protocol Layers
The following table shows an overview of the involved protocol layers. The XML message is sent on top of TCP/IP.
Local Till Interface (LTI) (Len + XML) |
TCP |
IP |
The XML message consists of a length field preceding the XML payload.
3.1 XML message length
The following table shows a Local Till Interface (LTI) frame layout.
Byte Nr |
Protocol Field |
---|---|
0..3 |
length (binary, big endian) |
4.. |
XML message payload |
Each XML message payload is preceded by 4 bytes containing the number of bytes of the following XML message. The encoding is binary, big endian. This allows the application layer to always be able to determine if a complete XML message has been received before parsing it, regardless of the underlying protocol. Since it is possible that the PIN pad sends more than one message consecutively and the data read from a TCP/IP socket are stream-oriented and not message oriented, it can be that two or more messages are present in the socket buffer simultaneously. Reading these messages without regarding the header and especially the preceding length bytes can result in an error. It is important that the till uses the length bytes to determine the number of bytes that form the corresponding XML message.
3.2 TCP/IP
The device (PIN pad) can send/receive data to/from the PoS system using the standard TCP/IP protocol. It is assumed that this is the primary choice in case of using a wired network. The PoS system acts as a client and the device acts as a server listening on a specified port number. The port number is defined in the configuration of the device. The default port number is 50000.
4 LTI Message Structure
The Local Till Interface (LTI) messaging is based on the request-response pattern. There are two main message communication types, which define flow direction:
- PoS message
Pair of messages: request sent from till system to PIN pad/device and response back to till system
- Device message
Pair of messages: request sent from PIN pad/device to till system and response back to device
It is essential that during processing of PoS messages, the device can send to the PoS system several device messages related to display or printer (i.e. a notification for an attendant or a request for the confirmation of a current operation).
Each message contains the following parts:
XML header
message
The XML (eXtended Markup Language) is used as a data format standard. 9 XML Schemas are part of this documentation. They accurately describe all valid messages and the used types.
4.1 Common elements
In the tables below, common parts of a message are presented.
4.1.1 XML header
Keyword |
Type |
Description |
Version |
xsd:string |
Version of the XML base specification e.g. “1.0” (optional argument) |
Encoding |
xsd:string |
Type of encoding used in message e.g. “UTF-8” (recommended value) |
Standalone |
xsd:string |
Information if file is linked with other types e.g. “yes” (recommended value) |
5 Examples
5.1 Maintenance communication example
The simple example of communication between the POS system and the device includes three disjoint PoS messages: siConfigRequest, siInitRequest and activationRequest with three related responses.
![_images/1000000000000698000007D849623F5FBF5B9181.png](_images/1000000000000698000007D849623F5FBF5B9181.png)
Fig. 1 Maintenance communication example
5.2 Submission communication example
Submission communication example shows a communication in case of end-of-day, when a shift of information (esp. information related to off-line transactions) is needed. In this case dialogue is fulfilled by miSubmissionMessage. Please note that the device communicates twice with the PoS system using device messages within an operation of processing a single PoS message.
![_images/1000000000000698000007D801041275E30B223F.png](_images/1000000000000698000007D801041275E30B223F.png)
Fig. 2 Submission communication example
5.3 Transaction communication example
The example assumes that a customer bought some goods and paid for them using a contactless payment system. Transaction was processed offline without authorization, PIN code or other confirmation (transactionType = 0). Similarly, as in the previous section it is noticeable that the device can send several device requests during the activity of processing one PoS message.
![_images/10000000000002570000020A1B6EDC6EFB4BA124.png](_images/10000000000002570000020A1B6EDC6EFB4BA124.png)
Fig. 3 Transaction communication example
6 Message Types
This section describes both request and response messages that are used in the interface protocol.
6.1 FinancialTrx Message
FinancialTrx message - Request to perform payment transaction. The type of transaction is defined by TransactionType, which includes i.e.: Purchase, Load, Cashback, Reservation etc.
Request:
Keyword |
Type |
Description |
---|---|---|
posId |
xsd:string |
PoS identifier |
trxData |
TransactionData |
Transaction data |
manualPanData |
ManualPanData |
Manually entered card data |
trxSyncNumber |
xsd:unsignedInt |
Number maintained by the PoS and changed after each successful transaction to recognize an out-of-sync situation. See 7 TransactionSyncNumber |
cardTokenData |
BarcodeCardData |
Card data referenced by a token instead of a primary account number |
generatePanToken |
xsd:boolean |
Flag to request the PAN-Token in the FinancialTrxResponse (optional) |
trxInfo |
xsd:base64Binary |
This field contains a bitmask to specify which 6.26 TransactionStatusNotification Messages should be sent by the terminal. This field should contain a series of 3 bytes in Base64 encoding. (see chapter 6.1.1 trxInfo bitmask) |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
tillMode |
xsd:string |
Optional field to give more information about where the financialTrxRequest started. (needed to distinguish between till client types) SDKApp - Till SDK related 3rd party apps VTIApp - local IP related 3rd party apps POSApp - local / remote IP related POS client apps WebApp - Portal |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:financialTrxRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>12345678</posId>
<trxSyncNumber>41</trxSyncNumber>
<trxData>
<amount>100</amount>
<currency>756</currency>
<transactionType>0</transactionType>
<partialApprovalCap>1</partialApprovalCap>
<noDCC>true</noDCC>
<merchantReference>EXAMPLE-12345-12</merchantReference>
</trxData>
<trxInfo>AAAf</trxInfo>
<receiptFormat>2</receiptFormat>
<tillMode>SDK</tillMode>
</vcs-pos:financialTrxRequest>
Response:
Keyword |
Type |
Description |
ep2AuthResponseCode |
xsd:string |
Authorization response code according to EP2 specification |
ep2AuthResult |
xsd:unsignedShort |
Authorization result according to EP2 specification |
ep2AuthCode |
xsd:string |
Authorization code according to EP2 specification |
ep2TrmId |
xsd:string |
Terminal Identifier according to EP2 specification |
ep2TrxSeqCnt |
xsd:unsignedInt |
Transaction sequence number according to EP2 specification |
trxResult |
xsd:unsignedByte |
Transaction result returned from VCS serve 0 – transaction authorised 1 – transaction declined |
amountAuth |
xsd:unsignedLong |
The authorised amount. Note that this might differ from the original amount in the request. |
amountAuthCurr |
CurrencyType |
The currency of the authorised amount. Three-digit currency code, according to ISO 4217 |
amountTip |
xsd:unsignedLong |
|
transactionRefNumber |
xsd:string |
Reference number for the transaction. Used as a reference for follow-up transactions like Reservation Adjustment and Purchase Reservation. |
cardNumber |
xsd:string |
The masked primary account number (masked PAN). |
cardSeqNumber |
xsd:unsignedShort |
Identifies and differentiates cards with the same PAN. Only available for EMV ICC or EMV contactless transactions. |
cardExpDate |
xsd:string |
The date after which the application expires. Format: yyMMdd |
cardAppLabel |
xsd:string |
The name of the used application. |
cardAppId |
xsd:string |
The identifier of the used application (AID). |
transactionTime |
xsd:string |
The time stamp of this transaction. Format: yyyyMMddHHmmss, e.g. ‘20150319160258’ means Mar-19-2015, 4:02.58 p.m. |
acquirerId |
xsd:string |
The unique identifier of the acquirer. |
dccTrxAmount |
xsd:unsignedLong |
The amount of DCC transaction (authorised amount converted by DCC service). Only set if DCC was successfully authorised. |
dccTrxAmountCurr |
CurrencyType |
The currency of the DCC transaction amount. Three-digit currency code, according to ISO 4217.Only set if DCC was successfully authorised. |
cvm |
xsd:unsignedShort |
The cardholder verification method used: 0 – unknown cardholder verification 1 – no cardholder verification 2 – signature 3 – online PIN 4 – offline encrypted PIN 5 – offline plaintext PIN 6 – offline encrypted PIN + signature 7 – offline plaintext PIN + signature 8 – online PIN + signature |
amountRemaining |
xsd:unsignedLong |
The remaining amount which was not authorised. Value = original amount in request - authorised amount. Exists if the transaction was partially approved. |
partialApprovalFlag |
PartialApprovalFlagType |
Indicates if partial approval was done or not. |
accardaClubCode |
xsd:string |
Code sent by the acquirer Accarda in the authorization response |
accardaPan |
xsd:base64Binary |
Primary account number (encrypted) sent in the authorization response by the acquirer Accarda in case of a token based transaction. |
accardaExpDate |
xsd:string |
Card expiration date sent in the authorization response by the acquirer Accarda in case of a token based transaction. |
brCode |
xsd:unsignedByte |
BRCode (Branchen-Code) read from card or (if different) the code sent by acquirer Accarda in authorization response |
trxSyncNumber |
xsd:unsignedInt |
The transaction synchronisation number contained in the request. |
panToken |
xsd:base64Binary |
The used PAN token. Only when requested per generatePanToken flag in the FinancialTrxRequest. |
trxCustomText |
xsd:string |
Custom text to be displayed on the screen when starting a transaction via this API. NOTE: In the StateWaitForCard screen only the custom text will be shown if there is a custom text available. Amount or “Present Card” will not be shown. |
cardIssuingCountry |
xsd:string |
This is used to show the Card’s issuing country (ex: “DE”, “CH”, “FR” etc). |
merchantReference Important: This field deprecates additionalMerchantData |
ans |
The PoS may add its own transaction specific data in this field (like an attendant reference number or its own transaction reference number). |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:financialTrxResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<ep2AuthResponseCode>00</ep2AuthResponseCode>
<ep2AuthResult>0</ep2AuthResult>
<ep2AuthCode>741392</ep2AuthCode>
<ep2TrmId>47110815</ep2TrmId>
<ep2TrxSeqCnt>281</ep2TrxSeqCnt>
<trxResult>0</trxResult>
<amountAuth>600</amountAuth>
<amountAuthCurr>756</amountAuthCurr>
<amountTip>100</amountTip>
<transactionRefNumber>654321</transactionRefNumber>
<cardNumber>XXXXXXXXXXXX0267</cardNumber>
<cardExpDate>151231</cardExpDate>
<cardAppLabel>Visa</cardAppLabel>
<cardAppId>A0000001570030</cardAppId>
<transactionTime>20150319160258</transactionTime>
<acquirerId>00000000001</acquirerId>
<dccTrxAmount>552</dccTrxAmount>
<dccTrxAmountCurr>978</dccTrxAmountCurr>
<cvm>2</cvm>
<trxSyncNumber>41</trxSyncNumber>
<merchantReference>EXAMPLE-12345-12</merchantReference>
<amountRemaining>200</amountRemaining><!-- in case of partial approval -->
<partialApprovalFlag>1</partialApprovalFlag>
</vcs-pos:financialTrxResponse>
6.1.1 trxInfo bitmask
The bitmask has a specified length of three bytes. The first two bytes are RFU and should contain only 0. The bits of the third byte are specified as follows.
Bit |
Associated Notification |
0 |
CardEntryNotification |
1 |
CardRemovalNotificatio |
2 |
TransactionStartNotification |
3 |
TransactionEndNotification |
4 |
TransactionAbortNotification |
5 |
RFU |
6 |
RFU |
7 |
RFU |
Example:
To receive the CardEntryNotification
and the CardRemovalNotification
but
no other notifications the trxInfo
field has to contain the bitmask
00000000 00000000 00000011
encoded in Base64 which results in AAAD
.
<trxInfo>AAAD</trxInfo>
6.2 Activation Message
Activation Message - the message sent by the PoS system to activate the terminal. Once activated the terminal is ready to process transactions. The terminal resets all activation related totals and counters.
The Point of Sale Management System (PMS) is informed that the terminal has been activated.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
language |
LanguageType |
Language code, according to ISO 639-1 |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:activationRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
<language>en</language>
<receiptFormat>1</receiptFormat>
</vcs-pos:activationRequest>
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:activationResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
6.3 SiConfig Message
SiConfig Message – the message sent from POS System to terminal – request to trigger configuration process of the Device.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:siConfigRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
</vcs-pos:siConfigRequest>
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:siConfigResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
6.4 Deactivation Message
Deactivation Message - the message sent by the PoS system to deactivate the terminal. Once deactivated the terminal no longer allows transactions to be processed. The PoS Management System is informed that the terminal has been deactivated.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:deactivationRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
<receiptFormat>2</receiptFormat>
</vcs-pos:deactivationRequest>
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:deactivationResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
6.5 BEFinalBalance Message
BeFinalBalance Message – the information on the end-of-day closing at the terminal by the PoS system. It informs the merchant about totals per product and currency since the last end-of-day closing. The PMS shall be informed about the closing.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
trxSyncNumber |
xsd:unsignedInt |
Number maintained by the PoS and changed after each successful transaction to recognize an out-of-sync situation (see chapter 10). |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:beFinalBalanceRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
<trxSyncNumber>2001</trxSyncNumber>
</vcs-pos:beFinalBalanceRequest>
Response:
Keyword |
Type |
Description |
trxSyncNumber |
xsd:unsignedInt |
The transaction synchronization number contained in the request. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:beFinalBalanceResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<trxSyncNumber>2001</trxSyncNumber>
</vcs-pos:beFinalBalanceResponse>
6.6 SIInit Message
SiInit Message – the initialization of the device in a payment acceptance network. It includes registration as an acquirer and receiving parameters required by the terminal.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:siInitRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
</vcs-pos:siInitRequest>
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:siInitResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
6.7 Ping Message
Ping Message – used for connection testing. Basic use of this message is limited to checking whether the connection is alive. Scope of use may be wider, i.e., keep-alive message or for evaluation of the response time.
Request:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:pingRequest xmlns:vcs-pos="http://www.vibbek.com/pos" />
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:pingResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
6.8 Reversal Message
Reversal Message – the message is sent by PoS system to cancel the previous transaction.
Request:
Keyword |
Type |
Description |
---|---|---|
posId |
xsd:string |
PoS identifier |
origTrxSeqCnt |
xsd:unsignedInt |
The transaction sequence counter of the transaction to be reversed. In case of multiple reversal of this field is mandatory. Multiple reversal must be configured for the terminal. |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
tillMode |
xsd:string |
Optional field to give more information about where the reversalRequest started. (needed to distinguish between till client types) SDKApp - Till SDK related 3rd party apps VTIApp - local IP related 3rd party apps POSApp - local / remote IP related POS client apps WebApp - Portal |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:reversalRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
<receiptFormat>1</receiptFormat>
<tillMode>VTIApp</tillMode>
</vcs-pos:reversalRequest>
Response:
Keyword |
Type |
Description |
ep2TrmId |
xsd:string |
Terminal identifier according to EP2 specification |
ep2TrxSeqCnt |
xsd:unsignedInt |
Transaction sequence number according to EP2 specification |
ep2TrxSeqCntOrigTrx |
xsd:unsignedInt |
Transaction sequence number which refers to previous transaction according to EP2 specification |
ep2TrxTypeExtOrigTrx |
xsd:unsignedByte |
Transaction type which refers to previous transaction according to EP2 specification |
amountRev |
xsd:unsignedLong |
The reversed amount. |
amountRevCurr |
CurrencyType |
The currency of the reversed amount. Three-digit currency code, according to ISO 4217 |
cardNumber |
xsd:string |
The masked primary account number (masked PAN). |
cardSeqNumber |
xsd:unsignedShort |
Identifies and differentiates cards with the same PAN. Only available for EMV ICC or EMV contactless transactions. |
cardExpDate |
xsd:string |
The date after which the application expires. Format: yyMMdd |
cardAppLabel |
xsd:string |
The name of the used application. |
cardAppId |
xsd:string |
The identifier of the used application (AID). |
transactionTime |
xsd:string |
The time stamp of this transaction. Format: yyyyMMddHHmmss, e.g. ‘20150319160258’ means Mar-19-2015, 4:02.58 p.m. |
acquirerId |
xsd:string |
The unique identifier of the acquirer. |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:reversalResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<ep2TrmId>TERM1234</ep2TrmId>
<ep2TrxSeqCnt>99985449</ep2TrxSeqCnt>
<ep2TrxSeqCntOrigTrx>99985448</ep2TrxSeqCntOrigTrx>
<ep2TrxTypeExtOrigTrx>0</ep2TrxTypeExtOrigTrx>
<amountRev>600</amountRev>
<amountRevCurr>756</amountRevCurr>
<cardNumber>XXXXXXXXXXXX0267</cardNumber>
<cardSeqNumber>1</cardSeqNumber>
<cardExpDate>151231</cardExpDate>
<cardAppLabel>Visa</cardAppLabel>
<cardAppId>A0000001570030</cardAppId>
<transactionTime>20150319160258</transactionTime>
<acquirerId>00000000001</acquirerId>
</vcs-pos:reversalResponse>
6.9 CancelReservation Message
CancelReservation Message – the message sent from the PoS system to cancel a previous reservation.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
acquirerId |
xsd:string |
Acquirer identifier of the reservation to cancel. |
transactionRefNumber |
xsd:string |
Reference number of the reservation to cancel. |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:cancelReservationRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
<acquirerId>00000000001</acquirerId>
<transactionRefNumber>654321</transactionRefNumber>
</vcs-pos:cancelReservationRequest>
Response:
Keyword |
Type |
Description |
acquirerId |
xsd:string |
Acquirer identifier of the cancelled reservation. |
transactionRefNumber |
xsd:string |
Reference number of the cancelled reservation. |
ep2TrxSeqCnt |
xsd:unsignedInt |
Transaction sequence number according to EP2 specification |
amountAuthCurr |
CurrencyType |
The currency of the cancelled reservation amount sent from the host. Three-digit currency code, according to ISO 4217. |
ep2AuthResult |
xsd:unsignedShort |
Authorization result sent from host according to EP2 specification. |
ep2TrmId |
xsd:string |
Terminal identifier according to EP2 specification. |
result |
CancelReservation ResultType |
Cancel reservation result returned from VCS server 0 – cancellation of reservation successful 1 – cancellation of reservation declined |
transactionTime |
xsd:string |
The time stamp of this transaction. Format: yyyyMMddHHmmss, e.g. ‘20150319160258’ means Mar-19-2015, 4:02.58 p.m. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:cancelReservationResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<acquirerId>00000000001</acquirerId>
<transactionRefNumber>654321</transactionRefNumber>
<ep2TrxSeqCnt>99985449</ep2TrxSeqCnt>
<amountAuth>500</amountAuth>
<amountAuthCurr>756</amountAuthCurr>
<ep2AuthResult>0</ep2AuthResult>
<ep2TrmId>TERM1234</ep2TrmId>
<result>0</result>
<transactionTime>20150319160258</transactionTime>
</vcs-pos:cancelReservationResponse>
6.10 MISubmission Message
MiSubmission Message – Request to perform data submission from device to acquirer. Transaction data and information such as off-line advice are sent to the acquirer for further processing.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:miSubmissionRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
</vcs-pos:miSubmissionRequest>
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:miSubmissionResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
6.11 BETransmission Message
BETransmission Message - the transmission of transaction data from the terminal to the Point of Sale Management System.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:beTransmissionRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
</vcs-pos:beTransmissionRequest>
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:beTransmissionResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
6.12 ReprintReceipt Message
The Reprint Receipt Message - reprints the last receipt of a requested type that is available. The receipt itself is sent in a PrinterNotification message.
Depending on whether the reprint error receipts feature (TRX receipt type only) is enabled, the receipts of the last unsuccessful transactions will be printed as well as the receipts of a successful last transaction.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
type |
ReceiptType |
Optional. If it is not set, the latest financial transaction receipt is requested. |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:reprintReceiptRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
<type>TRX</type>
</vcs-pos:reprintReceiptRequest>
Response:
Keyword |
Type |
Description |
lastTrx |
FinancialTrxResponse |
The response data of the last financial transaction (if the original request was answered by an error notification only as subset consisting of terminal ID, trx time and declined flag); only in case of type latest financial transaction receipt is requested |
lastRev |
ReversalResponse |
The reversal response data if last financial transaction was reversed; only in case of type latest financial transaction receipt is requested |
lastCancelRes |
CancelReservationResponse |
The response data of the last transaction, if last action was a cancellation of a reservation |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:reprintReceiptResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<lastTrx>
<ep2AuthResponseCode>00</ep2AuthResponseCode>
<ep2AuthResult>0</ep2AuthResult>
<ep2AuthCode>741392</ep2AuthCode>
<ep2TrmId>47110815</ep2TrmId>
<ep2TrxSeqCnt>281</ep2TrxSeqCnt>
<trxResult>0</trxResult>
<amountAuth>600</amountAuth>
<amountAuthCurr>756</amountAuthCurr>
<amountTip>100</amountTip>
<transactionRefNumber>654321</transactionRefNumber>
<cardNumber>XXXXXXXXXXXX0267</cardNumber>
<cardExpDate>151231</cardExpDate>
<cardAppLabel>Visa</cardAppLabel>
<cardAppId>A0000001570030</cardAppId>
<transactionTime>20150319160258</transactionTime>
<acquirerId>00000000001</acquirerId>
<dccTrxAmount>552</dccTrxAmount>
<dccTrxAmountCurr>978</dccTrxAmountCurr>
<cvm>2</cvm>
<trxSyncNumber>41</trxSyncNumber>
<merchantReference>Merchants Custom Ref</merchantReference>
<amountRemaining>200</amountRemaining><!-- in case of partial approval -->
<partialApprovalFlag>1</partialApprovalFlag>
</lastTrx>
</vcs-pos:reprintReceiptResponse>
Or
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:reprintReceiptResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<lastRev>
<ep2TrmId>TERM1234</ep2TrmId>
<ep2TrxSeqCnt>99985449</ep2TrxSeqCnt>
<ep2TrxSeqCntOrigTrx>99985448</ep2TrxSeqCntOrigTrx>
<ep2TrxTypeExtOrigTrx>0</ep2TrxTypeExtOrigTrx>
<amountRev>600</amountRev>
<amountRevCurr>756</amountRevCurr>
<cardNumber>XXXXXXXXXXXX0267</cardNumber>
<cardSeqNumber>1</cardSeqNumber>
<cardExpDate>151231</cardExpDate>
<cardAppLabel>Visa</cardAppLabel>
<cardAppId>A0000001570030</cardAppId>
<transactionTime>20150319160258</transactionTime>
<acquirerId>00000000001</acquirerId>
</lastRev>
</vcs-pos:reprintReceiptResponse>
Or
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:reprintReceiptResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<lastCancelRes>
<acquirerId>00000000001</acquirerId>
<transactionRefNumber>654321</transactionRefNumber>
<ep2TrxSeqCnt>99985449</ep2TrxSeqCnt>
<amountAuth>500</amountAuth>
<amountAuthCurr>756</amountAuthCurr>
<ep2AuthResult>0</ep2AuthResult>
<ep2TrmId>TERM1234</ep2TrmId>
<result>0</result>
<transactionTime>20150319160258</transactionTime>
</lastCancelRes>
</vcs-pos:reprintReceiptResponse>
6.13 ConfigData Message
The ConfigData Message – requests configuration data of the terminal which the PoS is interested in.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:configDataRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
</vcs-pos:configDataRequest>
Response:
Keyword |
Type |
Description |
acquirerDataList |
AcquirerDataList |
List of all acquirers configured for this terminal containing configured AIDs and brands. |
ep2Tcd |
Ep2TerminalConfigData |
Configured values of ep2 specific terminal configuration data. |
ep2Version |
xsd:string |
The configured ep2 version information. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:configDataResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<acquirerDataList>
<acquirerData>
<acquirerId>00000000001</acquirerId>
<terminalApplicationConfigDataList>
<terminalApplicationConfigData>
<aid>QTAwMDAwMDAwMDQzMDYw</aid>
<brand>Maestro</brand>
</terminalApplicationConfigData>
<terminalApplicationConfigData>
<aid>QTAwMDAwMDAwMDMyMDIw</aid>
<brand>Visa</brand>
</terminalApplicationConfigData>
</terminalApplicationConfigDataList>
</acquirerData>
</acquirerDataList>
<ep2Tcd>
<commAddrGateWay>
<internetPortNo>8080</internetPortNo>
<internetAddr>127.0.0.1</internetAddr>
</commAddrGateWay>
<trmId>12345678</trmId>
</ep2Tcd>
<ep2Version>0620</ep2Version>
</vcs-pos:configDataResponse>
6.14 ErrorNotification
The ErrorNotification is received when an error has occurred and a response which fits to the request cannot be sent.
Notification:
Keyword |
Type |
Description |
---|---|---|
cardId |
xsd:string |
An optional field containing an identifier of the card, if available. This value is returned to allow further processing by the till. |
errorCode |
xsd:string |
Optional field that can contain one of the defined error codes in 6.14.1 ErrorCodes. |
errorText |
xsd:string |
Textual description of the error above |
merchantReference |
ans |
The value which was provided by
the PoS in the |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:errorNotification xmlns:vcs-pos="http://www.vibbek.com/pos">
<merchantReference>EXAMPLE-12345-12</merchantReference>
</vcs-pos:errorNotification>
6.14.1 ErrorCodes
Code |
Description |
Example |
VCS.ERR.0005 |
Request not valid |
|
VCS.ERR.0031 |
No original transaction found. |
|
VCS.ERR.0032 |
Original transaction is not an authorization purchase. |
|
VCS.ERR.0033 |
Original transaction was not successful. |
|
VCS.ERR.0034 |
Original transaction was reserved. |
|
VCS.ERR.0035 |
No receipts for original transaction. |
|
VCS.ERR.0036 |
Original transaction has already been committed. |
|
VCS.ERR.0038 |
Amount to commit is higher than the authorized amount of original |
|
TRM.PR.0001 |
Failed to reference original transaction |
|
TRM.PT.0001 |
The card is removed from the terminal prior to completion of the transaction. |
Start a transaction, insert card in the chip reader and immediately remove it. |
TRM.PT.0002 |
The cardholder (or the attendant) presses the Stop key on the terminal during the transaction. |
Start a transaction, press stop at any point when the user interaction is expected (instead of inserting the card, typing in the pin code, etc.) |
TRM.PT.0003 |
“System Error” A technical problem occurred on the terminal, outside the exceptions specified. (Internal error in the ICC reader transaction) |
Internal error occurred during chip reader transaction |
TRM.PT.0201 |
Card not detected. The card was not detected within <Timeout Card Insertion> seconds. |
Start a transaction, wait for the timeout without presenting a card. |
TRM.PT.0300 |
Card not inserted |
|
TRM.PT.0405 |
Failed to Contact Card (1st attempt) The inserted card can not be contacted or read correctly by the ICR (1st attempt) |
Insert card wrong way. (e.g. chip backwards) |
TRM.PT.0406 |
Failed to Contact Card (2nd attempt) The inserted card can not be contacted (Used for the combined reader). |
Incorrectly insert card in the magstripe (2nd aatempt) |
TRM.PT.0609 |
Multiple reversal limit reached |
|
TRM.PT.0500 |
No Application Found The card does not contain an application supported by the terminal. |
use a card, which is not supported by the acquirer |
TRM.PT.0501 |
Card blocked or SELECT command not supported |
Use a blocked card |
TRM.PT.0700 |
The transaction cannot be executed with the selected application. |
Use the card with the application that doesn’t support the particular transaction |
TRM.PT.0701 |
Read Error. Read error happens (e.g. due to worn contacts of the chip, or any other unexpected error), but the card is still there. |
Use a card that has faulty contact chips (and leave it in the reader) |
TRM.PT.1100 |
Read Error. Transaction is denied after chip reader transaction start (Same as TRM.PT.0701, but at later stage of the transction) |
|
TRM.PT.0904 |
Signature not supported in case of unattended terminals (class UAT) the kernel requests “obtain signature” as cardholder verification method |
Signature verification is set up for an unattended terminal. |
TRM.PT.0905 |
Online PIN not supported in case of terminals of class UAT-NON-PED the kernel requests “Online PIN” as cardholder verification method |
PIN verification is set up for a terminal without a pin pad. |
TRM.ID.0007 |
Storing TR31 block of wrapped key in PED failed |
This error can only happen for EP2 version EP 7.3 or later, during SI-Init, when storing of the Key Pan Receipt Trm fails. Usually it happens when the device doesn’t support the TR31 function due to an outdated OS. |
6.15 Confirmation Message
Confirmation Message – The device uses this request to interact with an attendant if necessary.
Request:
Keyword |
Type |
Description |
display |
Display |
Contains lines to display |
timeout |
xsd:integer |
Time in seconds to confirm |
timeoutReminder |
xsd:integer |
If timeoutReminder is > 0 then after timeout seconds the PoS reminds the request to the attendant with a sound signal. If timeoutReminder is > 0 then the PoS waits (timeout + timeoutReminder) seconds for an input from the attendant. If timeoutReminder is 0 then the PoS does not remind the request with a sound signal and the PoS waits timeout seconds for an input from the attendant. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:confirmationRequest xmlns:vcs-device="http://www.vibbek.com/device" displayType="CARDHOLDER">
<display>
<line>Trx Amount</line>
<line>CHF 8.00 OK?</line>
</display>
<timeout>30</timeout>
<timeoutReminder>30</timeoutReminder>
</vcs-device:confirmationRequest>
Response:
Keyword |
Type |
Description |
result |
xsd:unsignedByte |
Confirmation result: 0 – negative 1 - positive |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:confirmationResponse xmlns:vcs-device="http://www.vibbek.com/device">
<result>1</result>
</vcs-device:confirmationResponse>
Timeout Notification
If the PoS waited (timeout + timeoutReminder) seconds and did not receive an input from the attendant then the PoS sends a Timeout Notification.
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:timeoutNotification xmlns:vcs-device="http://www.vibbek.com/device"/>
6.16 DisplayNotification Message
DisplayNotification – the message sent from terminal to PoS system in order to display required information
Request:
Keyword |
Type |
Description |
display |
Display |
Contains lines to display |
minDisplayTime |
xsd:integer |
Minimal time to display message in seconds (tag is optional) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:displayNotification xmlns:vcs-device="http://www.vibbek.com/device" displayType="CARDHOLDER">
<display>
<line>CHF 99.99</line>
<line>Available amount</line>
</display>
<minDisplayTime>4</minDisplayTime>
</vcs-device:displayNotification>
6.17 PrinterNotification Message
PrinterNotification – message to send a printout from terminal to PoS system (i.e. the transaction receipt; a receipt of the last transaction).
For details regarding the format of the receipts, please refer to the [ReceiptSpec].
Request:
Keyword |
Type |
Description |
merchantReceipt |
xsd:string |
Preformatted receipt for the merchant. UTF-8. The end of a line is marked by LF (0x0A). |
cardholderReceipt |
xsd:string |
Preformatted receipt for cardholder. UTF-8. The end of a line is marked by LF (0x0A). |
admin |
xsd:boolean |
Attribute only set on merchant receipt elements. Indicates if the receipt is an administrative receipt and not a financial transaction receipt. |
printCommands |
xsd:boolean |
Attribute. Optional. Indicates whether the receipt contains additional print commands. See [ReceiptSpec] for details. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:printerNotification xmlns:vcs-device="http://www.vibbek.com/device">
<merchantReceipt admin="false">
Purchase
MasterCard
541333XXXXXXXXXX
15.05.2006 10:44:34
Trm-Id: TERM1234
Act-Id: 49
AID: A0000000041010
Trx. Seq-Cnt: 99985389
8BE3C3842018142128EEE1EA
A74C22049542D649538E9815
EFT CHF : 301.00
Tip CHF : 0.00
Total-EFT CHF : 301.00
TSI: E800
</merchantReceipt>
</vcs-device:printerNotification>
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:printerNotification xmlns:vcs-device="http://www.vibbek.com/device">
<cardholderReceipt>
***Cardholder Receipt***
Purchase
MasterCard
541333XXXXXXXXXX
15.05.2006 10:44:34
Trm-Id: TERM1234
Trx. Seq-Cnt: 99985389
EFT CHF : 301.00
Tip CHF : 0.00
Total-EFT CHF : 301.00
</cardholderReceipt>
</vcs-device:printerNotification>
6.18 AbortCardEntryNotification Message
The message is sent from PoS to the terminal in order to request an
abort of the card entry of the current financial transaction process. If
the card entry has already happened, this notification has no effect.
The Notification can contain an abortCode
to trigger a different
handling within the PIN pad.
There is no specific response to this message. The transaction processing either continues if the card has already been read or aborts and returns an ErrorNotification message.
Notification:
Keyword |
Type |
Description |
---|---|---|
abortCode |
xsd:unsignedShort |
The abort code specifies the reason for the abort. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:abortCardEntryNotification xmlns:vcs-device="http://www.vibbek.com/device">
<abortCode>01</abortCode>
</vcs-device:abortCardEntryNotification>
6.18.1 Supported AbortCodes
Code |
Description |
01 |
Standard AbortCode with regular handling. |
02 |
Abort because of other payment methods e.g. cash. |
6.19 WaitForCardPresent Message
Message sent to the device to determine if a card is present and wait for it if not. This message can be used if a card must be present before a financial transaction is started.
This response will be sent immediately if a card is already present. Otherwise, the device will wait for a card contact or until the given time expires. The response contains the ‘card present’ status.
Request:
Keyword |
Type |
Description |
timeout |
xsd:integer |
Time to wait in seconds |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:waitForCardPresentRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<timeout>60</timeout>
</vcs-pos:waitForCardPresentRequest>
Response:
Keyword |
Type |
Description |
cardPresent |
xsd:boolean |
Flag indicating if a card is present |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:waitForCardPresentResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<cardPresent>true</cardPresent>
</vcs-pos:waitForCardPresentResponse>
6.20 WaitForCardRemoved Message
Message sent to the device to determine if a card is removed or no longer present. This message is the counterpart to the WaitForCardPresent message.
This response will be sent immediately if the card is no longer present. Otherwise, the device will wait for a card removal or until the given time expires. The response contains the ‘card present’ status.
Request:
Keyword |
Type |
Description |
timeout |
xsd:integer |
Time to wait in seconds |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:waitForCardRemovedRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<timeout>60</timeout>
</vcs-pos:waitForCardRemovedRequest>
Response:
Keyword |
Type |
Description |
cardPresent |
xsd:boolean |
Flag indicating if a card is present |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:waitForCardRemovedResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<cardPresent>false</cardPresent>
</vcs-pos:waitForCardRemovedResponse>
6.21 IntermediateEodReceipt Message
The IntermediateEodReceipt Message – requests an intermediate end of day receipt.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:interEodReceiptRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
</vcs-pos:interEodReceiptRequest>
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:interEodReceiptResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
6.22 CheckCouponId Message
The CheckCouponId Message – requests a check of a coupon id. The customer is requested to enter a coupon id. The entered id is compared to the id given in the request and the result is returned.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
couponId |
xsd:integer |
Expected coupon id |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:checkCouponIdRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
<couponId>123456</couponId>
</vcs-pos:checkCouponIdRequest>
Response:
Keyword |
Type |
Description |
result |
CheckCouponIdResultType |
Result of coupon id check 0 – entered coupon id is correct 1 – entered coupon id is not correct |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:checkCouponIdResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<result>0</result>
</vcs-pos:checkCouponIdResponse>
6.23 PinpadInformation Message
The PinpadInformation message requests hardware and basic configuration data from the PIN pad.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:pinpadInformationRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
</vcs-pos:pinpadInformationRequest>
Response:
Keyword |
Type |
Description |
terminalId |
xsd:string |
The ID of the terminal. |
vpjSoftwareVersion |
xsd:string |
The version number of the VPJ Software. |
serialNumber |
xsd:string |
The serial number of the PIN pad. |
hardwareType |
xsd:string |
The type of device. |
simCardNumber |
xsd:string |
The card number of the SIM card if the device communicates using GPRS or GSM. |
logLevel |
xsd:string |
The log level of the VPJ software. |
vcsIpAddr |
xsd:string |
The TCP/IP address of the VCS server. |
vcsIpPort |
xsd:string |
The port number of the VCS server. |
vcsConnectTimeout |
xsd:string |
The time in seconds to wait for an established connection to the VCS before aborting the attempt. |
vcsInactiveTimeout |
xsd:string |
The time in seconds to wait for the next message from the VCS before aborting thecurrent process. |
pinpadLocalTime |
xsd:string |
The current time in seconds including time zone offset since the epoch (Unix time). |
pinpadCurrentTime |
xsd:string |
The current time in seconds since the epoch (Unix time). |
timeZone |
xsd:string |
The PIN pad time zone. Value like ‘Europe/Berlin’ |
nextContactTime |
xsd:string |
The time in seconds until the next automatic contact to the VCS is send. |
pinpadRunningTime |
xsd:string |
The time in seconds since the last reboot. |
freeRamMemory |
xsd:string |
The total amount of free RAM memory in bytes. |
freeFlashMemory |
xsd:string |
The total amount of free flash memory in bytes. |
offlineTrxNumber |
xsd:string |
The total number of approved transactions on the device (deferred mode only). |
offlineTrxAmount |
xsd:string |
The total amount of approved transactions on the device (deferred mode only) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:pinpadInformationResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<terminalId>12345678</terminalId>
<vpjSoftwareVersion>1.0.r1234</vpjSoftwareVersion>
<serialNumber>1234</serialNumber>
<hardwareType>Yomani</hardwareType>
<simCardNumber>1</simCardNumber>
<logLevel>DEBUG</logLevel>
<vcsIpAddr>192.168.0.1</vcsIpAddr>
<vcsIpPort>61613</vcsIpPort>
<vcsConnectTimeout>30</vcsConnectTimeout>
<vcsInactiveTimeout>60</vcsInactiveTimeout>
<pinpadLocalTime>1472724587</pinpadLocalTime>
<pinpadCurrentTime>1472724589</pinpadCurrentTime>
<timeZone>Europe/Berlin</timeZone>
<nextContactTime>60</nextContactTime>
<pinpadRunningTime>1234</pinpadRunningTime>
<freeRamMemory>3490696 B</freeRamMemory>
<freeFlashMemory>13490696 B</freeFlashMemory>
<offlineTrxNumber>1</offlineTrxNumber>
<offlineTrxAmount>1299</offlineTrxAmount>
</vcs-pos:pinpadInformationResponse>
6.24 GeneratePanToken Message
The GeneratePanToken message requests the used PAN token.
Request:
Keyword |
Type |
Description |
---|---|---|
posId |
xsd:string |
PoS identifier |
trxCustomText |
xsd:string |
See: FinancialTrx message – Request. |
trxResultCustomText |
xsd:string |
As „trxCustomText” but displayed in resulting screen, eg „identification successfull”. |
selectedLang |
xsd:string |
Language symbol used by POS, eg „en”. |
trxInfo |
xsd:base64Binary |
This field contains a bitmask to specify which 6.26 TransactionStatusNotification Messages should be sent by the terminal. This field should contain a series of 3 bytes in Base64 encoding. (see chapter 6.1.1 trxInfo bitmask) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:generatePanTokenRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
<trxInfo>AAAD</trxInfo>
</vcs-pos:generatePanTokenRequest>
Response:
Keyword |
Type |
Description |
panToken |
xsd:base64Binary |
The requested PAN token. |
cardId |
xsd:string |
An optional Card Identifier read from non-EMV cards. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:generatePanTokenResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<panToken>MTE0NDU1MjAwMTE0MzU2Ng==</panToken>
</vcs-pos:generatePanTokenResponse>
6.25 PrintCurrencyRateTicket Message
The PrintCurrencyRateTicket message is a function only available for terminals with configured SIX DCC services. It requests the current change rates for different currencies and prints them as receipt on the PIN pad.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:printCurrencyRateTicketRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
</vcs-pos:printCurrencyRateTicketRequest>
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:printCurrencyRateTicketResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
6.26 TransactionStatusNotification Messages
These messages are sent from the terminal to the PoS system. They inform the PoS about different status changes throughout the transaction. They will only be sent in case the trxInfo is set true in the financialTrxRequest.
6.26.1 CardEntryNotification
Keyword |
Type |
Description |
cardEntryMode |
xsd:unsignedInt |
Which kind of card was used. 0 – Magstripe 1 – Chip/Contact 2 - Contactless |
This notification is sent to the PoS system, after the card has been inserted into the PIN pad.
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:cardEntryNotification xmlns:vcs-device="http://www.vibbek.com/device">
<cardEntryMode>1</cardEntryMode>
</vcs-device:cardEntryNotification>
6.26.2 CardRemovalNotification
This notification is sent to the PoS system, after the card has been removed from the PIN pad.
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:cardRemovalNotification xmlns:vcs-device="http://www.vibbek.com/device"/>
6.26.3 TransactionStartNotification
This notification is sent to the PoS system, after the transaction has been started on the terminal.
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:trxStartNotification xmlns:vcs-device="http://www.vibbek.com/device"/>
6.26.4 TransactionEndNotification
This notification is sent to the PoS system, after the transaction has been completed on the terminal.
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:trxEndNotification xmlns:vcs-device="http://www.vibbek.com/device"/>
6.26.5 TransactionAbortNotification
This notification is sent to the PoS system, after the transaction has been aborted on the terminal without correct completion.
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:trxAbortNotification xmlns:vcs-device="http://www.vibbek.com/device"/>
6.27 Low Power Mode Messages
Message sent to the device to enter sleep state. This function is only available for terminals which offer a sleep mode. If the device is not ready to enter sleep mode or a transaction is in progress it will send an error notification.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:sleepRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
</vcs-pos:sleepRequest>
Response:
Keyword |
Type |
Description |
nextContactTime |
xsd:integer |
Number of seconds in which the next auto contact needs to be performed. Thus the device should be woken after this time has expired. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:sleepResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<nextContactTime>120</nextContactTime>
</vcs-pos:sleepResponse>
6.28 AdaptAmount Message
The AdaptAmount message is only for vending machines to adapt the amount of the last transaction or transaction referenced by a given ep2 transaction sequence number. If the last or referenced transaction was not online authorised, declined, reversed, the currencies do not match or the new amount is greater than the authorised amount of the last transaction the device will send an error notification
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
adaptedAmount |
xsd:unsignedLong |
The adapted amount for the last transaction |
currency |
CurrencyType |
The currency of the amount to adapt |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:adaptAmountRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
<posId>2001</posId>
<adaptedAmount>400</adaptedAmount>
<currency>756</currency>
</vcs-pos:adaptAmountRequest>
Response:
Keyword |
Type |
Description |
(no tags) |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:adaptAmountResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
7 TransactionSyncNumber
7.1 Purpose
The TransactionSyncNumber is an optional feature that can be implemented by ECR integrators to prevent unwanted double charging the cardholder. This sometimes might happen in case of communication errors between ECR and terminal, if the result of a transaction is unclear to the ECR. If using the ReprintReceipt function in cases of an unclear transaction result is not feasible, it is strongly recommended to use this feature. The terminal uses the TransactionSyncNumber to ensure that the last transaction response has been correctly received and processed by the ECR. The terminal expects the TransactionSyncNumber sent with a FinancialTransactionRequest to be incremented after each completed transaction. A transaction is considered “completed” after the processing of the FinancialTransactionResponse has been completed by the ECR. If this requirement is not met, i.e. the ECR sends the same TransactionSyncNumber in two consecutive transactions, the previous transaction will be reversed automatically.
7.2 TransactionSyncNumber Sequence Diagrams
7.2.1 Financial Transaction Request Flow
The PoS system includes the TrxSyncNumber in each FinancialTransactionRequest. After each completed financial transaction (i.e. after receiving the FinancialTransactionResponse message), the PoS system creates a new one for the next transaction (for example by incrementing the number). After each failed transaction (i.e. the ECR did not receive a response, or received an ErrorNotification), the PoS system uses the same number again for the next transaction.
7.2.2 Auto-Reversal Situation Flow
If the terminal receives a FinancialTransactionRequest with the same TrxSyncNumber as the last completed transaction (from terminal point of view), it assumes that the response to the previous transaction has not been received and processed by the ECR. The result is an out-of-sync situation and the terminal triggers an automatic reversal of the previous transaction. After that, the current transaction continues. Another option, rather than sending a new FinancialTransactionRequest, would be to use the ReprintReceipt (see 9.12) function. After the response to the first FinancialTransactionRequest is lost, the ReprintReceipt operation would allow the till to automatically re-synchronize with the terminal.
7.2.3 Final Balance Flow
The PoS system also includes the current TrxSyncNumber in the BEFinalBalanceRequest message. This allows the terminal to recognize the out-of-sync situation and process an automatic reversal before processing the final balance.
7.3 Additions to the Final Balance Receipt
If the ECR uses the TransactionSyncNumber, this might lead to (wanted!) automatic reversals of transactions. This actually prevents double charging the customer in case of a communication error. In order to have control over this feature, a TransactionSyncReport is added to the Final Balance Receipt. This report contains a listing of all consecutive transactions that were requested with the same TransactionSyncNumber. If any but the last of these transactions had been approved, it has been reversed automatically.
This section does also contain the information, which automatic reversal has failed. An automatic reversal may for example fail if the transaction was already transmitted to the acquirer by a forced transmission.
Example:
Transaction Sync Report
18.04.2017 22:15:00
Report period:
From:17.04.2017 22:15:00
To: 18.04.2017 22:15:00
Trm-Id: 12345678
TrxType Amount AuthRes
TrxSeqCnt TrxSyncNo
Date Time
Purch 12343.00 A.Rev
12345672 98765432
18.04.2017 02:00:00
Purch 12344.00 Appr
12345673 98765432
18.04.2017 03:00:00
Purch 12345.00 A.Rev
12345674 98765431
18.04.2017 04:00:00
Reserv 7.00 Appr
12345675 98765431
18.04.2017 05:00:00
Purch 9.00 A.Rev
12345677 98765434
18.04.2017 07:00:00
Purch 10.00 A.Rev
12345678 98765434
18.04.2017 08:00:00
Purch 11.00 Decl
12345679 98765434
18.04.2017 09:00:00
In this example, the transaction performed at 02:00:00 has been automatically reversed, because the transaction at 03:00:00 (assuming there was no transaction in between) used the same TransactionSyncNumber. In this example it is also shown that the TransactionSyncCounter always has to be varied, even if the following transaction is of a different type. Also, this behaviour is independent of the result of the second transaction. As shown in the last two reported transactions, a previously approved transaction is reversed, even if the following transaction is declined.
8 Special Features
8.1 Tax Free
The VCS supports creation of Tax Free voucher receipts.
8.1.1 TaxFreeVoucher Message
Requests a Tax Free voucher based on the data given in the request message. Depending on the country some data might not be required or additional data is needed. In doubt please contact Wallee AG support regarding your integration of Tax Free.
The Tax Free voucher is provided in the PrinterNotification message, see chapter 9.17. The voucher contains print commands as described in [ReceiptSpec].
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
operatorId |
xsd:string |
The unique operator ID assigned by the merchant |
transactionType |
xsd:string |
The transaction type of the invoice: 1 – sale 2 – refund |
transactionDate |
xsd:string |
The date the transaction was carried out Format: yyyyMMdd |
transactionTime |
xsd:string |
The time at which the transaction was processed |
invoiceNumber |
xsd:string |
The invoice number of the transaction |
barcodeData |
xsd:string |
The data printed in the barcode on the invoice |
totalGrossAmount |
xsd:string |
Total transaction amount including VAT in minor units |
totalNetAmount |
xsd:string |
Total transaction amount less VAT in minor units |
totalVatAmount |
xsd:string |
Total transaction VAT amount in minor units |
countryOfOriginIsoCode |
xsd:string |
The country where the customer originated from as ISO-3166-3 numeric. Optional. |
countryOfOriginName |
xsd:string |
The country where the customer originated from. Optional. |
passportNumber |
xsd:string |
The passport number of the customer. Optional |
invoiceLineItems |
InvoiceLineItems |
Collection of invoice line items |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:taxFreeVoucherRequest xmlns:vcs-pos="http://www.vibbek.com/pos" xmlns:vcs-device="http://www.vibbek.com/device">
<posId>1111</posId>
<barcodeData>225042011234560876543345</barcodeData>
<invoiceLineItems>
<lineItem>
<description>Invoice Item</description>
<grossAmount>108000</grossAmount>
<netAmount>100000</netAmount>
<quantity>1</quantity>
<vatAmount>8000</vatAmount>
<vatRate>800</vatRate>
</lineItem>
</invoiceLineItems>
<invoiceNumber>78145</invoiceNumber>
<operatorId>1</operatorId>
<totalGrossAmount>108000</totalGrossAmount>
<totalNetAmount>100000</totalNetAmount>
<totalVatAmount>8000</totalVatAmount>
<transactionDate>20161115</transactionDate>
<transactionTime>235959</transactionTime>
<transactionType>1</transactionType>
</vcs-pos:taxFreeVoucherRequest>
Response:
Keyword |
Type |
Description |
voucherNumber |
xsd:string |
The voucher number in case the voucher was successfully created |
hostErrorDesc |
xsd:string |
An error description that contains elements received from the host system. Not available if successfully processed. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:taxFreeVoucherResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
<voucherNumber>27562202-000334-0110000131</voucherNumber>
</vcs-pos:taxFreeVoucherResponse>
8.1.2 TaxFreeVoidVoucher Message
Requests a Tax Free void voucher. This will mark the voucher on the server as voided, and release the invoices contained in the voucher to be used in other vouchers. This is used mainly for automatic voiding of vouchers where the decision was made not to print the voucher after creating the voucher or an error occurs during printing of the voucher.
Request:
Keyword |
Type |
Description |
posId |
xsd:string |
PoS identifier |
operatorId |
xsd:string |
The unique operator ID assigned by the merchant |
voucherNumber |
xsd:string |
The voucher number of the voucher to be |
voucherBarcode |
xsd:string |
The voucher number of the voucher to be voided. |
receiptFormat |
xsd:unsignedInt |
Expected format of receipts, either pre-formatted plain text or HTML based template: 1 – Pre-formatted plain text 2 – HTML-based template Default is pre-formatted plain text. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:taxFreeVoidVoucherRequest xmlns:vcs-pos="http://www.vibbek.com/pos" xmlns:vcs-device="http://www.vibbek.com/device">
<posId>1111</posId>
<operatorId>1</operatorId>
<voucherBarcode>225042011234560876543216</voucherBarcode>
<voucherNumber>27562202-000334-0110000131</voucherNumber>
</vcs-pos:taxFreeVoidVoucherRequest>
Response:
Keyword |
Type |
Description |
hostErrorDesc |
xsd:string |
An error description that contains elements received from the host system. Not available if successfully processed. |
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:taxFreeVoidVoucherResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>
9 XML Schemas
9.1 Base Types
See XML schema definition file schema/base_types.xsd
.
9.2 PoS Messages
See XML schema definition file schema/pos_messages.xsd
.
9.3 Device Messages
See XML schema definition file schema/device_messages.xsd
.
10 Glossary
Keyword |
Description |
---|---|
Attendant |
The attendant is the merchant representative at the Point of Sale. The attendant operates either the electronic cash register or the attendant module. |
Acquirer |
The Acquirer processes electronic payment transactions. The following services are provided:
|
Cardholder |
The cardholder uses a payment card for paying goods or services. |
ECR/PoS/Till system |
Point of Sale can be an attendant entry module, an electronic cash register (ECR)/till system and may be attended or unattended. |
Terminal/Device/PIN pad |
The terminal is used to perform electronic payment transactions at the Point of Sale. The terminal reads cards, authorizes transactions and transmits transaction data to the Acquirer or the PMS. In order to process transactions, the terminal must be configured and initialized properly. |
LAN |
Local Area Network |
VTI |
Vibbek Till Interface. Deprecated name for the LTI - Local Till Interface. |
PAN |
Primary Account Number |
11 Changelog
Note that versions before 2.44 are only available on request. Please contact support if you need an older version of the specification.
- Version:
2.47
- Date:
2024-07-03
- Changes:
Added an optional
trxInfo
property togeneratePanTokenRequest
.Change type of
merchantReference
fromxsd::string
toans
as defined in EP2 v7.4 Data Dictionary , chapter 4.2.4 “Special Characters (ans)”. All characters defined inxsd::string
are still supported by the terminal but some acquirers will reject requests with characters which are not allowed in typeans
.
- Migration Notes:
-
- Version:
2.46
- Date:
2024-05-02
- Changes:
Reworded the overview section and some section titles. No functional changes to the API.
- Migration Notes:
-
- Version:
2.45
- Date:
2024-04-22
- Changes:
The type of the field
transactionRefNumber
was changed fromxsd:unsignedLong
toxsd:string
.Added missing fileds to the XML schema for PoS messages:
commitAuthorisationPurchaseRequest
,commitAuthorisationPurchaseResponse
,merchantReference
,tillMode
,pinPadCurrentTime
- Migration Notes:
No actions required because the
transactionRefNumber
was always returned as an alphanumeric string. This change fixes the documentation to align with the implementation.
- Version:
2.44
- Date:
2024-04-03
- Changes:
This is the first online version of the LTI documentation. Internal details like the protocol used to connect to the wallee cloud were removed.
- Migration Notes:
-