.. sectnum:: Wallee AG |api_name| ======================== .. |api_name| replace:: Local Till Interface (LTI) .. |date| date:: Welcome to the Wallee AG |api_name| documentation for version: |release|, created on: |date| .. |wallee_logo_png| Overview ======== The |api_name| 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. .. uml:: 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] Integration Variants -------------------- This document describes one out of three different interfaces which are available to integrate with a Wallee terminal. * `Local Till Interface (LTI) `_: The LTI is described in this document. Integrators should use the LTI if the till application connects to the terminal via a local area network. The most common use case is if the terminal and till are connected to the same LAN at the merchant's site. The benefit is a fast connection as both, the till application and the terminal device, are in the same local network. One drawback is that the terminal's IP address needs to be known. It is also possible to install till applications directly on the device and use LTI via localhost. Nevertheless, if a till application is installed on an Android terminal, then using the `Android Till Interface (ATI)`_ is recommended. * `Android Till Interface (ATI)`_: Integrators are recommended to use the Android Till Interface if their till application is installed directly on an Android based terminal. This way, the till app can directly talk to the terminal software (via `android.os.Messenger `_). The benefit is that one can use our `Android Till SDK `_ to interact with the terminal. If the till app is not running on the terminal, then the Android Till Interface does not work. * `Cloud Till Interface (CTI) `_: By using the cloud interface, an integrator is using a public reachable API to interact with the terminal device. The benefit is that the till app does not need to know where the device is located and it works from any network. However there is a higher delay compared to other integration methods because the communication happens via a central server. .. _Android Till Interface (ATI): https://github.com/wallee-payment/android-till-sdk Note that there are also adaptors available for other protocols, like i.e: MDB which is commonly used on vending machines. For more information about adaptors, get in contact with Wallee's customer support. All integration options provide mechanisms for the same terminal features. Some of the features are as follows: * Request to perform payment transactions like Purchase, Load, Cashback, Reservation etc. * Activate and deactivate terminals (also called linking or unlinking). * Obtain surrogate PAN values (also called PAN hash or PAN token). * Trigger SI(CONFIG) and SI(INTI) procedures. * Receiving additional receipt or display information. Protocol Layers ======================== The following table shows an overview of the involved protocol layers. The XML message is sent on top of TCP/IP. +-------------------------------------------------+ | .. centered:: |api_name| (Len + XML) | +-------------------------------------------------+ | .. centered:: TCP | +-------------------------------------------------+ | .. centered:: IP | +-------------------------------------------------+ The XML message consists of a length field preceding the XML payload. XML message length ------------------ The following table shows a |api_name| 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. 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. LTI Message Structure =============================== The |api_name| 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. :ref:`XML Schemas` are part of this documentation. They accurately describe all valid messages and the used types. Common elements --------------- In the tables below, common parts of a message are presented. 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) | +------------+-------------+-----------------------------------------+ XML Namespaces and Tags ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Since there are two main types of messages body of each message contains following namespace definitions: .. literalinclude:: xml-examples/pos.xml :language: xml :emphasize-lines: 1 for PoS messages, and .. literalinclude:: xml-examples/device.xml :language: xml :emphasize-lines: 1 for device messages. Where xxxx is a message type according to :ref:`PoS Messages` or :ref:`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.: .. literalinclude:: xml-examples/messages.xml :language: xml Examples ======== 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. .. figure:: ./Pictures/1000000000000698000007D849623F5FBF5B9181.png :width: 4.6402in :height: 5.502in Maintenance communication example Submission communication example -------------------------------- :ref:`figsubmission` 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. .. _figsubmission: .. figure:: ./Pictures/1000000000000698000007D801041275E30B223F.png :width: 5.339in :height: 6.3492in Submission communication example 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. .. figure:: ./Pictures/10000000000002570000020A1B6EDC6EFB4BA124.png :width: 6.2398in :height: 5.4374in Transaction communication example Message Types ==================== This section describes both request and response messages that are used in the interface protocol. 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 :ref:`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:** .. literalinclude:: xml-examples/pos-messages/financialTrxRequest.xml :language: xml :caption: Example Request ``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 | xsd:string | The PoS may add its | | | | own transaction | | | | specific data in | | **Important: This | | this field (like an | | field deprecates | | attendant reference | | additionalMerchantData** | | number or its own | | | | transaction | | | | reference number). | +--------------------------+-------------------------+----------------------+ **Example:** .. literalinclude:: xml-examples/pos-messages/financialTrxResponse.xml :language: xml :caption: Example Response: ``financialTrxResponse`` 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``. .. literalinclude:: xml-examples/trxInfo.xml :language: xml 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:** .. literalinclude:: xml-examples/pos-messages/activationRequest.xml :language: xml :caption: Example Request: ``activationRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/activationResponse.xml :language: xml :caption: Example Response: ``activationResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/siConfigRequest.xml :language: xml :caption: Example Request: ``siConfigRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/siConfigResponse.xml :language: xml :caption: Example Response: ``siConfigResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/deactivationRequest.xml :language: xml :caption: Example Request: ``deactivationRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/deactivationResponse.xml :language: xml :caption: Example Response: ``deactivationResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/beFinalBalanceRequest.xml :language: xml :caption: Example Request: ``beFinalBalanceRequest`` **Response:** +---------------+------------------+---------------------------------+ | **Keyword** | **Type** | **Description** | +---------------+------------------+---------------------------------+ | trxSyncNumber | xsd:unsignedInt | The transaction synchronization | | | | number contained in the | | | | request. | +---------------+------------------+---------------------------------+ **Example:** .. literalinclude:: xml-examples/pos-messages/beFinalBalanceResponse.xml :language: xml :caption: Example Response: ``beFinalBalanceResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/siInitRequest.xml :language: xml :caption: Example Request: ``siInitRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/siInitResponse.xml :language: xml :caption: Example Response: ``siInitResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/pingRequest.xml :language: xml :caption: Example Request: ``pingRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/pingResponse.xml :language: xml :caption: Example Response: ``pingResponse`` 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 | xsd:unsignedInt | The PoS may add its | | dditionalMerchantData* | | own transaction | | | | specific data in this | | *(deprecated)* | | field (like an | | | | attendant reference | | Please use | | number or its own | | ``merchantReference`` | | 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:** .. literalinclude:: xml-examples/pos-messages/reversalRequest.xml :language: xml :caption: Example Request: ``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:** .. literalinclude:: xml-examples/pos-messages/reversalResponse.xml :language: xml :caption: Example Response: ``reversalResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/cancelReservationRequest.xml :language: xml :caption: Example Request: ``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 | Cancel reservation | | | | result returned from | | | ResultType | 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:** .. literalinclude:: xml-examples/pos-messages/cancelReservationResponse.xml :language: xml :caption: Example Response: ``cancelReservationResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/miSubmissionRequest.xml :language: xml :caption: Example Request: ``miSubmissionRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/miSubmissionResponse.xml :language: xml :caption: Example Response: ``miSubmissionResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/beTransmissionRequest.xml :language: xml :caption: Example Request: ``beTransmissionRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/beTransmissionResponse.xml :language: xml :caption: Example Response: ``beTransmissionResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/reprintReceiptRequest.xml :language: xml :caption: Example Request: ``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 | | The response data of | | | CancelReservationResponse | the last transaction, | | | | if last action was a | | | | cancellation of a | | | | reservation | +---------------+---------------------------+------------------------+ **Example:** .. literalinclude:: xml-examples/pos-messages/reprintReceiptResponse.xml :language: xml :caption: Example Response: ``reprintReceiptResponse`` **Or** .. literalinclude:: xml-examples/pos-messages/reprintReceiptResponseLastRev.xml :language: xml :caption: Example Response: ``reprintReceiptResponse`` **Or** .. literalinclude:: xml-examples/pos-messages/reprintReceiptResponseCancelRev.xml :language: xml :caption: Example Response: ``reprintReceiptResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/configDataRequest.xml :language: xml :caption: Example Request: ``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:** .. literalinclude:: xml-examples/pos-messages/configDataResponse.xml :language: xml :caption: Example Response: ``configDataResponse`` 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 | | | | :ref:`ErrorCodes`. | +-------------+------------+-----------------------------------------+ **Example:** .. literalinclude:: xml-examples/pos-messages/errorNotification.xml :language: xml :caption: Example Notification: ``errorNotification`` 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 | Start a transaction, | | | the terminal | insert card in the chip | | | | reader and immediately | | | prior to completion of | remove it. | | | the transaction. | | +--------------+--------------------------+--------------------------+ | TRM.PT.0002 | The cardholder (or the | Start a transaction, | | | attendant) presses the | press stop at any point | | | Stop key on the terminal | when the user | | | during the transaction. | interaction is expected | | | | (instead of inserting | | | | the card, typing in the | | | | pin code, etc.) | +--------------+--------------------------+--------------------------+ | TRM.PT.0003 | "System Error" A | Internal error occurred | | | technical problem | during chip reader | | | occurred on the | transaction | | | terminal, outside the | | | | exceptions specified. | | | | (Internal error in the | | | | ICC reader transaction) | | +--------------+--------------------------+--------------------------+ | TRM.PT.0201 | Card not detected. The | Start a transaction, | | | card was not detected | wait for the timeout | | | within | without presenting a | | | | card. | | | | | | | seconds. | | +--------------+--------------------------+--------------------------+ | TRM.PT.0300 | Card not inserted | | +--------------+--------------------------+--------------------------+ | TRM.PT.0405 | Failed to Contact Card | Insert card wrong way. | | | (1st attempt) | (e.g. chip backwards) | | | | | | | The inserted card can | | | | not be contacted or read | | | | correctly by the ICR | | | | (1st attempt) | | +--------------+--------------------------+--------------------------+ | TRM.PT.0406 | Failed to Contact Card | Incorrectly insert card | | | (2nd attempt) | in the magstripe (2nd | | | | aatempt) | | | The inserted card can | | | | not be contacted (Used | | | | for the combined | | | | reader). | | +--------------+--------------------------+--------------------------+ | TRM.PT.0609 | Multiple reversal limit | | | | reached | | +--------------+--------------------------+--------------------------+ | TRM.PT.0500 | No Application Found | use a card, which is not | | | | supported by the | | | The card does not | acquirer | | | contain an application | | | | supported by the | | | | terminal. | | +--------------+--------------------------+--------------------------+ | TRM.PT.0501 | Card blocked or SELECT | Use a blocked card | | | command not supported | | +--------------+--------------------------+--------------------------+ | TRM.PT.0700 | The transaction cannot | Use the card with the | | | be executed with the | application that doesn’t | | | selected application. | support the particular | | | | transaction | +--------------+--------------------------+--------------------------+ | TRM.PT.0701 | Read Error. Read error | Use a card that has | | | happens (e.g. due to | faulty contact chips | | | worn contacts of the | (and leave it in the | | | chip, or any other | reader) | | | unexpected error), but | | | | the card is still there. | | +--------------+--------------------------+--------------------------+ | 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 | Signature verification | | | | is set up for an | | | in case of unattended | unattended terminal. | | | terminals (class UAT) | | | | the kernel requests | | | | “obtain signature” as | | | | cardholder verification | | | | method | | +--------------+--------------------------+--------------------------+ | TRM.PT.0905 | Online PIN not supported | PIN verification is set | | | | up for a terminal | | | in case of terminals of | without a pin pad. | | | class UAT-NON-PED the | | | | kernel requests “Online | | | | PIN” as cardholder | | | | verification method | | +--------------+--------------------------+--------------------------+ | TRM.ID.0007 | Storing TR31 block of | This error can only | | | wrapped key in PED | happen for EP2 version | | | failed | 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. | +--------------+--------------------------+--------------------------+ 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:** .. literalinclude:: xml-examples/device-messages/confirmationRequest.xml :language: xml :caption: Example Request: ``confirmationRequest`` **Response:** =========== ================= ====================== **Keyword** **Type** **Description** result xsd:unsignedByte Confirmation result: 0 – negative 1 - positive =========== ================= ====================== **Example:** .. literalinclude:: xml-examples/device-messages/confirmationResponse.xml :language: xml :caption: Example Response: ``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:** .. literalinclude:: xml-examples/device-messages/timeoutNotification.xml :language: xml :caption: Example Notification: ``timeoutNotification`` 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:** .. literalinclude:: xml-examples/device-messages/displayNotification.xml :language: xml :caption: Example Notification: ``displayNotification`` 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:** .. literalinclude:: xml-examples/device-messages/printerNotification1.xml :language: xml :caption: Example Notification: ``printerNotification`` .. literalinclude:: xml-examples/device-messages/printerNotification2.xml :language: xml :caption: Example Notification: ``printerNotification`` 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 | The abort code specifies | | | ortCodexsd:unsignedShort | the reason for the | | | | abort. | +-------------+--------------------------+--------------------------+ **Example:** .. literalinclude:: xml-examples/device-messages/abortCardEntryNotification.xml :language: xml :caption: Example Notification: ``abortCardEntryNotification`` Supported AbortCodes ^^^^^^^^^^^^^^^^^^^^ ======== ================================================= **Code** **Description** 01 Standard AbortCode with regular handling. 02 Abort because of other payment methods e.g. cash. ======== ================================================= 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:** .. literalinclude:: xml-examples/pos-messages/waitForCardPresentRequest.xml :language: xml :caption: Example Request: ``waitForCardPresentRequest`` **Response:** =========== =========== ====================================== **Keyword** **Type** **Description** cardPresent xsd:boolean Flag indicating if a card is present =========== =========== ====================================== **Example:** .. literalinclude:: xml-examples/pos-messages/waitForCardPresentResponse.xml :language: xml :caption: Example Response: ``waitForCardPresentResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/waitForCardRemovedRequest.xml :language: xml :caption: Example Request: ``waitForCardRemovedRequest`` **Response:** =========== =========== ====================================== **Keyword** **Type** **Description** cardPresent xsd:boolean Flag indicating if a card is present =========== =========== ====================================== **Example:** .. literalinclude:: xml-examples/pos-messages/waitForCardRemovedResponse.xml :language: xml :caption: Example Response: ``waitForCardRemovedResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/interEodReceiptRequest.xml :language: xml :caption: Example Request: ``interEodReceiptRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/interEodReceiptResponse.xml :language: xml :caption: Example Response: ``interEodReceiptResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/checkCouponIdRequest.xml :language: xml :caption: Example Request: ``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:** .. literalinclude:: xml-examples/pos-messages/checkCouponIdResponse.xml :language: xml :caption: Example Response: ``checkCouponIdResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/pinpadInformationRequest.xml :language: xml :caption: Example Request: ``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:** .. literalinclude:: xml-examples/pos-messages/pinpadInformationResponse.xml :language: xml :caption: Example Response: ``pinpadInformationResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/generatePanTokenRequest.xml :language: xml :caption: Example Request: ``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:** .. literalinclude:: xml-examples/pos-messages/generatePanTokenResponse.xml :language: xml :caption: Example Response: ``generatePanTokenResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/printCurrencyRateTicketRequest.xml :language: xml :caption: Example Request: ``printCurrencyRateTicketRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/simpleExample.xml :language: xml :caption: Example 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. 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:** .. literalinclude:: xml-examples/device-messages/cardEntryNotification.xml :language: xml :caption: Example Notification: ``cardEntryNotification`` CardRemovalNotification ^^^^^^^^^^^^^^^^^^^^^^^ This notification is sent to the PoS system, after the card has been removed from the PIN pad. **Example:** .. literalinclude:: xml-examples/device-messages/cardRemovalNotification.xml :language: xml :caption: Example Notification: ``cardRemovalNotification`` TransactionStartNotification ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This notification is sent to the PoS system, after the transaction has been started on the terminal. **Example:** .. literalinclude:: xml-examples/device-messages/trxStartNotification.xml :language: xml :caption: Example Notification: ``trxStartNotification`` TransactionEndNotification ^^^^^^^^^^^^^^^^^^^^^^^^^^ This notification is sent to the PoS system, after the transaction has been completed on the terminal. **Example:** .. literalinclude:: xml-examples/device-messages/trxEndNotification.xml :language: xml :caption: Example Notification: ``trxEndNotification`` TransactionAbortNotification ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This notification is sent to the PoS system, after the transaction has been aborted on the terminal without correct completion. **Example:** .. literalinclude:: xml-examples/device-messages/trxAbortNotification.xml :language: xml :caption: Example Notification: ``trxAbortNotification`` 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:** .. literalinclude:: xml-examples/pos-messages/sleepRequest.xml :language: xml :caption: Example Request: ``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:** .. literalinclude:: xml-examples/pos-messages/sleepResponse.xml :language: xml :caption: Example Response: ``sleepResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/adaptAmountRequest.xml :language: xml :caption: Example Request: ``adaptAmountRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/adaptAmountResponse.xml :language: xml :caption: Example Response: ``adaptAmountResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/commitAuthorisationPurchaseRequest.xml :language: xml :caption: Example Request: ``commitAuthorisationPurchaseRequest`` **Response:** =========== ======== =============== **Keyword** **Type** **Description** (no tags) =========== ======== =============== **Example:** .. literalinclude:: xml-examples/pos-messages/commitAuthorisationPurchaseResponse.xml :language: xml :caption: Example Response: ``commitAuthorisationPurchaseResponse`` TransactionSyncNumber ===================== 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. TransactionSyncNumber Sequence Diagrams --------------------------------------- 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. 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. 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. 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. Special Features ================ Tax Free -------- The VCS supports creation of Tax Free voucher receipts. 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:** .. literalinclude:: xml-examples/pos-messages/taxFreeVoucherRequest.xml :language: xml :caption: Example Request: ``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:** .. literalinclude:: xml-examples/pos-messages/taxFreeVoucherResponse.xml :language: xml :caption: Example Response: ``taxFreeVoucherResponse`` 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:** .. literalinclude:: xml-examples/pos-messages/taxFreeVoidVoucherRequest.xml :language: xml :caption: Example Request: ``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:** .. literalinclude:: xml-examples/pos-messages/taxFreeVoidVoucherResponse.xml :language: xml :caption: Example Response: ``taxFreeVoidVoucherResponse`` XML Schemas =========== Base Types ---------- See XML schema definition file :download:`schema/base_types.xsd`. PoS Messages ------------ See XML schema definition file :download:`schema/pos_messages.xsd`. Device Messages --------------- See XML schema definition file :download:`schema/device_messages.xsd`. 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. | +-------------------------+------------------------------------------------+ | PAN | Primary Account Number | +-------------------------+------------------------------------------------+ 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.46 :Date: 2024-05-02 :Changes: Reworded the overview section and some section titles. No functional changes to the API. :Migration Notes: \- ------------ :Version: 2.45 :Date: 2024-04-22 :Changes: - The type of the field ``transactionRefNumber`` was changed 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: \- .. |wallee_logo_png| image:: ./Pictures/wallee_logo_RGB_turquoise.png :scale: 10% .. |image8| image:: ./Pictures/100002010000021300000150309625A00D613A56.png :width: 5.5311in :height: 3.5in .. |image9| image:: ./Pictures/1000020100000249000000E75954413DEFFDA54A.png :width: 6.0937in :height: 2.4063in .. |image10| image:: ./Pictures/1000020100000214000000F2A2DEE655AE8F8E2B.png :width: 5.5417in :height: 2.5209in