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

CONTENTS

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

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

2

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

GENERAL INTERFACE FUNCTIONALITY..........................................................6 2.1 PROPERTIES FOR THE TRANSACTION ..................................................................... 6 2.1.1 2.1.2 2.1.3 2.1.4 2.1.5 2.1.6 2.1.7 2.1.8 2.1.9 2.1.10 2.1.11 2.1.12 2.1.13 2.1.14 2.1.15 2.1.16 2.1.17 2.1.18 2.1.19 2.1.20 2.1.21 2.1.22 2.1.23 2.1.24 2.1.25 2.1.26 2.1.27 2.1.28 2.1.29 2.1.30 2.1.31 2.1.32 2.1.33 2.1.34 2.1.35 2.1.36 2.1.37

2.2

int Amount .......................................................................................................6 int AmountOther ...............................................................................................6 String ArchiveID ................................................................................................6 Hashtable BluetoothDevicesInRange ....................................................................6 CardEntryModes CardEntryMode..........................................................................7 String CommunicationPortname ..........................................................................7 String DataStoragePath ......................................................................................7 String FailureInfo ..............................................................................................7 bool MerchantInformationOnReceipt ....................................................................7 bool OnlineAvailable ..........................................................................................8 String ReceiptCustomer ......................................................................................8 String ReceiptGeneral ........................................................................................8 String ReceiptMerchant ......................................................................................8 String ReceiptTransmission .................................................................................8 TerminalDeviceTypes TerminalDeviceType ............................................................8 String TransactionReceiverAN .............................................................................8 int TransactionResult .........................................................................................8 TransactionTypes TransactionType ......................................................................8 TransactionTypes BonusTransactionType ..............................................................9 String UILanguageID .........................................................................................9 TerminalStates TerminalState .............................................................................9 bool TCPDisconnect ...........................................................................................9 bool HTTPProxyAuthentication .............................................................................9 bool CheckIdentity.............................................................................................9 bool CheckReceiptSignature ................................................................................9 bool MenuState ............................................................................................... 10 String PAN ...................................................................................................... 10 String DeviceInfo ............................................................................................ 10 String Track2Data ........................................................................................... 10 bool DebitPurchaseOnly.................................................................................... 10 String LastTransactionCurrency ......................................................................... 10 Hashtable MultiCurrencyAmount ........................................................................ 10 Hashtable MultiCurrencyAmountOther ................................................................ 11 bool UseBluetooth ........................................................................................... 11 bool MessagesInTransactionDialog ..................................................................... 11 int TipAmount ................................................................................................. 11 bool QuasiCashTerminal .................................................................................. 11

METHODS................................................................................................... 11

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

Lumo - Interface Specification (API)

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 2.3.2 2.3.3 2.3.4 2.3.5 2.3.6 2.3.7 2.3.8 2.3.9 2.3.10 2.3.11 2.3.12 2.3.13 2.3.14 2.3.15 2.3.16 2.3.17 2.3.18 2.3.19 2.3.20

OnBypassPINRequest ....................................................................................... 19 OnCheckIdentity ............................................................................................. 19 OnCheckSignature ........................................................................................... 20 OnIsCardPresent ............................................................................................. 20 OnHotCardAction ............................................................................................. 20 OnManualAuthorizationRequest ......................................................................... 20 OnPrintGenericReceipt ..................................................................................... 21 OnPrintTransactionReceipt ................................................................................ 21 OnPrintTransmissionReceipt .............................................................................. 21 OnRefundRequest ............................................................................................ 21 OnStatusUpdateReceived ................................................................................. 22 OnTransactionFinished ..................................................................................... 22 OnTransactionStateChanged ............................................................................. 22 OnVisualIdentificationRequest ........................................................................... 23 OnTerminalStateChanged ................................................................................. 23 OnGenericEvent .............................................................................................. 24 OnMgStripeReaden .......................................................................................... 24 OnBonusInformationReaden ............................................................................. 24 OnGotInput .................................................................................................... 24 OnResponseToAPI ........................................................................................... 25

Lumo - Interface Specification (API)

3 Lumo

2.4

ENUMERATIONS............................................................................................ 25

2.4.1 2.4.2 2.4.3 2.4.4 2.4.5 2.4.6 2.4.7

3

