Revision history

Introduction

This document describes the EPAS protocol implementation in the West payment application.

The EPAS protocol is one method of controlling a payment terminal from an Electronic Cash Register (ECR).  The EPAS protocol attempts to be very comprehensive and so there is a lot of the EPAS protocol that is unnecessary for these purposes.  Despite this, there are a number of gaps in the EPAS protocol that mean some customisation has been required.  The aim of this document is to specify which EPAS messages are used, which parts of the messages are relevant, and which messages have been customised to fit the requirements of the payment application.

This document will refer to two specifications:

1. EPAS Org, Sale to POI Protocol Specifications Version 1.0, Date 10^th October 2010
2. BABS and CEKAB Cardholder and Operator InterfaceVersion 4.02, Date 25^th August 2009

The first of these is the full EPAS specification, and is the primary source for all aspects of the EPAS protocol.  The second of these describes standardised screen layouts and messages.

Protocol overview

The interface between the payment application and the ECR provides a range of functionality including:

• ECR login
• Starting a transaction
• Handling message display on the ECR
• Printing receipts on the ECR
• Performing administrative functions

In an EPAS environment the ECR device is the retailer's interface to the complete sales system, while the payment terminal is the customer's interface. During a customer transaction, therefore, the retailer must be able to control and instruct the payment terminal via the ECR's display and keyboard.

Message transport and encoding

All EPAS messages are encoded in XML.  XML schema files are available and are used by the payment application to validate inbound messages in real time. The schema files are based on those supplied by EPAS but are amended to include the new messages and fields described in this document. Received messages that fail XML schema validation shall not be processed.

TCP/IP network connection

When operating over a TCP/IP network connection all messages are preceded by a four byte length field as described in section 3.3.1 of the EPAS specification.

You can find the terminal IP by pressing the buttons: 1 4 7 3 6 9 from the "terminals closed" screen and then select the Status menu and browse next until you find the terminals IP.

Default communication port

The default communication port for EPAS implementations is 3000.

Keepalive

Once connected the ECR must send something to the terminal at regular intervals, otherwise the terminal will assume that the ECR has gone offline or lost connection and will terminate any ongoing service.

If the ECR has no data to send then it can send an empty packet, which is a sequence of four bytes with value zero.  Since the first four bytes of a message indicate the message size, this is simply an empty message.

The ECR should aim to send something every two seconds.

The normal approach here is to have a timer that will expire in two seconds.  Whenever something is sent to the terminal the timer can be reset.  Whenever the timer fires an empty message header can be sent, and the timer is reset to fire two seconds later.

Serial connection (ONLY available for the Classic terminal family)

The payment application can operate EPAS over a serial connection and there is a separate specification that details the low-level protocol involved there.

Message header

The EPAS specification defines a header for each of the message types. The header may contain the following fields:

For compactness the message header is not included in the details of the messages below.

Message contents

This section describes the EPAS messages that are supported. Each message is described using the following conventions:

Field Repetitions

The column marked "Mult" describes the minimum and maximum occurrences of that particular element / field, e.g.
[1..1] the element must occur at least once and only once i.e. Mandatory.
[0..1] the element is Optional but may occur once.
[0..n] the element is Optional and may occur n times.

Field rule

The column marked "Rule" indicates any special conditions that apply to the field

Field usage

The column marked "Usage" is used as follows:
On messages originating from the ECR:

• Yes indicates that the element / attribute will, if present, be used by the payment application.
• No indicates that the element / attribute may occur but will be ignored.  These fields are marked in pink.

On messages originating from the terminal:

• Yes indicates that the element / attribute will be populated by the payment application.
• No indicates that the element / attribute will either not be included by the payment application, or it will be included but will not contain valid data.  These fields are also be marked in pink.

By definition if an element is marked as Yes then all attributes / children of that element will also be 'Yes' unless otherwise indicated, and vice versa.

Mandatory elements

Messages from the ECR to the terminal are validated against the EPAS XML message schema.  That means that data elements that are mandatory in the message must be included, even if this document says that they are not used, i.e. marked in red.

Where a data element is not used then the contents of that element are ignored, and all that is needed is to ensure that it meets the schema requirements.

Variations from the EPAS Specification

New message fields have been highlighted with a yellow background. These are not part of the EPAS specification.  Fields that are not supported are marked with a pink background. This is the case even if the EPAS specification indicates that those fields are mandatory.

Login message

The Login request is sent by the ECR to enable the payment application on the terminal to process transactions.  It contains the three elements required for transaction processing, specifically:

1. The terminal's TSP ID (the POIID data element in the message header);
2. The PPL server that the payment application should go to for configuration data (ConfigHostAddress);
3. The SPDH server that the payment application should use for transaction authorisation (TxnHostAddress).

If the terminal supports multiple concurrent TSP IDs ("Multi-TID") then the alternative TSP IDs can be specified in the ExtraPOIID element. These are in addition to the main TSP ID which still has to be put in the POIID element in the message header.

Login request message

