Page tree
Skip to end of metadata
Go to start of metadata

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 10th October 2010
  2. BABS and CEKAB Cardholder and Operator InterfaceVersion 4.02, Date 25th 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

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:

Data Element

Definition

ProtocolVersion

Version of the EPAS Sale to POI protocol specification.
The field is mandatory for a Login request, absent for other messages.  See section 3.4.3 of the EPAS specification.

MessageClass

Message class.  See section 3.4.2 of the EPAS specification.

MessageCategory

Category of message. See section 3.4.1.3 of the EPAS specification.

MessageType

Message type.  See section 3.4.1.3 of the EPAS specification.

ServiceID

The service ID, used to identify a request / response dialogue.

DeviceID

The ID of a device class message, used to match a request and response message pair.

WorkstationID

Identifies the terminal in respect of the EPAS protocol.  Once the workstation ID is established, any messages with a different workstation ID will be ignored.

POIID

Identifies the terminal in respect of the wider payment processing system.  The terminal ID here is used in PPL configuration and SPDH authorisation requests.

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

Login request message

Component

Mult.

Rule

Usage

LoginRequest

[1..1]

 

 

DateTime

[1..1]

 

Yes

SalesSoftware

[1..1]

 

No

ManufacturerID

[1..1]

 

 

ApplicationName

[1..1]

 

 

SoftwareVersion

[1..1]

 

 

CertificationCode

[1..1]

 

 

SaleTerminalData

[0..1]

Present if the login involves a Sale Terminal

No

TerminalEnvironment

[1..1]

 

 

SaleCapabilities

[1..1]

 

 

SaleProfile

[0..1]

If at least one element is present

 

GenericProfile

[0..1]

default Standard

 

ServiceProfiles

[0..1]

If a service profile could be requested

 

TotalsGroupID

[0..1]

If present, default value for all transactions.

 

TrainingModeFlag

[0..1]

default False

No

OperatorLanguage

[1..1]

Default value for Device type displays.

Yes

OperatorID

[0..1]

Four conditions to send it:
a) the Sale System wants the POI log it in the transaction log
b) because of reconciliation with total on OperatorID
c) because the POI needs it d) acquirer or issuer need it

Yes

ShiftNumber

[0..1]

Same as OperatorID

No

POISerialNumber

[0..1]

If the login involves a POI Terminal and not the first Login to the POI System

No

ConfigData

[0..1]

 

Yes

TxnHostAddress

[1..1]

This may be supplied as a name or a dotted format IP address.
The address may optionally include a port number.

 

ConfigHostAddress

[1..1]

This may be supplied as a name or a dotted format IP address.
The address may optionally include a port number.

 

ConfigFile

[1..1]Not currently used 

StorePay

[0..1]Used to define credentials for Svea StorePay / WebPay accessYes

ID

[1..1]Svea web API login ID 

Password

[1..1]Svea web API password 

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

Component

Mult.

Rule

Usage

LoginResponse

[1..1]

 

 

Response

[1..1]

 

Yes

Result

[1..1]

"Success" or "Failure".

 

ErrorCondition

[0..1]

Error classification in the failure case. See 2.7.5.3 in the EPAS specification.

 

AdditionalResponse

[0..1]

Description of the problem in the failure case.

 

POISystemData

[0..1]

if Response.Result is Success

Yes

DateTime

[1..1]

The current date and time on the terminal.

Yes

POISoftware

[1..1]

 

Yes

ManufacturerID

[1..1]

Empty

 

ApplicationName

[1..1]

Empty

 

SoftwareVersion

[1..1]

Payment application version.

 

CertificationCode

[1..1]

Empty

 

POITerminalData

[0..1]

Present if the login involves a POI Terminal.

Yes

TerminalEnvironment

[1..1]

"Attended"

 

POICapabilities

[1..1]

"CustomerDisplay CustomerError CustomerInput MagStripe ICC"

 

POIProfile

[0..1]

If at least one element is present.
The Sale System decides if it can continue or not.

No

GenericProfile

[0..1]

default Standard

 

ServiceProfiles

[0..1]

If a service profile could be requested

 

POISerialNumber

[1..1]

Terminal serial number

 

POIStatus

[0..1]

if Response.Result is Success

No

GlobalStatus

[1..1]

 

 

SecurityOKFlag

[0..1]

If security module present

 

PEDOKFlag

[0..1]

If PED present

 

CardReaderOKFlag

[0..1]

If card reader device present

 

PrinterOKFlag

[0..1]

If printer device present

 

CommunicationOKFlag

[0..1]

If communication infrastructure present

 

FraudPreventionFlag

[0..1]

Default False

 

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

Component

Mult.

Rule

Usage

LogoutResponse

[1..1]

 

 

Response

[1..1]

 

Yes

Result

[1..1]

"Success" or "Failure".

 

ErrorCondition

[0..1]

Error classification in the failure case. See 2.7.5.3 in the EPAS specification.

 

AdditionalResponse

[0..1]

Description of the problem in the failure case.

 

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

AdminRequest

Mult.

Profile

Rule

Usage

AdminRequest

[1..1]

 

AdminRequest.

 

ServiceIdentification

[0..1]

 

Required Service (see below).

Yes

OperatorID

[0..1]

Operator / cashier ID.

Used in message HostLogin when multiple merchants use the same terminal but with different terminal id:sYes

ServiceIdentification field

Possible Values:

ServiceIdentification

Function

ResetMerchantPassword

Resets the Merchant Password.

PrintLastEMVTransaction

Prints the EMV data from the last transaction (using a Print request message).

PrintTerminalConfig

Print details about the terminal's configuration (using a Print request message).

ExtractLogFiles

Sends the current trace log to the ECR via an FTP connection on port 21.

LogLevel_0

Log Error and Status level items.

LogLevel_1

Log Error and Status level items (same as LogLevel_0).

LogLevel_2

Log Warning, Error and Status level items.

LogLevel_3

Log Normal Debug, Warning, Error and Status level items.

LogLevel_4

Log High-volume Debug, Normal Debug, Warning, Error and Status level items

UpdateParametersInstructs the payment application to check for updated parameters on the PPL server, downloading and installing them if required.
HostLoginInstructs the payment application to perform a SPDH login transaction to the current SPDH host.
ExtractTransactionsRequests the payment application to report a summary of recent transactions.  See the associated additional documentation page for details.

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

AdminResponse

Mult.

Rule

Usage

AdminResponse

[1..1]

AdminResponse.

 

Response

[1..1]

 

 

Result

[1..1]

"Success" or "Failure".

Yes

ErrorCondition

[0..1]

Error classification in the failure case. See 2.7.5.3 in the EPAS specification.

Yes

AdditionalResponse

[0..1]

Description of the problem in the failure case.

Yes

AdditionalData[0..1]Additional data, depending on the nature of the requestYes

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

Component

Mult.

Rule

Usage

EnableService

[1..1]

 

 

TransactionAction

[1..1]

"StartTransaction" or "AbortTransaction"

Yes

ServicesEnabled

[0..1]

 

No

DisplayOutput

[0..1]

To display an abort message to the Customer.

No

Device

[1..1]

CustomerDisplay.

 

InfoQualify

[1..1]

Error.

 

OutputContent

[1..1]

 

 

OutputFormat

[1..1]

 

 

PredefinedContent

[0..1]

Same as Display.

 

ReferenceID

[1..1]

 

 

Language

[0..1]

Same as Display.

 

OutputText

[0..n]

Same as Display.

 

Text

[1..1]

 

 

CharacterSet

[0..1]

Same as Display.

 

Font

[0..1]

Same as Display.

 

StartRow

[0..1]

Same as Display.

 

StartColumn

[0..1]

Same as Display.

 

Color

[0..1]

Same as Display.

 

CharacterWidth

[0..1]

Same as Display.

 

CharacterHeight

[0..1]

Same as Display.

 

CharacterStyle

[0..1]

Same as Display.

 

Alignment

[0..1]

Same as Display.

 

OutputXHTML

[0..1]

Same as Display.

 

OutputSignature

[0..1]

If protection has to be provided to the vendor on the text to display.

 

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

Component

Mult.

Rule

Usage

EnableService

[1..1]

 

Yes

Response

[1..1]

 

 

Result

[1..1]

"Success" or "Failure".

 

ErrorCondition

[0..1]

Error classification in the failure case. See 2.7.5.3 in the EPAS specification.

 

AdditionalResponse

[0..1]

Description of the problem in the failure case.

 

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

