Emvlumo API

(1)

Lumo

SUBJECT: INTERFACE SPECIFICATION (API) COMPANY: NETS OY

COMMENTS: Specifications for application interface

DATE: 31.05.2013

(2)

CONTENTS ... 1

1 GENERAL ... 4

1.1 C

HANGE LOG

... 4

1.2 G

ENERAL INFORMATION ABOUT THE INTERFACE

... 4

1.2.1 Notes on using payment terminals with USB cable ... 5

2 GENERAL INTERFACE FUNCTIONALITY ... 6

2.1 P

ROPERTIES FOR THE TRANSACTION

... 6

2.1.1 int Amount ... 6 2.1.2 int AmountOther ... 6 2.1.3 String ArchiveID ... 6 2.1.4 Hashtable BluetoothDevicesInRange ... 6 2.1.5 CardEntryModes CardEntryMode... 7 2.1.6 String CommunicationPortname ... 7 2.1.7 String DataStoragePath ... 7 2.1.8 String FailureInfo ... 7 2.1.9 bool MerchantInformationOnReceipt ... 7 2.1.10 bool OnlineAvailable ... 8 2.1.11 String ReceiptCustomer ... 8 2.1.12 String ReceiptGeneral ... 8 2.1.13 String ReceiptMerchant ... 8 2.1.14 String ReceiptTransmission ... 8 2.1.15 TerminalDeviceTypes TerminalDeviceType ... 8 2.1.16 String TransactionReceiverAN ... 8 2.1.17 int TransactionResult ... 8 2.1.18 TransactionTypes TransactionType ... 8 2.1.19 TransactionTypes BonusTransactionType ... 9 2.1.20 String UILanguageID ... 9 2.1.21 TerminalStates TerminalState ... 9 2.1.22 bool TCPDisconnect ... 9 2.1.23 bool HTTPProxyAuthentication ... 9 2.1.24 bool CheckIdentity... 9 2.1.25 bool CheckReceiptSignature ... 9 2.1.26 bool MenuState ... 10 2.1.27 String PAN ... 10 2.1.28 String DeviceInfo ... 10 2.1.29 String Track2Data ... 10 2.1.30 bool DebitPurchaseOnly... 10 2.1.31 String LastTransactionCurrency ... 10 2.1.32 Hashtable MultiCurrencyAmount ... 10 2.1.33 Hashtable MultiCurrencyAmountOther ... 11 2.1.34 bool UseBluetooth ... 11 2.1.35 bool MessagesInTransactionDialog ... 11 2.1.36 int TipAmount ... 11 2.1.37 bool QuasiCashTerminal ... 11

2.2 M

ETHODS

... 11

2.2.1 int BluetoothGetDevicesInRange (int MaxCountOfDevices, bool IncludeAuthenticated, bool IncludeRemembered) ... 11

(3)

2.2.2 bool BluetoothPairRequest(string DeviceAddress, string PIN) ... 12

2.2.3 void BluetoothRemoveDevice(string DeviceAddress) ... 12

2.2.4 bool CancelTransaction() ... 12

2.2.5 bool CloseConnection() ... 12

2.2.6 bool Disconnect() ... 12

2.2.7 bool EnableDisableMenu(bool Disable) ... 12

2.2.8 bool InitializeSystem() ... 12

2.2.9 bool LoadParameters() ... 13

2.2.10 bool MakeTransaction(TransactionTypes TransactionType) ... 13

2.2.11 bool OpenConnection() ... 13

2.2.12 bool SendTransactionsBatch(TransactionBatchMethods BatchMethod) ... 13

2.2.13 bool StartTransaction() ... 13

2.2.14 bool DoDisplay(String XMLText) ... 14

2.2.15 bool DoDisplayMenu(string Title, int Timeout, string Itemlist) ... 14

2.2.16 bool DoPrint(string Text) ... 15

2.2.17 String GetPreviousReceipts(string ArchiveID, bool GetReceiptInfo) ... 15

2.2.18 bool PrintPreviousReceipt() ... 16 2.2.19 bool PrintMerchantInfo() ... 16 2.2.20 bool ReadMagStripe() ... 17 2.2.21 bool CancelReadBonusInformation() ... 17 2.2.22 bool CancelReadMagStripe() ... 17 2.2.23 bool CheckUpdate() ... 17

2.2.24 bool CreateBonusTransaction(string BonusPAN, int BonusType, int BonusAmount, string BonusValidity) ... 17

2.2.25 bool GetAmountInput(int Line1, int Line2, int Line3, int Nextscreen, int Timeout) .... 17

2.2.26 bool GetButton(int TimeOut) ... 18

2.2.27 bool GetNumberInput(int Line1, int Line2, int Line3, int Nextscreen, int Timeout, bool Active) 18 2.2.28 bool MakeMultiCurrencyTransaction(TransactionTypes TransactionType) ... 18

2.2.29 bool PrepareTransaction(bool ReadBonusInformation)... 18

2.2.30 bool ReadBonusInformation() ... 19

2.2.31 bool StartMultiCurrencyTransaction() ... 19

2.2.32 bool GetTransactionReceipt() ... 19

2.3 E

VENTS DURING THE TASK

... 19

2.3.1 OnBypassPINRequest ... 19 2.3.2 OnCheckIdentity ... 19 2.3.3 OnCheckSignature ... 20 2.3.4 OnIsCardPresent ... 20 2.3.5 OnHotCardAction ... 20 2.3.6 OnManualAuthorizationRequest ... 20 2.3.7 OnPrintGenericReceipt ... 21 2.3.8 OnPrintTransactionReceipt ... 21 2.3.9 OnPrintTransmissionReceipt ... 21 2.3.10 OnRefundRequest ... 21 2.3.11 OnStatusUpdateReceived ... 22 2.3.12 OnTransactionFinished ... 22 2.3.13 OnTransactionStateChanged ... 22 2.3.14 OnVisualIdentificationRequest ... 23 2.3.15 OnTerminalStateChanged ... 23 2.3.16 OnGenericEvent ... 24 2.3.17 OnMgStripeReaden ... 24 2.3.18 OnBonusInformationReaden ... 24 2.3.19 OnGotInput ... 24 2.3.20 OnResponseToAPI ... 25

(4)

2.4 E

NUMERATIONS

... 25

2.4.1 CardEntryModes ... 25 2.4.2 TerminalDeviceTypes ... 25 2.4.3 TransactionBatchMethods ... 26 2.4.4 TransactionTypes ... 26 2.4.5 TransactionState ... 26 2.4.6 TerminalStates ... 28 2.4.7 FailureInfo ... 28

3 TCP/IP SOCKET INTERFACE WITH XML MESSAGES (XMLCOMM) ... 31

3.1 C

OMMUNICATION

... 31

3.2 B

ASIC XML FRAME STRUCTURE

... 31

3.3 P

ROPERTIES

... 31

3.3.1 Set property value ... 31

3.3.2 Get property value ... 31

3.4 M

ETHODS

... 32

3.4.1 Example: Calling MakeTransaction to make purchase ... 32

3.4.2 Example: Calling BluetoothGetDevicesInRange ... 32

3.5 E

VENTS

... 33

3.5.1 Example: StatusUpdate ... 33

3.5.2 Example: OnBypassPINRequest ... 33