Login request example

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Service" MessageCategory="Login" MessageType="Request" ServiceID="2251" WorkstationID="" POIID="52400004" />
   <LoginRequest OperatorLanguage="en" OperatorID="Cashier16" ShiftNumber="2" POISerialNumber="78910AA46010005">
      <DateTime>2015-11-18T16:21:07.1480037+00:00</DateTime>
      <ExtraPOIID>52400005 52400006 52400007 52400008</ExtraPOIID>
      <SaleSoftware ManufacturerID="PointOfSaleCo" ApplicationName="SaleSys" SoftwareVersion="01.98.01" CertificationCode="ECTS2PS001" />
      <ConfigData>
         <TxnHostAddress>192,168.0.10:45002</TxnHostAddress>
         <ConfigHostAddress>192.168.0.10:21</ConfigHostAddress>
         <ConfigFile />
      </ConfigData>
      <StorePay ID="OSAIKTest" Password="684479" />
   </LoginRequest>
</SaleToPOIRequest>

Login response message

Login response example

<SaleToPOIResponse>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Service" MessageCategory="Login" MessageType="Response" ServiceID="2251" WorkstationID="" POIID="52400004" />
   <LoginResponse>
      <Response Result="Success" />
      <POISystemData>
         <DateTime>2015-11-18T16:21:07.0+00:00</DateTime>
         <POISoftware ManufacturerID="" ApplicationName="" SoftwareVersion="0.0.0" CertificationCode="" />
         <POITerminalData TerminalEnvironment="Attended" POISerialNumber="D0029">
            <POICapabilities>CustomerDisplay CustomerError CustomerInput MagStripe ICC</POICapabilities>
         </POITerminalData>
      </POISystemData>
   </LoginResponse>
</SaleToPOIResponse>

Logout message

The Logout request is the reverse of the Login request.  It may be sent by the ECR when one of the Login request parameters changes, e.g. the cashier ID, or it may be sent at close of business as a way to place the terminal in an idle mode.

Logout request message

The logout request message contain only the message header and a single LogoutRequest element.  It has no children or attributes.

Logout request example

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Service" MessageCategory="Logout" MessageType="Request" ServiceID="4783" WorkstationID="" POIID="52400004" />
   <LogoutRequest />
</SaleToPOIRequest>

Logout response message

Logout response example

<SaleToPOIResponse>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Service" MessageCategory="Logout" MessageType="Response" ServiceID="2252" WorkstationID="" POIID="52400004" />
   <LogoutResponse>
      <Response Result="Success" />
   </LogoutResponse>
</SaleToPOIResponse>

Admin message

The Admin message allows the ECR to request specific administrative tasks from the payment application on the terminal.  These are not related to an ongoing transaction.

Admin request

Admin request message

ServiceIdentification field

Possible Values:

Admin request example

<SaleToPOIRequest>
   <MessageHeader MessageClass="Service" MessageCategory="Admin" MessageType="Request" ServiceID="2254" WorkstationID="" POIID="52400004" />
   <AdminRequest>
      <ServiceIdentification>HostLogin</ServiceIdentification>
   </AdminRequest>
</SaleToPOIRequest>

Admin response message

Admin response example

<SaleToPOIResponse>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Service" MessageCategory="Admin" MessageType="Response" ServiceID="2254" WorkstationID="" POIID="52400004" />
   <AdminResponse>
      <Response Result="Success" />
   </AdminResponse>
</SaleToPOIResponse>

Enable Service message

The Enable Service message provides support to enable / disable the card readers outside of a transaction.  This allows the terminal to collect card details and perform initial checks and data acquisition ahead of the actual transaction, saving time for the customer since they can have the card ready to go while the cashier is busy.

Enable Service request message

TransactionAction field

When TransactionAction is set to "StartTransaction" then this request instructs the terminal to open the card readers and process any presented card data prior to the start of a transaction. This request does not itself indicate the start of a transaction, and a Payment request is still required (see below).

When TransactionAction is set to "AbortTransaction" then the card readers are closed and cards are not processed.

Enable Service request example

<SaleToPOIRequest>
   <MessageHeader MessageClass="Service" MessageCategory="EnableService" MessageType="Request" ServiceID="2255" WorkstationID="" POIID="52400004" />
   <EnableServiceRequest TransactionAction="StartTransaction" />
</SaleToPOIRequest>

Enable Service response message

Enable Service response example

<SaleToPOIResponse>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Service" MessageCategory="EnableService" MessageType="Response" ServiceID="2255" WorkstationID="" POIID="52400004" />
   <EnableServiceResponse>
      <Response Result="Success" />
   </EnableServiceResponse>
</SaleToPOIResponse>

Payment message

A Payment request sent by the ECR indicates the start of a transaction. It may include amount data, in which case the transaction can proceed normally, or it may exclude amount data in which case the amount data is provided later when known (the 'swipe-ahead' scenario.)

Payment request message

Payment request example