Component

Mult.

Rule

Usage

PaymentRequest

[1..1]

 

 

SaleData

[1..1]

 

Yes

OperatorID

[0..1]

If different from the Login.

No

OperatorLanguage

[0..1]

If different from the Login.

No

ShiftNumber

[0..1]

If different from the Login.

No

SaleTransactionID

[1..1]

 

Yes

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

SaleReferenceID

[0..1]

If payment reservation.

No

SaleTerminalData

[0..1]

If content is not empty.

No

TerminalEnvironment

[0..1]

If modified since the login.

 

SaleCapabilities

[0..1]

If modified since the login (devices failures).

 

TotalsGroupID

[0..1]

If modified since, or not in the login and used by the Sale System.

 

SaleToPOIData

[0..1]

Stored with the transaction.

No

SaleToAcquirerData

[0..1]

Send to the Acquirer if present.

No

SaleToIssuerData

[0..1]

Send to the Acquirer if present.

No

StatementReference

[0..1]

Information to print on the bank statement.

No

PaymentTransaction

[1..1]

 

 

AmountsReq

[1..1]

 

 

Currency

[1..1]

 

Yes

RequestedAmount

[0..1]

 

Yes

CashBackAmount

[0..1]

If payment with cash back requested by the Sale System.

Yes

TipAmount

[0..1]

If this attribute is present with value 0 then tipping is disabled for the transaction. Otherwise it is ignored. Note that this attribute does not specify the amount of tip to be applied.

No

PaidAmount

[0..1]

If SplitPaymentFlag is True.

No

MinimumAmountToDeliver

[0..1]

If unknown maximum amount for a OneTimeReservation or minimum amount requested by the Sale System.

No

MaximumCashBackAmount

[0..1]

Maximum amount which could be requested for cash-back to the Sale System.

No

MinimumSplitAmount

[0..1]

Minimum amount of a split, which could be requested.

No

OriginalTransaction

[0..1]

If UpdateReservation, Completion or Refund.

No

POITransactionID

[0..1]

If SaleReferenceID is insufficient to identify the transaction.

 

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

POIID

[0..1]

If original transaction is coming from another POI.

No

ReuseCardDataFlag

[0..1]

Default True.

No

ApprovalCode

[0..1]

If referral.

No

TransactionConditions

[0..1]

If one data element is present.

Yes

AllowedPaymentBrand

[0..n]

Restrict brand if present.

No

AllowedLoyaltyBrand

[0..n]

Restrict brand if present.

No

LoyaltyHandling

[0..1]

Default Allowed.

No

CustomerLanguage

[0..1]

If the language is selected by the Customer on the Sale System before the request to the POI.

No

ForceOnlineFlag

[0..1]

Default False. Go online if data sent.

No

ForceEntryMethod

[0..n]

Restrict entry mode if sent and no PaymentData or LoyaltyData.CardAcquisitionReference

No

MerchantCategoryCode

[0..1]

The payment implies a specific MCC.

No

AllowChipXpress

[0..1]Default true. Set false to disable the ChipXpress feature.Yes

WaitCardRemoval

[0..1]Default true. Set to false to complete the transaction, i.e. to send the PaymentResponse message, without waiting for the card to be removed.Yes

DisableTip

[0..1]Default false. Set to true to disable tip entry for the transaction.Yes

DisableBankAxept

[0..1]Default false. Set to true to disable the special handling rules that apply to BankAxept cards.Yes

SaleItem

[0..n]

If purchased products are required for the payment or loyalty.

Yes

ItemID

[1..1]

Ignored, but required by the message schema when the SaleItem element is present.

Yes

ProductCode

[1..1]

Produce group / code value. This is not directly used by the payment application but can be relevant to the authorisation system

Yes

EanUpc

[0..1]

If data sent, POI has to store it and send it if the host protocol allows it.

No

UnitOfMeasure

[0..1]

 

No

Quantity

[0..1]

If data sent, POI has to store it and send it if the host protocol allows it.

No

UnitPrice

[0..1]

 

No

ItemAmount

[1..1]

Ignored, but required by the message schema when the SaleItem element is present.

Yes

TaxCode

[0..1]

If data sent, POI has to store it and send it if the host protocol allows it.

No

SaleChannel

[0..1]

If data sent, POI has to store it and send it if the host protocol allows it.

No

AdditionalProductInfo

[0..1]

If data sent, POI has to store it and send it if the host protocol allows it.

No

PaymentData

[0..1]

If one data element is present.

Yes

PaymentType

[0..1]

Default "Normal", indicating a purchase. Other options are "Refund" and "CashAdvance".

Yes

SplitPaymentFlag

[0..1]

Default False.
If split of the amount with possible fleet cards.

No

RequestedReservationTimePeriod

[0..1]

If time period of the OneTimeReservation,
FirstReservation or UpdateReservation is requested.

No

CardAcquisitionReference

[0..1]

If the card data comes from a previous CardAcquisition.

No

TransactionID

[1..1]

 

No

TimeStamp

[1..1]

 

No

PaymentInstrumentData

[0..1]

If payment instrument data are read by the Sale System.

Yes

PaymentInstrumentType

[1..1]

Only "Card" is accepted.

Yes

CardData

[0..1]

If PaymentInstrumentType is "Card". Note: PCI payment card data will not be accepted by this method.

Yes

EntryMethod

[1..1]

Entry mode of the payment instrument, i.e. Magstripe or Manual

Yes

SensitiveCardData

[0..1]

If structure non empty (could be CMS protected EnvelopedData).

Yes

PAN

[0..1]

If EntryMethod is File, Keyed or Manual.

Yes

CardSeqNumb

[0..1]

If EntryMethod is File, Keyed or Manual and data available on the card.

No

ExpirationDate

[0..1]

If EntryMethod is File, Keyed or Manual and data available on the card.

Yes

TrackData

[0..3]

If EntryMethod is MagStripe or RFID.

Yes

TrackNumb

[0..1]

Default 2.

No

TrackFormat

[0..1]

Default ISO.

No

TrackValue

[1..1]

 

Yes

CheckData

[0..1]

If PaymentInstrumentType is "Check".

No

BankID

[0..1]

Mandatory if TrackData absent.

 

AccountNumber

[0..1]

Mandatory if TrackData absent.

 

CheckNumber

[0..1]

Mandatory if TrackData absent.

 

TrackData

[0..1]

Mandatory if CheckNumber absent.

 

TrackNumb

[0..1]

Default 2.

 

TrackFormat

[1..1]

"E-13B" or "CMC-7".

 

TrackValue

[1..1]

 

 

CheckCardNumber

[0..1]

If provided by the customer.

 

TypeCode

[0..1]

Default Personal.

 

Country

[0..1]

Absent if country of the Sale system.

 

MobileData

[0..1]

If PaymentInstrumentType is "Mobile".

No

MobileCountryCode

[0..1]

If data available.

 

MobileNetworkCode

[0..1]

If data available.

 

MaskedMSISDN

[0..1]

If data available.

 

Geolocation

[0..1]

If data available.

 

ProtectedMobileData

[0..1]

SensitiveMobileData protected by CMS EnvelopedData.

 

SensitiveMobileData

[0..1]

If unprotected mobile data.

 

IMSI

[1..1]

 

 

IMSI

[0..1]

If data available.

 

IMEI

[0..1]

If data available.

 

LoyaltyData

[0..n]

Loyalty cards used with the payment transaction and read by the Sale System.

No

CardAcquisitionReference

[0..1]

See Loyalty request.

 

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

LoyaltyAccountID

[0..1]

See Loyalty request.

 

EntryMethod

[1..1]

 

 

IdentificationType

[1..1]

 

 

LoyaltyID

[1..1]

 

 

LoyaltyAmount

[0..1]

When the Sale System want to make an additional award the Loyalty account.

 

LoyaltyUnit

[0..1]

See Loyalty request.

 

Currency

[0..1]

See Loyalty request.

 

AmountValue

[1..1]

 

 

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 response message

PaymentResponse

Mult.

Rule

Usage

PaymentResponse

[1..1]

 

 

Response

[1..1]

 

 

Result

[1..1]

"Success" or "Failure".

Yes

ErrorCondition

[0..1]

Error classification in the failure case. See 2.7.5.3 in the EPAS specification.

Yes

AdditionalResponse

[0..1]

Description of the problem in the failure case.

Yes

POIData

[1..1]

 

 

POITransactionID

[1..1]

 

 

TransactionID

