BAXI

BAXI.net BAXI.net Application Programmer’s Programmer ’s guide Version 1.3.2.0 Revision - A Date: 2014-01-16

Prepared by : Updated by: Target group :

NETS Norway AS BAXI Application Programmers guide

Per Rödström

ECR vendors, terminal vendors and other parties influenced by this specification.

Page 1 of 43

1

References.... eferences......... .......... .......... .......... .......... .......... ............ ..................... ............................ ...................4 .....4

2

Revision Record...... ecord........... .......... .......... .......... ........... .................... ............................ .....................4 .......4

3

Introductio Introduction..... n.......... .......... .......... .......... .......... .................. ........................... ............................ ................ 6

4

Procedures for using BAXI............................................ BAXI.................................................... ........ 6 4.1

Installati Installation.... on......... .......... .......... .......... .......... .......... .......... .......... .............. ...................... ........................6 ...........6

4.2

General General work fow....... fow............ .......... .......... .......... .......... .......... ........... .................. ........................6 ............6

4.3

Error situations............... situations......................................... ........................................................ .............................. 6

4.4

USB rs232 rs232 support... support........ .......... .......... .......... .......... ............... ...................... ......................... ................6 ...6

BAXI Properties............................ Properties.................................................... ............................................. ..................... 9

5

4.5

Read properties.. properties....... .......... .......... .......... .......... .......... .......... ................. ......................... .....................9 ........9

4.6

rite properties............. properties...................................... ................................................... ................................ ...... 9

BAXI Methods... Methods........ ......... ......... .......... .......... .......... ............... ........................ ..........................13 ............13 5.1

General General note on para!eter para!eters.... s......... ............. .................... ......................... .....................13 ........13

5.2

"pen....................................... "pen................................................................. ..............................................13 ....................13

5.3

#lose.... #lose......... .......... .......... .......... .......... .......... .......... .......... .......... ................ ........................ ........................13 ...........13

5.4

$rans%er& rans%er&!ount.. !ount....... .......... .......... .......... ........... .................. ......................... ......................... ...............14 ...14

5.5

&d!inistra &d!inistration... tion........ .......... .......... .......... .......... .......... .......... ........... ................... ......................... .............15 .15

5.6

$rans%er#ard'ata.................. rans%er#ard'ata.................................................... ............................................. .............. ...16 16