<SaleToPOIRequest>
   <MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="4779" WorkstationID="" POIID="52400004" />
   <PaymentRequest>
      <SaleData>
         <SaleTransactionID TransactionID="2587" TimeStamp="2017-07-05T17:04:50.0539062+01:00" />
      </SaleData>
      <PaymentTransaction>
         <AmountsReq Currency="SEK" RequestedAmount="1000" CashBackAmount="0" TipAmount="0.00" />
         <TransactionConditions LoyaltyHandling="Forbidden" />
      </PaymentTransaction>
      <PaymentData PaymentType="Normal">
         <PaymentInstrumentData PaymentInstrumentType="Card">
            <CardData EntryMethod="Manual">
               <SensitiveCardData PAN="5301250070000050" CardSeqNumb="01" ExpirationDate="0415" />
            </CardData>
         </PaymentInstrumentData>
      </PaymentData>
   </PaymentRequest>
</SaleToPOIRequest>

Payment request example (specifying Alternative Payment Method to use)

<SaleToPOIRequest>
   <MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="4779" WorkstationID="" POIID="52400004" />
   <PaymentRequest>
      <SaleData>
         <SaleTransactionID TransactionID="2587" TimeStamp="2017-07-05T17:04:50.0539062+01:00" />
      </SaleData>
      <PaymentTransaction>
         <AmountsReq Currency="SEK" RequestedAmount="1000" CashBackAmount="0" TipAmount="0.00" />
         <TransactionConditions LoyaltyHandling="Forbidden" />
      </PaymentTransaction>
      <PaymentData PaymentType="Normal" Method="Swish" />
   </PaymentRequest>
</SaleToPOIRequest>

Payment response message

Payment response example

<SaleToPOIResponse>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Service" MessageCategory="Payment" MessageType="Response" ServiceID="4778" WorkstationID="" POIID="52400004" />
   <PaymentResponse>
      <Response Result="Success" />
      <POIData>
         <POITransactionID TransactionID="000000402768" TimeStamp="2017-07-05T14:42:14.0+00:00" />
      </POIData>
      <PaymentResult PaymentType="Normal">
         <AmountsResp AuthorizedAmount="1000.00" />
      </PaymentResult>
   </PaymentResponse>
</SaleToPOIResponse>

Loyalty Message

A Loyalty request message is sent from the terminal to the ECR when a card is read and the card is confirmed as a loyalty card.  Note that PCI rules prohibit sending payment card details to the ECR  without encryption, therefore combined payment / loyalty cards are treated only as payment cards when the payment application is running EPAS.

Loyalty request message

Loyalty request example

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Device" MessageCategory="Loyalty" MessageType="Request" ServiceID="0" DeviceID="21" WorkstationID="" POIID="52400004" />
   <LoyaltyRequest>
      <SaleData>
         <SaleTransactionID TransactionID="" TimeStamp="0001-01-01T00:00:00.0+00:00" />
      </SaleData>
      <LoyaltyTransaction LoyaltyTransactionType="Award" Currency="SEK" TotalAmount="0.00" />
      <LoyaltyData>
         <LoyaltyAccountID EntryMethod="MagStripe" IdentificationType="PAN">
            <LoyaltyID>4581980303310132</LoyaltyID>
         </LoyaltyAccountID>
      </LoyaltyData>
   </LoyaltyRequest>
</SaleToPOIRequest>

Loyalty response message

Loyalty response example

<SaleToPOIResponse>
   <MessageHeader MessageClass="Service" MessageCategory="Loyalty" MessageType="Response" DeviceID="21" ServiceID="0" WorkstationID="" POIID="52400004" />
   <LoyaltyResponse>
      <Response Result="Success" />
      <POIData BatchID="">
         <POITransactionID TransactionID="" TimeStamp="2012-05-04T10:45:35.6+01:00" />
      </POIData>
   </LoyaltyResponse>
</SaleToPOIResponse>

Reversal Message

The Reversal request informs the terminal that the previous transaction must be reversed. Only the most recent transaction can be reversed, and when a new transaction is started then the previous transaction can no longer be reversed.

Reversal request message

Reversal request example

<SaleToPOIRequest>
   <MessageHeader MessageClass="Service" MessageCategory="Reversal" MessageType="Request" ServiceID="74" WorkstationID="" POIID="52400004" />
   <ReversalRequest ReversalReason="CustCancel">
      <OriginalTransaction WorkstationID="" POIID="52400004">
         <POITransactionID TransactionID="524000040436" TimeStamp="2012-05-04T16:05:21.0+00:00" />
      </OriginalTransaction>
   </ReversalRequest>
</SaleToPOIRequest>

Reversal response message

Reversal response example

<SaleToPOIResponse>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Service" MessageCategory="Reversal" MessageType="Response" ServiceID="77" WorkstationID="" POIID="52400004" />
   <ReversalResponse>
      <Response Result="Success" />
      <POIData>
         <POITransactionID TransactionID="" TimeStamp="0001-01-01T00:00:00.0+00:00" />
      </POIData>
   </ReversalResponse>
</SaleToPOIResponse>

Display Message

The EPAS specification defines the display processing as symmetrical, i.e. the ECR and the payment terminal can each send requests to the other to request that something is displayed on screen.  In practice there is limited support for this arrangement:

• Display request from the terminal:  The West payment application will sending display requests to the ECR to inform the cashier of the transaction progress and also to get input from the cashier.
• Display request from the ECR:  This is only supported in one specific case, which is to display a QR code on the screen of the payment application in order to support alternative payment methods.  The payment application will not handle requests to display text on the terminal's screen.