[1..1]

 

Yes

TimeStamp

[1..1]

 

Yes

BatchID

[0..1]

If Result is Success or Partial.

No

PaymentResult

[0..1]

If one data element is present.

Yes

PaymentType

[0..1]

Copy, default Normal.

Yes

PaymentInstrumentData

[0..1]

If a payment instrument is analysed by the POI.

No

PaymentInstrumentType

[1..1]

 

 

CardData

[0..1]

If PaymentInstrumentType is "Card".

 

PaymentBrand

[0..1]

If card PAN is readable.

 

MaskedPAN

[0..1]

If required for the card, instead of clear PAN.

 

EntryMethod

[1..1]

Copy if present in the request.

 

CardCountryCode

[0..1]

If available in the card.

 

ProtectedCardData

[0..1]

SensitiveCardData protected by CMS EnvelopedData.

 

SensitiveCardData

[0..1]

If structure non empty (unprotected).

 

PAN

[0..1]

If card PAN is readable.

 

CardSeqNumb

[0..1]

If data available on the card.

 

ExpirationDate

[0..1]

If data available on the card.

 

TrackData

[0..4]

If configured to be sent, and EntryMethod is
MagStripe or RFID.

 

TrackNumb

[0..1]

Default 2.

 

TrackFormat

[0..1]

Default ISO.

 

TrackValue

[1..1]

 

 

CheckData

[0..1]

If PaymentInstrumentType is "Check".

No

BankID

[0..1]

Mandatory if TrackData absent.

 

AccountNumber

[0..1]

Mandatory if TrackData absent.

 

CheckNumber

[0..1]

Mandatory if TrackData absent.

 

TrackData

[0..1]

Mandatory if CheckNumber absent.

 

TrackNumb

[0..1]

Default 2.

 

TrackFormat

[1..1]

"E-13B" or "CMC-7".

 

TrackValue

[1..1]

 

 

CheckCardNumber

[0..1]

If provided by the customer.

 

TypeCode

[0..1]

Default Personal.

 

Country

[0..1]

Absent if country of the Sale system.

 

MobileData

[0..1]

If PaymentInstrumentType is "Mobile".

No

MobileCountryCode

[0..1]

If data available.

 

MobileNetworkCode

[0..1]

If data available.

 

MaskedMSISDN

[0..1]

If data available.

 

Geolocation

[0..1]

If data available.

 

ProtectedMobileData

[0..1]

SensitiveMobileData protected by CMS EnvelopedData.

 

SensitiveMobileData

[0..1]

If unprotected mobile data.

 

MSISDN

[1..1]

 

 

IMSI

[0..1]

If data available.

 

IMEI

[0..1]

If data available.

 

AmountsResp

[0..1]

If Result is Success or Partial.

 

AuthorizedAmount

[1..1]

 

Yes

TotalRebatesAmount

[0..1]

If rebate on the total amount or rebate on individual products.

No

TotalFeesAmount

[0..1]

If fees to be charged from a financial service.

No

CashBackAmount

[0..1]

If cashback service was performed with the payment.

No

TipAmount

[0..1]

If payment with tip requested by the Sale System.

No

CurrencyConversion

[0..n]

If currency conversion the Sale needs to know.

No

ConvertedAmount

[1..1]

 

 

AmountValue

[1..1]

 

 

Currency

[1..1]

 

 

ForeignAmount

[0..1]

If the amount before conversion is required.

 

Declaration

[0..1]

If a declaration has to be presented to the customer.

 

MerchantOverrideFlag

[0..1]

Default "False". If payment forced by the Cashier.

No

AllowedReservationTimePeriod

[0..1]

If OneTimeReservation, FirstReservation or
UpdateReservation and Result is Success.

No

AllowedProduct

[0..n]

If ErrorCondition is "PaymentRestriction" (some
products are not payable by the payment card).

No

PaymentAcquirerData

[0..1]

If card PAN is readable.

No

AcquirerID

[0..1]

If several Acquirers.

 

AcquirerPOIID

[1..1]

 

 

AcquirerTransactionID

[0..1]

If provided by the Acquirer.

 

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

ApprovalCode

[0..1]

If available.

 

ReconciliationID

[0..1]

If provided by the Acquirer.

 

LoyaltyResult

[0..n]

Loyalty cards used with the payment transaction. First the loyalty account present in the request in the same order if any.

No

LoyaltyAccount

[1..1]

 

 

LoyaltyAccountID

[1..1]

 

 

EntryMethod

[1..1]

 

 

IdentificationType

[1..1]

 

 

IdentificationSupport

[1..1]

 

 

LoyaltyID

[1..1]

 

 

LoyaltyBrand

[0..1]

 

 

CurrentBalance

[0..1]

 

 

LoyaltyAmount

[0..1]

 

 

LoyaltyUnit

[0..1]

 

 

Currency

[0..1]

 

 

AmountValue

[1..1]

 

 

LoyaltyAcquirerData

[0..1]

 

 

LoyaltyAcquirerID

[0..1]

 

 

ApprovalCode

[0..1]

 

 

LoyaltyTransactionID

[0..1]

 

 

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

ReconciliationID

[0..1]

 

 

Rebates

[0..1]

 

 

TotalRebate

[0..1]

 

 

RebateLabel

[0..1]

 

 

SaleItemRebate

[0..n]

 

 

ItemID

[1..1]

 

 

ProductCode

[1..1]

 

 

UnitOfMeasure

[0..1]

 

 

Quantity

[0..1]

 

 

ItemAmount

[0..1]

 

 

RebateLabel

[0..1]

 

 

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

LoyaltyRequest Component

Mult.

Rule

Usage

LoyaltyRequest

[1..1]

 

 

SaleData

[1..1]

Same as PaymentRequest.SaleData.

 

OperatorID

[0..1]

 

No

OperatorLanguage

[0..1]

 

No

ShiftNumber

[0..1]

 

No

SaleTransactionID

[1..1]

 

Yes

TransactionID

[1..1]

Included in the request, but the transaction ID is not set

 

TimeStamp

[1..1]

Included in the request, but the timestamp is not set

 

SaleTerminalData

[0..1]

 

No

TerminalEnvironment

[0..1]

 

 

SaleCapabilities

[0..1]

 

 

TotalsGroupID

[0..1]

 

 

SaleToPOIData

[0..1]

Stored with the transaction.

No

SaleToAcquirerData

[0..1]

Sent to the Acquirer if present.

No

SaleToIssuerData

[0..1]

Sent to the Issuer if present and content is not empty (add an additional container).

No

StatementReference

[0..1]

 

 

LoyaltyTransaction

[1..1]

 

 

LoyaltyTransactionType

[1..1]

Uses the same transaction types as a payment request.

Yes

Currency

[0..1]

If TotalAmount is present, and different from default currency.

Yes

TotalAmount

[0..1]

If the loyalty transaction is linked to a payment transaction.

Yes

OriginalTransaction

[0..1]

If LoyaltyTransactionType is "AwardRefund", "RebateRefund" or "RedemptionRefund".

No

POITransactionID

[1..1]

 

 

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

ReuseCardDataFlag

[0..1]

Default True.

 

TransactionConditions

[0..1]

If one data element is present.

No

AllowedLoyaltyBrand

[0..n]

Restrict brand if data sent and no
LoyaltyData.CardAcquisitionReference.

 

CustomerLanguage

[0..1]

See Payment request.

 

ForceOnlineFlag

[0..1]

Default False. Go online if data sent.

 

ForceEntryMethod

[0..n]

Restrict entry mode if sent and no
LoyaltyData.CardAcquisitionReference.

 

SaleItem

[0..n]

If relevant for the loyalty transaction (see
PaymentRequest.transactionData).

No

ItemID

[1..1]

 

 

ProductCode

[1..1]

 

 

EanUpc

[0..1]

 

 

UnitOfMeasure

[0..1]

If Quantity present.

 

Quantity

[0..1]

 

 

UnitPrice

[0..1]

If Quantity present.

 

ItemAmount

[1..1]

 

 

TaxCode

[0..1]

 

 

SaleChannel

[0..1]

 

 

AdditionalProductInfo

[0..1]

 

 

LoyaltyData

[0..n]

If content is not empty.

Yes

CardAcquisitionReference

[0..1]

If the loyalty account ID comes from a previous.
CardAcquisition

No

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

LoyaltyAccountID

[0..1]

If loyalty identification of the loyalty account is realised by the Sale System.

Yes

EntryMethod

[1..1]

 

 