CardEntryModes .............................................................................................. 25 TerminalDeviceTypes ....................................................................................... 25 TransactionBatchMethods ................................................................................. 26 TransactionTypes ............................................................................................ 26 TransactionState ............................................................................................. 26 TerminalStates ................................................................................................ 28 FailureInfo ...................................................................................................... 28

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 3.3.2

Set property value ........................................................................................... 31 Get property value .......................................................................................... 31

3.4.1 3.4.2

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

3.5.1 3.5.2

Example: StatusUpdate .................................................................................... 33 Example: OnBypassPINRequest ......................................................................... 33

3.4 3.5 3.6

METHODS................................................................................................... 32 EVENTS ..................................................................................................... 33 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

Lumo - Interface Specification (API)

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.

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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

The amount being debited or credited Mandatory in the following cases: o Mandatory for all Cashback transactions Given without decimal separator (for example 1000 = € 10,00) Always positive number

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

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

8 Lumo

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.

Lumo - Interface Specification (API)

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 customer’s signature matches one on the card

Lumo - Interface Specification (API)

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.



Primary account number of last successful transaction.

2.1.27 String PAN

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 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 Given without decimal separator (for example 1000 = € 10,00) Always positive number Key indicates currency code in string format (e.g. EUR, SEK)

Lumo - Interface Specification (API)

11 Lumo



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



Supported from Lumo 1.8



Tip handling feature can be enabled only in device configuration



Returns tip amount. Property cannot be set

2.1.36 int TipAmount

2.1.37 bool QuasiCashTerminal 

Supported from Lumo 1.8



Quasi cash feature can be enabled only in device configuration



Returns true transcations

if

terminal

is

capable

of

handling

quasi

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.



Execution might take a while.

Lumo - Interface Specification (API)

cash

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

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

Initializes system. Attempts to start up payment terminal.

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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 Terminal has to be initialized before use.



Parameters:

transaction

receipts.

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: 0 110105004002 5.1.2011 13:34:20 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 1

Lumo - Interface Specification (API)

16 Lumo

110105004002 5.1.2011 13:34:21 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

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

Lumo - Interface Specification (API)

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



Parameters:

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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

19 Lumo

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.

Lumo - Interface Specification (API)

20 Lumo

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 Instructions, String Question, ref int Result)



Parameters in:



ActionCode,

String

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:

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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.

Lumo - Interface Specification (API)

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 

o

Can be obtained from TransactionReceiverAN property afterwards

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

Lumo - Interface Specification (API)

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

o

o

o

o

String PAN 

PAN present in the bonus information



If not present empty string is returned

Int BonusType 

1 = Ykkösbonus, 2 = S-Bonus, 3 = Plussa



If not present 0 is returned

String SettlementInfo 

Returned if available for given bonus type and information



If not present empty string is returned

String CustomerSegment 

Returned if available for given bonus type and information



If not present empty string is returned

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)

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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

o o o

Lumo - Interface Specification (API)

InsertCard = 0 (0x00)  Chip card should be inserted in terminal OR  Card number should be entered in terminal SearchingForCancellingTransaction = 1 (0x01)  Terminal is searching transaction to be cancelled SelectLanguage = 16 (0x10)  Language selection SelectApplication = 32 (0x20)  Application selection

27 Lumo

o o o o o o o o o o o o o o o o

o o o o

o

o o

o o

Lumo - Interface Specification (API)

ReadingCard = 48 (0x30)  Terminal is reading card EnterPin = 64 (0x40)  Payer is entering PIN IncorrectPIN = 65 (0x41)  Payer entered incorrect PIN LastPinTry = 66 (0x42)  Payer has last try for PIN entry PinLocked = 67 (0x43)  Card PIN has been locked PinEntryCompleted = 69 (0x45)  Payer has completed PIN entry Authorizing = 80 (0x50)  Terminal is authorizing RetryingAuthorization = 81 (0x51)  Retrying authorization for first time RetryingAuthorization2 = 82 (0x52)  Retrying authorization for second time CancellingAuthorization = 83 (0x53)  Cancelling authorization CancellingAuthorization2 = 84 (0x54)  Trying retry cancelling authorization CancellingAuthorization3 = 85 (0x55)  Trying retry cancelling authorization for second time Authorized = 96 (0x60)  Authorization call has approved PrintingReceipts = 112 (0x70)  Receipts are sent from terminal Completed = 128 (0x80)  Transaction is completed CompletedCardRemoved = 129 (0x81)  Card is removed from terminal (only in chip transactions) SendingBatches = 144 (0x90)  Batches are being sent SendingBatchesDone = 145 (0x91)  Sending batches is completed TransactionInterrupted = 240 (0xF0)  Transaction is interrupted FallbackToMagStripe = 241 (0xF1)  Reading cards chip has failed and payer has to use mag stripe reader TransactionAlreadyCancelled = 242 (0xF2)  Refund or cancelling transaction has already been done ChecksumMismatch = 243 (0xF3)  Manual authorization codes checksum mismatches. ReadyToReceiveSum = 245 (0xF5)  API is ready to start transaction with final sum (PrepareTransaction) Idle = 254 (0xFE)  Terminal is in idle state Unknown = 255 (0xFF)  Terminal is in unknown state