3.6 E

XAMPLE TRANSACTION

... 34

4 LUMOAPI COM INTEROP DLL ... 39

4.1 P

ROGRAMMING EXAMPLE (VISUAL BASIC

) ... 39

5 USAGE ... 41

5.1 E

XAMPLE: STARTING IN WINDOWS

... 42

6 INSTALLATION ... 43

6.1 I

NSTALLATION ON WINDOWS

... 43

7 TRANSACTION DIALOGS IN MAKETRANSACTION METHOD CALL ... 44

8 BASIC TRANSACTION FLOWS ... 50

8.1 BASIC CHIP TRANSACTION WITH STARTTRANSACTION METHOD ... 51

8.2 B

ASIC MAGNETIC STRIPE TRANSACTION WITH STARTTRANSACTION METHOD

... 52

8.3 M

AKETRANSACTION CALL

... 53

9 GETNUMBERINPUT AND GETAMOUNTINPUT LINE TEXTS ... 54

10 BONUS INFORMATION HANDLING ... 55

10.1 R

EADBONUSINFORMATION AND STARTTRANSACTION

... 55

10.2 T

RANSACTION STARTED WITH PREPARETRANSACTION CALL WITH READBONUSINFORMATION PARAMETER SET TO TRUE

... 59

10.2.1 Example: bonus information is read from chipcard and payment is given with another chipcard ... 59

(5)

1 GENERAL

1.1 Change Log

CHANGES

Change Version Date Name

Generic document update 1.06.00_v2 29.01.2013 Aka Changed Transaction States to decimal values.

Updated information about bonuses.

1.07.00 13.02.2013 SS Added BonusTransactionType property,

DoDisplayMenu and DoPrint methods. Added transaction flow diagram.

1.07.02 25.02.2013 ET

Added GetTransactionReceipt method and

MessagesInTransactionDialog property 1.07.03 23.3.2013 SS

Updated InputType information and added chapter about LumoAPI COM Interop DLL.

1.07.04 15.4.2013 ET Updated enum TransactionBatchMethods values

and SendTransactionBatch method. Updated

information about TransactionStateChanged-event, PAN has been removed from it earlier.

1.07.05 23.4.2013 SS

Updated DoDisplayMenu method information 1.07.06 15.5.2013 SS Added TipAmount and QuasiCashTerminal

Properties. Changed right decimal value for PinEntryCompleted in TransactionStates.

1.07.07 22.5.2013 SS

Added failureinfos to SendTransactionBatches.

Updated FailureInfo enum 1.07.08 31.5.2013 SS

1.2 General Information about the Interface

The calling program does not need to be EMV compliant, as Lumo takes care of all card payment procedures requiring EMV certification. It is however required, that all receipt lines

returned from Lumo are printed to the receipt without modifications.

Supported device types at the moment are Ingenico ML-30 series, iPP350 and iWL250 terminals. Currently supported operating systems and other additional requirements e.g. firewall

(6)

Interface consists of the TCP/IP Socket API. Socket interface is listening incoming request that are XML formatted. Format of the XML is described in this document in chapter 3 as properties, methods and events.

Interface for payment transaction can be used in two different modes. a) Dialog made and developed by Nets Oy

 Transaction is started with method MakeTransaction b) Transaction flow is controlled by external program

 Transaction is started with method StartTransaction

Option a) is easier way to achieve functionality for payments and it does not require any handling for the events in the API. However, in this option the EMVLumoAgent shows the dialog, so this might not be suitable if EMVLumoAgent is installed on a different PC than POS. Option b) requires that all the events are handled by external program calling API. This means that you should implement a dialog of your own to control the transaction. Instructions how to handle events are documented in events chapter 2.3. See MakeTransaction (2.2.10) and StartTransaction (2.2.13) methods.

You need to save receipts, filing code (archive id) and TransactionReceiverAN (settlement id) after successful transaction. Filing code identifies transaction and it can be used to follow it. It is also required for cancellation of the payment. Settlement id tells what type of card has been used for transaction.

If it is required to get some information for back office systems about transactions or batches that information may be extracted from the EmvHostOnline service. It is out of this document’s scope to explain that functionality.

There is also support for using EmvCard type of XML interface called "Dopay". Dopay protocol is described in another document and it is only there for supporting old integrations.

All new implementations should be done using XML-API that offers a lot more options and flexibility.

1.2.1 Notes on using payment terminals with USB cable

Payment terminals are normally connected to the system with the USB cable. If cable is disconnected unexpectedly it cannot always be detected by the Lumo system. If it happens during transaction, the transaction will be interrupted but you cannot know if it was registered into device. You can use functions to check last transactions to see if it was registered.

After USB disconnect is may be required to shut down all programs using port or call CloseConnection() to release port. It may also be required to reboot device again to allow access to port after disconnect.

Lumo application tries to reconnect terminal after reboot or power loss but there are some cases caused by virtual USB serial port where virtual USB port is locked by OS and interface cannot reconnect terminal.

(7)

2 GENERAL INTERFACE FUNCTIONALITY

2.1 Properties for the Transaction

2.1.1 int Amount

 The amount being debited or credited  Mandatory for all transactions

 Given without decimal separator (for example 1000 = € 10,00)  Always positive number

2.1.2 int AmountOther

 The amount being debited or credited  Mandatory in the following cases:

o Mandatory for all Cashback transactions

2.1.3 String ArchiveID

 Defines the filing code (archive identifier), which is used in referring to previous transactions

 Optional, except mandatory for Refund or cancellation transactions  The archive identifier is always found on the original receipt and

identifies transaction

 Cancellation transaction has the same filing code as original transaction

2.1.4 Hashtable BluetoothDevicesInRange

 Only supported on Windows and CE platforms  Gets the Bluetooth devices in range.

 Collection of the Bluetooth devices in range. XML formatted information structure

 It contains hashtable of devices and different properties can be extracted from the XML structure.

 In XML interface data is received as XML formatted string.  XML data contains following fields by device

o DeviceAddress, Bluetooth device address, presented as hexadecimal form

o DeviceName, Bluetooth device name, string value. It may be required to call this multiple times to get the name of the device. This is restriction in Bluetooth protocol

o Authenticated, specifies whether the device is authenticated, paired or bonded, “True” or “False” string values

o Connected, specifies whether the device is connected, “True” or “False” string values

(8)

o Remembered, specifies whether the device is a remembered device. Not all remembered devices are authenticated. “True” or “False” string values

o LastSeen, date and time this device was last seen by the system. Presented as formatted string value,

“yyyyMMddHHmmss”

o LastUsed, date and time this device was last used by the system. Presented as formatted string value,

“yyyyMMddHHmmss”  Example <DeviceAddress>000190E63E19</DeviceAddress><DeviceName>PP03100 00077</DeviceName><Authenticated>False</Authenticated><Connected >False</Connected><Remembered>False</Remembered><LastSeen>201 00527200708</LastSeen><LastUsed>00010101000000</LastUsed> 2.1.5 CardEntryModes CardEntryMode

 Card entry mode for transaction. Combined reader or manual entry. See CardEntryModes enumeration 2.4.1.

 Default value is CombinedReader (0) 2.1.6 String CommunicationPortname

 Communication port used for connections to terminal device.  In case of the Bluetooth device this is the Bluetooth device address