Display request message, when sent by the payment application

The ECR can use the display requests to track the progress of a transaction by checking the prompt ID. This allows the ECR / cashier to be aware of what stage the transaction has reached.  The prompt IDs are included in a table below.

The Display Request message shall be sent for every time the payment terminal prompts for new information, e.g. insert card, enter PIN, pin invalid – try again. The Display Request message is defined in section 4.5.2.3 of the EPAS specification. The payment terminal does not expect a response to this message. Display Response messages will be ignored.

The display output text will be provided in the chosen operator language, which may be different to the cardholder language being used on the terminal. To make it easier for the ECR device to know exactly which step the payment processing has reached, an enumerated type is added to the message. This will be constant regardless of the display language and uniquely identify each step.

Prompt ID

Where appropriate, the PromptID element contains the number of the screen being displayed as defined in the Carholder and Operator Interface specification (CHAOI).  For example, CHAOI screen reference 611 indicates that the terminal is waiting for a new customer, while 662 indicates an approved signature transaction.

CHAOI does not cover all the displays that are needed to operate the payment application.  The list below shows the custom prompts that have been implemented by the application but that are not covered in the CHAOI.

Custom Prompt IDs

ECR Input

The Display request has an optional Input component, discussed above. This indicates to the ECR that a response may be sent back to the terminal. Some of those responses are optional while some are required. Responses are always in text form, but the response may need to be formatted in a certain way. Some responses are items selected from a list of possibilities. Table 2 shows which responses are possible for each of the prompts that include an Input component.
Prompts are sent back to the terminal as an Input response message.

Responses to Input components in Display requests

Display request examples

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Device" MessageCategory="Display" MessageType="Request" ServiceID="4784" DeviceID="5" WorkstationID="" POIID="52400004" />
   <DisplayRequest>
      <DisplayOutput ResponseRequiredFlag="false" Device="CashierDisplay" InfoQualify="POIReplication">
         <OutputContent OutputFormat="Text">
            <OutputText>Invalid logon</OutputText>
            <OutputText>Call helpdesk Support</OutputText>
         </OutputContent>
      </DisplayOutput>
      <PromptId>682</PromptId>
   </DisplayRequest>
</SaleToPOIRequest>

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Device" MessageCategory="Display" MessageType="Request" ServiceID="4788" DeviceID="12" WorkstationID="" POIID="52400004" />
   <DisplayRequest>
      <DisplayOutput ResponseRequiredFlag="false" Device="CashierDisplay" InfoQualify="POIReplication">
         <OutputContent OutputFormat="Text">
            <OutputText>New customer</OutputText>
            <OutputText>Waiting for card</OutputText>
         </OutputContent>
      </DisplayOutput>
      <PromptId>612</PromptId>
      <Input Type="OptionList">
         <Option>Swedish</Option>
         <Option>English</Option>
         <Option>Norwegian</Option>
      </Input>
   </DisplayRequest>
</SaleToPOIRequest>

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Device" MessageCategory="Display" MessageType="Request" ServiceID="4791" DeviceID="19" WorkstationID="" POIID="52400004" />
   <DisplayRequest>
      <DisplayOutput ResponseRequiredFlag="false" Device="CashierDisplay" InfoQualify="POIReplication">
         <OutputContent OutputFormat="Text">
            <OutputText>1 000,00 SEK</OutputText>
            <OutputText>VISA</OutputText>
            <OutputText>Verify signature</OutputText>
         </OutputContent>
      </DisplayOutput>
      <PromptId>662</PromptId>
      <Input Type="OptionList" Required="Yes">
        <Option>yes</Option>
        <Option>no</Option>
      </Input>
   </DisplayRequest>
</SaleToPOIRequest>

Display request message, when sent by the ECR

There is only one situation where the ECR can send a display request to the payment application, and that is to display a QR code on the terminal screen.  The payment application will only display the QR code if that feature is enabled in configuration, and also it will only display the QR code at specific times.  So this display request can be interpreted as supplying a QR code value to be displayed when appropriate, rather than to be displayed at the time the message is sent.

If the QR code is no longer required then a new request can be sent where the QR code value is empty.

Display request example

<SaleToPOIRequest>
   <MessageHeader MessageClass="Device" MessageCategory="Display" MessageType="Request" WorkstationID="" POIID="52400004" />
   <DisplayRequest>
      <DisplayOutput Device="CustomerDisplay" InfoQualify="Display" ResponseRequiredFlag="true">
         <OutputContent OutputFormat="BarCode">
            <OutputBarcode BarcodeValue="http://www.westint.se/produkter-och-tjanster/#kortterminaler" />
         </OutputContent>
      </DisplayOutput>
   </DisplayRequest>
</SaleToPOIRequest>

Input response

The terminal application does not support the Input request message. Instead, if a response is required from the ECR then the information will be included in the optional Input element of the Display request that prompts for the information (see above).

Cashier responses are sent to the payment terminal using the Input response message.

The Input response message is also used to inform that application of the transaction amounts in cases where the Payment request was sent with no amount information.