28 Lumo

2.4.6 TerminalStates 

State of terminal



Members: o

NotInitialized = 0 

o

TerminalRebooting = 1 

o

Terminal has sent transactions

TerminalInitialized = 6 

o

Terminal is ready for starting a transaction

TerminalSendingTransactionsDone = 5 

o

Terminal is sending transactions

TerminalInIdleState = 4 

o

Terminal is initialized and ready for use

TerminalSendingTransactions = 3 

o

Terminal is rebooting

TerminalReady = 2 

o

Terminal is not initialized and not ready for use

Terminal is initialized and ready for use

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,

Lumo - Interface Specification (API)

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,

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

32 Lumo

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 0 Lumo -> POS (replying declined transaction) False 3.4.2 Example: Calling BluetoothGetDevicesInRange POS -> Lumo 1 True True Lumo -> POS 0

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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)

Lumo - Interface Specification (API)

35 Lumo

Lumo -> POS (Transaction is started successfully) True Lumo -> POS (Informational data) 500 CMD MAKE_TRANSACTION: 00-05 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)

Lumo - Interface Specification (API)

36 Lumo

100 CMD HTTP_REQUEST Lumo -> POS (informational data) 120 HTTP_REQUEST REPLY RECEIVED Lumo -> POS (informational data) 130 HTTP_REQUEST REPLY TO DEVICE DONE Lumo -> POS (informational data) 500 CMD MAKE_TRANSACTION: 00-05 Lumo -> POS (transaction is authorized) 01004 00 96 False Lumo -> POS (informational data) 500 CMD MAKE_TRANSACTION: 00-05 Lumo -> POS (transaction is completed) 01004 10070600100102 0000008000F800128 L5False Lumo -> POS (transaction is accepted)

Lumo - Interface Specification (API)

37 Lumo

1280 L5 Lumo -> POS (informational data) 300 CMD PRINT_TRANSACTION_RECEIPT Lumo -> POS (merchant receipt) 0 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

Lumo -> POS (customer receipt) 1 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 Lumo - Interface Specification (API)

38 Lumo

VARM: XXX P TC: XXX -------------------------------------VELOITUS: 10.04 EUR -------------------------------------ASIAKKAAN TOSITE: 06.07.2010 09:32:47 Connection is closed by Lumo

Lumo - Interface Specification (API)

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 C:\Windows\Microsoft.NET\Framework\v2.0.50727\regasm /tlb LumoAPI.dll. generates LumoAPI.tlb file that can be referenced from POS systems.

running This also

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 it’s the same computer). Port is which Lumo’s XML-interface is set to listen (Lumo listens “1234” as default). LumoAPI’s 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 LumoAPI’s Connectmethod 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!")

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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:AUTO”

–COMPORT:COM6”

or

“EMVLumoAgent

–

-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 system’s current directory

-NOTEST

Lumo - Interface Specification (API)

42 Lumo

o

Starts EMVLumoAgent without Transaction test possibility on Test tab

5.1 Example: Starting in Windows C:\EMVLumo> EMVLumoAgent -TRAY -COMPORT:COM6

Lumo - Interface Specification (API)

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.

Lumo - Interface Specification (API)

44 Lumo

7

TRANSACTION DIALOGS IN MAKETRANSACTION METHOD CALL

This chapter contains dialogs examples that Lumo API’s 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

Lumo - Interface Specification (API)

45 Lumo

Figure 7.4 FallbackToMagStripe state