(see BluetoothDevicesInRange property).  Example “COM9”

2.1.7 String DataStoragePath

 Where all the parameters and log files should be stored.  If empty, current path is used.

 Value can be local path or UNC-path. 2.1.8 String FailureInfo

 Contains information on errors, failures and declines that may happen at starting transaction or during process

 Property returns XML formatted information  Example:

 There can be multiple errors included in message 2.1.9 bool MerchantInformationOnReceipt

 Indicates whether merchant information (Name, street address, city, business identity code and phone number) is displayed on merchant receipt

(9)

2.1.10 bool OnlineAvailable

 Indicates if online network connection is available for use.  If disabled Lumo API won’t relay http requests to NetPAK server

(authorizations, getting parameters etc.) 2.1.11 String ReceiptCustomer

 Formatted layout data for customer receipt to be printed.  Receipt lines must be printed without modifications 2.1.12 String ReceiptGeneral

 Unformatted receipt to be printed.

 Contains generic print receipt to be printed. E.g. “Application version updated” or “Parameters expired”.

2.1.13 String ReceiptMerchant

 Formatted layout data for merchant receipt to be printed.  Receipt lines must be printed without modifications 2.1.14 String ReceiptTransmission

 Formatted layout data for transmission receipt (settlements). 2.1.15 TerminalDeviceTypes TerminalDeviceType

 Type of the terminal device. This may be set and saved outside of the interface.

 This value can be always ML30 even if the terminal is not ML30.  See TerminalDeviceTypes enumeration 2.4.2.

2.1.16 String TransactionReceiverAN

 Alphanumeric settlement identification code for the transaction.  Should be saved after transaction.

 Can be used to identify used card type 2.1.17 int TransactionResult

 Result code returned from the transaction.  0 = Accepted and 1 = Declined.

2.1.18 TransactionTypes TransactionType

 Type of the transaction. E.g. purchase or refund.  In XML interface value is presented as integer.

 Currently supported values: purchase = 0, cancel or refund = 1, cash withdrawal = 2, (cashback = 3, bonus = 6) and sending transactions = 8. See TransactionTypes enumeration 2.4.4.  If not set, default value purchase (0) is used.

(10)

2.1.19 TransactionTypes BonusTransactionType  Type of bonus transaction.

 In XML interface value is presented as integer.

 Supported values: purchase = 0, cancel or refund = 1.  If not set, default value purchase (0) is used.

2.1.20 String UILanguageID

 Language ID for user interface (merchant view).  Supported values are “fi”, “sv” and “en”.

2.1.21 TerminalStates TerminalState  State of terminal

 Value is presented as integer. See TerminalStates enumeration 2.4.6.

2.1.22 bool TCPDisconnect

 Controls how the TCP server handles socket connections

o If true the server will disconnect socket after every property or function. During StartTransaction function the socket is open until transaction is finished.

o If false socket is kept open until client closes it. This is the

preferred way to handle connection!  Only usable in XML interface

 XML Example:

<?xml version=”1.0” encoding=”utf-8”?><EMVLumo

xmlns=http://www.luottokunta.fi/EMVLumo><SetTCPDisconnect><Value> False</Value></SetTCPDisconnect></EMVLumo>

2.1.23 bool HTTPProxyAuthentication

 Indicates whether domain user credentials are sent with http requests to the http proxy. Only usable in Windows environment.  Some proxies authenticate user by domain user credentials and it is

needed that those are sent with HTTP requests. 2.1.24 bool CheckIdentity

 Indicates to merchant to check identity of the cardholder  E.g. Finnish bank cards over 50 euros amount

 In this case the merchant receipt will also have a place for identification

2.1.25 bool CheckReceiptSignature

 Indicates that merchant receipt has signature section and merchant is expected to check that customer’s signature matches one on the card

(11)

 Can be also used to check if signature receipt is about to be printed 2.1.26 bool MenuState

 Enables or disables menu button functionality in terminals. 2.1.27 String PAN

 Primary account number of last successful transaction. 2.1.28 String DeviceInfo

 Returns XML formatted information of payment terminal.  Usable only after initializing terminal.

 Message fields

Serial – Unique serial number.

Version – Software version of payment terminal Type – Terminal model and version

Merchant – Merchant ID POS – POS ID Terminal – Terminal ID  Example: <DeviceInfo> <Serial>29501109000010591234</Serial> <Version>v 1.4.952</Version> <Type>ML30 v 1.4.952</Type> <Merchant>111111111123</Merchant> <POS>004</POS> <Terminal>12C97004</Terminal> </DeviceInfo> 2.1.29 String Track2Data

 Track 2 of card’s magnetic stripe.

 Available after calling ReadMagStripe method and when card has been read.

2.1.30 bool DebitPurchaseOnly

 Indicates whether debit only transactions are allowed 2.1.31 String LastTransactionCurrency

 Currency code of last successful transaction (only in multicurrency transactions)

2.1.32 Hashtable MultiCurrencyAmount

 The amount being debited or credited  Mandatory for all multicurrency transactions

(12)

 Value indicates amount in that currency 2.1.33 Hashtable MultiCurrencyAmountOther

 The amount being debited or credited  Mandatory in the following cases:

o Mandatory for all Cashback multicurrency transactions  Given without decimal separator (for example 1000 = € 10,00)  Always positive number

 Key indicates currency code in string format (e.g. EUR, SEK)  Value indicates amount in that currency

2.1.34 bool UseBluetooth

 Defines whether Lumo should use Bluetooth connection towards the terminal

 This is optional as setting CommunicationPortname (see chapter 2.1.6) as a Bluetooth address will automatically enable this property 2.1.35 bool MessagesInTransactionDialog

 True, TransactionStateChanged-events come to API layer in MakeTransaction method. Various property values are updated from that event.

 False, TransactionStateChanged-events in MakeTransaction method are handled in GUI. API layer properties are not updated.

 This property should be true if MakeTransaction is used with XML API and properties

 Value is stored in database and read from there. Initial value after installation is false

2.1.36 int TipAmount

 Supported from Lumo 1.8

 Tip handling feature can be enabled only in device configuration  Returns tip amount. Property cannot be set

2.1.37 bool QuasiCashTerminal

 Supported from Lumo 1.8

 Quasi cash feature can be enabled only in device configuration  Returns true if terminal is capable of handling quasi cash

transcations

2.2 Methods

2.2.1 int BluetoothGetDevicesInRange (int MaxCountOfDevices, bool IncludeAuthenticated, bool IncludeRemembered)

 Only supported on Windows and CE platforms

 Finds Bluetooth devices in the range. Execution is blocked while Bluetooth devices are enumerated.

(13)

 Parameters:

o MaxCountOfDevices, the max count of devices

o IncludeAuthenticated, show also devices that have been already paired.

o IncludeRemembered, if set to true remembered devices are included in the query.

 Returns number of devices in range and initializes BluetoothDevicesInRange property.

2.2.2 bool BluetoothPairRequest(string DeviceAddress, string PIN)  Only supported on Windows and CE platforms  Sends pairing request to Bluetooth stack  Parameters:

o DeviceAddress, Bluetooth address for device to pair o PIN, Pin code for pairing

 Returns true if pairing succeeded. 2.2.3 void BluetoothRemoveDevice(string DeviceAddress)

 Only supported on Windows and CE platforms  Removes the device from paired items.  Parameters:

o DeviceAddress, The device address to be removed. 2.2.4 bool CancelTransaction()

 Cancels on-going transaction. Command is valid only when card has not been entered in terminal. Terminal interrupts transaction if possible.

 Returns true if command received successfully.

 If transaction is interrupted, transaction is finished with result declined.

2.2.5 bool CloseConnection()

 Closes the connections to the terminal.  Returns true if succeeded.

2.2.6 bool Disconnect()

 Forces server to disconnect current TCP socket. 2.2.7 bool EnableDisableMenu(bool Disable)

 Enables or disables Menu button functionality in terminal. 2.2.8 bool InitializeSystem()

(14)

 Returns true if connection was successful and initialization of parameters succeeded.

 Terminal may in certain cases reboot after initialization return. This can happen e.g. if terminal was offline (shut down) during the batch delivery. Reboot does not occur in normal conditions but you cannot rely on that everything is ready for transaction when this method returns.

2.2.9 bool LoadParameters()

 Used to load parameters for terminal.

 Returns true if parameters have been loaded successfully.  Terminal restarts after this command to load parameters. 2.2.10 bool MakeTransaction(TransactionTypes TransactionType)

 Starts transaction and returns control to calling application when transaction is finished.

 By this method call build in dialogs are shown by EMVLumoAgent and no events are fired to calling party.

 Transaction amount must set before calling this function.  Parameters:

o TransactionType, type of transaction to start (see 2.4.4). E.g. purchase or refund

 Returns true if transaction is accepted and false if declined. 2.2.11 bool OpenConnection()

 Attempts to open the connection to the terminal.

 CommunicationPortname and TerminalDeviceType properties must be set before calling this.

 Returns true if connection was opened successfully.

 After OpenConnection InitializeSystem should always be called 2.2.12 bool SendTransactionsBatch(TransactionBatchMethods BatchMethod)

 Attempts to send transaction batches.

 In Matador-mode, different batch sending types can be used with BatchMethod parameter. (1.7 SP1)

 CommunicationPortname and TerminalDeviceType properties must be set before calling this.

 Returns true if transactions sending was able to be started.  FailureInfo contains information if method was not succeed (1.8) 2.2.13 bool StartTransaction()

 Starts the transaction.

 Difference between StartTransaction and MakeTransaction methods is that MakeTransaction method handles transaction by its own UI

(15)

and StartTransaction method gives calling application (POS) events that it has to handle.

 Returns true if transaction has started successfully. If starting failures terminal might be in unexpected state or the serial/USB connection is lost.

 Transaction is finished either when OnTransactionFinished event is fired with declined return value or OnPrintTransactionReceipt event is fired with customer receipt.

2.2.14 bool DoDisplay(String XMLText)

 Used to show text in terminal while not in transaction state.  Returns true if succeeded

 Default text is restored after terminal reboot.  Message fields:

DoDisplay – actual message

Clear – Indicates whether terminal’s display should be cleared before showing a message. Tag is allowed only once in DoDisplay message. Boolean value.

RowText – Text in rows. Multiple or zero RowText tags can be in one DoDisplay message.

Row – Row number for text. Integer value.

Inverse – Inverse colors in message. Boolean value.

Alignment – Allowed values are Left, Center and Right. Alignment for row text.

Text – Text shown in row.  Example: <DoDisplay> <Clear>true</Clear> <RowText> <Row>0</Row> <Inverse>True</Inverse> <Alignment>Left</Alignment> <Text>Hello</Text> </RowText> <RowText> <Row>0</Row> <Inverse>False</Inverse> <Alignment>Right</Alignment> <Text>World!</Text> </RowText> </DoDisplay>

2.2.15 bool DoDisplayMenu(string Title, int Timeout, string Itemlist)

 Show selectable items on terminal in menu format. After user has selected an item OnGotInput -event is fired with selected menu item number.

 Due the blocking nature of this method, automated daily transaction batch sending and fetching parameters cannot be

(16)

guaranteed. Locking of transactions batches should be done using SendTransactioBatches method and daily parameters update using LoadParameters method.

 Parameters:

o Title – Title of menu.

o Timeout – Timeout in milliseconds. If 0 no timeout will be used.

o Itemlist – Comma separated list of menu items.  Returns true if menu is shown successfully on terminal. 2.2.16 bool DoPrint(string Text)

 Print text on terminal's printer.  Parameters:

o Text - Text to be printed.

 Return true if text was successfully printed.

2.2.17 String GetPreviousReceipts(string ArchiveID, bool GetReceiptInfo)

 Returns XML formatted list of previous transaction receipts. Terminal has to be initialized before use.

 Parameters:

ArchiveID – ArchiveID of receipt. If empty string, all receipts are shown.

GetReceiptInfo – If true, receipt texts are shown.  Message fields:

ReceiptType – “0” if merchant receipt and “1” if customer receipt ArchiveID – Archive identifier

EventDate – Receipt’s timestamp Text – Receipt text

 Example of XML formatted list: <Receipts> <Receipt> <ReceiptType>0</ReceiptType> <ArchiveID>110105004002</ArchiveID> <EventDate>5.1.2011 13:34:20</EventDate> <Text> Toni+Test \n Testikatu 1 \n 00100 Testilä \n

1234567890 \nSELITE: OSTO\nKORTTI: VISA CREDIT\nKÄYTTÖTAPA:LUOTTOKORTTI\nAID ID: A0000000031010\nNUMERO: ...8298\nAVIITE: 110105004002\nTVR: 0000000000 TSI: E800\nYRITYS: 111111111997 KP: 4 TA: 5399\n---\nVELOITUS: 1.00 EUR\n---\nKAUPPIAAN TOSITE: 05.01.2011 13:34:19\n</Text> </Receipt> <Receipt> <ReceiptType>1</ReceiptType>

(17)

<ArchiveID>110105004002</ArchiveID> <EventDate>5.1.2011 13:34:21</EventDate> <Text>SELITE: OSTO\nKORTTI: VISA

CREDIT\nKÄYTTÖTAPA:LUOTTOKORTTI\nAID ID: A0000000031010\nNUMERO: ...8298\nAVIITE: 110105004002\nTVR: 0000000000 TSI: E800\nYRITYS: 111111111997 KP: 4 TA: 5399\n---\nVELOITUS: 1.00 EUR\n---\nASIAKKAAN TOSITE: 05.01.2011 13:34:19\n</Text> </Receipt> </Receipts> 2.2.18 bool PrintPreviousReceipt()

 Commands terminal to send previous receipt  Returns true if succeeded

 Previous receipt is received by event (OnPrintGenericReceipt, OnPrintTransactionReceipt, OnPrintTransmissionReceipt)

 For transaction receipts applies method GetTransactionReceipt (1.6 SP3)

2.2.19 bool PrintMerchantInfo()

 Commands terminal to send merchant info  Returns true if succeeded

 Merchant info is received by OnPrintGenericReceipt event  Example receipt:

AS.TUNNUS: 123456789012 NIMI: Test Customer