IdentificationType

[1..1]

Always "PAN"

 

LoyaltyID

[1..1]

Loyalty card number / ID

 

LoyaltyAmount

[0..1]

If loyalty amount is not computed on TotalAmount.

No

LoyaltyUnit

[0..1]

Default Point.

 

Currency

[0..1]

If LoyaltyUnit is Monetary.

 

AmountValue

[1..1]

 

 

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

LoyaltyResponse Component

Mult.

Rule

Usage

LoyaltyResponse

[1..1]

 

 

Response

[1..1]

 

Yes

Result

[1..1]

"Success" or "Failure".

 

ErrorCondition

[0..1]

Error classification in the failure case. See 2.7.5.3 in the EPAS specification.

 

AdditionalResponse

[0..1]

Description of the problem in the failure case.

 

POIData

[1..1]

 

No

POITransactionID

[1..1]

 

 

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

BatchID

[1..1]

 

 

LoyaltyResult

[0..n]

See PaymentResponse.

No

LoyaltyAccount

[1..1]

 

 

LoyaltyAccountID

[1..1]

 

 

EntryMethod

[1..1]

 

 

IdentificationType

[1..1]

 

 

IdentificationSupport

[1..1]

 

 

LoyaltyID

[1..1]

 

 

LoyaltyBrand

[0..1]

If a card is analysed.

 

CurrentBalance

[0..1]

If known (provided by the card or an external host).

 

LoyaltyAmount

[0..1]

Mandatory if transaction success and no rebate.

 

LoyaltyUnit

[0..1]

Default Point.

 

Currency

[0..1]

If LoyaltyUnit is Monetary.

 

AmountValue

[1..1]

 

 

LoyaltyAcquirerData

[0..1]

If acquirer contacted.

 

LoyaltyAcquirerID

[0..1]

If available.

 

ApprovalCode

[0..1]

If provided by the Acquirer.

 

LoyaltyTransactionIDLoyalty

[0..1]

If provided by the Loyalty Acquirer.

 

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

ReconciliationID

[0..1]

If provided by the Acquirer.

 

Rebates

[0..1]

if rebates awarded.

 

TotalRebate

[0..1]

If rebate on the total amount for this loyalty program.

 

RebateLabel

[0..1]

If provided by the Acquirer.

 

SaleItemRebate

[0..n]

Only item with rebate (identified by ItemID).

 

ItemID

[1..1]

 

 

ProductCode

[1..1]

 

 

UnitOfMeasure

[0..1]

If Quantity present.

 

Quantity

[0..1]

If rebate is additional units.

 

ItemAmount

[0..1]

If rebate on the line item amount.

 

RebateLabel

[0..1]

If provided by the Acquirer.

 

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

ReversalRequest

Mult.

Rule

Usage

ReversalRequest

[1..1]

 

 

SaleReferenceID

[0..1]

If payment reservation reversal.

No

OriginalTransaction

[1..1]

 

Yes

WorkstationID

[0..1]

Default MessageHeader.WorkstationID.

No

POIID

[0..1]

Default MessageHeader.POIID.

No

POITransactionID

[1..1]

Identification of the Loyalty/Payment to reverse.

Yes

TransactionID

[1..1]

ID of the transaction to reverse

 

TimeStamp

[1..1]

Not used, but required by the schema

No

StorePay

[0..1]Used if reversing a Svea transactionYes

ContactID

[1..1]The Svea contract IDYes

OperatorID

[0..1]

Operator / cashier ID.

Used when multiple merchants use the same terminal but with different terminal id:s. If used, it must match the OperatorId on the transaction to be reversed.

ReversedAmount

[0..1]

 

No

ReversalReason

[1..1]

One of the reversal reasons defined in the EPAS specification

Yes

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

Component

Mult.

Rule

Usage

ReversalResponse

[1..1]

 

 

Response

[1..1]

 

Yes

Result

[1..1]

"Success" or "Failure".

 

ErrorCondition

[0..1]

Error classification in the failure case. See 2.7.5.3 in the EPAS specification.

 

AdditionalResponse

[0..1]

Description of the problem in the failure case.

 

POIData

[0..1]

If Result is Success.

Yes

POITransactionID

[1..1]

 

 

TransactionID

[1..1]

 

 

TimeStamp

[1..1]

 

 

BatchID

[0..1]

If Result is Success.

No

ReversedAmount

[0..1]

Copy.

No

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.

DisplayRequest

Mult.

Rule

Usage

DisplayRequest

[1..1]

 

 

DisplayOutput

[1..n]

Complete display content for output devices.
At most one DisplayOutput per Device/InfoQualify pair.

Yes

ResponseRequiredFlag

[0..1]

False The POI will not expect a response from the ECR for this message. If a response is received it will be ignored..

Yes

MinimumDisplayTime

[0..1]

Default 0

 

No

Device

[1..1]

CashierDisplay.

Yes

InfoQualify

[1..1]

POIReplication.

Yes

OutputContent

[1..1]

 

Yes

OutputFormat

[1..1]

Only ever set to "Text".

Yes

PredefinedContent

[0..1]

Mandatory, if OutputFormat is MessageRef. Otherwise not allowed.

No

ReferenceID

[1..1]

 

 

Language

[0..1]

Default language if absent.

 

OutputText

[0..n]

Mandatory, if OutputFormat is Text. Since this is the only supported display request, the output text should always be present.

There is one instance of the OutputText element per line of text to display. Instead of using the various attributes from the EPAS specification the payment application will include the text to display as the OutputText's data.

Yes

Text

[1..1]

 

No

CharacterSet

[0..1]

If not present, the settings of the target system or device are used.

 

Font

[0..1]

If not present, the settings of the target system or device are used.

 

StartRow

[0..1]

If not present, the settings of the target system or device are used (e.g. current row position).

 

StartColumn

[0..1]

If not present, the settings of the target system or device are used (e.g. current column position).

 

Color

[0..1]

If not present, default colour used.

 

CharacterWidth

[0..1]

If not present, default width used.

 

CharacterHeight

[0..1]

If not present, default height used.

 

CharacterStyle

[0..1]

If not present, default style used.

 

Alignment

[0..1]

If not present, default alignment used.

 

EndOfLineFlag

[0..1]

Default True.

 

OutputXHTML

[0..1]

Mandatory, if OutputFormat is XHTML Not allowed, otherwise.

No

OutputBarcode

[0..1]

Mandatory, if OutputFormat is BarCode
Not allowed, otherwise.

No

BarcodeType

[0..1]

Default EAN13
EAN8, EAN13, UPCA, Code25, Code128, PDF417.

 

BarcodeValue

[1..1]

 

 

OutputSignature

[0..1]

If protection has to be provided to the vendor on the text to display.

No

PromptID

[1..1]

Numeric prompt ID referring to CHAOI.

Yes

Input

[0..1]

If this element is present then it indicates that the ECR should prompt for cashier input. The input may be optional, e.g. the selection of the customer language, or it can be mandatory, e.g. a voice referral authorisation number is needed.

Responses are sent as a separate Input Response message. This is discussed later in this document.

Yes

Type

[1..1]

TextString, DecimalString, DigitString, Password or OptionList

The first four of these indicate the type of data that is required:

  • TextString: Any text can be entered.
  • DecimalString: Any decimal number can be entered, using a '.' as a decimal separator.
  • DigitString: Any sequence of digits can be entered, without a decimal separator.
  • Password: Any text can be entered, and normal password entry procedures should be followed to hide the entered password from view.

If the Type is OptionList then the ECR should present a list of options, detailed below, to the cashier for selection.

 

Required

[0..1]

Yes or No. If the input is required then the payment application will expect a response and will wait for the response to arrive. If No then the payment application will not wait for a response, but a response can be sent asynchronously.

If this attribute is missing then No should be assumed.

 

Option

[0..n]

At least one is required if Type = OptionList

 

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

Prompt ID

Display detail

100

Shows the idle screen, essentially a 'welcome' screen, prior to a transaction being initiated by the ECR. This includes the merchant name taken from configuration data.

101

Shows a 'please wait' screen. Note that this prompt ID should never be sent to the ECR, because this display is intended to be shown to the customer while another message (e.g. a Loyalty Request message) is being sent to the ECR. This is only listed here for completeness.

102

Shows 'Refund above maximum'. Where a refund request includes an amount above the limit configured for the card then this prompt is shown prior to the transaction ending.

103

Not used in this application.Contradicts the text at the beginning of the section.

104

