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
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
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
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
LUMOAPI COM INTEROP DLL ....................................................................... 39

4.1 PROGRAMMING EXAMPLE (VISUAL BASIC) ............................................................ 39
USAGE ......................................................................................................... 41
5.1 EXAMPLE: STARTING IN WINDOWS .................................................................... 42
INSTALLATION ............................................................................................ 43
6.1 INSTALLATION ON WINDOWS ........................................................................... 43
TRANSACTION DIALOGS IN MAKETRANSACTION METHOD CALL ................. 44
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
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
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
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
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
Authenticated, specifies whether the device is authenticated,

paired or bonded, True or False string values
Connected, specifies whether the device is connected, True

or False string values
7
Lumo
Remembered, specifies whether the device is a remembered

device. Not all remembered devices are authenticated. True
or False string values
LastSeen, date and time this device was last seen by the
system. Presented as formatted string value,
yyyyMMddHHmmss
LastUsed, date and time this device was last used by the
system. Presented as formatted string value,
yyyyMMddHHmmss
Example
<DeviceAddress>000190E63E19</DeviceAddress><DeviceName>PP03100
00077</DeviceName><Authenticated>False</Authenticated><Connected
>False</Connected><Remembered>False</Remembered><LastSeen>201
00527200708</LastSeen><LastUsed>00010101000000</LastUsed>
2.1.5 CardEntryModes CardEntryMode
Card entry mode for transaction. Combined reader or manual entry.

See CardEntryModes enumeration 2.4.1.
Default value is CombinedReader (0)
2.1.6 String CommunicationPortname
Communication port used for connections to terminal device.
In case of the Bluetooth device this is the Bluetooth device address

(see BluetoothDevicesInRange property).
Example COM9
2.1.7 String DataStoragePath
Where all the parameters and log files should be stored.
If empty, current path is used.
Value can be local path or UNC-path.
2.1.8 String FailureInfo
Contains information on errors, failures and declines that may

happen at starting transaction or during process
Property returns XML formatted information
Example:
<FailureInfo><Code></Code><Description></Description><MerchantInfo
></MerchantInfo><Code>...</MerchantInfo></FailureInfo>
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.
If false socket is kept open until client closes it. This is the
preferred way to handle connection!
Only usable in XML interface
XML Example:
<?xml version=1.0 encoding=utf-8?><EMVLumo
xmlns=http://www.luottokunta.fi/EMVLumo><SetTCPDisconnect><Value>
False</Value></SetTCPDisconnect></EMVLumo>
2.1.23 bool HTTPProxyAuthentication
Indicates whether domain user credentials are sent with http

requests to the http proxy. Only usable in Windows environment.
Some proxies authenticate user by domain user credentials and it is

needed that those are sent with HTTP requests.
2.1.24 bool CheckIdentity
Indicates to merchant to check identity of the cardholder
E.g. Finnish bank cards over 50 euros amount
In this case the merchant receipt will also have a place for
identification
2.1.25 bool CheckReceiptSignature
Indicates that merchant receipt has signature section and merchant

is expected to check that 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.
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:
<DeviceInfo>
<Serial>29501109000010591234</Serial>
<Version>v 1.4.952</Version>
<Type>ML30 v 1.4.952</Type>
<Merchant>111111111123</Merchant>
<POS>004</POS>
<Terminal>12C97004</Terminal>
</DeviceInfo>
2.1.29 String Track2Data
Track 2 of 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
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)
Finds Bluetooth devices in the range. Execution is blocked while

Bluetooth devices are enumerated.
Execution might take a while.
cash
12
Lumo
Parameters:
o
MaxCountOfDevices, the max count of devices
IncludeAuthenticated, show also devices that have been

already paired.
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:
DeviceAddress, Bluetooth address for device to pair
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:
<DoDisplay>
<Clear>true</Clear>
<RowText>
<Row>0</Row>
<Inverse>True</Inverse>
<Alignment>Left</Alignment>
<Text>Hello</Text>
</RowText>
<RowText>
<Row>0</Row>
<Inverse>False</Inverse>
<Alignment>Right</Alignment>
<Text>World!</Text>
</RowText>
</DoDisplay>
2.2.15 bool DoDisplayMenu(string Title, int Timeout, string Itemlist)
Show selectable items on terminal in menu format. After user has