OSOITE: Teststreet 1 KAUPUNKI: 00100 Testtown PUH.NRO: 1234567890 POS ID: 007 PANKKI: 010 TOIMIALAKOODI: 5399 OLETUSKIELI: fi TUETUT KIELET: fisven AUTOM. LÄH.AIKA: 16:38 AUTOM. LÄH. PÄÄLLÄ: 0 LAITT. SARJANUMERO: 29501109000010598154 SOPIMUKSET: LIITTYMÄTUN.: 100 SOP. NRO: 1111111 VARM. RAJA: 999999 LIITTYMÄTUN.: 040 SOP. NRO: 111111111997 VARM. RAJA: 999999 LIITTYMÄTUN.: 110 SOP. NRO: 9425821733 VARM. RAJA: 999999 LIITTYMÄTUN.: 120 SOP. NRO: 11111111 VARM. RAJA: 999999

(18)

2.2.20 bool ReadMagStripe()

 Begins to wait magnetic stripe data. When card has been swiped the track2 data will be available.

 Event OnMgStripeReaden is raised when data has been read. Data is also stored into Track2Data property.

 It is possible to get data only for payment or loyalty cards that are not in PCI scope.

 To read bonus and loyalty cards ReadBonusInformation –method is recommended.

2.2.21 bool CancelReadBonusInformation()

 Cancels ReadBonusInformation function call if terminal is in insert card state.

2.2.22 bool CancelReadMagStripe()

 Cancels ReadMagStripe function call if terminal is in insert card state.

2.2.23 bool CheckUpdate()

 Checks if updates are available for terminal.

 Update is not allowed if terminal holds unsent transactions. 2.2.24 bool CreateBonusTransaction(string BonusPAN, int BonusType, int

BonusAmount, string BonusValidity)

 Creates bonus transaction.

 Uses also properties BonusTransactionType, CardEntryMode and ArchiveID.

 In bonus transaction cancellation ArchiveID must be given and PAN not empty (ex. “0”)

 In bonus transaction refunds ArchiveID should be empty.  Parameters:

o PAN, PAN present in the bonus information

o BonusType, 1 = Ykkösbonus, 2 = S-Bonus, 3 = Plussa o BonusAmount, Bonus transaction amount

o BonusValidity, Bonus card validity. Optional. If not given, assuming validity “0000”.

2.2.25 bool GetAmountInput(int Line1, int Line2, int Line3, int Nextscreen, int Timeout)

 Reads user inputted amount from terminal. Amount input starts by terminal showing Line 1-3. After user has pressed first number button terminal will show new screen where first line is expressed by parameter Nextscreen. User inputted amount will be returned by OnGotInput event.

(19)

o Line1, Line2, Line3, Nextscreen. See reference to chapter 9. o Timeout, 1-65535 ms. If 0 there is no timeout.

2.2.26 bool GetButton(int TimeOut)

 Reads user inputted button press. Following buttons will be returned on OnGotInput event. o CANCEL = 24 o CLEAR = 8 o ENTER = 13 o F1 = 128 o F2 = 129 o F3 = 139 o F4 = 141  Parameters:

o Timeout, 1-65535 ms. If 0 there is no timeout. 2.2.27 bool GetNumberInput(int Line1, int Line2, int Line3, int Nextscreen, int

Timeout, bool Active)

 Reads user inputted number. Number input starts by terminal showing Line 1-3. After user has pressed first number button terminal will show new screen where first line is expressed by parameter Nextscreen. User inputted number will be returned by OnGotInput event.

 Parameters:

o Line1, Line2, Line3, Nextscreen. See reference to chapter 9. o Timeout, 1-65535 ms. If 0 there is no timeout.

o Active. If true, terminal won’t send transactions and stays in GetNumberInput state.

2.2.28 bool MakeMultiCurrencyTransaction(TransactionTypes TransactionType)  Same as MakeTransaction but with multicurrency.

 Amount is set to MulticurrencyAmount –property and AmountOther is set to MulticurrencyAmountOther –property.

2.2.29 bool PrepareTransaction(bool ReadBonusInformation)

 Starts transaction before final amount of transaction is known. This way transaction process can be accelerated since card information is read beforehand and bonus information can be returned to POS before actual transaction is started.

 Parameters:

o ReadBonusInformation. If true, bonus information is read from first card read.

(20)

o Reading bonus information doesn’t create automatically bonus transaction after transaction. See CreateBonusTransaction.

 See chapter 10.2 for more information. 2.2.30 bool ReadBonusInformation()

 Reads bonus information from card (chip or magstripe) or manually inputted card number (set CardEntryMode property)

 Bonus information is returned by OnReadBonusInformation event.  Reading bonus information doesn’t create automatically bonus

transaction after transaction. See CreateBonusTransaction.  See chapter 10.1 for more information.

2.2.31 bool StartMultiCurrencyTransaction()

 Same as StartTransaction but with multicurrency.

 Amount is set to MulticurrencyAmount property and AmountOther is set to MulticurrencyAmountOther property.

2.2.32 bool GetTransactionReceipt()

 Commands terminal to send previous transaction receipt to API (1.6 SP3)

 Returns true if succeeded

 Previous receipt is received in event OnPrintTransactionReceipt

2.3 Events during the task

2.3.1 OnBypassPINRequest

 Occurs when trying to bypass PIN entry.

 Cardholder can initiate this by pressing red button on the device and merchant must accept bypass.

 Handled via PINBypassRequestHandler(ref bool BypassAccepted)  Parameters out:

o BypassAccepted, true if bypass is acceptable or false if not. If false then transaction is interrupted and

OnTransactionFinished with declined return value is given. 2.3.2 OnCheckIdentity

 Occurs when terminal asks merchant to check identity of the cardholder

 E.g. Finnish bank cards over 50 euros amount  Handled via CheckIdentityHandler()

 Merchant receipt will also have place for identification  No parameters.

(21)

2.3.3 OnCheckSignature

 Occurs when merchant receipt has signature section and merchant is expected to check that customer’s signature matches one on the card

 Handled via CheckSignatureHandler() 2.3.4 OnIsCardPresent

 Occurs when merchant is asked to check if card is present

 This may happen with cancellation of payment and depends on card parameters

 Handled via IsCardPresentHandler(ref bool Result)  Parameters out:

o Result, true if card was present 2.3.5 OnHotCardAction

 Occurs when card is found on hotcard list with certain code that requires action from merchant

 Handled via HotCardActionHandler(int ActionCode, String Instructions, String Question, ref int Result)

 Parameters in:

o ActionCode, Numeric action code for informational purposes o Instructions, Instructions to merchant

o Question, Question that asks if card was taken from customer

 Parameters out:

o Result, 0 if card was taken from payer or 1 if card was not taken from payer

2.3.6 OnManualAuthorizationRequest

 Occurs when terminal asks merchant to make call confirmation  Occurs usually when online authorization fails.

 Handled via ManualAuthorizationHandler(string MerchantID, string PAN, string Amount, string PhoneNumber, ref string

AuthorizationCode)  Parameters in:

o MerchantID, merchants identification o PAN, Primary Account Number

 PAN is masked so merchant should look at terminal’s screen for full PAN

o Amount, Transaction amount

o PhoneNumber, Phone number where to call.  Parameters out:

(22)

o AuthorizationCode, the code that has been given by the authorized party.

2.3.7 OnPrintGenericReceipt

 Occurs when terminal sends generic print request to PC.  It is not necessary for POS system to handle these events.  These events contain generic information, e.g. terminal version