Note that the Input response may be sent to the payment terminal without a previous Input request having been issued (since Input request is not supported).

Input response message

InputCommand Field

There are three forms of the Input response message, and these are controlled by the InputCommand attribute.  The three options for InputCommand are:

"TransactionAmount"

 This is used to supply the amount details for a swipe-ahead transaction has that already begun.  A swipe-ahead transaction is one that is launched with zero amounts, in which case the payment application will wait for the amount data to be supplied via this input response mechanism.

In this case the AmountsReq element must be provided.

"NonPciCardData"

The ECR can supply card data for a non-PCI card via an Input response message.  This is done instead of the cardholder presenting the card on the terminal.

In this case the card number is given in the "Number" attribute and the expiry data in the "Expiry" attribute.

Prompt ID

If the InputCommand attribute contains the numeric prompt ID of a previous display request then the content of the TextInput attribute is interpreted as the ECR's response.

Input response examples

Example response to choose signature verification

Here the cashier has requested signature verification at the PIN entry stage (prompt 652)

<SaleToPOIResponse>
   <MessageHeader MessageClass="Device" MessageCategory="Input" MessageType="Response" ServiceID="4792" DeviceID="1" WorkstationID="" POIID="52400004" />
   <InputResponse>
      <InputResult Device="CashierInput" InfoQualify="Input">
         <Response Result="Success" />
         <Input InputCommand="652">
         <TextInput>sign</TextInput>
         </Input>
      </InputResult>
   </InputResponse>
</SaleToPOIResponse>

Example response to signature verification

Here the cashier has confirmed that the signature is correct (prompt 662)

<SaleToPOIResponse>
   <MessageHeader MessageClass="Device" MessageCategory="Input" MessageType="Response" ServiceID="4793" DeviceID="2" WorkstationID="" POIID="52400004" />
   <InputResponse>
      <InputResult Device="CashierInput" InfoQualify="Input">
         <Response Result="Success" />
         <Input InputCommand="662">
         <TextInput>yes</TextInput>
         </Input>
      </InputResult>
   </InputResponse>
</SaleToPOIResponse>

Example swipe-ahead amount supply

Here the ECR is providing the transaction amounts in a swipe-ahead transaction.  Note that the transaction value in this example will be 950.00.

<SaleToPOIResponse>
   <MessageHeader MessageClass="Device" MessageCategory="Input" MessageType="Response" ServiceID="4797" DeviceID="4" WorkstationID="" POIID="52400004" />
   <InputResponse>
      <InputResult Device="CashierInput" InfoQualify="Input">
         <Response Result="Success" />
         <Input InputCommand="TransactionAmount">
         <AmountsReq Currency="SEK" RequestedAmount="850" CashBackAmount="100" VatAmount="0.00" />
         </Input>
      </InputResult>
   </InputResponse>
</SaleToPOIResponse>

Example non-PCI card presentation

Here the ECR is providing the details of a non-PCI card.

<SaleToPOIResponse>
   <MessageHeader MessageClass="Device" MessageCategory="Input" MessageType="Response" ServiceID="4799" DeviceID="4" WorkstationID="" POIID="52400004" />
   <InputResponse>
      <InputResult Device="CashierInput" InfoQualify="Input">
         <Response Result="Success" />
         <Input InputCommand="NonPciCardData">
            <NonPciCardData Number="9752276400000003" Expiry="0821" />
         </Input>
      </InputResult>
   </InputResponse>
</SaleToPOIResponse>

Print request - terminal to ECR

The Print request message is sent by the terminal to request the ECR to print, normally, a card receipt, but it is also used for error message and reports.

The EPAS specification defines the printed content as a series of text elements, each with a set of attributes, but even though this seems like a flexible approach it means that the exact layout of the receipt becomes the responsibility of the payment application, even though it does not know what type of printer is in use, or the paper size, etc.  The payment application uses a substantially altered print request message where each data element is provided separately and then it is up to the ECR to decide how the receipt should be formatted.

When sending receipt data the print request message includes a pre-formatted receipt, but this is intended for debug / test purposes and may not be supported in the future.  It is strongly recommended that integrators should use the individual data elements provided and construct the receipt according to the applicable layout rules.

Note that the terminal does not expect to receive, and will not wait for, a Print response message.

Print request message

Print request examples

Normal purchase approval example

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Device" MessageCategory="Print" MessageType="Request" ServiceID="4791" DeviceID="20" WorkstationID="" POIID="52400004" />
   <PrintRequest>
      <PrintOutput DocumentQualifier="CustomerReceipt" ResponseMode="NotRequired" RequiredSignatureFlag="true">
         <OutputContent OutputFormat="Text">
            <OutputText>          HN-28

Test Shop
1 The High Street
IV51 9LP Somewhere
08-12 34 56
Org. nr: 123456-1234

Test Bank
Butiksnr: 2337335
Termid: 52400004
Kassörsnr: Cashier16
Thu 27 Jul 2017      17:06

KÖP
SEK                1000.00
TOTALT:            1000.00


************3825

VISA
C@1 3 001 SWE 170 968081

Ref. nr: 000000402771

