Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents
AlternativePaymentMethod

Revision history

DateAuthorNotes
18/11/20Colin MacDonaldAdded revision history for change tracking
18/11/20Johan EkbergAdded ExtAuth element to receipt data to indicate that an external (i.e. outside of the terminal) payment process was used
18/2/21Per Erik StendahlAdded the MarkUpDescription field in the DCC information
1/6/21Per Erik StendahlAdded the ExtraPOIID element to the LoginRequest message
16/2/22Markus Jägerskogh

Added the attributes Method and ReferenceNumber to the PaymentData element and AlternativePaymentMethod to ReceiptData




Introduction

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

...

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

Method

[0..1]

If the ECR wants/needs to require the PA to use a specific Alternative Payment Method, the name of that method is supplied here.

Yes

ReferenceNumber

[0..1]

If this is a reversal of a purchase made using an Alternative Payment Method, the reversal requires the reference number of the original transaction here.

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]

 

 

...

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.

 

AlternativePaymentMethod

[0..1]

If the transaction was made using an Alternative Payment Method, the name of the method is provided here.

 

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. Note that the timezone offset may not be valid in this field, depending on the terminal being used.  Westpay Classic terminals do not support timezone changes.

 

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.

 

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. Concerning alternative payment transactions, i.e. element ExtAuth is present, the value for FinancialInstitution is a three letter abbreviation of the name of the alternative payment method.

 

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. 

MarkUpDescription

[0..1]Extra information about the markup that should be printed next to the markup (on the next line), if provided.

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. 

ExtAuth

[0..1]Available when a alternative payment transaction has been performed, that is a non card transaction. E.g. Swish payment. 

Name

[1..1]Name of the alternative payment method. 

...

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

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

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

PURCHASE
SEK                1000.00
TOTAL:             1000.00


458109******3825

VISA

   AUTHORISATION FOR 
 DEBITING ABOVE ACCOUNT 


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


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

C@1 3 001 SWE 170 968081

Ref. nr: 000000402771

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

Alternative Payment purchase approval example

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

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

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

KÖP
SEK                1000.00
TOTALT:            1000.00


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

Swish

Ref. nr: 000000402771

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

DCC example

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

...