selected an item OnGotInput -event is fired with selected menu item
number.
Due the blocking nature of this method, automated daily

transaction batch sending and fetching parameters cannot be
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.
Timeout Timeout in milliseconds. If 0 no timeout will be

used.
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 Receipts timestamp
Text Receipt text
Example of XML formatted list:

<Receipts>
<Receipt>
<ReceiptType>0</ReceiptType>
<ArchiveID>110105004002</ArchiveID>
<EventDate>5.1.2011 13:34:20</EventDate>
<Text>
Toni+Test
\n
Testikatu 1
\n
00100 Testil
\n
1234567890
\nSELITE: OSTO\nKORTTI: VISA
CREDIT\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</Text>
</Receipt>
<Receipt>
<ReceiptType>1</ReceiptType>
16
Lumo
<ArchiveID>110105004002</ArchiveID>
<EventDate>5.1.2011 13:34:21</EventDate>
<Text>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</Text>
</Receipt>
</Receipts>
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
BonusType, 1 = Ykksbonus, 2 = S-Bonus, 3 = Plussa
BonusAmount, Bonus transaction amount
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
Line1, Line2, Line3, Nextscreen. See reference to chapter 9.
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
CLEAR = 8
ENTER = 13
F1 = 128
F2 = 129
F3 = 139
F4 = 141
Parameters:
o
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.
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
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
Instructions, String Question, ref int Result)
Parameters in:
ActionCode,
String
ActionCode, Numeric action code for informational purposes
Instructions, Instructions to merchant
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
PAN, Primary Account Number
PAN is masked so merchant should look at terminals

screen for full PAN
Amount, Transaction amount
PhoneNumber, Phone number where to call.
Parameters out:
21
Lumo
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
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
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.
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.
Result, 0 = Accepted, 1 = Declined
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.
Sum, amount of transaction which was given before calling

StartTransaction method. See chapter 2.1.1.
ArchiveID, archive identifier
Can be obtained from TransactionReceiverAN property

afterwards
Result, 0 = Accepted and 1 = Declined
InputType, Informs how card data has been read.
23
Lumo
0 = Manual input
1 = Magnetic stripe
2 = Chip
TVR, Terminal verification result
TSI, Transaction status information
State, Actual state for the transaction. See chapter 2.4.5.
TransactionReceiverAN, Settlement identification as

alphanumeric string
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
IssuerCountryCode, contains country code if transaction was

made from chip
TransactionSyncID, merchant ID(9+3) + archive ID(12) +

time HHMMSS(6)
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
Int BonusType
1 = Ykksbonus, 2 = S-Bonus, 3 = Plussa
If not present 0 is returned
String SettlementInfo
Returned if available for given bonus type and

information
String CustomerSegment
Returned if available for given bonus type and