Shows 'Card cannot be read, transaction not possible' when a magnetic stripe card read has failed three times and the terminal is configured such that manual entry is not allowed.

105

Shows the gratuity entry screen, allowing the customer to adjust the amount upwards if they want to. The ECR can instruct the terminal to skip this process.

106

Confirms the adjusted amount following gratuity entry, where the gratuity is more than 30% above the original amount.

107

Informs the customer that the adjusted amount is too low. The customer can press Enter to return to the gratuity entry screen (105).

108

Not used in this application.See previous comment.

109

Informs the user that, after choosing not to enter a PIN, a signature is not a valid authorisation mechanism for the card, and so the transaction can not continue.

110

Start-up screen, shown while waiting for an ECR event to initiate a transaction.

111

Not used in this application.

112

Shows the same text as screen 6221 (see ref [4]) but does not offer the 'Force' option to the ECR because the parameters do not allow that option.

113

'Network service error', shown to the cardholder when the terminal is unable to open a listening network connection for the ECR to connect to. By definition, therefore, this text cannot be shown on the ECR.

114

Shows a 'terminal not operational' prompt in the event that the EMV card profiles failed to load.

115

Shown when a loyalty card is rejected by the ECR

116

Asks the cardholder to confirm whether or not use the presented combination card as a payment card

117

Tells the cardholder that their loyalty card has been accepted and that they should now insert a payment card

118

Tells the cardholder that their card has been inserted early and that they should remove it.

119

Informs the cardholder that the terminal is about to restart.

120Indicates an approved reversal.
121Indicates that cashier input is needed.
122The adjusted amount (tip entry) is too high.
123A loyalty card should be inserted / swiped.
124A payment card should be inserted / swiped. This is used when a loyalty card has already been read.
125A loyalty card was required but the card that was presented was not a loyalty card.
126A payment card was required but the card that was presented was not a payment card.
127A loyalty card has been read in the context of a loyalty card transaction so the card can be taken.
128A chip failure has occurred, where the data received from the chip has not been correct.
129The payment application is loading parameters
130The pament application is being updated
131Not used
132A combined payment / loyalty card has been accepted. Note that this is not currently possible in an EPAS environment.
133A payment card has been accepted.
134A refund is being requested and DCC is enabled for the card being used. The cashier must check on the original receipt to see if DCC was used in the original transaction.
135In a DCC transaction the cardholder is being asked to select between their home currency or the local currency.
136A refund is being requested and DCC is enabled for the card being used. The cardholder is being asked if DCC was used in the original transaction.
137Svea transaction: the payment application is waiting for the transaction amount.
138Svea transaction: the list of payment plans is being retrieved.
139Svea transaction: the customer is being prompted to select a payment plan.
140Svea transaction: the type of customer ID is being requested.
141Svea transaction: the customer ID is being requested.
142Svea transaction: the customer is being asked to confirm the contract.
143Svea transaction: the customer has cancelled the contract.
144Svea transaction: a failure has occurred during the Svea transaction.
145Svea transaction: the Svea credit check has been declined.
160Contactless transaction: the customer is using a phone or other external device, and the payment application is waiting for something to be completed on the device.
161Contactless transaction: the contactless transaction has been denied and the customer should use the chip instead.
162Contactless transaction: the contactless transaction has been denied and the customer should use a different card, or the chip on the same card.
163Contactless transaction: A card collision has occurred, where multiple cards have been presented.
200IPOS environment only: The wrong data protection level has been selected.
201IPOS environment only: The cashier should enter the card number on the ECR.
202IPOS environment only: The cahier should enter the card's expiry date on the ECR.
203IPOS environment only: The cashier should re-enter the card's expiry date on the ECR.
300Unattended terminal: the terminal is out of service.

653

CHAOI extension: the standard meaning of this prompt is to say that a signature override is not possible. This prompt will be used in the same way as 652 but where 652 allows a signature override, prompt 653 does not.

800 - 899Reserved for internal use, these should not be reported to the ECR.
900The terminal is restarting due to a technical or system error.

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

Prompt ID

Purpose

Optional or Required

Response type

Response contents

105

Gratuity amount required

Optional

Option selection

"skip": continue the transaction without any gratuity
If no response is sent then the terminal will continue processing once the user has entered the gratuity amount.

613

The transaction amounts are needed for a magnetic stripe card transaction

Required

Decimal string

The response should contain the various financial amounts for the transaction, as documented in ref [4].

6221

Override the terminal so that a magnetic stripe swipe is enabled even though the card prefers that the chip be used

Optional

Option selection

"force": enable the magnetic stripe fallback
If no response is sent then the terminal will wait for the customer to insert the card into the chip reader.

6238

The transaction amounts are needed for a manually-entered card number transaction

Required

Decimal string

The response should contain the various financial amounts for the transaction, as documented in ref [4].

631

The transaction amounts are needed for a chip card transaction

Required

Decimal string

The response should contain the various financial amounts for the transaction, as documented in ref [4].

641

Selection between credit / debit card

Optional

Option selection

"credit": use credit card function of the presented card
"debit": use debit card function of the presented card

642

Payment code required

Required

Text string

The payment code should be supplied. Note that the payment code length is determined by the card parameters, and an incorrect payment code length will cause this prompt to be sent again.

643

Cash back amount required

Required

Decimal string

The amount of cash back that the customer requires. "0.00" should be used if no cash back is required.

645

VAT amount incorrect, re-enter

Required

Decimal string

The VAT amount supplied is too high (effective rate is > 100%) and must be re-entered

646

CV2 required

Required

Digit string

The CV2 / security code should be supplied. (This functionality is currently disabled due to PA/DSS requirements and local agreements.)

649

Imprint of embossed card should be taken

Required

Option selection

"continue": indicates that the card imprint has been taken.
If this is impossible, the transaction should be aborted.

6410

VAT amount confirmation required

Required

Decimal string

The VAT amount of the transaction is required. The terminal will include a proposed amount in the display request and the ECR may choose to display this amount as a default value. The amount sent back to the terminal will, however, be the definitive VAT amount for the transaction.

652

PIN Entry

Optional

Option

"sign": permit signature authentication rather than PIN entry
If no response is sent then the terminal will proceed with PIN entry.

653

PIN Entry

None

-

This screen does not follow the meaning in ref [4]. Instead it is identical to 652 except that no signature override is offered.

662Signature verificationRequiredOption

The customer should sign the receipt and the cashier should check the signature matches the one on the card.
"yes": signature is verified as correct.
"no": signature is not correct.

664

Voice referral

Required

Text string

The authorisation code for the transaction should be entered following a voice referral. Alternatively the transaction should be aborted if approval is not given.

6619

Voice referral

Required

Text string

The same as 664, but used where an invalid authorisation code was supplied.

676

Parameter download reminder

Required

Option

When the SPDH host sends a 13x trigger then the operator needs to be asked about a parameter download between each transaction.
"yes": download and apply the parameters now
"no": do not download the parameters yet.

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.

DisplayRequest

Mult.

Rule

Usage

DisplayRequest

[1..1]

 

 

DisplayOutput

[1..n]

Complete display content for output devices.
At most one DisplayOutput per Device/InfoQualify pair.

Yes

ResponseRequiredFlag

[0..1]

The payment application will send a response if required. The response indicates if QR codes are enabled in configuration, and does not indicate that the QR code has actually been displayed.

Yes

MinimumDisplayTime

[0..1]

Default 0

 

No

Device

[1..1]

Ignored

Yes

InfoQualify

[1..1]

Ignored

Yes

OutputContent

[1..1]

 

Yes

OutputFormat

[1..1]

"BarCode"

Yes

PredefinedContent

[0..1]

Mandatory, if OutputFormat is MessageRef. Otherwise not allowed.

No

ReferenceID

[1..1]

 

 

Language

[0..1]

Default language if absent.

 

OutputText

[0..n]

Not supported

No

Text

[1..1]

 

 

CharacterSet

[0..1]

If not present, the settings of the target system or device are used.

 

Font

[0..1]

If not present, the settings of the target system or device are used.

 

StartRow

[0..1]

If not present, the settings of the target system or device are used (e.g. current row position).

 

StartColumn

[0..1]

If not present, the settings of the target system or device are used (e.g. current column position).

 

Color

[0..1]

If not present, default colour used.

 

CharacterWidth

[0..1]

If not present, default width used.

 

CharacterHeight

[0..1]

If not present, default height used.

 

CharacterStyle

[0..1]

