emvlumo api

Lumo

SUBJECT: INTERFACE SPECIFICATION (API)

COMPANY: NETS OY

COMMENTS: Specifications for application interface

DATE: 31.05.2013

VERSION: 1.7.08

1

Lumo

Lumo - Interface Specification (API)

CONTENTS

CONTENTS .......................................................................................................... 1

1 GENERAL ....................................................................................................... 4 1.1 CHANGE LOG ................................................................................................. 4 1.2 GENERAL INFORMATION ABOUT THE INTERFACE ........................................................ 4

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

2 GENERAL INTERFACE FUNCTIONALITY .......................................................... 6 2.1 PROPERTIES 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 METHODS ................................................................................................... 11 2.2.1 int BluetoothGetDevicesInRange (int MaxCountOfDevices, bool IncludeAuthenticated, bool IncludeRemembered) ........................................................................................... 11

2

Lumo


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

3

Lumo


2.4 ENUMERATIONS ............................................................................................ 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 COMMUNICATION .......................................................................................... 31 3.2 BASIC XML FRAME STRUCTURE ......................................................................... 31 3.3 PROPERTIES ................................................................................................ 31

3.3.1 Set property value ........................................................................................... 31 3.3.2 Get property value .......................................................................................... 31

3.4 METHODS ................................................................................................... 32 3.4.1 Example: Calling MakeTransaction to make purchase ........................................... 32 3.4.2 Example: Calling BluetoothGetDevicesInRange ................................................... 32

3.5 EVENTS ..................................................................................................... 33 3.5.1 Example: StatusUpdate .................................................................................... 33 3.5.2 Example: OnBypassPINRequest ......................................................................... 33

3.6 EXAMPLE TRANSACTION .................................................................................. 34

4 LUMOAPI COM INTEROP DLL ....................................................................... 39 4.1 PROGRAMMING EXAMPLE (VISUAL BASIC) ............................................................ 39

5 USAGE ......................................................................................................... 41 5.1 EXAMPLE: STARTING IN WINDOWS .................................................................... 42

6 INSTALLATION ............................................................................................ 43 6.1 INSTALLATION 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 BASIC MAGNETIC STRIPE TRANSACTION WITH STARTTRANSACTION METHOD .................... 52 8.3 MAKETRANSACTION CALL ................................................................................ 53

9 GETNUMBERINPUT AND GETAMOUNTINPUT LINE TEXTS ............................ 54

10 BONUS INFORMATION HANDLING .............................................................. 55 10.1 READBONUSINFORMATION AND STARTTRANSACTION ............................................... 55 10.2 TRANSACTION 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 10.2.2 Example: bonus information is read from same chipcard as transaction is payed ..... 66

4

Lumo


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

configurations are found from the EMVLumo System Requirement document.

5

Lumo


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

6

Lumo


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


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

7

Lumo


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

00077FalseFalseFalse201

0052720070800010101000000

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

Default value is true

8

Lumo


2.1.10 bool OnlineAvailable

Indicates if online network connection is available for use.

If disabled Lumo API wont 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.

9

Lumo


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:

False

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 customers signature matches one on the card

10

Lumo


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:

29501109000010591234 v 1.4.952 ML30 v 1.4.952 111111111123 004 12C97004

2.1.29 String Track2Data

Track 2 of cards 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


Mandatory for all multicurrency transactions


Key indicates currency code in string format (e.g. EUR, SEK)

11

Lumo


Value indicates amount in that currency

2.1.33 Hashtable MultiCurrencyAmountOther


Mandatory in the following cases:

o Mandatory for all Cashback multicurrency transactions


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)


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

Execution might take a while.

12

Lumo


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)


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)


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

Initializes system. Attempts to start up payment terminal.

13

Lumo


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

14

Lumo


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

true 0 True Left Hello 0 False Right World!

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

15

Lumo


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

Text Receipt text

Example of XML formatted list:

0 110105004002 5.1.2011 13:34:20 Toni+Test \n Testikatu 1 \n 00100 Testil \n 1234567890 \nSELITE: OSTO\nKORTTI: VISA CREDIT\nKYTTTAPA: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 1

16

Lumo


110105004002 5.1.2011 13:34:21 SELITE: OSTO\nKORTTI: VISA CREDIT\nKYTTTAPA: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

2.2.18 bool PrintPreviousReceipt()

Commands terminal to send previous receipt


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


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. LH.AIKA: 16:38 AUTOM. LH. PLL: 0 LAITT. SARJANUMERO: 29501109000010598154 SOPIMUKSET: LIITTYMTUN.: 100 SOP. NRO: 1111111 VARM. RAJA: 999999 LIITTYMTUN.: 040 SOP. NRO: 111111111997 VARM. RAJA: 999999 LIITTYMTUN.: 110 SOP. NRO: 9425821733 VARM. RAJA: 999999 LIITTYMTUN.: 120 SOP. NRO: 11111111 VARM. RAJA: 999999

17

Lumo


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 = Ykksbonus, 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.

Parameters:

18

Lumo


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:


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 Active. If true, terminal wont 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.

19

Lumo


o Reading bonus information doesnt 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 doesnt 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)


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.

20

Lumo


2.3.3 OnCheckSignature

Occurs when merchant receipt has signature section and merchant is expected to check that customers 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 terminals screen for full PAN

o Amount, Transaction amount

o PhoneNumber, Phone number where to call.

Parameters out:

21

Lumo


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

22

Lumo


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

o InputType, Informs how card data has been read.

23

Lumo


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

o None

24

Lumo


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 = Ykksbonus, 2 = S-Bonus, 3 = Plussa

If not present 0 is returned

o String SettlementInfo

Returned if available for given bonus type and information


o String CustomerSegment

Returned if available for given bonus type and information


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.

Handled via GotInputHandler(string Result)

25

Lumo


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

26

Lumo


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

Application selection

27

Lumo


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)

Terminal is in unknown state

28

Lumo


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,

///

/// All authorization declines are 100-999

///

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,

29

Lumo


INVALID_CARD = 1010,

NO_MATCHING_APPLICATIONS_ON_CHIP = 1011,

///

/// If transaction is not found for cancellation with filing code and

/// user rejected refund.

///

REFUND_FALLBACK_REJECTED = 1080,

///

/// If user wants to cancel transaction and it has already been cancelled

///

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,

30

Lumo


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

31

Lumo


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

1000

3.3.2 Get property value

POS will send message to query property value. Get prefix will be used in propertys 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)

1000

32

Lumo


3.4 Methods

POS will send methods 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

0

Lumo -> POS (replying declined transaction)

False

3.4.2 Example: Calling BluetoothGetDevicesInRange

POS -> Lumo

1

True

True

Lumo -> POS

0

33

Lumo


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

500

CMD MAKE_TRANSACTION: 00-05

3.5.2 Example: OnBypassPINRequest

Lumo -> POS

POS -> Lumo

true

34

Lumo


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)

35

Lumo


Lumo -> POS (Transaction is started successfully)

True

Lumo -> POS (Informational data)

500


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

01004

00

0

False

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

01004

00

64

False

Lumo -> POS (Pin entry is completed)

01004

00

69

False

Lumo -> POS (Authorizing transaction)

01004

00

80

False

Lumo -> POS (informational data)

36

Lumo


100

CMD HTTP_REQUEST


120

HTTP_REQUEST REPLY RECEIVED


130

HTTP_REQUEST REPLY TO DEVICE DONE


500


Lumo -> POS (transaction is authorized)

01004

00

96

False


500


Lumo -> POS (transaction is completed)

01004

10070600100102

0000008000F800128

L5False

Lumo -> POS (transaction is accepted)

37

Lumo


1280

L5


300