information
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
ManualEntry = 1
2.4.2 TerminalDeviceTypes
Terminal device types
Members:
o
NONE = 0, initial state where no terminal is not set
SagemML30 = 30
SagemML30COM = 31
SagemiCT250 = 221
SagemiWL250 = 240
SagemiWL250B = 242
SagemiWL250G = 245
SagemiPP350 = 321
26
Lumo
Sagem930 = 930
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
SendUnsentTransactions = 1
LockBatches = 2
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
Refund_Cancel = 1
CashWithdrawal = 2
Cashback = 3
Bonus = 6
SendTransactions = 8
2.4.5 TransactionState
State of the transaction
Members:
o
o
o
o
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
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
TerminalRebooting = 1
Terminal has sent transactions
TerminalInitialized = 6
Terminal is ready for starting a transaction
TerminalSendingTransactionsDone = 5
Terminal is sending transactions
TerminalInIdleState = 4
Terminal is initialized and ready for use
TerminalSendingTransactions = 3
Terminal is rebooting
TerminalReady = 2
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,
/// <summary>
/// All authorization declines are 100-999
/// </summary>
AUTHORIZATION_DECLINE = 100,
EXPIRED_CARD = 101,
AUTHORIZATION_DECLINE_TAKE_CARD = 200,
AUTHORIZATION_ERROR = 900,
AUTHORIZATION_NO_ONLINE_CONNECTION = 999,
DATA_NOT_READ = 1000,
CARD_REMOVED = 1001,
AGREEMENT_NOT_FOUND = 1002,
INVALID_PAN_LENGTH = 1003,
AUTHORIZATION_CODE_CHECKSUM_MISMATCH = 1004,
KEYING_IN_NOT_ALLOWED = 1005,
PURCHASE_MAX_LIMIT_EXCEEDED = 1006,
PURCHASE_MIN_LIMIT_EXCEEDED = 1007,
CASHWITHDRAWAL_NOT_ALLOWED = 1008,
CREDIT_PURCHASE_NOT_ALLOWED = 1009,
29
Lumo
INVALID_CARD = 1010,
NO_MATCHING_APPLICATIONS_ON_CHIP = 1011,
/// <summary>
/// If transaction is not found for cancellation with filing code and
/// user rejected refund.
/// </summary>
REFUND_FALLBACK_REJECTED = 1080,
/// <summary>
/// If user wants to cancel transaction and it has already been cancelled
/// </summary>
INVALID_CANCELLATION = 1081,
CANCELLATION_NOT_ALLOWED = 1082,
PARTIAL_CANCELLATION_NOT_ALLOWED = 1083,
REFUND_NOT_ALLOWED = 1084,
PARTIAL_REFUND_NOT_ALLOWED = 1085,
BLACKLIST_FAILURE = 1090,
CARD_ON_BLACKLIST_TAKE_CARD = 1091,
CARD_ON_BLACKLIST_CALL_POLICE = 1092,
CARD_ON_BLACKLIST = 1093,
ICC_DECLINE = 1100,
CARD_BLOCKED = 1200,
BLOCKED_APPLICATION = 1201,
AID_OUTDATED = 1800,
BIN_OUTDATED = 1801,
PUBLIC_KEYS_OUTDATED = 1802,
HOTCARD_OUTDATED = 1803,
CONFIG_OUTDATED = 1804,
CONFIG_INVALID_OR_NOT_FOUND = 1805,
SERIAL_NBR_ERROR = 1806,
HOTCARD_NOT_FOUND = 1807,
TRANSLATION_OUTDATED = 1808,
CANCEL_ON_TERMINAL = 1900,
CANCEL_ON_API = 1901,
PIN_BYPASS_NOT_ACCEPTED = 1902,
NO_CONNECTION_TO_DEVICE = 1997,
INCORRECT_SW_ON_TERMINAL = 1998,
UNDEFINED = 1999,
MANUAL_INPUT_WITH_CASH_WITHDRAWAL_NOT_ALLOWED = 3000,
MANUAL_INPUT_WITH_CASHBACK_NOT_ALLOWED = 3010,
NEGATIVE_AMOUNT_NOT_ALLOWED = 3020,
ANOTHER_METHOD_IS_ONGOING = 3030,
OPEN_CONNECTION_FAILED = 3040,
TERMINAL_INITIALIZATION_FAILED = 3050,
PREPARE_ALLOWED_ONLY_WITH_PURCHASE = 3060,
TERMINAL_NOT_READY = 3070,
UNSUPPORTED_CURRENCY_CODE = 3080,
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
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.
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo">...</EMVLumo>
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
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo">
<SetAmount><Value>1000</Value></SetAmount></EMVLumo>
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)
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><GetAmount /></EMVLumo>
Lumo -> POS (reply)
<?xml version="1.0" encoding="utf-8"?>
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><GetAmount>
<Result>1000</Result></GetAmount></EMVLumo>
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
<MakeTransaction><TransactionType>0</TransactionType></MakeTransaction></EMVLumo>
Lumo -> POS (replying declined transaction)
<MakeTransaction><Result>False</Result></MakeTransaction></EMVLumo>
3.4.2 Example: Calling BluetoothGetDevicesInRange
POS -> Lumo
<BluetoothGetDevicesInRange>
<MaxCountOfDevices>1</MaxCountOfDevices>
<IncludeAuthenticated>True</IncludeAuthenticated>
<IncludeRemembered>True</IncludeRemembered>
</BluetoothGetDevicesInRange>
</EMVLumo>
Lumo -> POS
<BluetoothGetDevicesInRange>
<Result>0</Result>
</BluetoothGetDevicesInRange></EMVLumo>
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
<StatusUpdate>
<StatusCode>500</StatusCode>
<StatusInfo>CMD MAKE_TRANSACTION: 00-05</StatusInfo>
</StatusUpdate>
</EMVLumo>
3.5.2 Example: OnBypassPINRequest
Lumo -> POS
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><BypassPINRequest /></EMVLumo>
POS -> Lumo
<?xml version="1.0" encoding="UTF-8"?>
<BypassPINRequest><BypassAccepted>true</BypassAccepted></BypassPINRequest>
</EMVLumo>
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
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><StartTransaction /></EMVLumo>