update information

 Handled via GenericPrintHandler(string ReceiptData)  Parameters in:

o ReceiptData, unformatted text data 2.3.8 OnPrintTransactionReceipt

 Occurs when terminal sends transaction receipt print request to PC after accepted transaction

 Same information can be obtained from ReceiptMerchant and ReceiptCustomer properties

 Handled via TransactionReceiptHandler(int ReceiptType, string ReceiptData)

 Parameters in:

o ReceiptType, “0” if merchant receipt and “1” if customer receipt

o ReceiptData, formatted transaction receipt 2.3.9 OnPrintTransmissionReceipt

 Occurs when terminal sends transmission receipt print request to PC.

 Same information can be obtained from TransmissionReceipt property

 Handled via TransmissionReceiptHandler(string ReceiptData)  Parameters in:

o ReceiptData, formatted transmission receipt 2.3.10 OnRefundRequest

 Occurs when terminal asks merchant to confirm refund when

original transaction for cancellation was not found with given archive id

 Handled via RefundRequestHandler(ref bool RefundAccepted, ref bool FullRefund)

 Parameters out:

o RefundAccepted, true if refund is accepted o FullRefund, true if full refund is accepted

(23)

2.3.11 OnStatusUpdateReceived

 Occurs when terminal updates its own or transaction status, these messages can be http request, terminal start-up messages, announcement that terminal reboots etc.

 These messages are purely informational for POS

 Handled via StatusUpdateEventHandler(int StatusCode, string StatusInfo)

 Parameters in:

o StatusCode, integer value of status code. There is no list for the valid codes and this may change without notifications. Mainly for internal use.

o StatusInfo, information concerning this status update 2.3.12 OnTransactionFinished

 Occurs when transaction finishes.

 Handled via TransactionFinishedHandler(byte StatusCode, int Result, string TransactionReceiverAN)

 Parameters in:

o StatusCode, see chapter 2.4.5. o Result, 0 = Accepted, 1 = Declined

o TransactionReceiverAN, Settlement identification as alphanumeric string

2.3.13 OnTransactionStateChanged

 Occurs when transaction state changes. E.g. Reading card, enter pin, authorization etc.

 Handled via TransactionStateEventHandler(int TransactionType, int Amount, string ArchiveID, int Result, int InputType, string TVR, string TSI, byte State, string TransactionReceiverAN, bool

CheckIdentity, int IssuerCountryCode, string TransactionSyncID, string PAN)

 Fields are filled as transaction goes on, e.g. TVR/TSI information is filled in later transaction states

 Parameters in:

o TransactionType, type of the transaction which was given before calling StartTransaction method. See chapter 2.1.18. o Sum, amount of transaction which was given before calling

StartTransaction method. See chapter 2.1.1. o ArchiveID, archive identifier

 Can be obtained from TransactionReceiverAN property afterwards

o Result, 0 = Accepted and 1 = Declined

(24)

 0 = Manual input  1 = Magnetic stripe  2 = Chip

o TVR, Terminal verification result o TSI, Transaction status information

o State, Actual state for the transaction. See chapter 2.4.5. o TransactionReceiverAN, Settlement identification as

alphanumeric string

 Can be obtained from TransactionReceiverAN property afterwards

o CheckIdentity, Informs if the cardholder identity should be checked

 See also OnCheckIdentity event that is raised also is this value is true

o IssuerCountryCode, contains country code if transaction was made from chip

o TransactionSyncID, merchant ID(9+3) + archive ID(12) + time HHMMSS(6)

o PAN, with PrepareTransaction method masked PAN of card’s payment application is returned to POS. It can be used to determinate correct BIN range.

2.3.14 OnVisualIdentificationRequest

 Occurs when it is required to visually identify card. Occurs usually with non-domestic cards.

 Handled via VisualIdentificationHandler(string CardName, ref bool Accepted)

 Parameters in:

o CardName, name of the card (brand)  Parameters out:

o Accepted, true if card name matches to the physical card brand.

2.3.15 OnTerminalStateChanged

 Occurs when terminal changes its state, e.g. ML-30 does reboot itself while updating its software. By this event API informs when terminal is ready to use or when it does reboot.

 Handled via TerminalStateChangeHandler(int TerminalState)  Parameters in:

o TerminalState, see TerminalStates enumeration 2.4.6.  Parameters out:

(25)

2.3.16 OnGenericEvent

 Reserved for future use. 2.3.17 OnMgStripeReaden

 Occurs when track2 data has been read by magnetic stripe reader with ReadMagStripe function call.

 Handled via MgStripeReaderHandler(string Track2)  Parameters in:

o String Track2

- Contains track2 data as it has been read  Parameters out:

o None 2.3.18 OnBonusInformationReaden

 Occurs when card has been read after ReadBonusInformation call or PrepareTransaction with ReadBonusInformation set.

 Handled via BonusInformationReaderHandler(string PAN, int BonusType, string SettlementInfo, string CustomerSegment, string Validity)

 Parameters in: o String PAN

 PAN present in the bonus information  If not present empty string is returned o Int BonusType

 1 = Ykkösbonus, 2 = S-Bonus, 3 = Plussa  If not present 0 is returned

o String SettlementInfo

 Returned if available for given bonus type and information

 If not present empty string is returned o String CustomerSegment

 Returned if available for given bonus type and information

 If not present empty string is returned o String Validity

 Validity of the card if available 2.3.19 OnGotInput

 Occurs when user has inputted data after GetAmountInput, GetButton, GetNumberInput or DoDisplayMenu call.

(26)

 GetAmountInput returns amount comma separated format (XX.XX), e.g. 104.02

 GetButton returns button that was pressed. Values are: CANCEL = 24 CLEAR = 8 ENTER = 13 F1 = 128 F2 = 129 F3 = 130 F4 = 141

 GetNumberInput returns number that user entered, e.g. 123456.  DoDisplayMenu returns menu item number that was selected e.g. 2.  Parameters in:

o String Result 2.3.20 OnResponseToAPI

 Occurs when user has requested last transaction’s parameters or receipt

 Handled via ResponseToAPIEventHandler(Hashtable Data)

2.4 Enumerations

2.4.1 CardEntryModes

 Card entry mode  Members:

o CombinedReader = 0 o ManualEntry = 1 2.4.2 TerminalDeviceTypes

 Terminal device types  Members:

o NONE = 0, initial state where no terminal is not set o SagemML30 = 30 o SagemML30COM = 31 o SagemiCT250 = 221 o SagemiWL250 = 240 o SagemiWL250B = 242 o SagemiWL250G = 245 o SagemiPP350 = 321

(27)

o Sagem930 = 930 o Sagem930B = 931

 Normally there is no need change device type between terminals. SagemML30 should work with all of the terminals.

2.4.3 TransactionBatchMethods  Members: o NONE = 0 o SendUnsentTransactions = 1 o LockBatches = 2 o GetReport = 3

 NONE works as always; sends, locks and gets report from server.  LockBatches also sends unsent transactions and locks transactions in

server. (1.7 SP1)

 GetReport gets all transmission reports from server which hasn’t been received before. (1.7 SP1)

 SendUnsentTransactions, LockBatches and GetReport work only if terminal is configured ‘Matador-mode’ (1.7 SP1)

 LockBatches and GetReport can only be called if terminal is configured be Master terminal (1.7 SP1)