Figure 7.5 PinEntryCompleted state

Figure 7.6 Authorizing state

Figure 7.7 RetryingAuthorizing state

Lumo - Interface Specification (API)

46 Lumo

Figure 7.8 RetryingAuthorizing2 state

Figure 7.9 CancellingAuthorizing state

Figure 7.10 CancellingAuthorizing2 state

Figure 7.11 Authorized state

Lumo - Interface Specification (API)

47 Lumo

Figure 7.12 OnBypassPINRequest event

Figure 7.13 SearchingForCancellingTransaction state

Figure 7.14 IsCardPresent event

Figure 7.15 HotCardAction event

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

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.

Lumo - Interface Specification (API)

51 Lumo

8.1 Basic chip transaction with StartTransaction method StartTransaction() EmvLumo OnTransactionStateChanged (State=Enter card)

Multiapp card?

OnTransactionStateChanged (State=SelectApplication)

Supported language?

OnTransactionStateChanged (State=SelectLanguage)

OnTransactionStateChanged (State=ReadingCard)

OnTransactionStateChanged (State=EnterPin)

Bypass PIN?

OnBypassPINRequest

Chip 1st decision

OnTransactionStateChanged (State=Authorizing/ RetryingAuthorizing/ RetryingAuthorizing2)

OnTransactionStateChanged (State=CancellingAuthorization/ CancellingAuthorization2/ CancellingAuthorization3)

Online

OnTransactionStateChanged (State=Authorized)

Chip 2st decision

OnTransactionFinished (Result=Accepted)

OnTransactionFinished (Result=Declined)

OnPrintTransactionReceipt (ReceiptType=Merchant)

OnPrintTransactionReceipt (ReceiptType=Customer)

Lumo - Interface Specification (API)

Authorizing result

52 Lumo

8.2 Basic magnetic stripe transaction with StartTransaction method StartTransaction () EmvLumo OnTransactionStateChanged (State=Enter card)

”Multiapp” card?

OnTransactionStateChanged (State=SelectApplication)

Is Card on hotlist ?

OnHotCardAction

Terminal decision

OnTransactionStateChanged (State=Authorizing/ RetryingAuthorizing/ RetryingAuthorizing2)

Online

Authorizing result

OnTransactionStateChanged (State=CancellingAuthorization/ CancellingAuthorization2/ CancellingAuthorization3)

Cancelled authorization ?

OnTransactionStateChanged (State=Authorized)

OnManualAuthorization Is bankcard payment and over 50 euros ?

OnTransactionFinished (Result=Declined)

OnCheckIdentity

OnTransactionFinished (Result=Accepted)

OnPrintTransactionReceipt (ReceiptType=Merchant)

OnPrintTransactionReceipt (ReceiptType=Customer)

Lumo - Interface Specification (API)

53 Lumo

8.3 MakeTransaction call MakeTransaction starts

Dialog windows are shown

MakeTransaction ends

Lumo - Interface Specification (API)

54 Lumo

9

GETNUMBERINPUT AND GETAMOUNTINPUT LINE TEXTS

INDEX

ENGLISH

FINNISH

SWEDISH

1 2 3 4 5 6 7 8 9 16 17 18 19 32 33 34 35 36 37 38 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75

AMOUNT ENTER NEW TOTAL TOTAL AMOUNT AGAIN ENTER ADD INPUT CALL YOUR BANK BALANCE TIP GRATUITY SERVICE DONATION WAITER ID WAITER LOGON TABLE NUMBER BILL NUMBER LOCATION REF TAB NUMBER OPERATOR ID PAN CARD NUMBER EXPIRY DATE START DATE AS MMYY ISSUE NUMBER CVV/CVC SPLIT BY NO. OF PARTIES TO PAY AUTH CODE CASHBACK DUE MAXIMUM MINIMUM MULTIPLES OF FORMAT DATE INCORRECT ID INCORRECT NO. INCORRECT BILL NOT FOUND CASH CARD CHEQUE VOUCHER PAYMENT REFUND