Lumo -> POS (Transaction is started successfully)
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><StartTransaction
><Result>True</Result><StartTransaction /></EMVLumo>
Lumo -> POS (Informational data)
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><StatusUpdate>
<StatusInfo>CMD MAKE_TRANSACTION: 00-05</StatusInfo></StatusUpdate></EMVLumo>
Lumo -> POS (Payer is asked to insert card)
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><TransactionStateChanged>
<TransactionType>0</TransactionType><Sum>1004</Sum>
<ArchiveID /><Result>0</Result><InputType>0</InputType><TVR />
<TSI /><State>0</State><TransactionReceiverAN />
<CheckIdentity>False</CheckIdentity></TransactionStateChanged></EMVLumo>
Lumo -> POS (Payer is asked to enter PIN)
Lumo -> POS (Pin entry is completed)
Lumo -> POS (Authorizing transaction)
Lumo -> POS (informational data)
36
Lumo
<StatusInfo>CMD HTTP_REQUEST</StatusInfo></StatusUpdate></EMVLumo>
<StatusInfo>HTTP_REQUEST REPLY RECEIVED</StatusInfo></StatusUpdate></EMVLumo>
<StatusInfo>HTTP_REQUEST REPLY TO DEVICE DONE</StatusInfo>
</StatusUpdate></EMVLumo>
Lumo -> POS (transaction is authorized)
Lumo -> POS (transaction is completed)
<ArchiveID>100706001001</ArchiveID><Result>0</Result><InputType>2</InputType>
<TVR>0000008000</TVR><TSI>F800</TSI><State>128</State>
<TransactionReceiverAN>L5</TransactionReceiverAN><CheckIdentity>False</CheckIdentity>
</TransactionStateChanged></EMVLumo>
Lumo -> POS (transaction is accepted)
37
Lumo

<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><TransactionFinished>
<StatusCode>128</StatusCode><Result>0</Result>
<TransactionReceiverAN>L5</TransactionReceiverAN></TransactionFinished></EMVLumo>
<StatusInfo>CMD PRINT_TRANSACTION_RECEIPT</StatusInfo></StatusUpdate></EMVLumo>
Lumo -> POS (merchant receipt)
<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><PrintTransactionReceipt>
<ReceiptType>0</ReceiptType><ReceiptData>
Testshop
Teststreet 2
Testtown
1234567890
SELITE: OSTO
KORTTI: VISA DEBIT
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
</ReceiptData></PrintTransactionReceipt></EMVLumo>
Lumo -> POS (customer receipt)

<EMVLumo xmlns="http://www.luottokunta.fi/EMVLumo"><PrintTransactionReceipt>
<ReceiptType>1</ReceiptType><ReceiptData>
Testshop
Teststreet 2
Testtown
1234567890
SELITE: OSTO
KORTTI: VISA DEBIT
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
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 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 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!")
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
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:<com port>
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:<type of server mode>

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

communication mode
Acceptable values for parameter XMLCOMM or DOPAYCOMM
-TCPPORT:
o
Defines TCP API Server port
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
Starts EMVLumoAgent without Transaction test possibility on Test tab
5.1 Example: Starting in Windows

C:\EMVLumo> EMVLumoAgent -TRAY -COMPORT:COM6
43
Lumo
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
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
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

StartTransaction()
EmvLumo
OnTransactionStateChanged
(State=Enter card)
Multiapp card?
(State=SelectApplication)
Supported language?
(State=SelectLanguage)
(State=ReadingCard)
(State=EnterPin)
Bypass PIN?
OnBypassPINRequest
Chip 1st decision
(State=Authorizing/
RetryingAuthorizing/
RetryingAuthorizing2)
(State=CancellingAuthorization/
CancellingAuthorization2/
CancellingAuthorization3)
Online
(State=Authorized)
Chip 2st decision
OnTransactionFinished
(Result=Accepted)
(Result=Declined)
OnPrintTransactionReceipt
(ReceiptType=Merchant)
(ReceiptType=Customer)
Authorizing result
52
Lumo
8.2 Basic magnetic stripe transaction with StartTransaction method