5.(

Send$)' Send$)'..... .......... .......... .......... .......... .......... .......... .......... .......... ................ ....................... .......................1( ...........1(

5.*

Get$)'$a+.................... Get$)'$a+...................................................... ............................................. ...................... ........... 1(

5.9

BiB&d!inis BiB&d!inistrati tration.... on......... .......... .......... .......... .......... .......... ................. ......................... ...................1( ......1(

5.1, BiB$ransa-tion........ BiB$ransa-tion.................................. .......................................... ............................ .................... ........ 1*

6

BAXI vents..... vents.......... .......... .......... .......... .......... .......... .......... .......... .............. ....................... .................19 ...19 6.1

General note on eents................. eents.......................................... .........................................19 ................19

6.2

"n'ispla/$ "n'ispla/$e0t....................... e0t...................................................... .......................................... ................. ......19 19

6.3

"nrinter$e0t............................ e0t..................................................... ............................................ ................... 19

6.4

"n)o-al "n)o-alode.. ode....... .......... .......... .......... .......... .......... ............. .................... ......................... ....................2, .......2,

6.5

"nError................................. "nError........................................................... ................................................ ...................... 22

6.6

"n$)'R "n$)'Re-ei e-eied. ed...... .......... .......... .......... .......... .......... .......... ............... ...................... .......................22 ...........22

6.(

"nStdRsp.............................. "nStdRsp....................................................... ................................................ ....................... 23

6.*

"n$er!inalRea "n$er!inalRead/....................... d/.......................................... ................... ....................... ............ ............23 .23

6.9

"n)ast "n)astinan inan-ial -ialResu Result.... lt......... .......... .......... .......... .......... ................. ......................... ..................23 .....23

!

B"#i.ini B"#i.ini $%e...... $%e........... .......... .......... .......... .......... ................. .......................... ............................ ...............25 .25

&

'o((on 'o((on )se '"ses...... '"ses........... .......... .......... ............ .................... ........................... ...................26 .....26


Page 2 of 43

1

References.... eferences......... .......... .......... .......... .......... .......... ............ ..................... ............................ ...................4 .....4

2

Revision Record...... ecord........... .......... .......... .......... ........... .................... ............................ .....................4 .......4

3

Introductio Introduction..... n.......... .......... .......... .......... .......... .................. ........................... ............................ ................ 6

4

Procedures for using BAXI............................................ BAXI.................................................... ........ 6 4.1

Installati Installation.... on......... .......... .......... .......... .......... .......... .......... .......... .............. ...................... ........................6 ...........6

4.2

General General work fow....... fow............ .......... .......... .......... .......... .......... ........... .................. ........................6 ............6

4.3

Error situations............... situations......................................... ........................................................ .............................. 6

4.4

USB rs232 rs232 support... support........ .......... .......... .......... .......... ............... ...................... ......................... ................6 ...6

BAXI Properties............................ Properties.................................................... ............................................. ..................... 9

5

4.5

Read properties.. properties....... .......... .......... .......... .......... .......... .......... ................. ......................... .....................9 ........9

4.6

rite properties............. properties...................................... ................................................... ................................ ...... 9

BAXI Methods... Methods........ ......... ......... .......... .......... .......... ............... ........................ ..........................13 ............13 5.1

General General note on para!eter para!eters.... s......... ............. .................... ......................... .....................13 ........13

5.2

"pen....................................... "pen................................................................. ..............................................13 ....................13

5.3

#lose.... #lose......... .......... .......... .......... .......... .......... .......... .......... .......... ................ ........................ ........................13 ...........13

5.4

$rans%er& rans%er&!ount.. !ount....... .......... .......... .......... ........... .................. ......................... ......................... ...............14 ...14

5.5

&d!inistra &d!inistration... tion........ .......... .......... .......... .......... .......... .......... ........... ................... ......................... .............15 .15

5.6

$rans%er#ard'ata.................. rans%er#ard'ata.................................................... ............................................. .............. ...16 16

5.(

Send$)' Send$)'..... .......... .......... .......... .......... .......... .......... .......... .......... ................ ....................... .......................1( ...........1(

5.*

Get$)'$a+.................... Get$)'$a+...................................................... ............................................. ...................... ........... 1(

5.9

BiB&d!inis BiB&d!inistrati tration.... on......... .......... .......... .......... .......... .......... ................. ......................... ...................1( ......1(

5.1, BiB$ransa-tion........ BiB$ransa-tion.................................. .......................................... ............................ .................... ........ 1*

6

BAXI vents..... vents.......... .......... .......... .......... .......... .......... .......... .......... .............. ....................... .................19 ...19 6.1

General note on eents................. eents.......................................... .........................................19 ................19

6.2

"n'ispla/$ "n'ispla/$e0t....................... e0t...................................................... .......................................... ................. ......19 19

6.3

"nrinter$e0t............................ e0t..................................................... ............................................ ................... 19

6.4

"n)o-al "n)o-alode.. ode....... .......... .......... .......... .......... .......... ............. .................... ......................... ....................2, .......2,

6.5

"nError................................. "nError........................................................... ................................................ ...................... 22

6.6

"n$)'R "n$)'Re-ei e-eied. ed...... .......... .......... .......... .......... .......... .......... ............... ...................... .......................22 ...........22

6.(

"nStdRsp.............................. "nStdRsp....................................................... ................................................ ....................... 23

6.*

"n$er!inalRea "n$er!inalRead/....................... d/.......................................... ................... ....................... ............ ............23 .23

6.9

"n)ast "n)astinan inan-ial -ialResu Result.... lt......... .......... .......... .......... .......... ................. ......................... ..................23 .....23

!

B"#i.ini B"#i.ini $%e...... $%e........... .......... .......... .......... .......... ................. .......................... ............................ ...............25 .25

&

'o((on 'o((on )se '"ses...... '"ses........... .......... .......... ............ .................... ........................... ...................26 .....26


Page 2 of 43

*.1

$ransa-tions.............................. ransa-tions........................................................ ............................................26 ..................26

*.2

$opUp...................................... opUp..................................................................... .......................................... .............. ...3, 3,

*.3

Gi%t #ard.......................................... #ard.......................................................................... ..................................... .....3, 3,

*.4

Group Group I'..... I'.......... .......... .......... .......... .......... .......... .......... .......... .......... ................. ......................... .................3, ....3,

*.5

Get en-r/pted en-r/pted -ard data...... data........... .......... .......... .......... ............. ..................... ......................31 .........31

*.6

Get en-r en-r/pted /pted -ard data and issue issuerr I'...... I'........... .......... .......... ............ ...............31 ........31

*.(

Send Send a tra-k tra-k 2 -ard -ard swipe swipe to te te ter!i ter!inal... nal........ .......... .......... .......... ............31 .......31

*.*

$I........................................ $I.................................................................. ................................................32 ......................32

*.9

#e-k ost -onne-tion............... -onne-tion......................................... ............................................ .................. 32

*.1, Set ter!inal lan+ua+e................ lan+ua+e............................................ ....................................... ............... ....32 32 *.11 Re-eie a -ard inserted status eent...................................... 32 *.12 Get #usto!er In%o7....................... In%o7................................................ ....................................... .............. 32 *.13 Get #usto!er In%o7 wit &d!in inis........................... inis.................................. .......34 34 *.14 Inesti+atin+ results o% last last 8nan-ial 8nan-ial transa-tion....................34

Best pr"ctice i(p%e(ent"tion of securit* in the 'R interf"ce.. .36 9

+eprec"ted ,unctions........................ unctions................................................ ................................. ......... 3!

1- Re(oved Re(oved ,unctions.......................................... unctions.................................................... .................. ........3! 3! 1,.1 $rans%er&!oun $rans%er&!ount:2................................................... t:2................................................... ............3( ........... .3( 1,.2 $rans%er&!oun $rans%er&!ount:3................................................... t:3................................................... ............3( ........... .3( 1,.3 $rans%er&!oun $rans%er&!ount:4................................................... t:4................................................... ............3( ........... .3( 1,.4 &d!inistration; int ad!#ode< strin+ "perId=............... "perId=.................... .......... ......3( .3( 1,.5 Send$)'; Send$)'; strin+ t/peStrin+< >/te?@ tldield=............... tldield=..................... ........... ......3( .3( 1,.6 $rans%er#ard'ata; rans%er#ard'ata; int int tra-k$/pe< tra-k$/pe< strin+ strin+ tra-k'ata=.... tra-k'ata=......... .......... ........3( ...3( 1,.( BiB&d!inistration; int &d!#ode< strin+ "perI'=.................... "perI'=.....................3( .3( 1,.* BiB$ransa-tion; BiB$ransa-tion; int a!ount< a!ount< strin+ strin+ transa-tion'ata=......... transa-tion'ata=.............. ......3( .3(

11 Appendices.......................................... Appendices........................................................................ .............................. 3& 11.1 &ppendi0 & A Status -odes........................................... -odes..................................................... .......... 3* 11.2 &ppendi0 B A Seuen-e dia+ra!s............. dia+ra!s............................. ............................ ..............4, ..4,


Page 3 of 43

1 References 1. Nets proprietar proprietary y TLD (TypeLeng (TypeLengthDat thData) a) format format descrip description tion 2. BiBOpos

2 Revision Record DATE 2010-12-22 2011 011-01 -01-14 -14 2011 2011-0 -011-19 19 2011-02-23 2011 2011-0 -022-24 24 2011 011-03 -03-08 -08 2011-03-09 2011-03-11 2011-03-16 2011-03-21 2011-03-22 2011 2011-0 -044-01 01

VER. 1.0.0.16 1.0. .0.0.1 0.17 1.0. 1.0.2. 2.0 0 1.0.2.1 1.0. 1.0.2. 2.2 2 1.0. .0.2.3 2.3 1.0.2.4 1.0.2.5 1.0.2.6 1.0.2.7 1.0.2.8 1.0. 1.0.2. 2.9 9

2011-04-12 15.04.2011 19.04.2011 23.05.2011

1.0.3.0 1.03.1 1.0.3.2 1.2.0.3

06.06.2011 23.06 3.06.2 .20 011

1.2.0.5 1.2. .2.0.6 0.6

COMMENTS Version step only. Versio rsion n inc increm rement ent only only.. Vers Versio ion n inc incre reme ment nt only only.. See See rel relea ease se note notess for for more more deta detail ils. s. Added error code 7104. Vers Versio ion n inc incre reme ment nt only only.. See See rel relea ease se note notess for for more more deta detail ils. s. USB monit onitor orin ing g/su /suppor pport, t, add addeed ch chapte pter 4.4 4.4 Version step only. Force Offline Version step only Version step only. Version step only. Vers Versio ion n step step.. Adde Added d revi revisi sion on to enab enable le docu docume ment ntat atio ion n chan change gess when when BAXI version number should not change. Version step only. Internal re release on only Version step only. New interface. This involves refactoring existing existing implementations. implementations. It is especially important for COM clients to rebuild their interface files. Upgraded to support .net micro framework f ramework version 4.1. Version step only. Added ded Exte Extend ndeed LcalM calMo ode Doc Documena menati tio on: TotalAmount, RejectionSource, RejectionReason, TipAmount, SurchargeAmount, TerminalID, AcquirerMerchantID, CardIssuerName, ResponseCode, TCC, AID, TVR, TSI, ATC, AED, IAC


Page 4 of 43

DATE 18.07.2011

VER. 1.2.0.7

COMMENTS Added rejection error codes for new properties: UseDisplayTextID UseExtendedLocalMode 11.08.11 1.2.0.7-B Added Aministration Finish. 06.09.2011 1.2.0.8 Version step only. 16.09.11 1.2.0.9 Added new property SerialDriver. See properties chapter for more detail. 03.10.2011 1.2.1.0 Version step only. 17.10.2011 1.2.1.1 Version step only. 21.10.2011 1.2.1.1-B Added property DeviceString to document. 02/12/2011 1.3.0.1 Added new admin messages for last transction receipt and result, as well as the last transaction result message. 24/01/2012 1.3.0.2 Added new TLD fields:TCC,BankAgent Added new fields in extended Local Mode: AccountType,EncryptedPAN, BankAgent, organisationNumber. 16/02/2012 1.3.0.3 Added DoNotSplitDisplayText in ini file. 17.02.2012 1.3.0.4 Renamed DoNotSplitDisplayText UseSplitDisplayText 22.03.2012 1.3.0.5 Renamed UseSplitDisplayText UseJoinDisplayText 24.09.2012 1.3.0.6 Added property TerminalSwVersion. 15.10.12 1.3.0.7 Version increment only. 18.12.12 1.3.0.7-C Added Admin codes for Dataset and Software download. 14.01.12 1.3.0.8-A Version increment only. 2013-04-26 1.3.0.9 Version increment only. 2013-05-15 1.3.1.0 Version increment and update of event handling. Remark! The event is fired from an internal thread in baxi. The ECR client code is therefore executed from the baxi thread. It is important to release the event handler as fast as possible to let the thread go back and wait for more events. We recommend that the ECR programmer just create a new event and send the information to an internal thread of the ECR app. 2013-05-24 1.3.1.1

Version increment. Added OptionalData in Transfer Amount and LocalMode.

2013-06-17 1.3.1.2

Version increment. Added PreAuth Changed OptionalData in Transfer Amount and LocalMode. Version increment. Added new error codes 7515 and 7516 JSON Bad field valu7516 Transfer amount Optional Data too long. Version increment. JSON Bad field valu7516 Transfer amount Optional Data too long.

2013-07-02 1.3.1.3

2013-08-01 1.3.1.4


Page 5 of 43

DATE VER. 2013-08-13 1.3.1.5

2013-08-23 1.3.1.6

2013-09-04 1.3.1.7

COMMENTS Version increment. Added new error codes 7427 JSON Bad field valu7516 Transfer amount Optional Data too long. Version increment.| JSON Bad field valu7516 Transfer amount Optional Data too long. Version increment.| JSON Bad field valu7516 Transfer amount Optional Data too long.

2013-10-21 1.3.1.8

Added missing documentation in section 4.6 Write properties: UseSplitDisplayText LogAutoDeleteDays SocketListener SocketListenerPort Use2KBuffer

2013-11-05 1.3.1.9 A

2013-11-27 1.3.1.9 B

2014-01-16 1.3.2.0

DisplayTextInLocalMode JSON Bad field valu7516 Transfer amount Optional Data Version increment.| JSON Bad field valu7516 Transfer amount Optional Data Added JSON documentation JSON Bad field valu7516 Transfer amount Optional Data Version increment.| JSON Bad field valu7516 Transfer amount Optional Data


too long.

too long.

too long.

too long.

Page 6 of 43

3 Introduction BBS has developed BAXI to simplify integration of EFTPOS solutions to Windows-based point of sale (POS) applications. This implementation is based on the international OPOS standard. The interface is conforming to the existing Norwegian standard for integration of EFTPOS terminals. BAXI is a .NET dll. Supported environments: .NET 3.5 .NET micro 4.1 Mono (Linux) • • •

4 Procedures for using BAXI BAXI has four types of communication channels: Methods that can be called from the application to typically start a transaction Events that are sent from the terminal Properties containing information that can be read or written. Init file with configuration parameters • • • •

BAXI has two super states - bank mode and local mode. In bank mode, the terminal is in control. In local mode, the ECR is in control. Any method that puts the terminal in bank mode will always result in a local mode event. The local mode event usually indicates the final result of the operation.

4.1

Installation

The file baxi_dotnet.dll or baxi_dotnet_micro.dll must be placed in the same directory as the application executable.

4.2 1. 2. 3. 4.

4.3

General work flow Call a BAXI method. Wait for incoming events from BAXI. When an event gets triggered, act on the parameters of the event function. The OnLocalMode event signals a finished transaction.

Error situations

An error event normally occurs if a selected function cannot be performed. When BAXI has lost communication with the terminal during a transaction, the OnLocalMode event will be triggered, with the local mode result set to an unknown status. The status of the transaction must then be investigated! This can either be done manually, or new in version 1.3.0.1, via the ECR admin messages “Get Latest Financial Transaction Result” and “Get Latest Transaction Receipt”. These messages are documented in Chapter 5 and 6.


Page 7 of 43

4.4

USB rs232 support

BAXI.net supports monitoring of USB rs232 devices. This is to allow hot swapping USB payment terminals and that USB payment terminal reboots and still has contact with BAXI. USB rs232 support is always enabled, but its behaviour is controlled by the ComPort and DeviceString properties. PS!:

The Microsoft serial port implementation in the .net framework has a serious flaw with regards to USB rs232 ports disappearing. It is imperative that USB rs232 solutions use the Nets serial port driver. See the “SerialDriver” property for more details. ComPort: if this property is set to 0, this means that only DeviceString is used to dynamically find

and monitor a USB rs232 com port that matches the DeviceString. Multiple payment terminals on one machine is not supported. If ComPort is set to a number and DeviceString has a value, BAXI will first try this com port number. If it fails to open this com port, it will dynamically find any USB port based on the value in DeviceString. If DeviceString is not set, it will only use and monitor the port set in ComPort. DeviceString: this property matches the device friendly name that is part of the COM port name in

Windows’ Device Manager. For example, for the Ingenico Telium2 terminals, they are currently identified as DeviceString="SAGEM MONETEL USB Telium". This device friendly name can also be found in the registry under the USB enumerations, found under HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Enum/USB Under this key, all vendors have their own vendor and product ID. For Example, the Ingenico Telium 2 terminals are Vid_079b&Pid_0028. All entries will be under here and contain the following....

Use Friendly Name or DeviceDesc as identifier in baxi.ini and do not include the (COMXX) part. NETS Norway AS BAXI Application Programmers guide

Page 8 of 43

Below are the scenarios for USB support in baxi.ini described in detail. 1. ComPort set to X, DeviceString not set: BAXI will attempt to open Com X. If that fails, BAXI reports an error. If it succeeds, BAXI will only monitor inserts and removals of Com port X only. 2. ComPort set to X, DeviceString set: BAXI will first attempt to open Com X. If that fails, BAXI will dynamically try to find and open any com port that matches DeviceString. BAXI will monitor all com ports that match DeviceString for inserts/removals. 3. ComPort set to 0, DeviceString set: In this case, BAXI will skip straight to trying to find a com port dynamically, based on DeviceString. BAXI will monitor all com ports that match DeviceString for inserts/removals. Default is ComPort set to 0 and DeviceString set.


Page 9 of 43

5 BAXI Properties This list describes the properties that can be read /written in BAXI. Write properties (I/O = W) must be written before the method Open() is called. Any write property corresponding to a tag in the init file will override the init file tag value.

5.1

Read properties

These are available after a successful Open() dialogue. Name

Type

I/O

Description

Version

string

R

TerminalType

string

R

TerminalID

string

R

TerminalSwVersion

String

R

TerminalDeviceData _TLD MethodRejectInfo

byte[]

R

string

R

MethodRejectCode

int

R

This property is the BAXI version number. The format is a string of at least 35 in length containing a detailed version string for the BAXI component. This property is: First 2 bytes terminal type. Second 2 bytes Sofie protocol version. It can be read after a successful Open dialogue. This property is the terminal ID. It can be read after a successful Open dialogue. This is the Terminal software version, corresponding to the “ITU SW Version” tag 1005. This property contains TLD tag info retrieved from the terminal at start up. See Ref. 1 for details This property contains a string describing the reason why the last method call has returned 0 (rejected a request). This property contains a code describing the reason why the last method call has returned 0 (rejected a request). A list of method reject codes is available in Appendix A.

(old name Term_sw_version)

5.2

Write properties

These properties are also found in the baxi.ini file and can be both written to and read. All have default values in the baxi.ini file. Setting a property will override the corresponding entry in the baxi.ini file. If all entries in the baxi.ini file are set by properties, the baxi.ini file will be redundant and can be removed. Name

Typ e

I/O

Description

LogFilePrefix

strin g

R+W

A string which will be the prefix of the log file name. The log file name will end with the current date.

LogFilePath

strin g

R+W

The path to the wanted log directory.

TraceLevel

int

R+W

Accepted values are valid trace levels. Ex 2.


Page 10 of 43

Name

Typ e

I/O

Description

LogFilePrefix

strin g

R+W


LogFilePath

strin g

R+W

The path to the wanted log directory.

BaudRate

int

R+W

Accepted values are valid baudrates. Ex 9600.

ComPort

int

R+W

Accepted values are com ports ( 1 to 9). Ex 1.

HostPort

int

R+W

HostIpAddress

strin g

R+W

Accepted value is an int in the normal TCP/IP port number range (0 to 65536). Accepted value is a string containing an ip address, e.g. 192.168.1.1

MsgRouterOn

short R+W

Accepted values are 0 or 1. 0 means no Msg router used.

MsgRouterIpAddress

strin g

MsgRouterPort

short R+W

IndicateEotTransaction

int

R+W

This property sets the parameter “IpAddress” from the inifile. Accepted value is a string containing an ip address, e.g. 192.168.1.1 This property sets the parameter “Port” from the ini-file. Accepted value is an int in the normal TCP/IP port number range (0 to 65536). Accepted values are 0 or 1. 0 means no EOT indication.

CutterSupport

int

R+W

Accepted values are 0 or 1. 0 means no cutter support.

PrinterWidth

int

R+W

DisplayWidth

int

R+W

This property is in use only if the application prints the content of the PrintLine property. Default value is 60. In BAXI, assigning the value 0 to the PrinterWidth property makes the terminal do all the printing locally on the built in printer. Accepted values are 10 through 99.

VendorInfoExtended

strin g

R+W

R+W

This property contains four fields. Vendor Name, this will be a 3 letter description supplied from BBS to each vendor. Fixed length, 3 letters (A-Z). To receive a description contact [email protected] Vendor product/Application name. Vendor version/Application version. Tell ID, which should be used as a unique id for the POS, TVM, shop or similar that the terminal is installed in. To be able to identify where the terminal is installed is a demand in several markets, so the system supplier should be able to track the terminal based on this information. •

• • •

Rules: NETS Norway AS BAXI Application Programmers guide

Page 11 of 43

Name

Typ e

I/O

Description

LogFilePrefix

strin g

R+W


LogFilePath

strin g

R+W

The path to the wanted log directory. 1. Each field is terminated by the delimiter ”;”. The delimiter is mandatory. (Always 4 delimiters in string). 2. Maximum total length is 32 characters, including the delimiters. 3. All fields except VendorName have variable length and must be printable ASCII. Sample strings: 1. BBS;Retail;02.13.01;57807343803; 2. VIS;VBD/NAB;9.07;1234567890; 3. BBS;LightPos;2.0.0.3;;

PowerCycleCheck

int

R+W

TidSupervision

int

R+W

AutoGetCustomerInfo

int

R+W

Accepted values are 0 or 1. 1 means enabling of automatic Customer Info retrieval in the terminal. WARNING: This functionality is only supported on terminal versions 07.1X and higher. It must be turned off for older releases.

TerminalReady

int

R+W

Accepted values are 0 or 1. 1 means enabling of terminal ready signalling. WARNING: This functionality is only supported on terminal versions 07.1X and higher. It must be turned off for older releases.

UseDisplayTextID

Int

R+W

UseExtendedLocalMode

Int

R+W

Accepted values are 0 or 1. 1 means enabling usage of display text source identification and display text identification. See 7.2 for more details. Accepted values are 0 or 1. 1 means enable extended


Checks if the attached terminal has rebooted and if so, gives a warning and aborts the current transaction. The warning will be in the form of an OnDisplayText event and an OnPrintText event. Checks if the attached terminal has changed terminal id. Locks BAXI if TID mismatch! No transactions are allowed while BAXI is locked! A user trying to access a locked BAXI will receive an OnDisplayText event and an OnPrintText event with information about the locked state. To unlock BAXI, remove the file “terminalid.txt”, situated in the runtime executable directory.

Page 12 of 43

Name

Typ e

I/O

Description

LogFilePrefix

strin g

R+W


LogFilePath

strin g

R+W

The path to the wanted log directory. localmode. This means that the ECR will get new fields

SerialDriver

Strin g

R+W

in localMode. Current possible values are: Nets Microsoft The string is case sensitive. Default value if not set is “Microsoft”. For any implementation relying on USB to rs232 comms, be it directly through the Telium USB interface, or through a USB to rs232 adapter, it is imperative to use the Nets driver. This is because the Microsoft implementation has a flaw in discovering a removal of such a device/com port. An exception will be thrown which is impossible to catch in BAXI, resulting in the application having to handle it or crash/shut down. The Nets serialport implementation supports USB rs232 solutions, as described in 4.4 The string is case sensitive. See 4.4 for more details. • •

DeviceString

Strin g

R+W

UseSplitDisplayText

Int

R+W

LogAutoDeleteDays

Int

R+W

SocketListener

Int

R+W

SocketListenerPort

Int

R+W

Use2KBuffer

Int

R+W

DisplayTextInLocalMod e

Int

R+W


Accepted values are 0 or 1. 0 means to receive display text in single display text message towards ECR Accepted values are integer on how long we should save the Logging file in number of days. Accepted values are 0 or 1. 0 means don’t setup a tcp server. 1 means setup a TCP-server on open and listen on SocketListenerPort. This is the port number that the TCP-server will listen for Clients on. Accepted values are 0 or 1. 0 means that the terminal shall use the original 1Kbyte buffer. 1 means use that the terminal shall have increased buffer capacity of above 2Kbyte. Accepted values are 0 or 1. 1 means that the ECR system accepts display text in Local Mode

Page 13 of 43

 BAXI !et"ods All methods will return immediately with either 1 (success) or 0 (failure). The return value indicates if the BAXI component has accepted the request. A successful call that puts the terminal in bank mode will generate an OnLocalMode event and maybe other events as well. See Appendix B for common sequence diagrams. Methods that do not set the terminal in bank mode: SendTLD() TransferCardData() Close() • • •

The parameter operator ID has two different meanings: 1. Single TID terminal - identify the operator initiating a transaction. 2. Multi TID terminal - identify the logical terminal ID that shall be used in the transaction. Legal values 1-10. 1 is the master TID. If the parameter OperID is not used, it should be set to “0000”.

6.1

General note on paraeters.

Any method that expects parameters, will receive these in the form of an XYZArgs object. For example, to call TranferAmount, a TranferAmountArgs object must be filled out and passed as a parameter to the TransferAmount method.

6.2

!pen

PARAMETER: NONE RETURNS: 1 on success, local mode will follow 0 on failure, no local mode USAGE: 1. all O!en"#. $f O!en"# re%urns 0, c&ec' %&e Me%&odRe(ec%ode %o de%ermine %&e cause of %&e failure ). On success, wai% for On*ocalMode and OnError e+en%. . T&e resul% of On*ocalMode will de%ermine if %&e dialo-ue was successful or no%.

Initialises the control with the current values of the write properties and starts the communication with the terminal. This method generates a device attribute dialogue with the terminal. This method should be run at start up, after any write properties has been set.

6.3

"lose

PARAMETER: NONE RETURNS: 1 alwas "i% ne+er fails#, no local mode. USAGE:


Page 14 of 43

1. all lose"#. ). S&u% down ss%em if a!!lica/le.

This method performs shutdown of communication with the terminal. Synchronous, returns when operation completed. IMPORTANT: - This method shall be called prior to shutting down BAXI/ECR! Neglecting to call Close() before shut down will result in resources not being released!

6.4

#ransfer$ount

PARAMETER: TransferAmountArgs args RETURNS: 1 on success, local mode will follow 0 on failure, no local mode USAGE: 1. all TransferAmoun%"#. $f %&e func%ion re%urns 0, c&ec' %&e Me%&odRe(ec%ode %o de%ermine %&e cause of %&e failure. ). On success, wai% for Onis!laTe%, OnPrin%Te%, On*ocalMode and OnError e+en%s. Se+eral OnPrin%Te% e+en%s can occur durin- a %ransac%ion. . T&e resul% of On*ocalMode will de%ermine if %&e %ransac%ion was successful or no%.

TransferAmountArgs content:

operID: type1:

string See introduction.

int H30 = EFT Authorisation (KJØP) => Purchase amount H31 = Return of Goods (RETU) H32 = Reversal (ANNU) => Annulate last amount H33 = Purchase with Cash back (KONT) H34 = PRE Authorisation (GAR) H35 = Adjustment (OPPG) H36 = Balance Inquiry (DISP) H37 = Complete Receipt (KVIT) H38 = Deposit (INN) H39 = Cash Withdrawal (UT) H3A = Load e-purse card (LOAD) H3B = Merchandise Purchase H3C = Merchandise Reversal H3D = Merchandise Correction H40 = Force Offline H41 = Incremental PRE Authorisation H42 = Reversal PRE Authorisation => Partial and complete H43 = Sale Completion PRE Authorisation

amount1:

int Total amount.

type2:

int H30 = not in use


Page 15 of 43

amount2:

int Only used if = Purchase with Cashback (H33) – Total purchase amount.

type3:

int H30 = not in use H31 = not in use H32 = VAT (Value added tax) amount. The total tax amount supplied by the ECR.

amount3:

int VAT amount

hostdata:

string Variable field length, max 40 digits alfanumeric. The data is to be sent t o the HOST. The data characters must be in range H20 to H7F. This field is optional.

articleDetails:

string Variable field, alphanumeric data. Each record is separated with H1e, ASCII RS, A maximum of 3 records can be sent in one message, each separated with RS. The field is used to identify dedicated articles or reference to articles. This field is optional. ART # must be filled with article numbers in the purchase transaction ART # must be filled with references to the articles in a reversal transaction and correction transaction. This is application dependent, and must be clarified in each project. A Merchandise Reversal transaction and Merchandise Correction transaction can only include one article at a time.

paymentConditionCode: string Variable field length, max 3 alphanumeric char.

authCode:

string Authorisation Code field. Variable field length, max 6 characters. Lower and upper case is allowed. Special characters like ‘@#£¤%&’ are NOT allowed. This field is optional. The field is used for Force Offline transactions.

OptionalData :

6.5

Optional Data field. Variable field length, max 1024 ASCII characters. The context, contents and format of this field is specified and maintained by Nets Terminal IT. See ECR Chapter 13 Appendix C - Optional Data.

$dinistration

PARAMETER: AdministrationArgs args RETURNS: 1 on success, local mode will follow 0 on failure, no local mode USAGE: 1. all Adminis%ra%ion"#. $f %&e func%ion re%urns 0, c&ec' %&e Me%&odRe(ec%ode %o de%ermine %&e cause of %&e failure.


Page 16 of 43

). On success, wai% for Onis!laTe%, OnPrin%Te%, On*ocalMode and OnError e+en%s. Se+eral OnPrin%Te% e+en%s can occur durin- an adminis%ra%ion dialo-ue. . T&e resul% of On*ocalMode will de%ermine if %&e adminis%ra%i+e func%ion was successful or no%.

Starts one of the administration dialogues.

AdministrationArgs content:

admCode:

int 0x3030 = not used ........... 0x3039 = not used 0x3130 = RECONCILIATION function. 0x3131 = Empty terminal print buffer. 0x3132 = Cancellation request. The terminal has the choice to ignore the request. The OnLocalMode result will determine the final status of the transaction. 0x3134 = ANNUL from ECR should be mapped by ITU to perform REVERSAL transaction. 0x3135 = Balance Inquiry. 0x3136 = X-report. 0x3137 = Z-report. 0x3138 = Send Offline Transactions to HOST. 0x313A = Print of stored EOT transactions 0x313B=Finish current dialogue (behaves as Cancel, but silently). 0x313C = Print Latest Financial Transaction Receipt 0x313D = Send Latest Financial Transaction Result 0x313E = Start Software Download 0x313F = Start Dataset Download

operID:

string See introduction.

Messages 0x313C and 0x313D are used to find out the result the previous transaction. This will typically be used when an error or loss of communications occurs and the result of the transaction is unknown. By using these messages, one can find out if the ITU completed the transaction or not, so that a decision can be made to either attempt the transaction again or give the customer the proper receipt and goods. 0x313C gives the receipt copy as a printtext. 0x313D gives a Last Financial Transaction Result message (0x45) and its corresponding event in BAXI. See Ch. 8 for a common usage example and Ch. 6 for description of the Last Financial Transaction Result event.

6.6

#ransfer"ard%ata

PARAMETER: TransferCardDataArgs args RETURNS: 1 on success, no local mode 0 on failure, no local mode USAGE: 1. all TransferAmoun%"# %o do a de!osi%.


Page 17 of 43

). all Transferarda%a"#. $f %&e func%ion re%urns 0, c&ec' %&e Me%&odRe(ec%ode %o de%ermine %&e cause of %&e failure. . On success follow %&e !rocedure of a normal %ransac%ion.

This method sends the information in a magnetic card track to the Terminal. The terminal will act as if the card was swiped locally on the terminal. The function is targeted at the specific use case of depositing money on gift cards. It is not intended to be used to enable the ECR to pass customer card track contents to the terminal! Only track 2 content cards are supported. This message is only allowed when the terminal is in bank mode typically during a deposit. TransferCardDataArgs content:

trackType: int 0x32 = Origin track 2 0x40 = Origin Manually

trackData: string The track content.

6.&

Send#'%

PARAMETER:

SendTldArgs args

RETURNS: 1 on success, some%imes local mode, de!endin- on T* %a- ran-e 0 on failure, no local mode USAGE: 1. all SendT*"# %o !erfom a func%ion. $f %&e func%ion re%urns 0, c&ec' %&e Me%&odRe(ec%ode %o de%ermine %&e cause of %&e failure. ). On success and if %!eS%rin- is se% %o 2RE34, wai% for %&e res!onse in %&e OnT*Recei+ed e+en%.

This method is a general purpose method, used to trigger various functions. This function will set the protocol in bank mode, thus end the dialogue with a local mode message when using TLD tags in the groups “Card info” (range 2000) and “ECR info” (range 3000). Currently, the function does not set the protocol in bank mode for requests in the 1000 range.

SendTldArgs content: TldType:

string

Specifies the TLD tag type. Possible values are: “REQ” “CMD” • •

TldField:

byte[] (array of bytes) A TLD field built up as described in ref 1.

6.(

Get#'%#a)

PARAMETER:

byte[] wantedTldTag, byte[] tlduffer, byte[] wantedTldTag!alue

RETURNS: 1 on success, no local mode 0 on failure, no local mode


Page 18 of 43

USAGE: all Ge%T*Ta-"# %o re%rie+e a wan%ed %a- +alue from a T* /uffer.

This method is a helper function for parsing a TLD buffer. It is utilitarian in nature and does not use the EventArgs interface contract, like the other methods.

wantedTldTag The wanted TLD tag.

tldBuffer The TLD buffer in which to search.

wantedTldTagValue On success this byte buffer will hold the wanted tag value.

6.*

Send+son

PARAMETER:

Send"sonArgs args

RETURNS: 1 on success 0 on failure USAGE: all Send5son"# %o !erform a func%ion. $f %&e func%ion re%urns 0, c&ec' %&e Me%&odRe(ec%ode %o de%ermine %&e cause of %&e failure. On success 6ai% on %&e res!onse in %&e OnJsonReceived e+en%.

SendTldArgs content: !u/lic s%rin- 5sona%a7

6.1, BiB$dinistration PARAMETER: iAdministrationArgs args RETURNS: 1 on success, local mode will follow 0 on failure, no local mode USAGE:

Special custom function, see Ref [2]. Similar in usage to the Administration() method.

6.11 BiB#ransa-tion PARAMETER: iTransa#tionArgs args RETURNS: 1 on success, local mode will follow 0 on failure, no local mode USAGE:

Special custom function, see Ref [2]. Similar in usage to the TransferAmount method.


Page 19 of 43

# BAXI $vents &.1

General note on eents

All event delegates that contain data, will give this data in EventArgs objects. For example, the OnDisplayText event, will give a DisplayTextEventArgs object that contains the display text string and any other pertinent fields as well. Remark! The event is fired from an internal thread in baxi. The ECR client code is therefore executed from the baxi thread. It is important to release the event handler as fast as possible to let the thread go back and wait for more events. We recommend that the ECR programmer just create a new event and send the information to an internal thread of the ECR app.

&.2

!n%ispla/#e0t

$ubli# delegate %oid Dis$layTe&tE%ent'andler(ob)e#t sender, Dis$layTe&tE%entArgs e*+

DisplayTextEventArgs contents:

DisplayText :

DisplayTextSourceID:

DisplayTextID:

&.3

string A display text has been received from the terminal. Max length is 80 characters. int The source that generated the display text. See 5.2 UseDisplayTextID. int The unique identifier of a display text. Mostly intended for unattended solutions. See 5.2 UseDisplayTextID.

!nrinter#e0t

$ubli# delegate %oid PrintTe&tE%ent'andler(ob)e#t sender, PrintTe&tE%entArgs args*+

PrintTextEventArgs content:

PrintText: string This is the printer text (the receipt) formatted in lines with a maximum line length of 24 characters. Several print text messages could come during a transaction. Separators: 0xA = Separator line feed. Will be used throughout the printText string to allow correct formatting of the receipts. •


Page 20 of 43

•

•

&.4

0xC = Separator end of text. Will be used at the very end of every string to indicate the end of text. 0xE = Separator cutter(optional). Can appear if the property CutterSuppor t is set. Can be used anywhere in the printText string to indicate a request to cut the receipt.

!n'o-alode

$ubli# delegate %oid o#alModeE%ent'andler(ob)e#t sender, o#alModeE%entArgs args*+

Signals the application that a financial or administrative transaction is completed. LocalModeEventArgs content:

LocalModeResultData : string This parameter contains the complete local mode reply from the terminal in raw format.

Result: int This is the result of the transaction: 0 : Financial transaction OK, accumulator updated 1 : Administrative transaction OK, no update of accumulator 2 : Transaction rejected, no update of accumulator 3 : Transaction is Loyalty Transaction 99 : Unknown result. Lost communication with terminal. Baxi has generated this local mode.

AccumulatorUpdate: int H20 = indicates standard update of accumulator. H21 = Not used in current software in the ITU. H22 = indicates transaction is finalised as Offline transaction. H23 .. H2F = Reserved for future use. The ECR shall finalise the transaction as OK. Accumulator type is uncertain for the time being. H30 = indicates no update of accumulator.

IssuerId: int This is the card issuer ID.

TruncatedPan : string This parameter contains card information. The format is the card number with length up to 19 digits.

Timestamp: string This parameter contains the timestamp of the transaction. The format is YYYYMMDDHHMMSS

VerificationMethod: int This is a code for cardholder verification method (CVM). The codes are: 0: Transaction is PIN based (default) NETS Norway AS BAXI Application Programmers guide

Page 21 of 43

1: Transaction is signature based 2: No CVM. With or without amount confirmation by cardholder. 3: Transaction is Loyalty Transaction For the code 3, local mode result will always be 3.

TotalAmount: int Used in: Restaurant or Hotel environment where TIP is added to the purchase amount on the ITU. Used in the Purchase or Adjustment transaction. Transactions with surcharge. This total amount will contain the sum of the original amount plus the surcharge amount. •

•

SessionNumber : string This parameter contains the session number of the transaction (3 bytes numeric data). This number is global for a site and gets incremented after a reconciliation.

StanAuth : string This parameter contains the transaction reference number. The length is 12 characters

SequenceNumber: string 4 bytes numeric data (H30 .. H39). This is the customer number if the transaction was PreAuth transaction. Must be used as reference in Transfer Amount - Adjustment transaction.

TotalAmount: int This parameter is the Total ITU transaction amount used in Restaurant or Hotel environment where TIP is added to the purchase amount on the ITU. It’s also used if a surcharge fee is added to the purchase amount on the ITU.

RejectionSource: in This parameter indicates the source for the rejection. Fixed length, 2 characters. This field is optional. Rejection sources will be added as they are needed. If a rejection source is present, there will always also be a rejection reason present.

RejectionReason: string This parameter indicates the reason for a rejection. Variable length, maximum 20 characters. This field is optional. Rejection reasons will be added as they are needed. If a rejection reason field is present, there will always also be a rejection source present.

TipAmount: int This parameter is used in Restaurant or Hotel environment where TIP is added to the purchase amount on the ITU.

SurchargeAmount: int This parameter is used if surcharge fee is added to the purchase amount on the ITU.

TerminalID: string This parameter is the terminal ID.

AcquirerMerchantID: string This parameter is the Site ID. NETS Norway AS BAXI Application Programmers guide

Page 22 of 43

CardIssuerName: string This parameter will be ApplicationLabel in case of chip cards

ResponseCode: string This parameter will contain PSP response codes in case of online approved transactions & Y codes from terminal for offline approved transaction.

TCC: string This parameter is Transaction Condition Code.3 byte alphanumeric data. Each byte indicates as following: TCC [0] = Card Data Entry Method TCC [1] = CVM Method TCC [2] = Authorization Method

AID: string This parameter is Chip Card Application Identifier

TVR: string This parameter is Chip Card Terminal Verification Result

TSI: string This parameter is Chip Card Terminal Status Information

ATC: string This parameter is Chip Card Application Transaction Counter

AED: string This parameter is Chip Card Application Effective Data

IAC: string This parameter is Chip Card Issuer Action Code OptionalData: String Variable field length, max 1024 ASCII characters. The context, contents and format of this field is specified and maintained by Nets Terminal IT. See ECR Chapter 13 Appendix C - Optional Data.

&.5

!nError

$ubli# delegate %oid a&iErrorE%ent'andler(ob)e#t sender, a&iErrorE%entArgs args*+

OnError signals to the application that an error has occurred. BaxiErrorEventArgs contents:

ErrorCode : int A list of error codes is available in Appendix A. NETS Norway AS BAXI Application Programmers guide

Page 23 of 43

ErrorString : string A short textual description of the error.

&.6

!n#'%Re-eied

$ubli# delegate %oid TDRe#ei%ed'andler(ob)e#t sender, TDRe#ei%edArgs args*+

This event receive a TLD tag data string from the terminal. See r ef 1 for details. TLDReceivedArgs contents:

TldType : string Specifies the TLD tag type. Possible values are: “RESP” “STATUS” “INFO” • • •

TldData : byte[] (array of bytes) A TLD field

&.&

!n+sonRe-eied

$ubli# delegate

%oid -n"sonRe#ei%ed(ob)e#t sender, "sonRe#ei%edArgs args*+

This event receive a Json tag data string from the terminal. See ref. JsonReceivedArgs contents:

JsonString: string

&.(

!nStdRsp

$ubli# delegate %oid StdRs$Re#ei%ed'andler(ob)e#t sender, StdRs$Re#ei%edArgs args*+

This is an optional special purpose event. It triggers each time the terminal sends a response frame to BAXI. A user wanting to make quick consecutive calls to BAXI can use this event to find out when BAXI has finished processing the last call. Example of use: 1. TransferAmount(); 2. Wait for OnStdRsp() event. 3. SendTLD(); StdRspReceivedArgs contents:

Response: string The response code from the terminal. Always “00” per today. NETS Norway AS BAXI Application Programmers guide

Page 24 of 43

&.*

!n#erinalRead/

$ubli# delegate %oid TerminalReadyE%ent'andler(ob)e#t sender, TerminalReadyE%entArgs args*+

WARNING: This functionality is only supported on terminal versions 07.1X and higher. It must

be turned off for older releases. This is an optional special purpose event. It triggers each time the terminal determines that it has completed terminal management. Typically, this will occur as the terminal goes into idle after an activity, like a purchase. After this event has triggered, the terminal should always be ready to handle a new function, such as TransferAmount. One other use is for performing a Close-Open sequence without disrupting terminal communication towards host, such as swapping between two instances of BAXI. TerminalReadyEventArgs contents: There is no content so far for this EventArgs object.

&.1, !n'astinan-ialResult Public delegate void LastFinancialResultEventHandler( object sender LastFinancialResultEvent!rgs args"# This is a special purpose event. It is sent by the ITU when the ECR invokes the message Admin(SendLatestFinancialResult(0x313D)). The contents are identical to the contents of a Local Mode message, but it contains the results of the last/latest financial operation. This data can be used to determine what happened to a transaction in case of communications errors or other causes of a loss of transaction result.


Page 25 of 43

% Ba&i.ini file The baxi.ini file can be used to set up the environment for BAXI. It should be placed in the same directory as the application executable running BAXI. All the tag entries can also be set via properties. If there is a conflict between a tag entry and a property, the property always overrides the init- file. If all the init-file tag entries are set by properties, baxi.ini is redundant and can be removed altogether. The baxi.ini file entries maps 1-1 to the writable properties. See corresponding write property for details!


Page 26 of 43

' (ommon )se (ases Here follows a list of example usage of the current transaction types. Basic functions that should always be integrated in a POS application are: Purchase Purchase with cash withdrawal Reversal Return of goods Reconciliation It is important to implement reversal because it will be necessary to cancel a transaction if signature control fails or a similar situation. • • • • •

US = 0x1F RS = 0x1E

*.1

#ransa-tions

'.1.1 Purc"ase Normal purchase transaction request (10.00 kr) : Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/0,# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# a!rticle*etails & +-# aPay%ent2ondition2ode & +-# a!ut32ode & +-# int result & 4a/iTrans$er!%ount(a"#

Normal purchase transaction request (10.00 kr) with VAT (3 kr): Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/0,# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/01# a!%ount0 & 0,,# aHost*ata & +-# a!rticle*etails & +-# aPay%ent2ondition2ode & +-# a!ut32ode & +-# NETS Norway AS BAXI Application Programmers guide

Page 27 of 43

int result & 4a/iTrans$er!%ount(a"#

Normal purchase transaction request (10.00 kr) with loyalty info (“abcdefg”): Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/0,# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +abcde$g-# a!rticle*etails & +-# aPay%ent2ondition2ode & +-# a!ut32ode & +-# int result & 4a/iTrans$er!%ount(a"#

Normal purchase transaction request (10.00 kr) with payment condition code “2”: Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/0,# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# a!rticle*etails & +-# aPay%ent2ondition2ode & +1-# a!ut32ode & +-# int result & 4a/iTrans$er!%ount(a"#

'.1.2 Return of goods Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/0.# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# a!rticle*etails & +-# aPay%ent2ondition2ode & +-# NETS Norway AS BAXI Application Programmers guide

Page 28 of 43

a!ut32ode & +-# int result & 4a/iTrans$er!%ount(a"#

'.1.3 Reversal Reversal of the last transaction (10 kr). Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/01# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# a!rticle*etails & +-# aPay%ent2ondition2ode & +-# a!ut32ode & +-# int result & 4a/iTrans$er!%ount(a"#

'.1.4 Purc"ase *it" (as"+ac,

Purchase transaction request (10.00 kr) with cash back (2 kr) : Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/00# a!%ount. & .1,,# aType1 & ,/0,# a!%ount1 & .,,,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# a!rticle*etails & +-# aPay%ent2ondition2ode & +-# a!ut32ode & +-# int result & 4a/iTrans$er!%ount(a"#

'.1.5 Balance in-uir Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/05# a!%ount. & ,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# NETS Norway AS BAXI Application Programmers guide

Page 29 of 43

a!rticle*etails & +-# aPay%ent2ondition2ode & +-# a!ut32ode & +-# int result & 4a/iTrans$er!%ount(a"#

'.1. /eposit Can be used for example to deposit money on gift cards. Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/06# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# a!rticle*etails & +-# aPay%ent2ondition2ode & +-# a!ut32ode & +-# int result & 4a/iTrans$er!%ount(a"#

'.1.# (as" *it"dra*al Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/07# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# a!rticle*etails & +-# aPay%ent2ondition2ode & +-# a!ut32ode & +-# int result & 4a/iTrans$er!%ount(a"#

'.1.% 0orce ffline

Force an offline purchase of amount 1000 with authcode of ‘ABC’. Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/8,# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# NETS Norway AS BAXI Application Programmers guide

Page 30 of 43

a!rticle*etails & +-# aPay%ent2ondition2ode & +-# a!ut32ode & +!42-# int result & 4a/iTrans$er!%ount(a"#

*.2

#opUp

These are typically used to load a mobile phone with more call time. See ref 1 for details. The EAN number of the transaction is specified in the articleDetails parameter. Buy a NetCom 150 TopUp code: Trans$er!%ount!rgs a & ne' Trans$er!%ount!rgs("# aOper)* & +,,,,-# aType. & ,/04# a!%ount. & .,,,# aType1 & ,/0,# a!%ount1 & ,# aType0 & ,/0,# a!%ount0 & ,# aHost*ata & +-# a!rticle*etails & +,9,1.78,,,16.,-  ;
Receive the topup code from the OnTLDReceived event, TLDReceivedArgs contents: RS = “\x1e”, US = “\x1f” TldType : “INFO” Tld*ata: ./0012

3 4S 3 .000552 3 4S 3 .060789/0007802 3 4S 3 .00000000;;2 3 4S 3 .68/5/86/16/882 3 4S 3 .000000/755< 9/<692 3 4S 3 .00810002 3 RS

*.3

Gift "ard

Gift card is implemented as a two transaction solution. 1. First do a normal purchase with the customer card. 2. Do a deposit with the same amount as the customer purchase. 3. Send the track 2 content of the giftcard with the TransferCardData() function. The terminal will finish the deposit on the gift card.

*.4

Group I%

Group ID is a function used to separate cards within the same range based on values returned from the card. This functionality is currently only supported by BBS cards. This functionality is used in situations where you want to give different prices to customers with the same type of prepaid BBS cards, typically in canteens used by more than one company, where employees from the different companies gets different prices.


Page 31 of 43

To retreive the Group ID use the following sequence: Call the function SendTLD() specifying a Group ID request:

SendTld!rgs a & ne' SendTld!rgs("# aTldType & +RE>-# aTldField & +0,,,-# 4a/iSendTL*(a"# Get the group ID from the OnTLDReceived event, TLDReceivedArgs contents: TldType : “RESP” TldData : .;0002 3

*.5

4S 3 .00012 3 4S 3 .87;/12 3 RS

Get en-r/pted -ard data

Call the function SendTLD() specifying a request encrypted card data:

SendTld!rgs a & ne' SendTld!rgs("# aTldType & +RE>-# aTldField & +0,,9-# 4a/iSendTL*(a"# Read the encrypted card data in the OnTLDReceived event, TLDReceivedArgs contents: TldType : “RESP” TldData : .;0062 3

*.6

4S 3 .00812 3 4S 3 .0000000000000002 3 RS

Get en-r/pted -ard data and issuer I%

Call the function SendTLD() specifying a request encrypted card data and issuer:

SendTld!rgs a & ne' SendTld!rgs("# aTldType & +RE>-# aTldField & +0,,6-# 4a/iSendTL*(a"# Read the encrypted card data in the OnTLDReceived response, TLDReceivedArgs contents: TldType : “RESP” TldData : “;002 3

*.&

4S 3 .00812 3 4S 3 .0000000000000002 3 RS

Send a tra-k 2 -ard swipe to te terinal

Trans$er2ard*ata!rgs a & ne' Trans$er2ard*ata!rg("# aTrac?Type & ,/01# aTrac?*ata & [email protected].,,,,,,,,,105-# 4a/iTrans$er2ard*ata(a"# NETS Norway AS BAXI Application Programmers guide

Page 32 of 43

*.(

#I

To be able to use tip, the service has to be enabled for the terminal. This can be ordered from your dealer. If the amount received in the amount field in the Local Mode message from the terminal is larger than the amount sent to the terminal in the Transfer Amount message, the difference should be treated as tip.

*.*

"e-k ost -onne-tion

Call the function SendTLD() specifying a request for host connection status:

SendTld!rgs a & ne' SendTld!rgs("# aTldType & +RE>-# aTldField & +.,.1-# 4a/iSendTL*(a"# Read the host connect status in the OnTLDReceived response, TLDReceivedArgs contents: Ex connected to host: TldType : “RESP” TldData : .80872 3

4S 3 200082 3 4S 3 202 3 RS

*.1, Set terinal lan)ua)e Call the function SendTLD() specifying setting terminal language. E& Englis=:

SendTld!rgs a & ne' SendTld!rgs("# aTldType & +2A*-# aTldField & +.,.8-  BS  +,,,1-  BS  +en-  RS# 4a/iSendTL*(a"#

*.11 Re-eie a -ard inserted status eent The terminal can be set to send events when a card is inserted or removed. Read the status in the OnTLDReceived function. Ex card inserted: TldType : “STATUS” TldData : .808;2 3 4S

3 200082 3 4S 3 282 3 RS

*.12 Get "ustoer Info7


Page 33 of 43

WARNING: This functionality is only supported on terminal versions

07.1X and higher. It must be turned off for older releases. The generic TLD format is defined in [1]. The ECR invokes the Get Customer Info by sending a TLD request with the following tags in the given order:

+1,,,-  BS  -,,,0-  BS  -,,.-  RS  +1,,1-  BS  -,,,0-  BS  -,,.-  RS  +1,,.-  BS  -,,,,-  BS  RS The tags must be in the order above for the request to work. The ITU typically returns the customer information from the above request in the following manner:

+1,,,+1,,1+1,,.+1,,0-

 BS  BS  BS  BS

 +,,,0-  BS  +,,.-  RS   +,,,0-  BS  +,,.-  RS   +,,01-  BS  +,,7695@8  +,,,1-  BS  +,,-  RS

+  RS 

When the ITU sends a TLD Status “Card inserted with Issuer ID” message, it typically contains the following (for a BankAxept card, issuer 30):

+.,.0-  BS  +,,,.-  BS  +.-  RS  +0,,1-  BS  +,,.,-  BS  +,,,,,,,,0,-  RS To receive the issuer ID tag in the card stat us message, the parameter for sending issuer ID with card status must be enabled in the ITU. There are 2 normal use cases for the Customer Info functionality. . T3e E2R al'ays initiates a Cet2usto%er)n$o be$ore t3e purc3ase (!uto%atic retrieval o$ 2usto%er )n$o is turned on in t3e )TB" )t is t3en t3e )TB '3ic3 decides i$ t3ere s3ould be a reDuest to t3e 3ost based on )ssuer )* and ter%inal conguration 1 T3e E2R receives +card inserted 'it3 issuer )*- $ro% t3e )TB and based on issuer )* elects to initiate a custo%er in$o reDuest or not

Below are these 2 use cases described in detail. The data within the messages will typically be as described above. 1. ECR initiates GetCustomerInfo.

The parameter for sending card status messages should be disabled for this scenario. This is because it is not needed by the ECR and it can also increase the risk of collisions and retransmissions. !uto%atic custo%er in$o retrieval is enabled SeDuence: T3e E2R 'ill al'ays initiate a transaction 'it3 a Cet2usto%er)n$o reDuest to t3e )TB t3roug3 a TL* ReDuest T3e ter%inal goes into 4an? Aode T3e ter%inal 'ill eit3er as? $or a card or start processing i$ a card is already inserted or s'iped

•

• •


Page 34 of 43

•

•

•

T3e ter%inal 'ill return t3e 2usto%er )n$o to E2R t3roug3 a TL* Response and re%ains in ban? %ode )t is a'aiting a Trans$er!%ount transaction T3e E2R processes t3e 2usto%er )n$o and initiates a transaction )t is also possible to send an !d%in 2ancel (or !d%in nis3 see belo'" at t3is stage i$ t3e E2R is not interested in any additional actions ot3er t3an t3e custo%er in$o data T3e )TB 'ill co%plete any transaction or cancellation 'it3 a Local Aode %essage

2. ECR reacts to Card Inserted

Automatic customer info retrieval is disabled. “Card status messages with Issuer ID” is enabled in the ITU. Sequence: •

•

• • •

• •

•

T3e )TB 'ill send a TL* Status %essage 'it3 +2ard inserted and )ssuer )*- to t3e E2R '3en t3e custo%er inserts or s'ipes a card in t3e )TB E2R processes t3e )ssuer )* and decides i$ it s3ould send a Cet 2usto%er )n$o reDuest or not E2R sends a 2usto%er )n$o TL* ReDuest T3e )TB goes into 4an? Aode T3e )TB reDuests t3e custo%er in$o $ro% t3e 3ost and sends a TL* Response 'it3 2usto%er )n$o to t3e E2R T3e )TB t3en a'aits $urt3er action $ro% t3e E2R and re%ains in 4an? Aode T3e E2R processes t3e 2usto%er )n$o and nor%ally sends a Trans$er!%ount %essage to t3e )TB T3e )TB 'ill 3andle t3e transaction li?e nor%al and co%plete it 'it3 a Local Aode %essage