SUMMA UUSI LOPPUSUMMA LOPPUSUMMA SUMMA UUDELLEEN SYÖTÄ LISÄÄ NÄPPÄILE SOITA PANKKIIN SALDO JUOMARAHA JUOMARAHA PALVELU LAHJOITUS TARJOILIJATUNNUS KIRJAA TARJOILIJ PÖYDÄN NUMERO LASKUN NUMERO SIJAINTI JÄLKIVELOITUS NR KÄYTTÄJÄTUNNUS MAKSUSOVELLUS KORTIN NUMERO VOIMASSAOLOAIKA KÄYTTÖÖNOTTO MUODOSSA KKVV LIIKKEELLELASKU CVV/CVC JAA OSAPUOLTEN LKM MAKSETTAVAA VARMENNUSTUNNUS RAHAA TAKAISIN SAATAVA ENINTÄÄN VÄHINTÄÄN JAOLL. LUVULLLA MUOTO PÄIVÄYS VÄÄRIN TUNNUS VÄÄRIN NUMERO VÄÄRIN LASKUA EI LÖYDY KÄTEINEN KORTTI SHEKKI LOUNASSETELI MAKSU HYVITYS

BELOPP NY SLUTSUMMAN SLUTSUMMA BELOPP IGEN ANGE TILLSÄTTA MATA IN KONTAKTA BANKEN SALDO DRICKS DRICKS SERVICE GÅVA SERVITÖR ID REGISTR SERVITÖR BORD NUMMER BERÄKNING NR STÄLLNING EFTERDEBIT NR ANVÄNDARE ID BETALN APPLIKAT KORTETS NUMMER GILTIGHET IBRUKTAGANDE FORMAT MMÅÅ EMITTERINGS NR CVV/CVC DIVIDERA ANTAL PARTY BETALBAR AUKTORISER. KOD KONTANT TILLBAKS FORDRING HÖGST MINST DELBAR MED FORMAT DATUM FEL FEL IDENTIFIER. FEL NUMMER HITTAR EJ FAKTUR KONTANT KORT CHECK LUNCHSEDEL BETALNING ÅTERBETALNING

Lumo - Interface Specification (API)

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

Lumo - Interface Specification (API)

56 Lumo

POS -> Lumo: 0 POS -> Lumo: Lumo -> POS: True 4. (API starts transaction) Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 0100000False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000032False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000048False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005

Lumo - Interface Specification (API)

57 Lumo

Lumo -> POS: 01000064False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000069False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 0100110426004002020000000000E800128L1False Lumo -> POS: 1280L1 Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 0100110426004002020000000000E800112L1False Lumo -> POS: 300CMD PRINT_TRANSACTION_RECEIPT

Lumo - Interface Specification (API)

58 Lumo

Lumo -> POS: 0 Test Testikatu 1 00100 Testilä 1234567890 SELITE: OSTO KORTTI: Visa KÄYTTÖTAPA: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 KÄYTTÖTAPA:LUOTTOKORTTI AID ID: A0000000031010 NUMERO: ............4321 AVIITE: 110426004002

Lumo - Interface Specification (API)

59 Lumo

TVR:

0000000000

TSI: E800

YRITYS: XXXXXXXXXXXX KP: 4 TA: 5399 -------------------------------------VELOITUS: 1.00 EUR -------------------------------------ASIAKKAAN TOSITE: 26.04.2011 12:19:02 Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 0100110426004002020000000000E800129L1False (Note CompletedCardRemoved –event)

10.2 Transaction started with PrepareTransaction call with ReadBonusInformation parameter set to true Benefit of calling PrepareTransaction is that EMV handling can be started before transaction’s final amount is known. This will save few seconds in transaction process. There are few things to be concern: 

It is assumed that first card inserted will be bonus card/paycard. If bonus information is not read from first card and card is removed, transaction will be cancelled.



If bonus information is read from first card and card have been removed API is waiting for card insert or call to cancel transaction.



API will be waiting for StartTransaction call after TransactionStateChanged event where state is ReadyToReceiveSum.



Final sum should be set after ReadyToReceiveSum state change and transaction should be started with StartTransaction call.

10.2.1 Example: bonus information is read from chipcard and payment is given with another chipcard 1. (PrepareTransaction is called with ReadBonusInformation set) POS -> Lumo: 0

Lumo - Interface Specification (API)

60 Lumo

POS -> Lumo: POS -> Lumo: 0 POS -> Lumo: True Lumo -> POS: True 2. (API is waiting for inserting card) Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 0100000False 2.1.

(API returns bonus information)

