.. 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 :ref:`?` | ManualPanData | Manually entered card data | +-------------------------------------+------------------+-----------------------------------------------+ | trxSyncNumber :ref:`?` | xsd:unsignedInt | Number maintained by the | | | | PoS and changed after each | | | | successful transaction to | | | | recognize an out-of-sync | | | | situation. See :ref:`Transaction Sync Number` | +-------------------------------------+------------------+-----------------------------------------------+ | generatePanToken :ref:`?` | xsd:boolean | Flag to request the | | | | PAN-Token in the | | | | FinancialTrxResponse | +-------------------------------------+------------------+-----------------------------------------------+ | trxInfo | xsd:base64Binary | This field contains a | | | | bitmask to specify which | | | | :ref:`TransactionStatusNotification Messages` | | | | should be sent by the | | | | terminal. This field | | | | should contain a series of | | | | 3 bytes in Base64 | | | | encoding. (see chapter | | | | :ref:`trxInfo bitmask`) | +-------------------------------------+------------------+-----------------------------------------------+ | receiptFormat :ref:`?` | 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 :ref:`?` | xsd:string | 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:** .. _financialTrxRequest: .. 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 :ref:`?` | 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 :ref:`?` | xsd:unsignedLong | | +-----------------------------------------+-------------------------+----------------------+ | transactionRefNumber :ref:`?` | xsd:string | Reference number for | | | | the transaction. | | | | Used as a reference | | | | for follow-up | | | | transactions like | | | | Reservation | | | | Adjustment and | | | | Purchase | | | | Reservation. | +-----------------------------------------+-------------------------+----------------------+ | cardNumber :ref:`?` | xsd:string | The masked primary | | | | account number | | | | (masked PAN). | | | | It's not provided | | | | for Reservation | | | | Adjustment. | +-----------------------------------------+-------------------------+----------------------+ | cardSeqNumber :ref:`?` | xsd:unsignedShort | Identifies and | | | | differentiates cards | | | | with the same PAN. | | | | Only available for | | | | EMV ICC or EMV | | | | contactless | | | | transactions. | +-----------------------------------------+-------------------------+----------------------+ | cardExpDate :ref:`?` | xsd:string | The date after which | | | | the application | | | | expires. Format: | | | | yyMMdd | +-----------------------------------------+-------------------------+----------------------+ | cardAppLabel :ref:`?` | xsd:string | The name of the used | | | | application. | | | | It's not provided | | | | for Reservation | | | | Adjustment. | +-----------------------------------------+-------------------------+----------------------+ | cardAppId :ref:`?` | xsd:string | | | | | The identifier of | | | | the used application | | | | (AID). | | | | It's not provided | | | | for Reservation | | | | Adjustment. | +-----------------------------------------+-------------------------+----------------------+ | 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 :ref:`?` | xsd:unsignedLong | The amount of DCC | | | | transaction | | | | (authorised amount | | | | converted by DCC | | | | service). Only set | | | | if DCC was | | | | successfully | | | | authorised. | +-----------------------------------------+-------------------------+----------------------+ | dccTrxAmountCurr :ref:`?` | CurrencyType | The currency of the | | | | DCC transaction | | | | amount. Three-digit | | | | currency code, | | | | according to ISO | | | | 4217.Only set if DCC | | | | was successfully | | | | authorised. | +-----------------------------------------+-------------------------+----------------------+ | cvm :ref:`?` | 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 :ref:`?` | xsd:unsignedLong | The remaining amount | | | | which was not | | | | authorised. Value = | | | | original amount in | | | | | | | | request - authorised | | | | amount. Exists if | | | | the transaction was | | | | partially approved. | +-----------------------------------------+-------------------------+----------------------+ | partialApprovalFlag :ref:`?` | 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 :ref:`?` | xsd:unsignedInt | The transaction | | | | synchronisation | | | | number contained in | | | | the request. | +-----------------------------------------+-------------------------+----------------------+ | panToken :ref:`?` | 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 | | | | StateWaitForCard | | | | screen. | | | | NOTE: | | | | The text provided | | | | will be displayed on | | | | a single line of 25 | | | | characters max. | | | | The amount will be | | | | displayed under the | | | | custom text. | +-----------------------------------------+-------------------------+----------------------+ | cardIssuingCountry :ref:`?` | xsd:string | This is used to show | | | | the Card's issuing | | | | country (ex: “DE”, | | | | “CH”, “FR” etc). | +-----------------------------------------+-------------------------+----------------------+ | merchantReference :ref:`?` | ans | 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). | +-----------------------------------------+-------------------------+----------------------+ | paymentEntryMethod :ref:`?` | xsd:string | The payment method | | | | used on the PoS: | | | | | | | | – MAGSTRIPE | | | | | | | | – ICC | | | | | | | | – CTLS | | | | | | | | – QR | | | | | | | | – MANUAL | +-----------------------------------------+-------------------------+----------------------+ **Example:** .. _financialTrxResponse: .. 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 :ref:`?` | LanguageType | Language code, according to ISO | | | | 639-1 | +----------------------------------+-----------------+---------------------------------+ | receiptFormat :ref:`?` | 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 :ref:`?` | 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 :ref:`?` | 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 :ref:`?` | xsd:unsignedInt | Number maintained by the PoS | | | | and changed after each | | | | successful transaction to | | | | recognize an | | | | | | | | out-of-sync situation (see | | | | :ref:`Transaction Sync Number`). | +----------------------------------+-----------------+----------------------------------+ | receiptFormat :ref:`?` | 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:** .. _beFinalBalanceRequest: .. literalinclude:: xml-examples/pos-messages/beFinalBalanceRequest.xml :language: xml :caption: Example Request: ``beFinalBalanceRequest`` **Response:** +----------------------------------+-----------------+---------------------------------+ | Keyword | Type | Description | +==================================+=================+=================================+ | trxSyncNumber :ref:`?` | 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 :ref:`?` | 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 | +----------------------------------+-----------------+------------------------+ | origTrxSeqCnt :ref:`?` | 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 :ref:`?` | 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 :ref:`?` | xsd:string | 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 :ref:`?` | xsd:unsignedShort | Identifies and | | | | differentiates cards | | | | with the same PAN. | | | | Only available for | | | | EMV ICC or EMV | | | | | | | | contactless | | | | transactions. | +----------------------------------+-------------------+-----------------------+ | cardExpDate :ref:`?` | 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. | +----------------------+------------+------------------------+ **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 :ref:`?` | xsd:string | Reference number of | | | | the cancelled | | | | reservation. | +-----------------------------------------+-------------------+-------------------------------------------------------------+ | ep2TrxSeqCnt | xsd:unsignedInt | Transaction sequence | | | | number according to | | | | EP2 specification | +-----------------------------------------+-------------------+-------------------------------------------------------------+ | amountAuthCurr :ref:`?` | CurrencyType | The currency of the | | | | cancelled reservation | | | | amount sent from the | | | | host. Three-digit | | | | currency | | | | | | | | code, according to | | | | ISO 4217. | +-----------------------------------------+-------------------+-------------------------------------------------------------+ | amountAuth :ref:`?` | xsd:unsignedInt | The amount of the cancelled reservation sent from the host. | +-----------------------------------------+-------------------+-------------------------------------------------------------+ | ep2AuthResult :ref:`?` | 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 :ref:`?` | 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 :ref:`?` | 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 | +=========================+=============+==============================+ | type :ref:`?` | ReceiptType | If it is not set, the | | | | latest financial transaction | | | | receipt is requested. | +-------------------------+-------------+------------------------------+ **Example:** .. literalinclude:: xml-examples/pos-messages/reprintReceiptRequest.xml :language: xml :caption: Example Request: ``reprintReceiptRequest`` **Response:** +-----------------------------------+---------------------------+------------------------+ | Keyword | Type | Description | +===================================+===========================+========================+ | lastTrx :ref:`?` | 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 :ref:`?` | ReversalResponse | The reversal response | | | | data if last financial | | | | transaction was | | | | reversed; only in case | | | | of type latest | | | | financial transaction | | | | receipt is requested | +-----------------------------------+---------------------------+------------------------+ | lastCancelRes :ref:`?` | CancelReservationResponse | The response data of | | | | 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 :ref:`?` | AcquirerDataList | List of all acquirers configured for this terminal. It | | | | contains configured AIDs and brands. | +--------------------------------------+-----------------------+-----------------------------------------------------------+ | ep2Tcd :ref:`?` | Ep2TerminalConfigData | Configured values of ep2-specific terminal configuration | | | | data. | +--------------------------------------+-----------------------+-----------------------------------------------------------+ | ep2Version :ref:`?` | xsd:string | The configured ep2 version information. | +--------------------------------------+-----------------------+-----------------------------------------------------------+ | currencyItemsList :ref:`?` | CurrencyItemsList | List of all currency items configured for the terminal, | | | | including currencyType and currency. **currencyType** - | | | | The supported currencies by the terminal, with "LOCAL" | | | | and "FOREIGN" as options. The local currency is the | | | | default. **currency** - ISO 4217 three-letter alphabetic | | | | codes that represent global currencies. Example: CHF,USD. | +--------------------------------------+-----------------------+-----------------------------------------------------------+ **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 :ref:`?` | xsd:string | Contains the | | | | identifier of the card, if available. | | | | This value is returned to allow further | | | | processing by the till. | +--------------------------------------+------------+------------------------------------------------------------------+ | errorCode :ref:`?` | xsd:string | Contains one of | | | | the defined error codes in | | | | :ref:`ErrorCodes`. | +--------------------------------------+------------+------------------------------------------------------------------+ | errorText :ref:`?` | xsd:string | Textual description of the error above | +--------------------------------------+------------+------------------------------------------------------------------+ | merchantReference :ref:`?` | ans | The value which was provided by | | | | the PoS in the ``financialTrxRequest.trxData.merchantReference`` | +--------------------------------------+------------+------------------------------------------------------------------+ **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 a 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 | +------------------------------------+-------------+-------------------------------------------------------------+ | displayType :ref:`` | DisplayType | Contains the display type like *CARDHOLDER* and *ATTENDANT* | +------------------------------------+-------------+-------------------------------------------------------------+ | timeout | xsd:integer | Time in seconds to confirm | +------------------------------------+-------------+-------------------------------------------------------------+ | timeoutReminder :ref:`?` | 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 **Notification:** +----------------------------------+-------------+-------------------------------------------------------------+ | Keyword | Type | Description | +==================================+=============+=============================================================+ | display | Display | Contains lines to display | +----------------------------------+-------------+-------------------------------------------------------------+ | displayType :ref:`` | DisplayType | Contains the display type like *CARDHOLDER* and *ATTENDANT* | +----------------------------------+-------------+-------------------------------------------------------------+ **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). **Notification:** +--------------------------------------+-------------+---------------------------------+ | Keyword | Type | Description | +======================================+=============+=================================+ | merchantReceipt :ref:`?` | xsd:string | Preformatted receipt for the | | | | merchant. UTF-8. The end of a | | | | line is marked by LF (0x0A). | +--------------------------------------+-------------+---------------------------------+ | cardholderReceipt :ref:`?` | xsd:string | Preformatted receipt for | | | | cardholder. UTF-8. The end of a | | | | line is marked by LF (0x0A). | +--------------------------------------+-------------+---------------------------------+ | admin :ref:`?` | xsd:boolean | Attribute only set on merchant | | | | receipt elements. Indicates if | | | | the receipt is an | | | | administrative | | | | | | | | receipt and not a financial | | | | transaction receipt. | +--------------------------------------+-------------+---------------------------------+ **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. 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 | +================================+=============+==================================================================+ | silentAbort :ref:`?` | xsd:boolean | If set to true then the terminal does not show the abort screen. | | | | Default is false. | +--------------------------------+-------------+------------------------------------------------------------------+ **Example:** .. literalinclude:: xml-examples/device-messages/abortCardEntryNotification.xml :language: xml :caption: Example Notification: ``abortCardEntryNotification`` IntermediateEodReceipt Message ------------------------------ The IntermediateEodReceipt Message – requests an intermediate end of day receipt. **Request:** +----------------------------------+-----------------+---------------------------------+ | Keyword | Type | Description | +==================================+=================+=================================+ | posId | xsd:string | PoS identifier | +----------------------------------+-----------------+---------------------------------+ | receiptFormat :ref:`?` | 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 :ref:`?` | xsd:string | The ID of the terminal. | +---------------------------------------+------------+-------------------------------+ | vpjSoftwareVersion :ref:`?` | xsd:string | The version number of the VPJ | | | | Software. | +---------------------------------------+------------+-------------------------------+ | serialNumber :ref:`?` | xsd:string | The serial number of the PIN | | | | pad. | +---------------------------------------+------------+-------------------------------+ | hardwareType :ref:`?` | xsd:string | The type of device. | +---------------------------------------+------------+-------------------------------+ | logLevel :ref:`?` | xsd:string | The log level of the VPJ | | | | software. | +---------------------------------------+------------+-------------------------------+ | osVersion :ref:`?` | xsd:string | - | +---------------------------------------+------------+-------------------------------+ | merchantId :ref:`?` | xsd:string | - | +---------------------------------------+------------+-------------------------------+ | merchantName :ref:`?` | xsd:string | - | +---------------------------------------+------------+-------------------------------+ | spaceId :ref:`?` | xsd:string | - | +---------------------------------------+------------+-------------------------------+ | offlineTrxNumber :ref:`?` | xsd:string | The total number of approved | | | | transactions on the device | | | | (deferred mode only). | +---------------------------------------+------------+-------------------------------+ | offlineTrxAmount :ref:`?` | 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 :ref:`?` | xsd:string | See: FinancialTrx message – | | | | Request. | +----------------------------------------+------------------+-----------------------------------------------+ | trxResultCustomText :ref:`?` | xsd:string | As „trxCustomText” but | | | | displayed in resulting screen, | | | | eg „identification | | | | successfull”. | +----------------------------------------+------------------+-----------------------------------------------+ | selectedLang :ref:`?` | xsd:string | Language symbol used by POS, eg | | | | „en”. | +----------------------------------------+------------------+-----------------------------------------------+ | trxInfo :ref:`?` | xsd:base64Binary | This field contains a | | | | bitmask to specify which | | | | :ref:`TransactionStatusNotification Messages` | | | | should be sent by the | | | | terminal. This field | | | | should contain a series of | | | | 3 bytes in Base64 | | | | encoding. (see chapter | | | | :ref:`trxInfo bitmask`) | +----------------------------------------+------------------+-----------------------------------------------+ **Example:** .. literalinclude:: xml-examples/pos-messages/generatePanTokenRequest.xml :language: xml :caption: Example Request: ``generatePanTokenRequest`` **Response:** +-----------------------------+------------------+--------------------------+ | Keyword | Type | Description | +=============================+==================+==========================+ | panToken :ref:`?` | xsd:base64Binary | The requested PAN token. | +-----------------------------+------------------+--------------------------+ | cardId :ref:`?` | xsd:string | A 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 :ref:`?` | 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 :ref:`?` | 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. The ``adaptAmountRequest`` is not supported if the last transaction: * Was declined. * Was reversed. * Was in deferred mode. * Has a different currency than the new one. * Has an authorized amount lower than the new amount. If an ``adaptAmountRequest`` is sent in one of the cases above, then the device will return 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. | +---------------------+------------------+------------------------+ **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`` Transaction Sync Number ======================= Purpose ------- The ``trxSyncNumber`` 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 :ref:`ReprintReceipt Message` in cases of an unclear transaction result is not feasible, then it is strongly recommended to use this feature. The terminal uses the ``trxSyncNumber`` to ensure that the last transaction response has been correctly received and processed by the ECR. The terminal expects the ``trxSyncNumber`` sent with a :ref:`financialTrxRequest ` to be incremented after each completed transaction. A transaction is considered completed after the processing of the :ref:`financialTrxResponse ` has been completed by the ECR. If this requirement is not met, i.e. the ECR sends the same ``trxSyncNumber`` in two consecutive transactions, the previous transaction will be reversed automatically. Financial Transaction Request Flow --------------------------------------- |image8| The PoS system includes the ``trxSyncNumber`` in each :ref:`financialTrxRequest `. After each completed financial transaction (i.e. after receiving the :ref:`financialTrxResponse `), 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 :ref:`ErrorNotification`), the PoS system uses the same number again for the next transaction. Auto-Reversal Situation Flow --------------------------------------- |image9| If the terminal receives a :ref:`financialTrxRequest ` 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 :ref:`financialTrxRequest `, would be to use the :ref:`reprintReceiptRequest `. After the response to the first :ref:`financialTrxRequest ` is lost, the ReprintReceipt operation would allow the till to automatically re-synchronize with the terminal. Final Balance Flow --------------------------------------- The PoS system also includes the current ``trxSyncNumber`` in the :ref:`beFinalBalanceRequest ` message. |image10| This allows the terminal to recognize possible out-of-sync situations and process an automatic reversal before processing the final balance. .. uml:: skinparam monochrome true participant PoS as pos participant "PIN pad" as terminal pos -> terminal: Financial Transaction Request (trxSyncNumber=1) activate terminal terminal -->X pos: Financial Transaction Response (Approved) deactivate terminal pos -> terminal: BE Final Balance Request (trxSyncNumber=1) activate terminal terminal --> terminal: Auto-Reversal activate terminal deactivate terminal terminal --> pos: BE Final Balance Response (trxSyncNumber=1) deactivate terminal Additions to the Final Balance Receipt ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the ECR uses the ``trxSyncNumber``, 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 ``trxSyncNumber``. 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 ``trxSyncNumber``. 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. 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 | +-------------------------+------------------------------------------------+ .. _footnote: Footnotes ============ :?: The property is marked as optional. It may not be present in the message :: The property is an attribute in the xml tag. 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.49 :Date: 2025-01-07 :Changes: - Updated description of property ``trxCustomText`` in the ``financialTrxRequest``. - Removed features that are supported only by legacy application. - Add optional ``?`` and attribute ```` symbols to indicate extra informations about message's fields. - Drop the (never implemented) ``abortCode`` in favor of a ``true`` tag as part of the ``abortCardEntryNotification``. :Migration Notes: \- ------------ :Version: 2.48 :Date: 2024-09-20 :Changes: - Added an additional sequence diagram about using the ``trxSyncNumber`` in conjunction with a ``beFinalBalanceRequest`` and linked message names in the same chapter. - Fields ``cardAppLabel``, ``cardAppId``, and ``cardNumber`` were never provided in the ``financialTrxResponse`` for card-not-present transactions like the Reservation Adjustment. - Added an optional ``paymentEntryMethod`` property to ``financialTrxResponse``. - Added ``currencyItemsList`` to ``configDataResponse`` and update ``configDataResponse`` fields and documentation to reflect the current response format. - Fixed the documentation for the ``adaptAmountRequest``: Offline transactions are supported but referenced transactions were never supported. :Migration Notes: \- ------------ :Version: 2.47 :Date: 2024-07-03 :Changes: - Added an optional ``trxInfo`` property to ``generatePanTokenRequest``. - Change type of ``merchantReference`` from ``xsd::string`` to ``ans`` as defined in EP2 v7.4 Data Dictionary , chapter 4.2.4 "Special Characters (ans)". All characters defined in ``xsd::string`` are still supported by the terminal but some acquirers will reject requests with characters which are not allowed in type ``ans``. :Migration Notes: \- ------------ :Version: 2.46 :Date: 2024-05-02 :Changes: Reworded the overview section and some section titles. No functional changes to the API. :Migration Notes: \- ------------ :Version: 2.45 :Date: 2024-04-22 :Changes: - The type of the field ``transactionRefNumber`` was changed 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