StartTransaction ()
EmvLumo
(State=Enter card)
Multiapp card?
(State=SelectApplication)
Is Card on hotlist ?
OnHotCardAction
Terminal decision
(State=Authorizing/
RetryingAuthorizing/
RetryingAuthorizing2)
Online
Authorizing result
(State=CancellingAuthorization/
CancellingAuthorization2/
CancellingAuthorization3)
Cancelled authorization ?
(State=Authorized)
OnManualAuthorization
Is bankcard payment and
over 50 euros ?
(Result=Declined)
OnCheckIdentity
(Result=Accepted)
(ReceiptType=Merchant)
(ReceiptType=Customer)
53
Lumo
8.3 MakeTransaction call

MakeTransaction starts
Dialog windows are shown
MakeTransaction ends
54
Lumo
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
SYT
LIS
NPPILE
SOITA PANKKIIN
SALDO
JUOMARAHA
JUOMARAHA
PALVELU
LAHJOITUS
TARJOILIJATUNNUS
KIRJAA TARJOILIJ
PYDN NUMERO
LASKUN NUMERO
SIJAINTI
JLKIVELOITUS NR
KYTTJTUNNUS
MAKSUSOVELLUS
KORTIN NUMERO
VOIMASSAOLOAIKA
KYTTNOTTO
MUODOSSA KKVV
LIIKKEELLELASKU
CVV/CVC
JAA
OSAPUOLTEN LKM
MAKSETTAVAA
VARMENNUSTUNNUS
RAHAA TAKAISIN
SAATAVA
ENINTN
VHINTN
JAOLL. LUVULLLA
MUOTO
PIVYS
VRIN
TUNNUS VRIN
NUMERO VRIN
LASKUA EI LYDY
KTEINEN
KORTTI
SHEKKI
LOUNASSETELI
MAKSU
HYVITYS
BELOPP
NY SLUTSUMMAN
SLUTSUMMA
BELOPP IGEN
ANGE
TILLSTTA
MATA IN
KONTAKTA BANKEN
SALDO
DRICKS
DRICKS
SERVICE
GVA
SERVITR ID
REGISTR SERVITR
BORD NUMMER
BERKNING NR
STLLNING
EFTERDEBIT NR
ANVNDARE ID
BETALN APPLIKAT
KORTETS NUMMER
GILTIGHET
IBRUKTAGANDE
FORMAT MM
EMITTERINGS NR
CVV/CVC
DIVIDERA
ANTAL PARTY
BETALBAR
AUKTORISER. KOD
KONTANT TILLBAKS
FORDRING
HGST
MINST
DELBAR MED
FORMAT
DATUM
FEL
FEL IDENTIFIER.
FEL NUMMER
HITTAR EJ FAKTUR
KONTANT
KORT
CHECK
LUNCHSEDEL
BETALNING
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: <?xml version="1.0" encoding="utf-8"?><EMVLumo
xmlns="http://www.luottokunta.fi/EMVLumo"><ReadBonusInformation /></EMVLumo>
Lumo -> POS: <?xml version="1.0" encoding="utf-8"?><EMVLumo
xmlns="http://www.luottokunta.fi/EMVLumo"><ReadBonusInformation><Result>True</Resu
lt></ReadBonusInformation></EMVLumo>
2. (User inserts bonus card and EMVLumo returns bonus information)
xmlns="http://www.luottokunta.fi/EMVLumo"><BonusInformationReaden><PAN>600407.....
.1234</PAN><BonusType>2</BonusType><SettlementInfo>B3</SettlementInfo><Custome
rSegment /><Validity /></BonusInformationReaden></EMVLumo> (Note PAN is masked)
xmlns="http://www.luottokunta.fi/EMVLumo"><StatusUpdate><StatusCode>3300</StatusC
ode><StatusInfo>CMD READ_BONUS_INFORMATION PAN (600407......1234) BonusType (2)
SettlementInfo (B3) Cancel (-1) CustomerSegment () Validity () ManualInput
(48)</StatusInfo></StatusUpdate></EMVLumo>
3. (POS sets transaction properties and starts transaction)
xmlns="http://www.luottokunta.fi/EMVLumo"><SetTransactionType><Value>0</Value></S
etTransactionType></EMVLumo>
xmlns="http://www.luottokunta.fi/EMVLumo"><SetArchiveID><Value
/></SetArchiveID></EMVLumo>
xmlns="http://www.luottokunta.fi/EMVLumo"><SetCardEntryMode><Value>0</Value></Set
CardEntryMode></EMVLumo>
xmlns="http://www.luottokunta.fi/EMVLumo"><SetAmount><Value>100</Value></SetAmo
unt></EMVLumo>
56
Lumo