2.4.4 TransactionTypes

 All possible transaction types  Members:

o Purchase = 0, normal payment o Refund_Cancel = 1 o CashWithdrawal = 2 o Cashback = 3 o Bonus = 6 o SendTransactions = 8 2.4.5 TransactionState

 State of the transaction  Members:

o InsertCard = 0 (0x00)

 Chip card should be inserted in terminal OR  Card number should be entered in terminal o SearchingForCancellingTransaction = 1 (0x01)

 Terminal is searching transaction to be cancelled o SelectLanguage = 16 (0x10)

 Language selection o SelectApplication = 32 (0x20)

(28)

o ReadingCard = 48 (0x30)  Terminal is reading card o EnterPin = 64 (0x40)

 Payer is entering PIN o IncorrectPIN = 65 (0x41)

 Payer entered incorrect PIN o LastPinTry = 66 (0x42)

 Payer has last try for PIN entry o PinLocked = 67 (0x43)

 Card PIN has been locked o PinEntryCompleted = 69 (0x45)

 Payer has completed PIN entry o Authorizing = 80 (0x50)

 Terminal is authorizing o RetryingAuthorization = 81 (0x51)

 Retrying authorization for first time o RetryingAuthorization2 = 82 (0x52)

 Retrying authorization for second time o CancellingAuthorization = 83 (0x53)

 Cancelling authorization o CancellingAuthorization2 = 84 (0x54)

 Trying retry cancelling authorization o CancellingAuthorization3 = 85 (0x55)

 Trying retry cancelling authorization for second time o Authorized = 96 (0x60)

 Authorization call has approved o PrintingReceipts = 112 (0x70)

 Receipts are sent from terminal o Completed = 128 (0x80)

 Transaction is completed

o CompletedCardRemoved = 129 (0x81)

 Card is removed from terminal (only in chip transactions)

o SendingBatches = 144 (0x90)  Batches are being sent o SendingBatchesDone = 145 (0x91)

 Sending batches is completed o TransactionInterrupted = 240 (0xF0)

 Transaction is interrupted o FallbackToMagStripe = 241 (0xF1)

 Reading cards chip has failed and payer has to use mag stripe reader

o TransactionAlreadyCancelled = 242 (0xF2)

 Refund or cancelling transaction has already been done

o ChecksumMismatch = 243 (0xF3)

 Manual authorization codes checksum mismatches. o ReadyToReceiveSum = 245 (0xF5)

 API is ready to start transaction with final sum (PrepareTransaction)

o Idle = 254 (0xFE)

 Terminal is in idle state o Unknown = 255 (0xFF)

(29)

2.4.6 TerminalStates

 State of terminal  Members:

o NotInitialized = 0

 Terminal is not initialized and not ready for use o TerminalRebooting = 1

 Terminal is rebooting o TerminalReady = 2

 Terminal is initialized and ready for use o TerminalSendingTransactions = 3

 Terminal is sending transactions o TerminalInIdleState = 4

 Terminal is ready for starting a transaction o TerminalSendingTransactionsDone = 5

 Terminal has sent transactions o TerminalInitialized = 6

 Terminal is initialized and ready for use o ProcessingTransaction = 7

 Terminal is processing a transaction

2.4.7 FailureInfo

NOT_SET = -1, ACCEPTED = 0, /// <summary>

/// All authorization declines are 100-999 /// </summary> AUTHORIZATION_DECLINE = 100, EXPIRED_CARD = 101, AUTHORIZATION_DECLINE_TAKE_CARD = 200, AUTHORIZATION_ERROR = 900, AUTHORIZATION_NO_ONLINE_CONNECTION = 999, DATA_NOT_READ = 1000, CARD_REMOVED = 1001, AGREEMENT_NOT_FOUND = 1002, INVALID_PAN_LENGTH = 1003, AUTHORIZATION_CODE_CHECKSUM_MISMATCH = 1004, KEYING_IN_NOT_ALLOWED = 1005, PURCHASE_MAX_LIMIT_EXCEEDED = 1006, PURCHASE_MIN_LIMIT_EXCEEDED = 1007, CASHWITHDRAWAL_NOT_ALLOWED = 1008, CREDIT_PURCHASE_NOT_ALLOWED = 1009,

(30)

INVALID_CARD = 1010,

NO_MATCHING_APPLICATIONS_ON_CHIP = 1011, /// <summary>

/// If transaction is not found for cancellation with filing code and /// user rejected refund.

/// </summary>

REFUND_FALLBACK_REJECTED = 1080, /// <summary>

/// If user wants to cancel transaction and it has already been cancelled /// </summary> INVALID_CANCELLATION = 1081, CANCELLATION_NOT_ALLOWED = 1082, PARTIAL_CANCELLATION_NOT_ALLOWED = 1083, REFUND_NOT_ALLOWED = 1084, PARTIAL_REFUND_NOT_ALLOWED = 1085, BLACKLIST_FAILURE = 1090, CARD_ON_BLACKLIST_TAKE_CARD = 1091, CARD_ON_BLACKLIST_CALL_POLICE = 1092, CARD_ON_BLACKLIST = 1093, ICC_DECLINE = 1100, CARD_BLOCKED = 1200, BLOCKED_APPLICATION = 1201, AID_OUTDATED = 1800, BIN_OUTDATED = 1801, PUBLIC_KEYS_OUTDATED = 1802, HOTCARD_OUTDATED = 1803, CONFIG_OUTDATED = 1804, CONFIG_INVALID_OR_NOT_FOUND = 1805, SERIAL_NBR_ERROR = 1806, HOTCARD_NOT_FOUND = 1807, TRANSLATION_OUTDATED = 1808, CANCEL_ON_TERMINAL = 1900, CANCEL_ON_API = 1901, PIN_BYPASS_NOT_ACCEPTED = 1902, NO_CONNECTION_TO_DEVICE = 1997, INCORRECT_SW_ON_TERMINAL = 1998, UNDEFINED = 1999, MANUAL_INPUT_WITH_CASH_WITHDRAWAL_NOT_ALLOWED = 3000, MANUAL_INPUT_WITH_CASHBACK_NOT_ALLOWED = 3010, NEGATIVE_AMOUNT_NOT_ALLOWED = 3020, ANOTHER_METHOD_IS_ONGOING = 3030, OPEN_CONNECTION_FAILED = 3040, TERMINAL_INITIALIZATION_FAILED = 3050, PREPARE_ALLOWED_ONLY_WITH_PURCHASE = 3060, TERMINAL_NOT_READY = 3070, UNSUPPORTED_CURRENCY_CODE = 3080,

(31)

SECOND_AMOUNT_IS_MISSING = 3090, COULD_NOT_START_TRANSACTION = 3100, INVALID_BONUS_TRANSACTION_TYPE = 3110, INVALID_BONUS_ID = 3120, SEND_TRANSACTIONS_ERROR = 5000, LOCKING_BATCHES_ERROR = 5010, LOCKING_BATCHES_CONNECTION_ERROR = 5011, GET_REPORT_ERROR = 5020, GET_REPORT_CONNECTION_ERROR = 5021, GET_REPORT_NO_NEW_REPORT_AVAILABLE = 5022, SERVER_ERROR = 9999