If not present, default style used.

 

Alignment

[0..1]

If not present, default alignment used.

 

EndOfLineFlag

[0..1]

Default True.

 

OutputXHTML

[0..1]

Mandatory, if OutputFormat is XHTML Not allowed, otherwise.

No

OutputBarcode

[0..1]

Mandatory, if OutputFormat is BarCode
Not allowed, otherwise.

Yes

BarcodeType

[0..1]

Ignored, only QR codes are supported.

No

BarcodeValue

[1..1]

The value to be encoded as a QR code image

 

OutputSignature

[0..1]

If protection has to be provided to the vendor on the text to display.

No

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

Component

Mult.

Rule

Usage

InputResponse

[1..1]

 

Yes

OutputResult

[0..1]

If DisplayOutput present in the request.

No

Device

[1..1]

Copy.

 

InfoQualify

[1..1]

Copy.

 

Response

[1..1]

 

 

Result

[1..1]

"Success" or "Failure".

 

ErrorCondition

[0..1]

Error classification in the failure case. See 2.7.5.3 in the EPAS specification.

 

AdditionalResponse

[0..1]

Description of the problem in the failure case.

 

InputResult

[1..1]

 

 

Device

[1..1]

CashierInput , CustomerInput. Only "CashierInput" is supported.

Yes

InfoQualify

[1..1]

Input, CustomerAssistance.

Yes

Response

[1..1]

 

Yes

Result

[1..1]

"Success" or "Failure".

 

ErrorCondition

[0..1]

Error classification in the failure case. See 2.7.5.3 in the EPAS specification.

 

AdditionalResponse

[0..1]

Description of the problem in the failure case.

 

Input

[0..1]

If Response.Result is Success and AmountsReq is not used.

Yes

InputCommand

[1..1]

  • "TransactionAmount", or
  • "NonPciCardData", or
  • the Prompt ID echoed from the associated Display request.

Yes

ConfirmedFlag

[0..1]

Mandatory, if InputCommand is GetConfirmation or SiteManager. Not allowed, otherwise.

No

FunctionKey

[0..1]

Mandatory, if InputCommand is GetFunctionKey. Not allowed, otherwise.

No

TextInput

[0..1]

Mandatory, if InputCommand is a prompt ID

Yes

DigitInput

[0..1]

Mandatory, if InputCommand is DigitString. Not allowed, otherwise.

No

Password

[0..1]

Mandatory, if InputCommand is Password. Not allowed, otherwise.

No

MenuEntryNumber

[0..1]

Mandatory, if InputCommand is GetMenuEntry. Not allowed, otherwise.

No

AmountsReq

[0..1]

Required if InputCommand = TransactionAmount

Yes

RequestedAmount

[0..1]

Must be non-zero.

 

CashBackAmount

[0..1]

If payment with cash back requested by the Sale System. Only required if non-zero.

 

TipAmount

[0..1]

If this attribute is present with value 0 then tipping is disabled for the transaction. Otherwise it is ignored. Note that this attribute does not specify the amount of tip to be applied.

 

VatAmount

[0..1]

VAT amount

 

NonPciCardData

[0..1]Required if InputCommand = NonPciCardData 

Number

[1..1]Card number 

Expiry

[1..1]Card expiry date, formatted as MMYY 

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

Component

Mult.

Rule

Usage

PrintRequest

[1..1]

 

Yes

PrintOutput

[1..1]

 

Yes

DocumentQualifier

[1..1]

 

Yes

ResponseMode

[1..1]

Set to 'NotRequired'. Print Response is not required but will be accepted.

Yes

IntegratedPrintFlag

[0..1]

default False. Not allowed if DocumentQualifier is not "CashierReceipt" or "CustomerReceipt".

No

RequiredSignatureFlag

[0..1]

Only included if signature is required. If not included then assume no signature is needed.

Yes

OutputContent

[1..1]

 

Yes

OutputFormat

[1..1]

MessageRef, Text, BarCode, XHTML. Only "Text" is used here.

Yes

PredefindContent

[0..1]

Same as Display.

No

ReferenceID

[1..1]

Same as Display.

 

Language

[0..1]

Same as Display.

 

OutputText

[0..n]

 

Yes

Text

[1..1]

Contains the pre-formatted debug / test receipt. May not be supported in future revisions.

Yes

CharacterSet

[0..1]

Same as Display.

No

Font

[0..1]

Same as Display.

No

StartColumn

[0..1]

Same as Display.

No

Color

[0..1]

Same as Display.

No

CharacterWidth

[0..1]

Same as Display.

No

CharacterHeight

[0..1]

Same as Display.

No

CharacterStyle

[0..1]

Same as Display.

No

Alignment

[0..1]

Same as Display.

No

EndOfLineFlag

[0..1]

Same as Display.

No

OutputXHTML

[0..1]

Same as Display.

No

OutputBarcode

[0..1]

Same as Display.

No

BarcodeType

[0..1]

Same as Display.

 

BarcodeValue

[1..1]

Same as Display.

 

ReceiptData

[1..1]

 

Yes

Message

[0..1]Provided if the receipt is a plain text error message or report, rather than a transaction. 

Transaction

[0..1]

Provided if the receipt data is for a transaction, rather than an error message or report.

 

Status

[0..1]

This field provides the overall status of the transaction (e.g. AUTHORISED, DECLINED, CANCELLED etc).

 

DenialReason

[0..1]

If the transaction was denied then this indicates the reason for the transaction being declined.

 

Message

[0..1]

A plain text message typically used for diagnostic purposes or ad-hoc printed reports rather than for a financial transaction.

 

MerchantData

[1..1]

Merchant data.

 

Name

[0..1]

Merchant name.

 

Address

[0..1]

Merchant address.

 

City

[0..1]

Merchant city.

 

ZipCode

[0..1]

Merchant postal code.

 

PhoneNumber

[0..1]

Merchant phone number.

 

OrganisationNumber

[0..1]

Merchant's organisation number.

 

HelplineNumber

[0..1]

Helpline phone number.

 

BankAgentName

[0..1]

Bank agent.

 

AcquirerReference

[0..1]

Acquirer reference used in clearing.

 

TerminalId

[0..1]

Terminal ID.

 

OperatorId

[0..1]

Operator / cashier ID.

 

StorePay

[0..1]Present only for Svea transactions. For a full interpretation of these data elements the reader should consult Svea documentation to become familiar with the concepts involved. 

Contract

[1..1]  

ContractId

[1..1]The Svea contract ID. 

Confirmed

[1..1]Indicates if the contract has been confirmed or not. 

Approved

[1..1]Indicates if the contrat has been approved or not. 

ApprovedAmount

[1..1]Indicates the value of the contract. 

ReferenceNumber

[1..1]Contract reference number, used in reversals. 

ContractResponseInformation

[1..1]Used only where the contract has been declined. Contains a response that should give information on the reason for the decline. 

LegalContractName

[1..1]The contract name. 

Customer

[0..1]Present if customer information has been acquired. 

Name

[1..1]Customer name. 

SecurityNumber

[1..1]Customer's security / ID number. 

Address

[1..1]Customer's address. 

PostalCode

[1..1]Customer's postal code. 

PostArea

[1..1]Customer's postal area. 

PhoneNumber

[1..1]Customer's phone number. 

Email

[1..1]Customer's email address. 

PaymentPlan

[0..1]Present if a Svea payment plan has been selected. 

Id

[1..1]Payment plan ID. 

Description

[1..1]Payment plan text description. 

StartFee

[1..1]Initial fee for the payment plan. 

MonthlyFee

[1..1]Recurring monthly fee for the payment plan. 

DurationInMonths

[1..1]Length of the payment plan in months. 

MonthlyCost

[1..1]The monthly cost of the payment plan. 

InterestRate

[1..1]The interest rate that applies. 

InterestRateEffective

[1..1]The effective interest rate that applies. 

NumberOfPaymentFreeMonths

[1..1]Number of payment-free months in the payment plan. 

TransactionData

[0..1]

Present if amount data is known in the terminal and if the Message component is not used.

 

Type

[1..1]

There shall be a defined mapping between this transaction type and the SPDH 'Transaction Code'.

 

DateTime

[1..1]

Transaction date and time. (see WP-1159 - Getting issue details... STATUS for more info on handling date time)

 

CurrencyCode

[1..1]

Currency code supplied as per ISO 4217.

 

CurrencyNum

[1..1]

Currency number as per ISO 4217.

 

Amount

[1..1]