xmlns="http://www.luottokunta.fi/EMVLumo"><SetAmountOther><Value>0</Value></SetA
mountOther></EMVLumo>
xmlns="http://www.luottokunta.fi/EMVLumo"><StartTransaction /></EMVLumo>
xmlns="http://www.luottokunta.fi/EMVLumo"><StartTransaction><Result>True</Result></
StartTransaction></EMVLumo>
4. (API starts transaction)
xmlns="http://www.luottokunta.fi/EMVLumo"><StatusUpdate><StatusCode>500</StatusCo
de><StatusInfo>CMD MAKE_TRANSACTION: 0005</StatusInfo></StatusUpdate></EMVLumo>
xmlns="http://www.luottokunta.fi/EMVLumo"><TransactionStateChanged><TransactionType
>0</TransactionType><Sum>100</Sum><ArchiveID
/><Result>0</Result><InputType>0</InputType><TVR /><TSI
/><State>0</State><TransactionReceiverAN
/><CheckIdentity>False</CheckIdentity></TransactionStateChanged></EMVLumo>
57
Lumo

>0</TransactionType><Sum>100</Sum><ArchiveID>110426004002</ArchiveID><Result
>0</Result><InputType>2</InputType><TVR>0000000000</TVR><TSI>E800</TSI><Sta
te>128</State><TransactionReceiverAN>L1</TransactionReceiverAN><CheckIdentity>False
</CheckIdentity></TransactionStateChanged></EMVLumo>
xmlns="http://www.luottokunta.fi/EMVLumo"><TransactionFinished><StatusCode>128</Sta
tusCode><Result>0</Result><TransactionReceiverAN>L1</TransactionReceiverAN></Trans
actionFinished></EMVLumo>
de><StatusInfo>CMD
PRINT_TRANSACTION_RECEIPT</StatusInfo></StatusUpdate></EMVLumo>
58
Lumo

xmlns="http://www.luottokunta.fi/EMVLumo"><PrintTransactionReceipt><ReceiptType>0</R
eceiptType><ReceiptData>
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
de><StatusInfo>CMD
eceiptType><ReceiptData>SELITE: OSTO
KORTTI: Visa
AID ID: A0000000031010
NUMERO: ............4321
AVIITE: 110426004002
59
Lumo
TVR:
0000000000
TSI: E800

-------------------------------------VELOITUS: 1.00 EUR
</CheckIdentity></TransactionStateChanged></EMVLumo> (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 transactions
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)
60
Lumo

xmlns="http://www.luottokunta.fi/EMVLumo"><PrepareTransaction><ReadBonusInformation
>True</ReadBonusInformation></PrepareTransaction></EMVLumo>
xmlns="http://www.luottokunta.fi/EMVLumo"><PrepareTransaction><Result>True</Result>
</PrepareTransaction></EMVLumo>
2. (API is waiting for inserting card)
2.1.
(API returns bonus information)

xmlns="http://www.luottokunta.fi/EMVLumo"><BonusInformationReaden><PAN>600407
5678</PAN><BonusType>2</BonusType><SettlementInfo>B3</SettlementInfo><Custome
rSegment /><Validity /></BonusInformationReaden></EMVLumo>
61
Lumo

2.2.
(API is waiting to receive final amount)

2.3.
(Card is removed from terminal)

2.4.
(Card is inserted)

62
Lumo
2.5.
(API is waiting to receive final amount)

3. (POS will give final amount and starts transaction)
unt></EMVLumo>
63
Lumo

xmlns="http://www.luottokunta.fi/EMVLumo"><TransactionFinished><StatusCode>128</Sta
tusCode><Result>0</Result><TransactionReceiverAN>L1</TransactionReceiverAN></Trans
actionFinished></EMVLumo>
64
Lumo

de><StatusInfo>CMD
eceiptType><ReceiptData>
Test
Testikatu 1
00100 Testil
1234567890
SELITE: OSTO
KORTTI: Visa
AID ID: A0000000031010
NUMERO: 492019...9876
AVIITE: 110426004003
TVR:
0000000000
TSI: E800