*.13 Get "ustoer Info7 wit $din inis. For the “Get Customer Info” dialogues or any other TLD request dialogue, the terminal can remain in Bank Mode and expect a final transaction to take place. There are occurrences where such a transaction will not take place and the ECR wishes to force the Terminal out of bank mode and back to idle. This effectively completes the operation/dialogue and makes the terminal ready for a new operation/dialogue. This has been achieved with Admin Cancel in the past. This has the unwanted behaviour of the terminal aborting the transaction in full, including display texts and showing “Cancelled by operator” in its display etc. The Admin Finish command is an alternative to Admin Cancel in these cases, where it is better for the terminal to silently abort and revert to Local Mode and showing an idle screen.

*.14 Inesti)atin) results of last finan-ial transa-tion. If an error occurs in the middle of a transaction, BAXI will return an error and a local mode result of “Unknown”. If such an error or other errors make the result of a transaction unavailable or incomplete, one can use the Administration functions “Print Latest Financial Transaction Receipt” and “Send Latest Financial Transaction Result” to fetch the result from the ITU. This is a NETS Norway AS BAXI Application Programmers guide

Page 35 of 43

complement to the manual routines to provide an integrated solution for this problem for ECR vendors. Let us assume that a transaction is unknown. To retrieve all necessary information, the ECR will have to perform the following:

int result & 4a/i!d%inistration(ne' !d%inistration!rgs(,/0.02 +,,,,-""# This results in a PrintText event, which will contain a copy receipt of the latest financial transaction result. This is identical to entering the ITU menu and manually print out the copy receipt. After the Local mode is received (administration is done), the ECR can send the next administration message to get the Latest Financial transaction result, which contains the Local mode data from the last financial transaction.

int result & 4a/i!d%inistration(ne' !d%inistration!rgs(,/0.0* +,,,,-""# This results in a LastFinancialTransactionResult event, which contains the local mode identical data from the last financial transaction. The administration operation is then completed with a local mode message.


Page 36 of 43

Best practice implementation of securit in t"e $(R interface. These are recommendations concerning some of the security functions offered with Baxi and BBS terminals. Recommended practice is to implement all functions with high security. These recommendations are based on experienced skimming practices which mainly have been: . S?i%%ing eDuip%ent is %ounted on t3e ter%inal '3en t3e s3op is closed 1 T3e s3ops ter%inal is replaced 'it3 a ter%inal 'it3 s?i%%ing eDuip%ent %ounted

Powercyclecheck is designed to counter scenario 1, while the other functions are designed to counter scenario 2.

Function

Low security

Medium security

High security

VendorInfo extendended.

Identification of pos application supplier in the vendorinfoextended string

Identification of pos application supplier and Identification of sit e in the vendorinfoextended string

Identification of pos application supplier and unique Identification of POS in the vendorinfoextended string

Turned off

Turned on

Action demanded from the POS operator on the OnDisplayText generated

Turned off

Turned on

Data reported by ECR to terminal. Readable by BBS. Powercyclecheck

Checks when the terminal has been tuned on and off. Tidcheck

Checks if the TID (TermianlD) of the terminal has changed . Serial number check

Checks if the physical serialnumber of the terminal has changed.

Turned off in Baxi.ini, but implemented tid check in the POS application with action required from the pos operator on tid change, Preferable with operator authentication. No serial number check. Implement serial number Implement serial number check in the POS check in the POS application application with action with action required from required from the pos the pos operator on serial operator on serial number change with number. operator authentication.


Page 37 of 43

1/eprecated 0unctions These functions will be supported for backwards compatibility.

11Removed 0unctions These functions have been removed entirely and are no longer supported

11.1 #ransfer$ount892 Replaced by TransferAmount_V4. Same as TransferAmount_V4 but without the parameter PaymentCardCondition and AuthCode.

11.2 #ransfer$ount893 Replaced by TransferAmount_V4. Same as TransferAmount_V4 but without the parameter AuthCode.

11.3 #ransfer$ount894 11.4 $dinistration: int ad"ode; strin) !perId< Replaced by the new Args type interface Administration(AdministrationArgs args).

11.5 Send#'%: strin) t/peStrin); =/te>? tldield< Replaced by the new Args type interface SendTLD(SendTldArgs args).

11.6 #ransfer"ard%ata: int tra-k#/pe; strin) tra-k%ata< Replaced by the new Args type interface TransferCardData(TransferCardDataArgs args).

11.& BiB$dinistration: int $d"ode; strin) !perI%< Replaced by the new Args type interface BiBAdministration( BiBAdministrationArgs args).

11.( BiB#ransa-tion: int aount; strin) transa-tion%ata< Replaced by the new Args type interface BiBTransaction( BiBTransactionArgs args).


Page 38 of 43

12Appendices 12.1 $ppendi0 $ @ Status -odes 12.1.1$rror codes $rror code 2011 6006 7001 $rror code 2100 2101 2102 210% 210' 210( 2106

/escription Error when sending message Baxi locked Unknown Error !sgRouter errors MsgRo!er Error Range s!ar!s wi!h 2100" !his code is no! sed# $eneral msgro!er error Msgro!er !imeo! &ocke! error Message leng!h error &ending o) message )ailed *onnec!ion error

700( 7007 700/ 700 7010 7011 7012 701% 701(

+,en reec!ed +.sole!e !erminal version o hos! con!ac!# o res,onse )rom !erminal *rea!e log direc!or )ail +,en 3+ )ail Unex,ec!ed )rame *lose reec!ed Unknown !erminal )rame

12.1.2!et"od reect codes !et"od Reect code

/escription

eneral cases 7100 7101 7102 710% 710'

4rocessing ,revios command Una.le !o ,rocess Alread +,en o! Ac!ive 5erminal .s" adminis!ra!ion

Propert +ad values 7'01 7'02 7'0% 7'0' 7'0( 7'06 7'07 7'0/ 7'0 7'10

og )ile ,re)ix og )ile ,a!h os! 34 address Vendor in)o ex!ended 5race level Bad ra!e *+M ,or! os! ,or! 3ndica!e E+5 !ransac!ions *!!er s,,or!


Page 39 of 43

!et"od Reect code 7'11 7'12 7'1% 7'1' 7'1( 7'16 7'20 7'21 7'22 7'2% 7'2' 7'2( 9815 9819

/escription 4rin!er wid!h 8is,la wid!h 4ower ccle check 538 s,ervision A!o ge! cs!omer in)o 8evice&!ring 5erminal read Use8is,la5ex!38 UseEx!endedocalMode MsgRo!er3,Address MsgRo!er+n MsgRo!er4or! 8oo!&,li!8is,la5ex! 8is,la5ex!3nM

0unction argument +ad values 7(01 7(02 7(0% 7(0' 7(0( 7(06 7(07 7(0/ 7(0 7(10 7(11 7(12 7(1% 7(1' 7(1( 7(16

+nl !rack 2 s,,or! 3nvalid !rack leng!h 5rans)er amon! invalid !,e 5rans)er amon! da!a !oo long 5rans)er amon! ar!icle de!ails !oo long 3nvalid o,era!or 38 3nvalid adminis!ra!ion code 58 nknown !,e 58 .ad )ield vale 58 cold no! .ild 5rans)er amon! 4** !oo long 5rans)er amon! 4** no! al,hanmeric 5rans)er amon! A!h*ode !oo long# 5rans)er amon! A!h*ode no! al,hanmeric# 9&+ Bad )ield vale 5rans)er amon! +,!ional 8a!a !oo long#


Page 40 of 43

12.2 $ppendi0 B @ SeAuen-e dia)ras 12.2.1Initialisation

12.2.2uccessful purc"ase


Page 41 of 43

12.2.3)nsuccessful purc"ase


Page 42 of 43

BAXI

Recommend Documents