Amount of purchase / refund.

 

CashBack

[0..1]

Cash back amount.

 

Gratuity

[0..1]

Gratuity amount (not used).

 

Vat

[0..1]

VAT amount, included in the Amount value.

 

CashAdvanceCharge

[0..1]Surcharge for a cash advance transaction. 

Total

[0..1]

Combined total.

 

ReferenceNumber

[1..1]

Transaction reference number.

 

AuthorisationData

[0..1]

Present if the Message component is not used.

 

PosEntryMode

[1..1]

See 8.1.2 of CHAOI.

 

IdMethod

[1..1]

See 8.1.3 of CHAOI.

 

Channel

[1..1]

See 8.1.4 of CHAOI.

 

Responder

[1..1]

See 8.1.5 of CHAOI.

 

ResponseCode

[1..1]

See 8.1.6 of CHAOI.

 

FinancialInstitution

[1..1]

See 8.1.7 of CHAOI.

 

BatchNumber

[1..1]

The batch number for the transaction.

 

ApprovalCode

[1..1]

Transaction approval code, if appropriate. Locally-generated approval codes begin with "L".

 

VerifiedByDevice

[0..1]Present and set to "true" if the cardholder was verified by a consumer device. According to VISA requirements the receipt must include the text "Verified by device" if this is the case. 

CardData

[0..1]

Present if a card number has been established.

 

MaskedPan

[1..1]

Masked card number.

 

Name

[1..1]

Card name / type.

 

CreditDebit

[1..1]

If the cardholder was asked to choose between a credit or debit account then this will be set to CREDIT or DEBIT. If this attribute is not included then the cardholder was not asked to choose the account type.

 

PaymentCode

[1..1]

Payment code, may be empty.

 

EmvData

[0..1]

Included for EMV transactions.

 

ApplicationId

[1..1]

The application ID, or AID, is given here.

 

Tvr

[1..1]

Terminal Verification Results.

 

Tsi

[1..1]

Transaction Status Indicator.

 

ResponseCode

[0..1]EMV response code, if available. 

PanSequenceNumber

[1..1]PAN sequence number. 

DCC

[0..1]Included for Dynamic Currency Conversion transactions. 

Provider

[1..1]The DCC service provider. 

Rate

[1..1]Currency conversion rate in decimal. 

Source

[1..1]Source of the conversion rate. 

DateTime

[1..1]Timestamp of the currency conversion. 

Amount

[1..1]Converted transaction amount. 

CurrencyNum

[1..1]ISO 4217 currency number of the converted currency. 

CurrencyCode

[1..1]ISO 4217 currency code of the converted currency. 

Exponent

[1..1]Number of digits following the decimal point in this currency. 

MarkUp

[1..1]The conversion charge / mark up as a percentage. This is included in the total. 

Gratuity

[1..1]The value of any gratuity in the converted currency. 

Scheme

[1..1]"V" = Visa, "M" = Mastercard. 

Disclaimer

[1..1]Disclaimer text that must be included in the receipt. 


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>

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%
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" 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

Component

Mult.

Rule

Usage

PrintRequest

[1..1]

 

Yes

PrintOutput

[1..1]

 

Yes

DocumentQualifier

[1..1]

Not used.

Yes

ResponseMode

[1..1]

"NotRequired" - no response is sent. "Immediate" - response is sent when the request is received. "PrintEnd" - response is sent when printing is complete.

Yes

IntegratedPrintFlag

[0..1]

default False. Not allowed if DocumentQualifier is not "CashierReceipt" or "CustomerReceipt".

No

RequiredSignatureFlag

[0..1]

Only included if signature is required. If not included then assume no signature is needed.

No

OutputContent

[1..1]

 

Yes

OutputFormat

[1..1]

"Bitmap" should be used here.

Yes

PredefindContent

[0..1]

Same as Display.

No

ReferenceID

[1..1]

Same as Display.

 

Language

[0..1]

Same as Display.

 

OutputText

[0..n]

 

No

Text

[1..1]

Contains the pre-formatted debug / test receipt. May not be supported in future revisions.

 

CharacterSet

[0..1]

Same as Display.

 

Font

[0..1]

Same as Display.

 

StartColumn

[0..1]

Same as Display.

 

Color

[0..1]

Same as Display.

 

CharacterWidth

[0..1]

Same as Display.

 

CharacterHeight

[0..1]

Same as Display.

 

CharacterStyle

[0..1]

Same as Display.

 

Alignment

[0..1]

Same as Display.

 

EndOfLineFlag

[0..1]

Same as Display.

 

OutputXHTML

[0..1]

Same as Display.

 

OutputBarcode

[0..1]

Same as Display.

 

BarcodeType

[0..1]

Same as Display.

 

BarcodeValue

[1..1]

Same as Display.

 

Bitmap

[0..1] Yes

ImageData

[1..1]Base64 encoded monochrome Windows bitmap data, compressed using the gzip algorithm. 

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

ComponentMulti.RuleUsage
ReconciliationResponse[1..1]  Yes

DocumentQualifier

[1..1]"CustomerReceipt" 

Response

[1..1]The result of the Print request. 

Result

[1..1]"Success" or "Failure" 

ErrorCondition

[0..1]Error classification in the failure case. See 2.7.5.3 in the EPAS specification. 

AdditionalResponse

[0..1]Description of the problem in the failure case. 

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

Component

Mult.

Rule

Usage

AbortRequest

[1..1]

 

 

MessageReference

[1..1]

 

 

MessageCategory

[1..1]

Input, Loyalty, Payment, Reconciliation, Reversal.

Yes

ServiceID

[0..1]

 

No

DeviceID

[0..1]

 

No

WorkstationID

[1..1]

Default MessageHeader.WorkstationID.

No

POIID

[1..1]

Default MessageHeader.POIID.

No

AbortReason

[1..1]

Text indicating the reason for the abort request. If provided, this is used only for logging purposes.

Yes

DisplayOutput

[0..1]

To display an abort message to the Customer.

No

Device

[1..1]

CustomerDisplay.

 

InfoQualify

[1..1]

Error.

 

OutputContent

[1..1]

 

 

OutputFormat

[1..1]

 

 

PredefinedContent

[0..1]

Same as Display.

 

ReferenceID

[1..1]

 

 

Language

[0..1]

Same as Display.

 

OutputText

[0..n]

Same as Display.

 

Text

[1..1]

 

 

CharacterSet

[0..1]

Same as Display.

 

Font

[0..1]

Same as Display.

 

StartRow

[0..1]

Same as Display.

 

StartColumn

[0..1]

Same as Display.

 

Color

[0..1]

Same as Display.

 

CharacterWidth

[0..1]

Same as Display.

 

CharacterHeight

[0..1]

Same as Display.

 

CharacterStyle

[0..1]

Same as Display.

 

Alignment

[0..1]

Same as Display.

 

OutputXHTML

[0..1]

Same as Display.

 

OutputSignature

[0..1]

If protection has to be provided to the vendor on the text to display.

 

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

EventNotification

Mult.

Profile

Rule

Usage

EventNotification

[1..1]

 

 

 

TimeStamp

[1..1]

 

 

Yes

EventToNotify

[1..1]

 

 

Yes

EventDetails

[0..1]

 

Details of the event, useful for logging purposes.

Yes

RejectedMessage

[0..1]

 

Mandatory if EventToNotify is "Reject", absent in other cases.

Yes

MaintenanceRequiredFlag

[0..1]

 

Default False.

No

DisplayOutput

[0..n]

 

To display an event message.

No

Device

[1..1]

 

CashierDisplay

 

InfoQualify

[1..1]

 

Error.

 

OutputContent

[1..1]

 

 

 

OutputFormat

[1..1]

 

Text, XHTML.

 

OutputText

[0..n]

 

Same as Display.

 

Text

[1..1]

 

Same as Display.

 

CharacterSet

[0..1]

 

Same as Display.

 

Font

[0..1]

 

Same as Display.

 

StartRow

[0..1]

 

Same as Display.

 

StartColumn

[0..1]

 

Same as Display.

 

Color

[0..1]

 

Same as Display.

 

CharacterWidth

[0..1]

 

Same as Display.

 

CharacterHeight

[0..1]

 

Same as Display

 

CharacterStyle

[0..1]

 

Same as Display.

 

Alignment

[0..1]

 

Same as Display.

 

OutputXHTML

[0..1]

 

Same as Display.

 

OutputSignature

[0..1]

 

If protection has to be provided to the vendor on the text to display.

 

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