CMD PRINT_TRANSACTION_RECEIPT

Lumo -> POS (merchant receipt)

0

Testshop

Teststreet 2

Testtown

1234567890

SELITE: OSTO

KORTTI: VISA DEBIT

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

Lumo -> POS (customer receipt)

1

Testshop

Teststreet 2

Testtown

1234567890

SELITE: OSTO

KORTTI: VISA DEBIT

KYTTTAPA:PANKKIKORTTI

AID ID: XXX

NUMERO: XXX

AVIITE: XXX

TVR: XXX TSI: XXX

YRITYS: XXX KP: X TA: XXX

38

Lumo


VARM: XXX P

TC: XXX

--------------------------------------

VELOITUS: 10.04 EUR

--------------------------------------

ASIAKKAAN TOSITE: 06.07.2010 09:32:47

Connection is closed by Lumo

39

Lumo


4 LUMOAPI COM INTEROP DLL

LumoAPI is a .NET class library which also provides a COM Interop interface. It uses Lumo through socket with XML-interface described in chapter 3, and it provides interface described in chapter 2. LumoAPI can be registered as COM object so that it can be used from POS systems programmed with e.g. Visual Basic.

LumoAPI can be registered by running C:\Windows\Microsoft.NET\Framework\v2.0.50727\regasm /tlb LumoAPI.dll. This also generates LumoAPI.tlb file that can be referenced from POS systems.

LumoAPI.dll must also be added to Global Assembly Cache (GAC) by running gacutil /i LumoAPI.dll. Gacutil is a tool provided by Microsoft for adding libraries into GAC.

LumoAPI must be initialized before usage. This is done with Initialize-method. Parameters are Hostname, Port and SocketAutoConnect. Hostname is the address where Lumo is installed (use 127.0.0.1 if its the same computer). Port is which Lumos XML-interface is set to listen (Lumo listens 1234 as default).

LumoAPIs socket connection handling to Lumo can be used in two ways. This is defined with SocketAutoConnect-parameter. Setting it to False, POS has to call LumoAPIs Connect-method before calling any other methods or properties, and Disconnect after LumoAPI is no longer used. This adds more complexity and responsibility about connection handling to POS, but this way no unnecessary connection openings or closings can happen during usage of Lumo, so there is no delay caused by this.

When SocketAutoConnect-parameter is set to True, LumoAPI handles all connections internally, so that POS does not have to call Connect and Disconnect. This way LumoAPI is easier to use and POS has less responsibility about connection handling, but this might result unnecessary connection opening and closing between sequential calls, which may cause unwanted delays. Timeout after connection is closed can be adjusted with DisconnectTimeout-property.

4.1 Programming example (Visual Basic)

Add LumoAPI.tlb as a reference in your Visual Basic 6.0 project (Project->References->Browse).

Example how to create object and start transaction with MakeTransaction-method:

Private WithEvents lumo As LumoAPI.LumoAPI

Private Sub MakeTransactionButton_Click()

Set lumo = New LumoAPI.LumoAPI

Dim result As Boolean

lumo.LoggingFolder = "C:\lumoapi" ' Use this only for debugging purposes

result = lumo.Initialize(127.0.0.1, 1234, True) ' Address and port where LumoAgent is listening, SocketAutoConnect = True so that LumoAPI handles connections internally

If result Then

lumo.Amount = 1000

result = lumo.MakeTransaction(TransactionTypes_Purchase)

If result Then

MsgBox ("Transaction successful!")

Else

MsgBox ("Transaction failed!")

40

Lumo


End If

Else

MsgBox ("Initialize failed!")

End If

End Sub

' Example how to handle events from Lumo.

Private Sub lumo_OnStatusUpdateReceived(ByVal StatusCode As Long, ByVal StatusInfo As

String)

MsgBox ("Status update received: " & StatusCode & " " & StatusInfo)

End Sub

41

Lumo


5 USAGE

It is required that LumoAgent application is always running when using the interface.

