1 Wallee AG Local Till Interface (LTI)

Welcome to the Wallee AG Local Till Interface (LTI) documentation for version: 2.44, created on: 2024-09-20

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

_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

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

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>
      <merchantReference>Merchant’s Custom Ref</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:unsignedLong

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

cardAppId

xsd:string

xsd:string

The name of the used application.

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

Par tialApprovalFlagType

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 addi tionalMerchantData

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

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

trxSeqCnt

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

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>
   <cardSeqNum>1</cardSeqNum>
   <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:unsignedLong

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

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>
      <!-- ... -->
   </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>
      <amountRev>500</amountRev>
      <amountRevCurr>756</amountRevCurr>
      <!-- ... -->
   </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>
      <amountAuth>2000</amountAuth>
      <amountAuthCurr>756</amountAuthCurr>
      <!-- ... -->
   </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>A0000000043060</aid>
                  <brand>Maestro</brand>
               </terminalApplicationConfigData>
               <terminalApplicationConfigData>
                  <aid>A0000000032020</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 9.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:stringr

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">
</vcs-pos:interEodReceiptResponse>

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

image8

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

image9

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

image10

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