AID: A0000000031010
TVR: 0000080000
TSI: F800
</OutputText>
         </OutputContent>
      </PrintOutput>
      <ReceiptData>
         <Transaction Status="AUTHORISED" />
         <MerchantData Name="Test Shop" Address="1 The High Street" City="Somewhere" ZipCode="IV51 9LP" PhoneNumber="08-12 34 56" OrganisationNumber="123456-1234" HelplineNumber="Support" />
         <BankAgentName>Test Bank</BankAgentName>
         <AcquirerReference>2337335</AcquirerReference>
         <TerminalId>52400004</TerminalId>
         <OperatorId>Cashier16</OperatorId>
         <TransactionData Type="Debit" DateTime="2017-07-27T17:06:13.0+00:00" CurrencyCode="SEK" CurrencyNum="SEK" Amount="1000.00" CashBack="0.00" Gratuity="0.00" Vat="0.00" CashAdvanceCharge="0.00" Total="1000.00" ReferenceNumber="000000402771" />
         <AuthorisationData PosEntryMode="C" IdMethod="@" Channel="1" Responder="3" ResponseCode="001" FinancialInstitution="SWE" BatchNumber="170" ApprovalCode="968081" />
         <CardData MaskedPan="************3825" Name="VISA" PaymentCode="" />
         <EmvData ApplicationId="A0000000031010" Tvr="0000080000" Tsi="F800" ResponseCode="00" PanSequenceNumber="0" />
      </ReceiptData>
   </PrintRequest>
</SaleToPOIRequest>

Signature authorisation example

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Device" MessageCategory="Print" MessageType="Request" ServiceID="4791" DeviceID="16" WorkstationID="" POIID="52400004" />
   <PrintRequest>
      <PrintOutput DocumentQualifier="CashierReceipt" ResponseMode="NotRequired" RequiredSignatureFlag="true">
         <OutputContent OutputFormat="Text">
            <OutputText>          HN-28

Test Shop
1 The High Street
IV51 9LP Somewhere
08-12 34 56
Org. nr: 123456-1234

Test Bank
Acq Ref: 2337335
Termid: 52400004
Cashier No: Cashier16
Thu 27 Jul 2017      17:06

PURCHASE
SEK                1000.00
TOTAL:             1000.00


458109******3825

VISA

   AUTHORISATION FOR 
 DEBITING ABOVE ACCOUNT 


.........................
LEG


.........................
SIGN

C@1 3 001 SWE 170 968081

Ref. nr: 000000402771

AID: A0000000031010
TVR: 0000080000
TSI: F800
</OutputText>
         </OutputContent>
      </PrintOutput>
      <ReceiptData>
         <Transaction Status="AUTHORISED" />
         <MerchantData Name="Test Shop" Address="1 The High Street" City="Somewhere" ZipCode="IV51 9LP" PhoneNumber="08-12 34 56" OrganisationNumber="123456-1234" HelplineNumber="Support" />
         <BankAgentName>Test Bank</BankAgentName>
         <AcquirerReference>2337335</AcquirerReference>
         <TerminalId>52400004</TerminalId>
         <OperatorId>Cashier16</OperatorId>
         <TransactionData Type="Debit" DateTime="2017-07-27T17:06:13.0+00:00" CurrencyCode="SEK" CurrencyNum="SEK" Amount="1000.00" CashBack="0.00" Gratuity="0.00" Vat="0.00" CashAdvanceCharge="0.00" Total="1000.00" ReferenceNumber="000000402771" />
         <AuthorisationData PosEntryMode="C" IdMethod="@" Channel="1" Responder="3" ResponseCode="001" FinancialInstitution="SWE" BatchNumber="170" ApprovalCode="968081" />
         <CardData MaskedPan="458109******3825" Name="VISA" PaymentCode="" />
         <EmvData ApplicationId="A0000000031010" Tvr="0000080000" Tsi="F800" ResponseCode="00" PanSequenceNumber="0" />
      </ReceiptData>
   </PrintRequest>
</SaleToPOIRequest>

Alternative Payment purchase approval example

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Device" MessageCategory="Print" MessageType="Request" ServiceID="4791" DeviceID="20" WorkstationID="" POIID="52400004" />
   <PrintRequest>
      <PrintOutput DocumentQualifier="CustomerReceipt" ResponseMode="NotRequired" RequiredSignatureFlag="true">
         <OutputContent OutputFormat="Text">
            <OutputText>          HN-28

Test Shop
1 The High Street
IV51 9LP Somewhere
08-12 34 56
Org. nr: 123456-1234

Test Bank
Butiksnr: 2337335
Termid: 52400004
Kassörsnr: Cashier16
Thu 27 Jul 2017      17:06

KÖP
SEK                1000.00
TOTALT:            1000.00


************3825

Swish

Ref. nr: 000000402771