EMVLumoAgent accepts the following command line parameters:

-NOGUI

o EMVLumoAgent is started with no graphical user interface (Notice: MakeTransaction method is not usable when started with this mode)

-TRAY

o EMVLumoAgent is started as minimized window. Application window can be restored by clicking tray icon (gnome, windows)

-COMPORT:

o Start EMVLumoAgent with defined communication port.

o e. g. EMVLumoAgent COMPORT:COM6 or EMVLumoAgent COMPORT:AUTO

-COMTYPE:

o Start EMVLumoAgent with defined terminal type. This parameter has no effect unless you specify COM port also

o e.g. EMVLumoAgent -COMPORT:COM7 -COMTYPE:SagemiWL250

-TCP

o Starts EMVLumoAgent TCP server as application starts

-TCPTYPE:

o Defines whether TCP mode is started with XMLCOMM or DOPAYCOMM based communication mode

o Acceptable values for parameter XMLCOMM or DOPAYCOMM

-TCPPORT:

o Defines TCP API Server port

o This parameter has no effect unless you specify API Type also

o e.g. EMVLumoAgent -TCPTYPE:XMLCOMM -TCPPORT:4321

-TCPTIMEOUT:

o Sets HTTP request timeout (in ms)

-HTTPPROXY

o Sets HTTP Proxy authentication property on

-DATAPATH:

o Path where to store data (StoragePath)

-CURRPATH:

o Sets systems current directory

-NOTEST

42

Lumo


o Starts EMVLumoAgent without Transaction test possibility on Test tab

5.1 Example: Starting in Windows

C:\EMVLumo> EMVLumoAgent -TRAY -COMPORT:COM6

43

Lumo


6 INSTALLATION

6.1 Installation on Windows

Installation on Windows is made with MSI installer package and it can be automated in a

way that there is no user interface during process.

Example: EMVLumoSetup_1.00.031.exe /exenoui /quiet APPDIR=d:\My Lumo

This will install application with no GUI and to the My Lumo folder on local disk d.

Command line parameter /quiet may be replaced with /passive to show the progress dialog. Passive parameter does not require any user actions but shows the basic GUI.

Parameter APPDIR is not required if default installation path (C:\EMVLumo) will be used.

Installation and runtime requirements are listed in "Lumo System Requirements" document.

44

Lumo


7 TRANSACTION DIALOGS IN MAKETRANSACTION METHOD CALL

This chapter contains dialogs examples that Lumo APIs MakeTransaction call shows for merchant on transaction. API contains language support, e.g. Swedish, English. In these examples Finnish

language is used.

Figure 7.1 InsertCard state when CombinedReader is chosen as CardEntryMode

Figure 7.2 InsertCard state when ManualEntry is chosen as CardEntryMode

Figure 7.3 EnterPIN state

45

Lumo


Figure 7.4 FallbackToMagStripe state

Figure 7.5 PinEntryCompleted state

Figure 7.6 Authorizing state

Figure 7.7 RetryingAuthorizing state

46

Lumo


Figure 7.8 RetryingAuthorizing2 state

Figure 7.9 CancellingAuthorizing state

Figure 7.10 CancellingAuthorizing2 state

Figure 7.11 Authorized state

47

Lumo


Figure 7.12 OnBypassPINRequest event

Figure 7.13 SearchingForCancellingTransaction state

Figure 7.14 IsCardPresent event

Figure 7.15 HotCardAction event

48

Lumo


Figure 7.16 HotCardAction event

Figure 7.17 VisualIdentification event

Figure 7.18 Cancelling Transaction after CancelTransaction method call

Figure 7.19 Declined transaction after TransactionFinished event

49

Lumo


Figure 7.20 Accepted transaction after TransactionFinished event

Figure 7.21 TransactionInterrupted state

Figure 7.22 TransactionAlreadyCancelled state

Figure 7.23 Completed state

50