(32)

3 TCP/IP SOCKET INTERFACE WITH XML MESSAGES (XMLCOMM)

The EMVLumoAgent application included in the Lumo setup monitors incoming TCP/IP traffic. Upon receiving instructions it activates the card payment and forwards events to the calling program.

3.1 Communication

Communication is handled with XML messages via TCP connection. Default listening port number for server is 1234 while this can be configured (see EMVLumoAgent usage).

Connection is started by POS by opening connection to port and ended when Lumo closes connection. Connection is closed by default when transaction has been finished or single property has been retrieved or set. This behaviour can be changed by TCPDisconnect variable. The preferred way of doing communication is setting it false, so that connection is not closed. If connection is opened and POS has not been sending message for a one minute connection is closed. Lumo handles connection requests in single threaded mode and answers for requests by order of connection request.

Before the XML message EMVLumoAgent sends 3 bytes byte-order-marker (BOM). Single messages in both directions end with null mark (0x00).

3.2 Basic XML frame structure

Messages are closed inside EMVLumo tags and encoded as UTF8. E.g.

3.3 Properties

3.3.1 Set property value

Properties are set by using Set prefix in property’s name and value is given inside Value frame. Value is given inside property tag. Lumo will not reply for these messages. E.g. setting amount: POS -> Lumo

3.3.2 Get property value

POS will send message to query property value. Get prefix will be used in property’s name inside basic xml structure. Lumo will reply queried property value inside Result tag and originally queried property name. E.g. getting amount:

POS -> Lumo (query for value)

Lumo -> POS (reply)

<?xml version="1.0" encoding="utf-8"?>

(33)

3.4 Methods

POS will send method’s name inside basic xml structure and parameters inside method. Lumo will reply possible return value inside Result tag. Result value informs if the method was able being started, not if method was successfully completed. Boolean values are presented in string form of “True” or “False”. Different enumerations are presented as integer values as defined in chapter 2.4.

Lumo blocks new methods and returns result “False” until ongoing method is completed or cancelled.

During StartTransaction and MakeTransaction only CancelTransaction method can be called. During PrepareTransaction StartTransaction, MakeTransaction and CancelTransaction can be called.

During ReadBonusInformation only CancelReadBonusInformation can be called. 3.4.1 Example: Calling MakeTransaction to make purchase

POS -> Lumo

Lumo -> POS (replying declined transaction)

<MakeTransaction><Result>False</Result></MakeTransaction></EMVLumo>

3.4.2 Example: Calling BluetoothGetDevicesInRange POS -> Lumo <EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"> <BluetoothGetDevicesInRange> <MaxCountOfDevices>1</MaxCountOfDevices> <IncludeAuthenticated>True</IncludeAuthenticated> <IncludeRemembered>True</IncludeRemembered> </BluetoothGetDevicesInRange> </EMVLumo> Lumo -> POS <?xml version="1.0" encoding="utf-8"?> <EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"> <BluetoothGetDevicesInRange> <Result>0</Result> </BluetoothGetDevicesInRange></EMVLumo>

(34)

3.5 Events

When transaction is started by StartTransaction method Lumo will send events to POS. POS should reply reference parameters in reply message where parameters tagged inside original event tag. 3.5.1 Example: StatusUpdate <?xml version="1.0" encoding="utf-8"?> <EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"> <StatusUpdate> <StatusCode>500</StatusCode>

<StatusInfo>CMD MAKE_TRANSACTION: 00-05</StatusInfo> </StatusUpdate>

</EMVLumo>

3.5.2 Example: OnBypassPINRequest Lumo -> POS

POS -> Lumo

<?xml version="1.0" encoding="UTF-8"?>

(35)

3.6 Example transaction

In Figure 3.1 is shown how messages are exchanged between POS and Lumo when StartTransaction is made.

POS

Lumo

StartTransaction StartTransaction(True) StatusUpdate TransactionStateChanged(InsertCard) TransactionStateChanged(EnterPIN) TransactionStateChanged(Authorizing) StatusUpdate StatusUpdate StatusUpdate StatusUpdate TransactionStateChanged(Authorized) StatusUpdate TransactionStateChanged(Completed) TransactionFinished StatusUpdate StatusUpdate PrintTransactionReceipt(Merchant) PrintTransactionReceipt(Customer)

Figure 3.1. Diagram of basic StartTransaction sequence. Next the same message exchanging is shown in detail. Connection is opened by POS

POS -> Lumo (Starts transaction)

(36)

Lumo -> POS (Transaction is started successfully)

<?xml version="1.0" encoding="UTF-8"?>

Lumo -> POS (Informational data)

<StatusInfo>CMD MAKE_TRANSACTION: 00-05</StatusInfo></StatusUpdate></EMVLumo>

Lumo -> POS (Payer is asked to insert card)

<CheckIdentity>False</CheckIdentity></TransactionStateChanged></EMVLumo>

Lumo -> POS (Payer is asked to enter PIN)

Lumo -> POS (Pin entry is completed)

Lumo -> POS (Authorizing transaction)

Lumo -> POS (informational data)

(37)

<StatusInfo>CMD HTTP_REQUEST</StatusInfo></StatusUpdate></EMVLumo>

<StatusInfo>HTTP_REQUEST REPLY RECEIVED</StatusInfo></StatusUpdate></EMVLumo>

<StatusInfo>HTTP_REQUEST REPLY TO DEVICE DONE</StatusInfo> </StatusUpdate></EMVLumo>

Lumo -> POS (transaction is authorized)

Lumo -> POS (transaction is completed)

<TransactionReceiverAN>L5</TransactionReceiverAN><CheckIdentity>False</CheckIdentity> </TransactionStateChanged></EMVLumo>

(38)

<StatusInfo>CMD PRINT_TRANSACTION_RECEIPT</StatusInfo></StatusUpdate></EMVLumo>

Lumo -> POS (merchant receipt)

<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><PrintTransactionReceipt> <ReceiptType>0</ReceiptType><ReceiptData> Testshop Teststreet 2 Testtown 1234567890 SELITE: OSTO

KORTTI: VISA DEBIT

KÄYTTÖTAPA:PANKKIKORTTI AID ID: XXX NUMERO: XXX AVIITE: XXX TVR: XXX TSI: XXX YRITYS: XXX KP: X TA: XXX VARM: XXX P --- VELOITUS: 10.04 EUR --- KAUPPIAAN TOSITE: 06.07.2010 09:32:47 </ReceiptData></PrintTransactionReceipt></EMVLumo> Lumo -> POS (customer receipt)

<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><PrintTransactionReceipt> <ReceiptType>1</ReceiptType><ReceiptData> Testshop Teststreet 2 Testtown 1234567890 SELITE: OSTO

KORTTI: VISA DEBIT

KÄYTTÖTAPA:PANKKIKORTTI AID ID: XXX NUMERO: XXX AVIITE: XXX TVR: XXX TSI: XXX YRITYS: XXX KP: X TA: XXX

(39)

VARM: XXX P TC: XXX --- VELOITUS: 10.04 EUR --- ASIAKKAAN TOSITE: 06.07.2010 09:32:47 </ReceiptData></PrintTransactionReceipt></EMVLumo>

Connection is closed by Lumo