</OutputText>
         </OutputContent>
      </PrintOutput>
      <ReceiptData>
         <Transaction Status="AUTHORISED" AlternativePaymentMethod="Swish" />
         <MerchantData Name="Test Shop" Address="1 The High Street" City="Somewhere" ZipCode="IV51 9LP" PhoneNumber="08-12 34 56" OrganisationNumber="123456-1234" HelplineNumber="Support" />
         <BankAgentName>Test Bank</BankAgentName>
         <AcquirerReference>2337335</AcquirerReference>
         <TerminalId>52400004</TerminalId>
         <OperatorId>Cashier16</OperatorId>
         <TransactionData Type="Debit" DateTime="2017-07-27T17:06:13.0+00:00" CurrencyCode="SEK" CurrencyNum="SEK" Amount="1000.00" CashBack="0.00" Gratuity="0.00" Vat="0.00" CashAdvanceCharge="0.00" Total="1000.00" ReferenceNumber="000000402771" />
         <AuthorisationData PosEntryMode="A" IdMethod="-" Channel="1" Responder="0" ResponseCode="000" FinancialInstitution="SWI" BatchNumber="" ApprovalCode="900164" />
      </ReceiptData>
   </PrintRequest>
</SaleToPOIRequest>

DCC example

Note: this example uses test data that has been hard-coded.  The calculations regarding the rate conversion are not correct.

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Device" MessageCategory="Print" MessageType="Request" ServiceID="4803" DeviceID="21" WorkstationID="" POIID="52400004" />
   <PrintRequest>
      <PrintOutput DocumentQualifier="CustomerReceipt" ResponseMode="NotRequired">
         <OutputContent OutputFormat="Text">
            <OutputText>          HN-28

Test Shop
1 The High Street
IV51 9LP Somewhere
08-12 34 56
Org. nr: 123456-1234

Test Bank
Butiksnr: 2337335
Termid: 52400004
Kassörsnr: Cashier16
Tue 1 Aug 2017       17:36

KÖP
SEK                 600.00
Txn currency EUR    120.39
Exchange rate       0.8246
MarkUp               3.25%
MarkUp Above European
Central Bank
Source: Fake DCC bank

************3825

VISA
MEDGES EJ
NEKAT
Ca1 0 898 BAM 171 000000

Ref. nr: 000000402773

AID: A0000000031010
TVR: 0000000000
TSI: E800
</OutputText>
         </OutputContent>
      </PrintOutput>
      <ReceiptData>
         <Transaction Status="DECLINED" DenialReason="NEKAT" />
         <MerchantData Name="Test Shop" Address="1 The High Street" City="Somewhere" ZipCode="IV51 9LP" PhoneNumber="08-12 34 56" OrganisationNumber="123456-1234" HelplineNumber="Support" />
         <BankAgentName>Test Bank</BankAgentName>
         <AcquirerReference>2337335</AcquirerReference>
         <TerminalId>52400004</TerminalId>
         <OperatorId>Cashier16</OperatorId>
         <TransactionData Type="Debit" DateTime="2017-08-01T17:36:41.0+00:00" CurrencyCode="SEK" CurrencyNum="SEK" Amount="600.00" CashBack="0.00" Gratuity="0.00" Vat="0.00" 
                          CashAdvanceCharge="0.00" Total="600.00" ReferenceNumber="000000402773" />
         <AuthorisationData PosEntryMode="C" IdMethod="a" Channel="1" Responder="0" ResponseCode="898" FinancialInstitution="BAM" BatchNumber="171" ApprovalCode="000000" />
         <CardData MaskedPan="************3825" Name="VISA" PaymentCode="" />
         <EmvData ApplicationId="A0000000031010" Tvr="0000000000" Tsi="E800" ResponseCode="05" PanSequenceNumber="0" />
         <DCC Provider="Fake DCC responder" Rate="0.8246" Source="Fake DCC bank" DateTime="2017-08-01T17:36" Amount="120.39" CurrencyNum="978" 
              CurrencyCode="EUR" Exponent="2" MarkUp="3.25" MarkUpDescription="MarkUp above European Central Bank" Gratuity="0.00" Scheme="V"
              Disclaimer="Cardholder has chosen to pay in EUR. This transaction is based on Fake DCC bank exchange rate of 01 Aug 2017 incl. 3.25 percent international 
              conversion margin.\nThis is not an additional fee and replaces Currency Conversion charges normally applied. My choice is final. Transactions can also be 
              conducted in SEK. This Dynamic currency conversion service is provided by Fake DCC responder." />
      </ReceiptData>
   </PrintRequest>
</SaleToPOIRequest>

Print request - ECR to terminal

The ECR can send a print request to the terminal, but this is a very specific and limited implementation.  Support for this is a specific configuration option that must be enabled in the terminal.  The print request can only contain a monochrome Windows bitmap (.BMP) image and it must be no wider than 384 pixels.

The image data is prepared by taking the contents of a bitmap file and compressing it using the gzip compression algorithm.  It is then encoded using base64.  An example of this preparation is as follows:

byte[] compressed = null;
string base64String = null;
using (Stream fs = File.OpenRead(filename))
{
    using (MemoryStream ms = new MemoryStream())
    {
        // Read the file into a GZip compressor
        using (GZipStream gz = new GZipStream(ms, CompressionMode.Compress))
        {
            int bytesRead;
            byte[] buffer = new byte[1000];
            while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) > 0)
            {
                gz.Write(buffer, 0, bytesRead);
            }
            compressed = ms.ToArray();
            base64String = Convert.ToBase64String(compressed, 0, compressed.Length);
        }
    }
}