Lumo


8 BASIC TRANSACTION FLOWS

These transaction flows are meant to be used to understand how transaction events are fired from Lumo API and to show difference between StartTransaction and MakeTransaction methods.

51

Lumo


8.1 Basic chip transaction with StartTransaction method

OnTransactionStateChanged

(State=Enter card)

EmvLumo


(State=SelectApplication)


(State=SelectLanguage)


(State=ReadingCard)

Multiapp card?

Supported language?

Bypass PIN? OnBypassPINRequest

Chip 1st decision


(State=Authorizing/

RetryingAuthorizing/

RetryingAuthorizing2)

OnTransactionFinished

(Result=Accepted)


(State=Authorized)

StartTransaction()


(State=EnterPin)


(State=CancellingAuthorization/

CancellingAuthorization2/

CancellingAuthorization3)


(Result=Declined)

Chip 2st decision

OnPrintTransactionReceipt

(ReceiptType=Merchant)


(ReceiptType=Customer)

Online Authorizing result

52

Lumo


8.2 Basic magnetic stripe transaction with StartTransaction method


(State=Enter card)

EmvLumo


(State=SelectApplication)Multiapp card?

Terminal decision

StartTransaction ()


(State=Authorizing/

RetryingAuthorizing/

RetryingAuthorizing2)

Online


(State=CancellingAuthorization/

CancellingAuthorization2/

CancellingAuthorization3)

Authorizing result


(State=Authorized)


(Result=Accepted)


(Result=Declined)


(ReceiptType=Merchant)


(ReceiptType=Customer)

Is Card on hotlist ? OnHotCardAction

Is bankcard payment and

over 50 euros ?

OnCheckIdentity

Cancelled authorization ? OnManualAuthorization

53

Lumo


8.3 MakeTransaction call

MakeTransaction starts

Dialog windows are shown

MakeTransaction ends

54

Lumo


9 GETNUMBERINPUT AND GETAMOUNTINPUT LINE TEXTS

INDEX ENGLISH FINNISH SWEDISH

1 AMOUNT SUMMA BELOPP

2 ENTER NEW TOTAL UUSI LOPPUSUMMA NY SLUTSUMMAN

3 TOTAL LOPPUSUMMA SLUTSUMMA

4 AMOUNT AGAIN SUMMA UUDELLEEN BELOPP IGEN

5 ENTER SYT ANGE

6 ADD LIS TILLSTTA

7 INPUT NPPILE MATA IN

8 CALL YOUR BANK SOITA PANKKIIN KONTAKTA BANKEN

9 BALANCE SALDO SALDO

16 TIP JUOMARAHA DRICKS

17 GRATUITY JUOMARAHA DRICKS

18 SERVICE PALVELU SERVICE

19 DONATION LAHJOITUS GVA

32 WAITER ID TARJOILIJATUNNUS SERVITR ID

33 WAITER LOGON KIRJAA TARJOILIJ REGISTR SERVITR

34 TABLE NUMBER PYDN NUMERO BORD NUMMER

35 BILL NUMBER LASKUN NUMERO BERKNING NR

36 LOCATION REF SIJAINTI STLLNING

37 TAB NUMBER JLKIVELOITUS NR EFTERDEBIT NR

38 OPERATOR ID KYTTJTUNNUS ANVNDARE ID

48 PAN MAKSUSOVELLUS BETALN APPLIKAT

49 CARD NUMBER KORTIN NUMERO KORTETS NUMMER

50 EXPIRY DATE VOIMASSAOLOAIKA GILTIGHET

51 START DATE KYTTNOTTO IBRUKTAGANDE

52 AS MMYY MUODOSSA KKVV FORMAT MM

53 ISSUE NUMBER LIIKKEELLELASKU EMITTERINGS NR

54 CVV/CVC CVV/CVC CVV/CVC

55 SPLIT BY JAA DIVIDERA

