1 Wallee AG Local Till Interface (LTI)

Welcome to the Wallee AG Local Till Interface (LTI) documentation for version: 2.45, created on: 2024-05-07

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.

$cloud "Merchant Site" { interface "**LTI**" as lti component "Terminal\nPIN pad\nDevice" as terminal component "ECR\nTill\nPoint of Sale" as till note top of lti: scope of this document } component "Wallee Cloud" as vcs till .right.> lti : use lti - terminal terminal - vcs vcs - EP2 EP2 - [Acquirer]$

Note that there are different options available to integrate with a Wallee terminal. An integrator should:

Use the Local Till Interface (LTI), if the ECR/PoS/till application connects to the terminal via a local network. The most common use case is if the terminal and till are connected to the same LAN at the merchant’s site.
Use the Android Till Interface SDK, if the ECR/PoS/till application is installed directly on an Android based terminal.
Use the Cloud Till Interface, if the ECR/PoS/till application connects to the terminal via the Internet.

All integration options provide mechanisms for the same terminal features. Some of the features are as follows:

Cardholder and card interface
EMV functionality
Message authentication, security and data encryption to ensure a single crypt-zone for all EP2 interfaces and P2PE to Acquirer
Storage of terminal configuration for EMV processing
Storage of keys and secrets needed for EP2 message authentication security and encryption (e.g. EP2 component secret, EP2 public keys, CA public keys, Static Key PAN receipt)

3 Message Communication 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. 10 XML schemas are part of this documentation. They accurately describe all valid messages and the used types.

4 Message Communication list

In the tables below, common parts of a message are presented.

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

4.2 Common elements

Since there are two main types of messages body of each message contains following namespace definitions:

<vcs-pos:xxxx xmlns:vcs-pos=”http://www.vibbek.com/pos”>
    <!--message tags-->
</vcs-pos:xxxx>

for PoS messages, and

<vcs-device:xxxx xmlns:vcs-device=”https://www.vibbek.com/device”>
    <!--message tags-->
</vcs-device:xxxx>

for device messages.

Where xxxx is a message type according to 10.2 PoS Messages or 10.3 Device Messages.

For messages displayNotification or confirmationRequest there is an additional tag possible to define if action is related to sales attendant or cardholder, i.e.:

<vcs-device:displayNotification displayType="ATTENDANT"
xmlns:vcs-device="http://www.vibbek.com/device">

<vcs-device:displayNotification displayType="CARDHOLDER"
xmlns:vcs-device="http://www.vibbek.com/device">

<vcs-device:confirmationRequest displayType="ATTENDANT"
xmlns:vcs-device="http://www.vibbek.com/device">

<vcs-device:confirmationRequest displayType="CARDHOLDER"
xmlns:vcs-device="http://www.vibbek.com/device">

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.

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.

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.

Fig. 3 Transaction communication example

6 Data transmission

6.1 Protocol layer overview

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.

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

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

7 Messages description

This section describes both request and response messages that are used in the interface protocol.

7.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 8 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 Tran sactionStatusNotifications should be sent by the terminal. This field should contain a series of 3 bytes in Base64 encoding. (see chapter 9.1.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.
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:

Listing 1 Example Request financialTrxRequest

<?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>
   </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).
cardIssuingCountry	xsd:string	This is used to show the Card’s issuing country (ex: “DE”, “CH”, “FR” etc).
merchantReference Important: This field deprecates additionalMerchantData	xsd:string	The PoS may add its own transaction specific data in this field (like an attendant reference number or its own transaction reference number).

Example:

Listing 2 Example Response: financialTrxResponse

<?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>Merchants Custom Ref</merchantReference>
    <amountRemaining>200</amountRemaining><!-- in case of partial approval -->
    <partialApprovalFlag>1</partialApprovalFlag>
</vcs-pos:financialTrxResponse>

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

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

Listing 3 Example Request: activationRequest

<?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:

Listing 4 Example Response: activationResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:activationResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

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

Listing 5 Example Request: siConfigRequest

<?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:

Listing 6 Example Response: siConfigResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:siConfigResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

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

Listing 7 Example Request: deactivationRequest

<?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:

Listing 8 Example Response: deactivationResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:deactivationResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

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

Listing 9 Example Request: beFinalBalanceRequest

<?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:

Listing 10 Example Response: beFinalBalanceResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:beFinalBalanceResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
    <trxSyncNumber>2001</trxSyncNumber>