Lumo -> POS: 600407…… 56782B3 Lumo -> POS: 3300CMD READ_BONUS_INFORMATION PAN (600407......5678) BonusType (2) SettlementInfo (B3) Cancel (-1) CustomerSegment () Validity () ManualInput (48) Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000048False

Lumo - Interface Specification (API)

61 Lumo

Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 2.2.

(API is waiting to receive final amount)

Lumo -> POS: 010000245False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 2.3.

(Card is removed from terminal)

Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 00000False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 2.4.

(Card is inserted)

Lumo -> POS: 000032False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 000048False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 2.5.

(API is waiting to receive final amount)

Lumo -> POS: 0000245False 3. (POS will give final amount and starts transaction) POS -> Lumo: 0 POS -> Lumo: POS -> Lumo: 0 POS -> Lumo: 100 POS -> Lumo: 0 POS -> Lumo: Lumo -> POS: True Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005

Lumo - Interface Specification (API)

63 Lumo

Lumo -> POS: 0100000False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000064False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000069False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 0100110426004003020000000000E800128L1False Lumo -> POS: 1280L1 Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005

Lumo - Interface Specification (API)

64 Lumo

Lumo -> POS: 0100110426004003020000000000E800112L1False Lumo -> POS: 300CMD PRINT_TRANSACTION_RECEIPT Lumo -> POS: 0 Test Testikatu 1 00100 Testilä 1234567890 SELITE: OSTO KORTTI: Visa KÄYTTÖTAPA:LUOTTOKORTTI AID ID: A0000000031010 NUMERO: 492019…...9876 AVIITE: 110426004003 TVR:

0000000000

TSI: E800

YRITYS: XXXXXXXXXXXX KP: 4 TA: 5399 -------------------------------------VELOITUS: 1.00 EUR -------------------------------------KAUPPIAAN TOSITE: 26.04.2011 13:08:35 Lumo -> POS: 300CMD PRINT_TRANSACTION_RECEIPT

Lumo - Interface Specification (API)

65 Lumo

Lumo -> POS: 1SELITE: OSTO KORTTI: Visa KÄYTTÖTAPA:LUOTTOKORTTI AID ID: A0000000031010 NUMERO: ............9876 AVIITE: 110426004003 TVR:

0000000000

TSI: E800

YRITYS: XXXXXXXXXXXX KP: 4 TA: 5399 -------------------------------------VELOITUS: 1.00 EUR -------------------------------------ASIAKKAAN TOSITE: 26.04.2011 13:08:35 Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 4. Card is removed from terminal Lumo -> POS: 0100110426004003020000000000E800129L1False

Lumo - Interface Specification (API)

66 Lumo

10.2.2 Example: bonus information is read from same chipcard as transaction is payed 1. (POS starts PrepareTransaction) POS -> Lumo: 0 POS -> Lumo: POS -> Lumo: 0 POS -> Lumo: True Lumo -> POS: True Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 0100000False 2. (Payer insert card) Lumo -> POS: 600407…… 11112B3 Lumo -> POS: 3300CMD READ_BONUS_INFORMATION PAN (600407......1111) BonusType (2) SettlementInfo (B3) Cancel (-1) CustomerSegment () Validity () ManualInput (48) Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005

Lumo - Interface Specification (API)

67 Lumo

Lumo -> POS: 01000048False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 3. (Lumo API is waiting for final amount) Lumo -> POS: 010000245False 4. (POS sets transaction amount and starts transaction) POS -> Lumo: 0 POS -> Lumo: POS -> Lumo: 0 POS -> Lumo: 100 POS -> Lumo: 0 POS -> Lumo: Lumo -> POS: True Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005

Lumo - Interface Specification (API)

68 Lumo

Lumo -> POS: 0100000False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000064False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000069False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000080False Lumo -> POS: 100CMD HTTP_REQUEST Lumo -> POS: 110HTTP_REQUEST SENT slave1.screenway.comGET /emvx.php?acq=100&asi=3212451234997&t

Lumo - Interface Specification (API)

69 Lumo

Lumo -> POS: 120HTTP_REQUEST REPLY RECEIVED (351) Lumo -> POS: 130HTTP_REQUEST REPLY TO DEVICE DONE (0) Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 Lumo -> POS: 01000096False Lumo -> POS: 500CMD MAKE_TRANSACTION: 0005 …

Lumo - Interface Specification (API)

70 Lumo

End of doc.

Lumo - Interface Specification (API)