56 NO. OF PARTIES OSAPUOLTEN LKM ANTAL PARTY

57 TO PAY MAKSETTAVAA BETALBAR

58 AUTH CODE VARMENNUSTUNNUS AUKTORISER. KOD

59 CASHBACK RAHAA TAKAISIN KONTANT TILLBAKS

60 DUE SAATAVA FORDRING

61 MAXIMUM ENINTN HGST

62 MINIMUM VHINTN MINST

63 MULTIPLES OF JAOLL. LUVULLLA DELBAR MED

64 FORMAT MUOTO FORMAT

65 DATE PIVYS DATUM

66 INCORRECT VRIN FEL

67 ID INCORRECT TUNNUS VRIN FEL IDENTIFIER.

68 NO. INCORRECT NUMERO VRIN FEL NUMMER

69 BILL NOT FOUND LASKUA EI LYDY HITTAR EJ FAKTUR

70 CASH KTEINEN KONTANT

71 CARD KORTTI KORT

72 CHEQUE SHEKKI CHECK

73 VOUCHER LOUNASSETELI LUNCHSEDEL

74 PAYMENT MAKSU BETALNING

75 REFUND HYVITYS TERBETALNING

55

Lumo


10 BONUS INFORMATION HANDLING

Lumo API offers two different ways to handle reading bonus information during transaction.

Read bonus information before actual transaction with ReadBonusInformation method or get information during transaction with PrepareTransaction. These methods are described in following chapters.

10.1 ReadBonusInformation and StartTransaction

Bonus information is read by calling ReadBonusInformation and transaction is started after reading bonus information.

E.g. Calls in XMLComm:

1. (POS calls ReadBonusInformation)

POS -> Lumo:

Lumo -> POS: True

2. (User inserts bonus card and EMVLumo returns bonus information)

Lumo -> POS: 600407.....

.12342B3 (Note PAN is masked)

Lumo -> POS: 3300CMD READ_BONUS_INFORMATION PAN (600407......1234) BonusType (2)

SettlementInfo (B3) Cancel (-1) CustomerSegment () Validity () ManualInput

(48)

3. (POS sets transaction properties and starts transaction)

POS -> Lumo: 0

POS -> Lumo:

POS -> Lumo: 0

POS -> Lumo: 100

56

Lumo


POS -> Lumo: 0

POS -> Lumo:

Lumo -> POS: True

4. (API starts transaction)

Lumo -> POS: 500CMD MAKE_TRANSACTION: 00-

05

Lumo -> POS: 0100000False


05



05



05

57

Lumo




05



05

Lumo -> POS: 0100110426004002020000000000E800128L1False

Lumo -> POS: 1280L1


05

Lumo -> POS: 0100110426004002020000000000E800112L1False

Lumo -> POS: 300CMD

PRINT_TRANSACTION_RECEIPT

58

Lumo


Lumo -> POS: 0 Test

Testikatu 1

00100 Testil

1234567890

SELITE: OSTO

KORTTI: Visa

KYTTTAPA:LUOTTOKORTTI

AID ID: A0000000031010

NUMERO: 492019......4321

AVIITE: 110426004002

TVR: 0000000000 TSI: E800

YRITYS: XXXXXXXXXXXX KP: 4 TA: 5399

--------------------------------------

VELOITUS: 1.00 EUR

--------------------------------------

KAUPPIAAN TOSITE: 26.04.2011 12:19:02

Lumo -> POS: 300CMD

PRINT_TRANSACTION_RECEIPT

Lumo -> POS: 1SELITE: OSTO

KORTTI: Visa

KYTTTAPA:LUOTTOKORTTI

AID ID: A0000000031010

NUMERO: ............4321

AVIITE: 110426004002

59

Lumo

Lumo - I

emvlumo api

Documents

string archiveid

string communicationportname

string datastoragepath

string failureinfo

string receiptcustomer

string receiptgeneral

string receiptmerchant

string receipttransmission