</vcs-pos:beFinalBalanceResponse>

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

Listing 11 Example Request: siInitRequest

<?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:

Listing 12 Example Response: siInitResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:siInitResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

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

Listing 13 Example Request: pingRequest

<?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:

Listing 14 Example Response: pingResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:pingResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

7.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
a dditionalMerchantData (deprecated) Please use `merchantReference`	xsd:unsignedInt	The PoS may add its own transaction specific data in this field (like an attendant reference number or its own transaction reference number).
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.
merchantReference	xsd:string	The PoS may add its own transaction specific data in this field (like an attendant reference number or its own transaction reference number).
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:

Listing 15 Example Request: reversalRequest

<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:reversalRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
    <posId>2001</posId>
    <merchantReference>No. 1234567890</merchantReference>
    <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:

Listing 16 Example Response: reversalResponse

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

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

Listing 17 Example Request: cancelReservationRequest

<?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:

Listing 18 Example Response: cancelReservationResponse

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

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

Listing 19 Example Request: miSubmissionRequest

<?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:

Listing 20 Example Response: miSubmissionResponse

<?xml version="1.0" encoding="UTF-8"?>
<vcs-pos:miSubmissionResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

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

Listing 21 Example Request: beTransmissionRequest

<?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:

Listing 22 Example Response: beTransmissionResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:beTransmissionResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

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

Listing 23 Example Request: reprintReceiptRequest

<?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:

Listing 24 Example Response: reprintReceiptResponse

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

Listing 25 Example Response: reprintReceiptResponse

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

Listing 26 Example Response: reprintReceiptResponse

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

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

Listing 27 Example Request: configDataRequest

<?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:

Listing 28 Example Response: configDataResponse

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

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

Example:

Listing 29 Example Notification: errorNotification

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:errorNotification xmlns:vcs-pos="http://www.vibbek.com/pos"/>

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

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

Listing 30 Example Request: confirmationRequest

<?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:

Listing 31 Example Response: confirmationResponse

<?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:

Listing 32 Example Notification: timeoutNotification

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:timeoutNotification xmlns:vcs-device="http://www.vibbek.com/device"/>

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

Listing 33 Example Notification: displayNotification

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

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

Listing 34 Example Notification: printerNotification

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

Listing 35 Example Notification: 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>

7.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	ab ortCodexsd:unsignedShort	The abort code specifies the reason for the abort.

Example:

Listing 36 Example Notification: abortCardEntryNotification

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:abortCardEntryNotification xmlns:vcs-device="http://www.vibbek.com/device">
    <abortCode>01</abortCode>
</vcs-device:abortCardEntryNotification>

7.18.1 Supported AbortCodes

Code	Description
01	Standard AbortCode with regular handling.
02	Abort because of other payment methods e.g. cash.

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

Listing 37 Example Request: waitForCardPresentRequest

<?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:

Listing 38 Example Response: waitForCardPresentResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:waitForCardPresentResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
    <cardPresent>true</cardPresent>
</vcs-pos:waitForCardPresentResponse>

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

Listing 39 Example Request: waitForCardRemovedRequest

<?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:

Listing 40 Example Response: waitForCardRemovedResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:waitForCardRemovedResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
    <cardPresent>false</cardPresent>
</vcs-pos:waitForCardRemovedResponse>

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

Listing 41 Example Request: interEodReceiptRequest

<?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:

Listing 42 Example Response: interEodReceiptResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:interEodReceiptResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

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

Listing 43 Example Request: checkCouponIdRequest

<?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:

Listing 44 Example Response: checkCouponIdResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:checkCouponIdResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
    <result>0</result>
</vcs-pos:checkCouponIdResponse>

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

Listing 45 Example Request: pinpadInformationRequest

<?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:

Listing 46 Example Response: pinpadInformationResponse

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

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

Example:

Listing 47 Example Request: generatePanTokenRequest

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:generatePanTokenRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
    <posId>2001</posId>
</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:

Listing 48 Example Response: generatePanTokenResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:generatePanTokenResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
    <panToken>MTE0NDU1MjAwMTE0MzU2Ng==</panToken>
</vcs-pos:generatePanTokenResponse>

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

Listing 49 Example Request: printCurrencyRateTicketRequest

<?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:

Listing 50 Example

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:printCurrencyRateTicketResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

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

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