-------------------------------------VELOITUS: 1.00 EUR
de><StatusInfo>CMD
65
Lumo

eceiptType><ReceiptData>SELITE: OSTO
KORTTI: Visa
AID ID: A0000000031010
NUMERO: ............9876
AVIITE: 110426004003
TVR:
0000000000
TSI: E800

-------------------------------------VELOITUS: 1.00 EUR
4. Card is removed from terminal
66
Lumo
10.2.2 Example: bonus information is read from same chipcard as transaction is payed
1. (POS starts PrepareTransaction)
xmlns="http://www.luottokunta.fi/EMVLumo"><PrepareTransaction><ReadBonusInformation
>True</ReadBonusInformation></PrepareTransaction></EMVLumo>
xmlns="http://www.luottokunta.fi/EMVLumo"><PrepareTransaction><Result>True</Result>
</PrepareTransaction></EMVLumo>
2. (Payer insert card)
xmlns="http://www.luottokunta.fi/EMVLumo"><BonusInformationReaden><PAN>600407
1111</PAN><BonusType>2</BonusType><SettlementInfo>B3</SettlementInfo><Custome
rSegment /><Validity /></BonusInformationReaden></EMVLumo>
67
Lumo

3. (Lumo API is waiting for final amount)
4. (POS sets transaction amount and starts transaction)
unt></EMVLumo>
68
Lumo

de><StatusInfo>CMD HTTP_REQUEST</StatusInfo></StatusUpdate></EMVLumo>
de><StatusInfo>HTTP_REQUEST SENT slave1.screenway.comGET
/emvx.php?acq=100&asi=3212451234997&t</StatusInfo></StatusUpdate></EMV
Lumo>
69
Lumo

de><StatusInfo>HTTP_REQUEST REPLY RECEIVED
de><StatusInfo>HTTP_REQUEST REPLY TO DEVICE DONE
70
Lumo
End of doc.

Emvlumo API

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Emvlumo API

Hochgeladen von

Copyright:

Verfügbare Formate

Lumo

INTERFACE SPECIFICATION (API)

Specifications for application interface

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

GENERAL INTERFACE FUNCTIONALITY..........................................................6

int Amount .......................................................................................................6

2.2.1 int BluetoothGetDevicesInRange (int MaxCountOfDevices, bool IncludeAuthenticated,

Lumo - Interface Specification (API)

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

EVENTS DURING THE TASK ............................................................................... 19

Lumo - Interface Specification (API)

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

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

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

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

LUMOAPI COM INTEROP DLL ....................................................................... 39

TRANSACTION DIALOGS IN MAKETRANSACTION METHOD CALL ................. 44

BASIC TRANSACTION FLOWS ...................................................................... 50

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

10 BONUS INFORMATION HANDLING .............................................................. 55

Lumo - Interface Specification (API)

1.1 Change Log

Generic document update

Changed Transaction States to decimal values.

Added BonusTransactionType property,

Added GetTransactionReceipt method and

Updated InputType information and added chapter

Updated enum TransactionBatchMethods values

Updated DoDisplayMenu method information

Added TipAmount and QuasiCashTerminal

Added failureinfos to SendTransactionBatches.

1.2 General Information about the Interface

Lumo - Interface Specification (API)

Lumo - Interface Specification (API)

GENERAL INTERFACE FUNCTIONALITY

2.1 Properties for the Transaction

The amount being debited or credited

2.1.2 int AmountOther

The amount being debited or credited

2.1.3 String ArchiveID

Defines the filing code (archive identifier), which is used in referring

Optional, except mandatory for Refund or cancellation transactions

The archive identifier is always found on the original receipt and

Cancellation transaction has the same filing code as original

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

It contains hashtable of devices and different properties can be

In XML interface data is received as XML formatted string.

XML data contains following fields by device

DeviceAddress, Bluetooth device address, presented as

DeviceName, Bluetooth device name, string value. It may be

Authenticated, specifies whether the device is authenticated,

Connected, specifies whether the device is connected, True

Lumo - Interface Specification (API)

Remembered, specifies whether the device is a remembered

2.1.5 CardEntryModes CardEntryMode

Card entry mode for transaction. Combined reader or manual entry.

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