ComponentMulti.RuleUsage
ReconciliationRequest[1..1]  

ReconciliationType

[1..1]The type of reconciliation which is requested. Only SaleReconciliation is supported.Yes

Reconciliation request message example

<SaleToPOIRequest>
   <MessageHeader MessageClass="Service" MessageCategory="Reconciliation" MessageType="Request" ServiceID="4787" WorkstationID="" POIID="52400004" />
   <ReconciliationRequest ReconciliationType="SaleReconciliation" />
</SaleToPOIRequest>

Reconciliation response message

ComponentMulti.RuleUsage
ReconciliationResponse[1..1]  

ReconciliationType

[1..1]The copy of the requested type of reconciliation. 

BatchIDType

[0..1]The identification of the reconciliation period related to the provided totals. 

Response

[1..1]The result of the Reconciliation. 

Result

[1..1]"Success" or "Failure". 

ErrorCondition

[0..1]Error classification in the failure case. See 2.7.5.3 in the EPAS specification. 

AdditionalResponse

[0..1]Description of the problem in the failure case. 

TransactionTotals

[0..n]A sequence data structure containing totals of transactions for each totals group. 

PaymentCurrency

[0..1]Currency code 

TotalsGroupID

[0..1]ID of the totals group 

PaymentTotals

[0..10]The totals of the payment transactions per type of transaction. 

TransactionType

[1..1]"Debit" (payment) or "Credit" (refund) 

TransactionCount

[1..1]Number of transactions 

TransactionAmount

[1..1]Total value of this type of transaction 

Reconciliation response message example

<SaleToPOIResponse>
   <MessageHeader ProtocolVersion="1.0" MessageClass="Service" MessageCategory="Reconciliation" MessageType="Response" ServiceID="4384" WorkstationID="" POIID="52400004" />
   <ReconciliationResponse BatchID="163" ReconciliationType="SaleReconciliation">
      <Response Result="Success" />
      <TransactionTotals PaymentCurrency="SEK" TotalsGroupID="SWE">
         <PaymentTotals TransactionType="Debit" TransactionCount="5" TransactionAmount="1110.00" />
         <PaymentTotals TransactionType="Credit" TransactionCount="0" TransactionAmount="0.00" />
         <TransactionTotals PaymentCurrency="SEK" TotalsGroupID="SVEA">
            <PaymentTotals TransactionType="Debit" TransactionCount="0" TransactionAmount="0.00" />
            <PaymentTotals TransactionType="Credit" TransactionCount="0" TransactionAmount="0.00" />
         </TransactionTotals>
      </TransactionTotals>
   </ReconciliationResponse>
</SaleToPOIResponse>


GetTotals message

The Get totals message is used to create the same kind of reports as Reconciliation did, but without closing the batch. 

Get totals request message

Component

Multi.

Rule

Usage

GetTotalsRequest[1..1]  

TotalDetails

[0..1]
No
TotalFilter[0..1]
No

GetTotals request message example

<SaleToPOIRequest>
   <MessageHeader MessageClass="Service" MessageCategory="GetTotals" MessageType="Request" ServiceID="4787" WorkstationID="" POIID="52400004" />
   <GetTotalsRequest />
</SaleToPOIRequest>

GetTotals response message

Component

Multi.

Rule

Usage

GetTotalsResponse[1..1]  

BatchIDType

[0..1]The identification of the period related to the provided totals. 
____GratuityAmount[1..1]Total amount of gratuity for the transactions
________Gratuity[1..1]Total gratuity amount

Response

[1..1]The result of the GetTotals. 

Result

[1..1]"Success" or "Failure". 

ErrorCondition

[0..1]Error classification in the failure case. See 2.7.5.3 in the EPAS specification. 

AdditionalResponse

[0..1]Description of the problem in the failure case. 

TransactionTotals

[0..n]A sequence data structure containing totals of transactions for each totals group. 
CardBrand[1..1]Card brand used for the transaction

PaymentCurrency

[0..1]Currency code 

TotalsGroupID

[0..1]ID of the totals group 

PaymentTotals

[0..10]The totals of the payment transactions per type of transaction. 

TransactionType

[1..1]"Debit" (payment) or "Credit" (refund) 

TransactionCount

[1..1]Number of transactions 

TransactionAmount

[1..1]Total value of this type of transaction 

GetTotals response message example

<SaleToPOIResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="EpasSaleToPOIMessages.xsd">
    <MessageHeader  MessageClass="Service" 
                    MessageCategory="GetTotals" 
                    MessageType="Response" 
                    ServiceID="619" 
                    WorkstationID="SaleServer" 
                    POIID="POIServer"/>
        <GetTotalsResponse BatchID="8927">
            <Response Result="Success"/>
            <GratuityAmount Gratuity="20.00"/>
            <TransactionTotals  CardBrand="CardPlus" 
                                AcquirerID="876355543" 
                                ReconciliationID="98535" 
                                WorkstationID="SaleTermA" 
                                OperatorID="213" 
                                ShiftNumber="1" 
                                PaymentCurrency="EUR">
                <PaymentTotals TransactionType="Debit" TransactionCount="61" TransactionAmount="4253.19"/>
                <PaymentTotals TransactionType="Credit" TransactionCount="1" TransactionAmount="27.01"/>
            </TransactionTotals>
    </GetTotalsResponse>
</SaleToPOIResponse>

Transaction Flows

This section provides some example message flow diagrams. The earlier sections define the contents of the messages, this section shows how multiple messages are used to perform a complete function.

Start-up and Login

This diagram shows the start-up steps and sending the first message exchange. This will normally be a login request.

The dotted lines represent TCP-IP events and the solid lines are EPAS messages.

Payment Transaction (Example)


Payment Without Amount, Early PIN Entry (Example)



Payment With Swipe Ahead (Example)


 

<SaleToPOIResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="EpasSaleToPOIMessages.xsd">
<MessageHeader MessageClass="Service"
MessageCategory="GetTotals"
MessageType="Response"
ServiceID="619"
WorkstationID="SaleServer"
POIID="POIServer"/>
<GetTotalsResponse BatchID="8927">
<Response Result="Success"/>
<TransactionTotals CardBrand="CardPlus"
AcquirerID="876355543"
ReconciliationID="98535"
WorkstationID="SaleTermA"
OperatorID="213"
ShiftNumber="1"
PaymentCurrency="EUR">
<PaymentTotals TransactionType="Debit" TransactionCount="61" TransactionAmount="4253.19"/>
<PaymentTotals TransactionType="Credit" TransactionCount="1" TransactionAmount="27.01"/>
</TransactionTotals>
<TransactionTotals CardBrand="CardPlus"
AcquirerID="876355543"
ReconciliationID="98535"
WorkstationID="SaleTermD"
OperatorID="213"
ShiftNumber="2"
PaymentCurrency="EUR">
<PaymentTotals TransactionType="Debit" TransactionCount="45" TransactionAmount="744.79"/>
</TransactionTotals>
<TransactionTotals CardBrand="ExpressCard"
AcquirerID="876355543"
ReconciliationID="98535"
WorkstationID="SaleTermD"
OperatorID="29"
ShiftNumber="1"
PaymentCurrency="EUR">
<PaymentTotals TransactionType="Debit" TransactionCount="17" TransactionAmount="353.61"/>
</TransactionTotals>
<TransactionTotals CardBrand="ExpressCard"
AcquirerID="876355543"
ReconciliationID="98535"
WorkstationID="SaleTermD"
OperatorID="213"
ShiftNumber="2"
PaymentCurrency="EUR">
<PaymentTotals TransactionType="Debit" TransactionCount="18" TransactionAmount="711.48"/>
<PaymentTotals TransactionType="ReverseDebit" TransactionCount="1" TransactionAmount="37.99"/>
</TransactionTotals>
<TransactionTotals CardBrand="SuperBonus"
AcquirerID="93582"
WorkstationID="SaleTermD"
OperatorID="213"
ShiftNumber="1">
<LoyaltyTotals TransactionType="Award" TransactionCount="25" TransactionAmount="278"/>
</TransactionTotals>
<TransactionTotals CardBrand="SuperBonus"
AcquirerID="93582"
WorkstationID="SaleTermD"
OperatorID="213"
ShiftNumber="2">
<LoyaltyTotals TransactionType="Award" TransactionCount="23" TransactionAmount="182"/>
</TransactionTotals>
</GetTotalsResponse>
</SaleToPOIResponse>
  • No labels