Listing 51 Example Notification: cardEntryNotification

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:cardEntryNotification xmlns:vcs-device="http://www.vibbek.com/device">
    <cardEntryMode>1</cardEntryMode>
</vcs-device:cardEntryNotification>

7.26.2 CardRemovalNotification

This notification is sent to the PoS system, after the card has been removed from the PIN pad.

Example:

Listing 52 Example Notification: cardRemovalNotification

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:cardRemovalNotification xmlns:vcs-device="http://www.vibbek.com/device"/>

7.26.3 TransactionStartNotification

This notification is sent to the PoS system, after the transaction has been started on the terminal.

Example:

Listing 53 Example Notification: trxStartNotification

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:trxStartNotification xmlns:vcs-device="http://www.vibbek.com/device"/>

7.26.4 TransactionEndNotification

This notification is sent to the PoS system, after the transaction has been completed on the terminal.

Example:

Listing 54 Example Notification: trxEndNotification

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:trxEndNotification xmlns:vcs-device="http://www.vibbek.com/device"/>

7.26.5 TransactionAbortNotification

This notification is sent to the PoS system, after the transaction has been aborted on the terminal without correct completion.

Example:

Listing 55 Example Notification: trxAbortNotification

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-device:trxAbortNotification xmlns:vcs-device="http://www.vibbek.com/device"/>

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

Listing 56 Example Request: sleepRequest

<?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:

Listing 57 Example Response: sleepResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:sleepResponse xmlns:vcs-pos="http://www.vibbek.com/pos">
    <nextContactTime>120</nextContactTime>
</vcs-pos:sleepResponse>

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

Listing 58 Example Request: adaptAmountRequest

<?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:

Listing 59 Example Response: adaptAmountResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:adaptAmountResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

7.29 CommitAuthorisationPurchase Message

The CommitAuthorisationPurchase message updates the effective transaction amount of a financial transaction with transaction type ‘AuthorisationPurchase’. The ECR shall send this message even if the effective amount is not changed. The amount “0” is valid too.

When all security session slots are full and a new Authorisation Purchase transaction is requested by the ECR, the VPJ shall free the oldest slot by automatically committing its Authorisation Purchase with amount 0.

Request:

Keyword	Type	Description
posId	xsd:string	PoS identifier
amount	xsd:unsignedLong	The effective amount for the ‘authorisation purchase’ transaction
currency	CurrencyType	Same currency as used in ‘authorisation purchase’ transaction
ep2TrxSeqCntOrigTrx	xsd:unsignedInt	The ep2 transaction sequence counter of referenced ‘authorisation purchase’ transaction to update the amount for.
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:

Listing 60 Example Request: commitAuthorisationPurchaseRequest

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:commitAuthorisationPurchaseRequest xmlns:vcs-pos="http://www.vibbek.com/pos">
    <posId>2001</posId>
    <amount>350</amount>
    <currency>756</currency>
    <ep2TrxSeqCntOrigTrx>99985448</ep2TrxSeqCntOrigTrx>
</vcs-pos:commitAuthorisationPurchaseRequest>

Response:

Keyword	Type	Description
(no tags)

Example:

Listing 61 Example Response: commitAuthorisationPurchaseResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:commitAuthorisationPurchaseResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

8 TransactionSyncNumber

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

8.2 TransactionSyncNumber Sequence Diagrams

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

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

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

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

9 Special features

9.1 Tax Free

The VCS supports creation of Tax Free voucher receipts.

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

Listing 62 Example Request: taxFreeVoucherRequest

<?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:

Listing 63 Example Response: taxFreeVoucherResponse

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

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

Listing 64 Example Request: taxFreeVoidVoucherRequest

<?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:

Listing 65 Example Response: taxFreeVoidVoucherResponse

<?xml version="1.0" encoding="UTF-8" ?>
<vcs-pos:taxFreeVoidVoucherResponse xmlns:vcs-pos="http://www.vibbek.com/pos"/>

10 XML schemas

10.1 Base types

See XML schema definition file schema/base_types.xsd.

10.2 PoS Messages

See XML schema definition file schema/pos_messages.xsd.

10.3 Device Messages

See XML schema definition file schema/device_messages.xsd.

11 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: on-line authorization of transactions processing of submitted transaction data providing of reconciliation advice data setup and change of initialisation data
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.

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

Date:

2024-04-22

Changes:

The type of the field transactionRefNumber was changed from xsd:unsignedLong to xsd: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:: -