Print request message

Print request example

<SaleToPOIRequest>
   <MessageHeader MessageClass="Device" MessageCategory="Print" MessageType="Request" DeviceID="4" WorkstationID="" POIID="10.0.1.156:8002" />
   <PrintRe<SaleToPOIRequest>
   <MessageHeader MessageClass="Device" MessageCategory="Print" MessageType="Request" DeviceID="4" WorkstationID="" POIID="10.0.1.156:8002" />
   <PrintRequest>
      <PrintOutput DocumentQualifier="CustomerReceipt" ResponseMode="PrintEnd">
         <OutputContent OutputFormat="Bitmap">
            <Bitmap ImageData="H4sIAAAAAAAEAO29B2AcSZYlJi9tynt/SvV ......." />
         </OutputContent>
      </PrintOutput>
   </PrintRequest>
</SaleToPOIRequest>

Print response message

Abort message

The Abort request message instructs the terminal to cancel the ongoing service request.  If there is no ongoing service request then the abort request will be ignored.

Note that there is no abort response; nstead, the normal service response will be sent.  For example, if a payment request is aborted then the payment response will be sent with the appropriate values in place.

If the abort request is received but the ongoing service request cannot be aborted then an event notification with a Reject status (see below) will be sent to indicate this.

Note that the terminal will regard the request as applying to the service that is active at the time when the request is received, and will not use the ServiceID component.  The MessageCategory value is only used in an error response, and is otherwise ignored.

Abort request message

Abort Request Example

<SaleToPOIRequest> 
   <MessageHeader MessageClass ="Service" MessageCategory ="Abort" MessageType ="Request" ServiceID ="106" WorkstationID ="" POIID ="52400004" /> 
   <AbortRequest> 
      <MessageReference MessageCategory ="Payment" ServiceID ="105" /> 
      <AbortReason>Abort button clicked</AbortReason> 
   </AbortRequest> 
</SaleToPOIRequest>

Event Notification

The Event Notification message is essentially as defined in the EPAS specification, but extends the list of events that can be notified.
The following values are used in the Event Notification message's EventToNotify element.

• BeginMaintenance
• EndMaintenance
• Shutdown
• CardInserted
• CardRemoved
• CardAccepted (extension to EPAS specification)
• Completed
• EventLog (extension to EPAS specification)
• Reject

CardAccepted

This event notification is sent when a card is recognised as a valid payment card, i.e. it has a BIN row and is considered as acceptable by the application. In a Swipe Ahead scenario there may be multiple CardAccepted notifications if the cardholder inserts multiple cards.

EventLog

This event notification carries the section of event log that has built up since the last time that this notification was sent, i.e. it sends incremental event log additions to the ECR.
This event notification is sent immediately after a Login response, Reversal response and a Payment response.

Event notification message

Event notification example

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Event" MessageCategory="Event" MessageType="Notification" DeviceID="3" WorkstationID="" POIID="52400004" />
   <EventNotification TimeStamp="2017-07-25T10:15:22.0+00:00" EventToNotify="BeginMaintenance">
      <EventDetails>POI Maintenance: Updating and loading parameters</EventDetails>
   </EventNotification>
</SaleToPOIRequest>

Event notification with log extract

<SaleToPOIRequest>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Event" MessageCategory="Event" MessageType="Notification" DeviceID="21" WorkstationID="" POIID="52400004" />
   <EventNotification TimeStamp="2017-07-25T12:40:49.0+00:00" EventToNotify="EventLog">
      <EventDetails>[2017-07-25T12:39:15 52400004 D0029 Status] Request denied:  Close batch is overdue
[2017-07-25T12:39:20 52400004 D0029 Status] Commencing Close Batch
[2017-07-25T12:39:34 52400004 D0029 Status] New transaction: Payment Request 4788: Payment Request: Amount 1000.00 Cashback: 0.00 ID: 2589, Time: 7/25/2017 10:39:33 AM, Type: Normal
[2017-07-25T12:40:47 52400004 D0029 Warning] Abandoning transaction:  -- User cancellation
[2017-07-25T12:40:47 52400004 D0029 Status] Transaction:  Type=PurchaseRequest Ref=000000402769 Status=0x105  ////  Amounts: Main=1 000,00 SEK  Cashback=0,00 SEK  Extra=0,00 SEK  CA Charge=0,00 SEK  ////  EMV: TVR=0000000000 TSI=0000 AID=A000000003-1010  ////  Card: Name=VISA Type=Debit card Issuer=Swedbank Product=Visa  ////  
[2017-07-25T12:40:47 52400004 D0029 Status] Abandoning PurchaseRequest
[2017-07-25T12:40:47 52400004 D0029 Status]  Ret. Ref. No: 000000402769
</EventDetails>
   </EventNotification>
</SaleToPOIRequest>

Reconciliation message

Note:

The Reconciliation message is obsolete from v1.22.3, hence the response message will only return Success as Result. 

Reconciliation request message