BAXI

BAXI.
net Application Programmers

guide
Version 1.3.2.0
Revision - A
Date: 2014-01-16
Preparedby:
Updatedby:
Targetgroup:
NETSNorwayAS
BAXIApplicationProgrammersguide
PerRdstrm
ECRvendors,terminalvendorsandother
partiesinfluencedbythisspecification.
Page1of43
References..........................................................................4
Revision Record...................................................................4
Introduction........................................................................6
Procedures for using BAXI....................................................6

4.1
Installation.............................................................................6
4.2
General work flow...................................................................6
4.3
Error situations.......................................................................6
4.4
USB rs232 support..................................................................6
BAXI Properties......................................................................... 9
4.5
Read properties......................................................................9
4.6
Write properties......................................................................9
BAXI Methods....................................................................13
5.1
General note on parameters..................................................13
5.2
Open.....................................................................................13
5.3
Close....................................................................................13
5.4
TransferAmount....................................................................14
5.5
Administration......................................................................15
5.6
TransferCardData..................................................................16
5.7
SendTLD...............................................................................17
5.8
GetTLDTag............................................................................17
5.9
BiBAdministration.................................................................17
5.10 BiBTransaction......................................................................18
BAXI Events.......................................................................19
6.1
General note on events..........................................................19
6.2
OnDisplayText.......................................................................19
6.3
OnPrinterText........................................................................19
6.4
OnLocalMode........................................................................20
6.5
OnError.................................................................................22
6.6
OnTLDReceived.....................................................................22
6.7
OnStdRsp..............................................................................23
6.8
OnTerminalReady..................................................................23
6.9
OnLastFinancialResult...........................................................23
Baxi.ini file........................................................................25
Common Use Cases............................................................26
NETSNorwayAS
Page2of43
8.1
Transactions..........................................................................26
8.2
TopUp...................................................................................30
8.3
Gift Card...............................................................................30
8.4
Group ID...............................................................................30
8.5
Get encrypted card data........................................................31
8.6
Get encrypted card data and issuer ID....................................31
8.7
Send a track 2 card swipe to the terminal:..............................31
8.8
TIP........................................................................................32
8.9
Check host connection...........................................................32
8.10 Set terminal language...........................................................32

8.11 Receive a card inserted status event......................................32
8.12 Get Customer Info..............................................................32
8.13 Get Customer Info with Admin Finish..................................34
8.14 Investigating results of last financial transaction....................34
Best practice implementation of security in the ECR interface.. .36

9
Deprecated Functions.........................................................37
10 Removed Functions............................................................37
10.1 TransferAmount_V2...............................................................37
10.4 Administration( int admCode, string OperId)..........................37
10.5 SendTLD( string typeString, byte[] tldField)...........................37
10.6 TransferCardData( int trackType, string trackData).................37
10.7 BiBAdministration( int AdmCode, string OperID).....................37
10.8 BiBTransaction( int amount, string transactionData)...............37
11 Appendices........................................................................38
11.1 Appendix A Status codes.....................................................38
11.2 Appendix B Sequence diagrams...........................................40
NETSNorwayAS
Page3of43
1 References
1. NetsproprietaryTLD(TypeLengthData)formatdescription
2. BiBOpos
2 Revision Record
DATE
20101222
20110114
20110119
20110223
20110224
20110308
20110309
20110311
20110316
20110321
20110322
20110401
VER.
1.0.0.16
1.0.0.17
1.0.2.0
1.0.2.1
1.0.2.2
1.0.2.3
1.0.2.4
1.0.2.5
1.0.2.6
1.0.2.7
1.0.2.8
1.0.2.9
20110412
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.2011
1.2.0.5
1.2.0.6
NETSNorwayAS
COMMENTS
Versionsteponly.
Versionincrementonly.
Versionincrementonly.Seereleasenotesformoredetails.
Addederrorcode7104.
Versionincrementonly.Seereleasenotesformoredetails.
USBmonitoring/support,addedchapter4.4
Versionsteponly.
ForceOffline
Versionsteponly
Versionsteponly.
Versionsteponly.
Versionstep.Addedrevisiontoenabledocumentationchangeswhen
BAXIversionnumbershouldnotchange.
Versionsteponly.
Internalreleaseonly
Versionsteponly.
Newinterface.Thisinvolvesrefactoringexistingimplementations.Itis
especiallyimportantforCOMclientstorebuildtheirinterfacefiles.
Upgradedtosupport.netmicroframeworkversion4.1.
Versionsteponly.
AddedExtendedLcalModeDocumenation:
TotalAmount,
RejectionSource,
RejectionReason,
TipAmount,
SurchargeAmount,
TerminalID,
AcquirerMerchantID,
CardIssuerName,
ResponseCode,
TCC,
AID,
TVR,
TSI,
ATC,
AED,
IAC
Page4of43
DATE
18.07.2011
VER.
1.2.0.7
11.08.11
06.09.2011
16.09.11
03.10.2011
17.10.2011
21.10.2011
02/12/2011
1.2.0.7B
1.2.0.8
1.2.0.9
1.2.1.0
1.2.1.1
1.2.1.1B
1.3.0.1
24/01/2012
1.3.0.2
16/02/2012
17.02.2012
22.03.2012
24.09.2012
15.10.12
18.12.12
14.01.12
20130426
20130515
1.3.0.3
1.3.0.4
1.3.0.5
1.3.0.6
1.3.0.7
1.3.0.7C
1.3.0.8A
1.3.0.9
1.3.1.0
COMMENTS
Addedrejectionerrorcodesfornew
properties:
UseDisplayTextID
UseExtendedLocalMode
AddedAministrationFinish.
Versionsteponly.
AddednewpropertySerialDriver.Seepropertieschapterformoredetail.
Versionsteponly.
Versionsteponly.
AddedpropertyDeviceStringtodocument.
Addednewadminmessagesforlasttransctionreceiptandresult,aswellas
thelasttransactionresultmessage.
AddednewTLDfields:TCC,BankAgent
AddednewfieldsinextendedLocalMode:
AccountType,EncryptedPAN,BankAgent,organisationNumber.
AddedDoNotSplitDisplayTextininifile.
RenamedDoNotSplitDisplayTextUseSplitDisplayText
RenamedUseSplitDisplayTextUseJoinDisplayText
AddedpropertyTerminalSwVersion.
AddedAdmincodesforDatasetandSoftwaredownload.
Versionincrementandupdateofeventhandling.
Remark!
Theeventisfiredfromaninternalthreadinbaxi.TheECRclientcodeis
thereforeexecutedfromthebaxithread.Itisimportanttoreleasetheevent
handlerasfastaspossibletoletthethreadgobackandwaitformore
events.WerecommendthattheECRprogrammerjustcreateanewevent
andsendtheinformationtoaninternalthreadoftheECRapp.
20130524 1.3.1.1
Versionincrement.
AddedOptionalDatainTransferAmountandLocalMode.
20130617 1.3.1.2
Versionincrement.
AddedPreAuth
ChangedOptionalDatainTransferAmountandLocalMode.
Versionincrement.
Addednewerrorcodes7515and7516
JSONBadfieldvalu7516
TransferamountOptionalDatatoolong.
Versionincrement.
20130702 1.3.1.3
20130801 1.3.1.4
NETSNorwayAS
Page5of43
DATE
VER.
20130813 1.3.1.5
20130823 1.3.1.6
20130904 1.3.1.7
20131021 1.3.1.8
COMMENTS
Versionincrement.
Addednewerrorcodes7427
Versionincrement.|
Versionincrement.|
Addedmissingdocumentationinsection4.6Writeproperties:
UseSplitDisplayText
LogAutoDeleteDays
SocketListener
SocketListenerPort
Use2KBuffer
20131105 1.3.1.9A
20131127 1.3.1.9B
20140116 1.3.2.0
NETSNorwayAS
DisplayTextInLocalMode
Versionincrement.|
AddedJSONdocumentation
Versionincrement.|
Page6of43
3 Introduction
BBShasdevelopedBAXItosimplifyintegrationofEFTPOSsolutionstoWindowsbasedpointof
sale(POS)applications.ThisimplementationisbasedontheinternationalOPOSstandard.The
interfaceisconformingtotheexistingNorwegianstandardforintegrationofEFTPOSterminals.
BAXIisa.NETdll.
Supportedenvironments:
.NET3.5
.NETmicro4.1
Mono(Linux)
4 Procedures for using BAXI

BAXIhasfourtypesofcommunicationchannels:
Methodsthatcanbecalledfromtheapplicationtotypicallystartatransaction
Eventsthataresentfromtheterminal
Propertiescontaininginformationthatcanbereadorwritten.
Initfilewithconfigurationparameters
BAXIhastwosuperstatesbankmodeandlocalmode.
Inbankmode,theterminalisincontrol.Inlocalmode,theECRisincontrol.
Anymethodthatputstheterminalinbankmodewillalwaysresultinalocalmodeevent.Thelocal
modeeventusuallyindicatesthefinalresultoftheoperation.
4.1
Installation
Thefilebaxi_dotnet.dllorbaxi_dotnet_micro.dllmustbeplacedinthesamedirectoryasthe
applicationexecutable.
4.2
1.
2.
3.
4.
4.3
General work flow

CallaBAXImethod.
WaitforincomingeventsfromBAXI.
Whenaneventgetstriggered,actontheparametersoftheeventfunction.
TheOnLocalModeeventsignalsafinishedtransaction.
Error situations
Anerroreventnormallyoccursifaselectedfunctioncannotbeperformed.
WhenBAXIhaslostcommunicationwiththeterminalduringatransaction,theOnLocalMode
eventwillbetriggered,withthelocalmoderesultsettoanunknownstatus.Thestatusofthe
transactionmustthenbeinvestigated!Thiscaneitherbedonemanually,ornewinversion1.3.0.1,
viatheECRadminmessagesGetLatestFinancialTransactionResultandGetLatest
TransactionReceipt.ThesemessagesaredocumentedinChapter5and6.
NETSNorwayAS
Page7of43
4.4
USB rs232 support
BAXI.netsupportsmonitoringofUSBrs232devices.Thisistoallow
hotswappingUSBpaymentterminalsandthatUSBpaymentterminalrebootsandstillhascontact
withBAXI.
USBrs232supportisalwaysenabled,butitsbehaviouriscontrolledbytheComPortand
DeviceStringproperties.
PS!:
TheMicrosoftserialportimplementationinthe.netframeworkhasaseriousflawwithregardsto
USBrs232portsdisappearing.ItisimperativethatUSBrs232solutionsusetheNetsserialport
driver.SeetheSerialDriverpropertyformoredetails.
ComPort:ifthispropertyissetto0,thismeansthatonlyDeviceStringisusedtodynamicallyfind
andmonitoraUSBrs232comportthatmatchestheDeviceString.Multiplepaymentterminalson
onemachineisnotsupported.
IfComPortissettoanumberandDeviceStringhasavalue,BAXIwillfirsttrythiscomport
number.Ifitfailstoopenthiscomport,itwilldynamicallyfindanyUSBportbasedonthevalue
inDeviceString.
IfDeviceStringisnotset,itwillonlyuseandmonitortheportsetinComPort.
DeviceString:thispropertymatchesthedevicefriendlynamethatispartoftheCOMportnamein
WindowsDeviceManager.Forexample,fortheIngenicoTelium2terminals,theyarecurrently
identifiedasDeviceString="SAGEMMONETELUSBTelium".
ThisdevicefriendlynamecanalsobefoundintheregistryundertheUSBenumerations,found
under
HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Enum/USB
Underthiskey,allvendorshavetheirownvendorandproductID.ForExample,theIngenico
Telium2terminalsareVid_079b&Pid_0028.Allentrieswillbeunderhereandcontainthe
following....
UseFriendlyNameorDeviceDescasidentifierinbaxi.inianddonotincludethe(COMXX)part.
NETSNorwayAS
Page8of43
BelowarethescenariosforUSBsupportinbaxi.inidescribedindetail.
1. ComPortsettoX,DeviceStringnotset:
BAXIwillattempttoopenComX.Ifthatfails,BAXIreportsanerror.
Ifitsucceeds,BAXIwillonlymonitorinsertsandremovalsofComportXonly.
2. ComPortsettoX,DeviceStringset:
BAXIwillfirstattempttoopenComX.Ifthatfails,BAXIwilldynamicallytrytofindand
openanycomportthatmatchesDeviceString.BAXIwillmonitorallcomportsthatmatch
DeviceStringforinserts/removals.
3. ComPortsetto0,DeviceStringset:
Inthiscase,BAXIwillskipstraighttotryingtofindacomportdynamically,basedon
DeviceString.BAXIwillmonitorallcomportsthatmatchDeviceStringfor
inserts/removals.
DefaultisComPortsetto0andDeviceStringset.
NETSNorwayAS
Page9of43
5 BAXI Properties
Thislistdescribesthepropertiesthatcanberead/writteninBAXI.
Writeproperties(I/O=W)mustbewrittenbeforethemethodOpen()iscalled.Anywriteproperty
correspondingtoatagintheinitfilewilloverridetheinitfiletagvalue.
5.1
Read properties
TheseareavailableafterasuccessfulOpen()dialogue.
Name
Type
I/O Description
Version
string
TerminalType
string
TerminalID
string
TerminalSwVersion
String
TerminalDeviceData
_TLD
MethodRejectInfo
byte[]
string
MethodRejectCode
int
(oldnameTerm_sw_version)
5.2
ThispropertyistheBAXIversionnumber.
Theformatisastringofatleast35inlengthcontaininga
detailedversionstringfortheBAXIcomponent.
Thispropertyis:
First2bytesterminaltype.
Second2bytesSofieprotocolversion.
ItcanbereadafterasuccessfulOpendialogue.
ThispropertyistheterminalID.
ItcanbereadafterasuccessfulOpendialogue.
ThisistheTerminalsoftwareversion,correspondingtothe
ITUSWVersiontag1005.
ThispropertycontainsTLDtaginforetrievedfromtheterminal
atstartup.SeeRef.1fordetails
Thispropertycontainsastringdescribingthereasonwhythelast
methodcallhasreturned0(rejectedarequest).
Thispropertycontainsacodedescribingthereasonwhythelast
methodcallhasreturned0(rejectedarequest).Alistofmethod
rejectcodesisavailableinAppendixA.
Write properties
Thesepropertiesarealsofoundinthebaxi.inifileandcanbebothwrittentoandread.Allhave
defaultvaluesinthebaxi.inifile.
Settingapropertywilloverridethecorrespondingentryinthebaxi.inifile.Ifallentriesinthe
baxi.inifilearesetbyproperties,thebaxi.inifilewillberedundantandcanberemoved.
Name
Typ
e
I/O
Description
LogFilePrefix
strin
g
R+W
Astringwhichwillbetheprefixofthelogfilename.The
logfilenamewillendwiththecurrentdate.
LogFilePath
strin
g
R+W
Thepathtothewantedlogdirectory.
TraceLevel
int
R+W
Acceptedvaluesarevalidtracelevels.Ex2.
NETSNorwayAS
Page10of43
Name
Typ
e
I/O
Description
LogFilePrefix
strin
g
R+W
LogFilePath
strin
g
R+W
BaudRate
int
R+W
Acceptedvaluesarevalidbaudrates.Ex9600.
ComPort
int
R+W
Acceptedvaluesarecomports(1to9).Ex1.
HostPort
int
R+W
HostIpAddress
strin
g
R+W
AcceptedvalueisanintinthenormalTCP/IPportnumber
range(0to65536).
Acceptedvalueisastringcontaininganipaddress,e.g.
192.168.1.1
MsgRouterOn
short R+W
Acceptedvaluesare0or1.0meansnoMsgrouterused.
MsgRouterIpAddress
strin
g
MsgRouterPort
short R+W
IndicateEotTransaction
int
R+W
ThispropertysetstheparameterIpAddressfromtheini
file.Acceptedvalueisastringcontaininganipaddress,
e.g.192.168.1.1
ThispropertysetstheparameterPortfromtheinifile.
AcceptedvalueisanintinthenormalTCP/IPportnumber
range(0to65536).
Acceptedvaluesare0or1.0meansnoEOTindication.
CutterSupport
int
R+W
Acceptedvaluesare0or1.0meansnocuttersupport.
PrinterWidth
int
R+W
DisplayWidth
int
R+W
Thispropertyisinuseonlyiftheapplicationprintsthe
contentofthePrintLineproperty.Defaultvalueis60.
InBAXI,assigningthevalue0tothePrinterWidth
propertymakestheterminaldoalltheprintinglocallyon
thebuiltinprinter.
Acceptedvaluesare10through99.
VendorInfoExtended
strin
g
R+W
R+W
Thispropertycontainsfourfields.
VendorName,thiswillbea3letterdescription
suppliedfromBBStoeachvendor.Fixedlength,3
letters(AZ).Toreceiveadescriptioncontact
baxi@bbs.no
Vendorproduct/Applicationname.
Vendorversion/Applicationversion.
TellID,whichshouldbeusedasauniqueidforthe
POS,TVM,shoporsimilarthattheterminalis
installedin.Tobeabletoidentifywherethe
terminalisinstalledisademandinseveralmarkets,
sothesystemsuppliershouldbeabletotrackthe
terminalbasedonthisinformation.
Rules:
NETSNorwayAS
Page11of43
Name
Typ
e
I/O
Description
LogFilePrefix
strin
g
R+W
LogFilePath
strin
g
R+W
1. Eachfieldisterminatedbythedelimiter;.The
delimiterismandatory.(Always4delimitersin
string).
2. Maximumtotallengthis32characters,including
thedelimiters.
3. AllfieldsexceptVendorNamehavevariablelength
andmustbeprintableASCII.
Samplestrings:
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
Acceptedvaluesare0or1.1meansenablingofautomatic
CustomerInforetrievalintheterminal.
WARNING:Thisfunctionalityisonlysupportedon
terminalversions07.1Xandhigher.Itmustbeturnedoff
forolderreleases.
TerminalReady
int
R+W
Acceptedvaluesare0or1.1meansenablingofterminal
readysignalling.
WARNING:Thisfunctionalityisonlysupportedon
terminalversions07.1Xandhigher.Itmustbeturnedoff
forolderreleases.
UseDisplayTextID
Int
R+W
Int
R+W
Acceptedvaluesare0or1.1meansenablingusageof
displaytextsourceidentificationanddisplaytext
identification.See7.2formoredetails.
Acceptedvaluesare0or1.1meansenableextended
NETSNorwayAS
Checksiftheattachedterminalhasrebootedandifso,
givesawarningandabortsthecurrenttransaction.The
warningwillbeintheformofanOnDisplayTexteventand
anOnPrintTextevent.
Checksiftheattachedterminalhaschangedterminalid.
LocksBAXIifTIDmismatch!Notransactionsareallowed
whileBAXIislocked!Ausertryingtoaccessalocked
BAXIwillreceiveanOnDisplayTexteventandan
OnPrintTexteventwithinformationaboutthelockedstate.
TounlockBAXI,removethefileterminalid.txt,situated
intheruntimeexecutabledirectory.
Page12of43
Name
Typ
e
I/O
Description
LogFilePrefix
strin
g
R+W
LogFilePath
strin
g
R+W
localmode.ThismeansthattheECRwillgetnewfields
SerialDriver
Strin
g
R+W
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
NETSNorwayAS
inlocalMode.
Currentpossiblevaluesare:
Nets
Microsoft
Thestringiscasesensitive.Defaultvalueifnotsetis
Microsoft.
ForanyimplementationrelyingonUSBtors232comms,
beitdirectlythroughtheTeliumUSBinterface,orthrough
aUSBtors232adapter,itisimperativetousetheNets
driver.ThisisbecausetheMicrosoftimplementationhasa
flawindiscoveringaremovalofsuchadevice/comport.
Anexceptionwillbethrownwhichisimpossibletocatch
inBAXI,resultingintheapplicationhavingtohandleitor
crash/shutdown.
TheNetsserialportimplementationsupportsUSBrs232
solutions,asdescribedin4.4
Thestringiscasesensitive.See4.4formoredetails.
Acceptedvaluesare0or1.0meanstoreceivedisplaytext
insingledisplaytextmessagetowardsECR
Acceptedvaluesareintegeronhowlongweshouldsave
theLoggingfileinnumberofdays.
Acceptedvaluesare0or1.0meansdontsetupatcp
server.1meanssetupaTCPserveronopenandlistenon
SocketListenerPort.
ThisistheportnumberthattheTCPserverwilllistenfor
Clientson.
Acceptedvaluesare0or1.0meansthattheterminalshall
usetheoriginal1Kbytebuffer.1meansusethatthe
terminalshallhaveincreasedbuffercapacityofabove
2Kbyte.
Acceptedvaluesare0or1.1meansthattheECRsystem
acceptsdisplaytextinLocalMode
Page13of43
6 BAXI Methods
Allmethodswillreturnimmediatelywitheither1(success)or0(failure).Thereturnvalue
indicatesiftheBAXIcomponenthasacceptedtherequest.
AsuccessfulcallthatputstheterminalinbankmodewillgenerateanOnLocalModeeventand
maybeothereventsaswell.
SeeAppendixBforcommonsequencediagrams.
Methodsthatdonotsettheterminalinbankmode:
SendTLD()
TransferCardData()
Close()
TheparameteroperatorIDhastwodifferentmeanings:
1. SingleTIDterminalidentifytheoperatorinitiatingatransaction.
2. MultiTIDterminalidentifythelogicalterminalIDthatshallbeusedinthetransaction.
Legalvalues110.1isthemasterTID.
IftheparameterOperIDisnotused,itshouldbesetto0000.
6.1
General note on parameters.
Anymethodthatexpectsparameters,willreceivetheseintheformofanXYZArgsobject.
Forexample,tocallTranferAmount,aTranferAmountArgsobjectmustbefilledoutandpassedas
aparametertotheTransferAmountmethod.
6.2
Open
PARAMETER: NONE
RETURNS: 1 on success, local mode will follow
0 on failure, no local mode
USAGE:
1. Call Open(). If Open() returns 0, check the MethodRejectCode to determine
the cause of the failure
2. On success, wait for OnLocalMode and OnError event.
3. The result of OnLocalMode will determine if the dialogue was successful or
not.
Initialisesthecontrolwiththecurrentvaluesofthewritepropertiesandstartsthecommunication
withtheterminal.Thismethodgeneratesadeviceattributedialoguewiththeterminal.
Thismethodshouldberunatstartup,afteranywritepropertieshasbeenset.
6.3
Close
PARAMETER: NONE
RETURNS: 1 always (it never fails), no local mode.
USAGE:
NETSNorwayAS
Page14of43
1. Call Close().
2. Shut down system if applicable.
Thismethodperformsshutdownofcommunicationwiththeterminal.
Synchronous,returnswhenoperationcompleted.
IMPORTANT:
ThismethodshallbecalledpriortoshuttingdownBAXI/ECR!
NeglectingtocallClose()beforeshutdownwillresultinresourcesnotbeingreleased!
6.4
TransferAmount
PARAMETER: TransferAmountArgs args

USAGE:
1. Call TransferAmount(). If the function returns 0, check the
MethodRejectCode to determine the cause of the failure.
2. On success, wait for OnDisplayText, OnPrintText, OnLocalMode and OnError
events. Several OnPrintText events can occur during a transaction.
3. The result of OnLocalMode will determine if the transaction was successful
or not.
TransferAmountArgscontent:
operID:
type1:
int
string
Seeintroduction.
H30=EFTAuthorisation
(KJP)=> Purchaseamount
H31=ReturnofGoods
(RETU)
H32=Reversal
(ANNU)=> Annulatelastamount
H33=PurchasewithCashback
(KONT)
H34=PREAuthorisation
(GAR)
H35=Adjustment
(OPPG)
H36=BalanceInquiry
(DISP)
H37=CompleteReceipt
(KVIT)
H38=Deposit
(INN)
H39=CashWithdrawal
(UT)
H3A=Loadepursecard
(LOAD)
H3B=MerchandisePurchase
H3C=MerchandiseReversal
H3D=MerchandiseCorrection
H40=ForceOffline
H41=IncrementalPREAuthorisation
H42=ReversalPREAuthorisation=>Partialandcomplete
H43=SaleCompletionPREAuthorisation
amount1:
type2:
int
Totalamount.
int
H30=notinuse
NETSNorwayAS
Page15of43
amount2:
int
Only used if <TYPE 1> = Purchase with
Cashback(H33)
Totalpurchaseamount.
type3:
int
H30=notinuse
H31=notinuse
H32=VAT(Valueaddedtax)amount.
ThetotaltaxamountsuppliedbytheECR.
amount3:
int
VATamount
hostdata:
string
articleDetails:
Variablefieldlength,max40digitsalfanumeric.Thedataistobesenttothe
HOST.ThedatacharactersmustbeinrangeH20toH7F.Thisfieldis
optional.
string
Variablefield,alphanumericdata.EachrecordisseparatedwithH1e,ASCII
RS,Amaximumof3recordscanbesentinonemessage,eachseparatedwith
RS.
Thefieldisusedtoidentifydedicatedarticlesorreferencetoarticles.This
fieldisoptional.ART#mustbefilledwitharticlenumbersinthepurchase
transactionART#mustbefilledwithreferencestothearticlesinareversal
transactionandcorrectiontransaction.Thisisapplicationdependent,and
mustbeclarifiedineachproject.
AMerchandiseReversaltransactionandMerchandiseCorrectiontransaction
canonlyincludeonearticleatatime.
paymentConditionCode:
string
Variablefieldlength,max3alphanumericchar.
authCode:
string
AuthorisationCodefield.Variablefieldlength,max6characters.
Loweranduppercaseisallowed.Specialcharacterslike@#%&are
NOTallowed.
Thisfieldisoptional.ThefieldisusedforForceOfflinetransactions.
OptionalData:OptionalDatafield.Variablefieldlength,max1024ASCIIcharacters.
6.5
Thecontext,contentsandformatofthisfieldisspecifiedandmaintainedby
NetsTerminalIT.SeeECRChapter13AppendixCOptionalData.
Administration
PARAMETER: AdministrationArgs args

USAGE:
1. Call Administration(). If the function returns 0, check the
NETSNorwayAS
Page16of43
2. On success, wait for OnDisplayText, OnPrintText,

OnLocalMode and OnError events. Several OnPrintText
events can occur during an administration dialogue.
3. The result of OnLocalMode will determine if the administrative function
was successful or not.
Startsoneoftheadministrationdialogues.
AdministrationArgscontent:
admCode: int
0x3030=notused
...........
0x3039=notused
0x3130=RECONCILIATIONfunction.
0x3131=Emptyterminalprintbuffer.
0x3132=Cancellationrequest.Theterminalhasthechoicetoignoretherequest.
TheOnLocalModeresultwilldeterminethefinalstatusofthetransaction.
0x3134=ANNULfromECRshouldbemappedbyITUtoperformREVERSAL
transaction.
0x3135=BalanceInquiry.
0x3136=Xreport.
0x3137=Zreport.
0x3138=SendOfflineTransactionstoHOST.
0x313A=PrintofstoredEOTtransactions
0x313B=Finishcurrentdialogue(behavesasCancel,butsilently).
0x313C=PrintLatestFinancialTransactionReceipt
0x313D=SendLatestFinancialTransactionResult
0x313E=StartSoftwareDownload
0x313F=StartDatasetDownload
operID:
string
Seeintroduction.
Messages0x313Cand0x313Dareusedtofindouttheresulttheprevioustransaction.Thiswill
typicallybeusedwhenanerrororlossofcommunicationsoccursandtheresultofthetransactionis
unknown.Byusingthesemessages,onecanfindoutiftheITUcompletedthetransactionornot,so
thatadecisioncanbemadetoeitherattemptthetransactionagainorgivethecustomertheproper
receiptandgoods.0x313Cgivesthereceiptcopyasaprinttext.0x313DgivesaLastFinancial
TransactionResultmessage(0x45)anditscorrespondingeventinBAXI.SeeCh.8foracommon
usageexampleandCh.6fordescriptionoftheLastFinancialTransactionResultevent.
6.6
TransferCardData
PARAMETER: TransferCardDataArgs args

RETURNS: 1 on success, no local mode
USAGE:
1. Call TransferAmount() to do a deposit.
NETSNorwayAS
Page17of43
2. Call TransferCardData(). If the function returns 0,

check the MethodRejectCode to determine the cause of
the failure.
3. On success follow the procedure of a normal transaction.
ThismethodsendstheinformationinamagneticcardtracktotheTerminal.Theterminalwillact
asifthecardwasswipedlocallyontheterminal.Thefunctionistargetedatthespecificusecaseof
depositingmoneyongiftcards.ItisnotintendedtobeusedtoenabletheECRtopasscustomer
cardtrackcontentstotheterminal!
Onlytrack2contentcardsaresupported.
Thismessageisonlyallowedwhentheterminalisinbankmodetypicallyduringadeposit.
TransferCardDataArgscontent:
trackType: int
0x32=Origintrack2
0x40=OriginManually
trackData: string
Thetrackcontent.
6.7
SendTLD
PARAMETER:
SendTldArgs args
RETURNS: 1 on success, sometimes local mode, depending on TLD tag range

USAGE:
1. Call SendTLD() to perfom a function. If the function returns 0, check the
2. On success and if typeString is set to REQ, wait for the response in the
OnTLDReceived event.
Thismethodisageneralpurposemethod,usedtotriggervariousfunctions.Thisfunctionwillset
theprotocolinbankmode,thusendthedialoguewithalocalmodemessagewhenusingTLDtags
inthegroupsCardinfo(range2000)andECRinfo(range3000).Currently,thefunctiondoes
notsettheprotocolinbankmodeforrequestsinthe1000range.
SendTldArgscontent:
TldType:
string
SpecifiestheTLDtagtype.
Possiblevaluesare:
REQ
CMD
TldField:
byte[](arrayofbytes)
ATLDfieldbuiltupasdescribedinref1.
6.8
GetTLDTag
PARAMETER:
byte[] wantedTldTag, byte[] tldBuffer, byte[] wantedTldTagValue
RETURNS: 1 on success, no local mode

NETSNorwayAS
Page18of43
USAGE:
Call GetTLDTag() to retrieve a wanted tag value from a
TLD buffer.
ThismethodisahelperfunctionforparsingaTLDbuffer.Itisutilitarianinnatureanddoesnot
usetheEventArgsinterfacecontract,liketheothermethods.
wantedTldTag
ThewantedTLDtag.
tldBuffer
TheTLDbufferinwhichtosearch.
wantedTldTagValue
Onsuccessthisbytebufferwillholdthewantedtagvalue.
6.9
SendJson
PARAMETER:
SendJsonArgs args
RETURNS: 1 on success
0 on failure
USAGE:
Call SendJson() to perform a function.
If the function returns 0, check the MethodRejectCode to determine the cause of
the failure.
On success Wait on the response in the OnJsonReceived event.
SendTldArgscontent:
public string JsonData;
6.10 BiBAdministration
PARAMETER: BiBAdministrationArgs args
USAGE:
Specialcustomfunction,seeRef[2].SimilarinusagetotheAdministration()method.
6.11 BiBTransaction
PARAMETER: BiBTransactionArgs args
USAGE:
Specialcustomfunction,seeRef[2].SimilarinusagetotheTransferAmountmethod.
NETSNorwayAS
Page19of43
7 BAXI Events
7.1
General note on events
Alleventdelegatesthatcontaindata,willgivethisdatainEventArgsobjects.Forexample,the
OnDisplayTextevent,willgiveaDisplayTextEventArgsobjectthatcontainsthedisplaytextstring
andanyotherpertinentfieldsaswell.
Remark!
Theeventisfiredfromaninternalthreadinbaxi.TheECRclientcodeisthereforeexecutedfrom
thebaxithread.Itisimportanttoreleasetheeventhandlerasfastaspossibletoletthethreadgo
backandwaitformoreevents.WerecommendthattheECRprogrammerjustcreateanewevent
andsendtheinformationtoaninternalthreadoftheECRapp.
7.2
OnDisplayText
public delegate void DisplayTextEventHandler(object sender,

DisplayTextEventArgs e);
DisplayTextEventArgscontents:
DisplayText:
DisplayTextSourceID:
DisplayTextID:
7.3
string
Adisplaytexthasbeenreceivedfromtheterminal.Maxlengthis80
characters.
int
Thesourcethatgeneratedthedisplaytext.
See5.2UseDisplayTextID.
int
Theuniqueidentifierofadisplaytext.
Mostlyintendedforunattendedsolutions.
See5.2UseDisplayTextID.
OnPrinterText
public delegate void PrintTextEventHandler(object sender,

PrintTextEventArgs args);
PrintTextEventArgscontent:
PrintText:string
Thisistheprintertext(thereceipt)formattedinlineswithamaximumlinelengthof24characters.
Severalprinttextmessagescouldcomeduringatransaction.
Separators:
0xA=Separatorlinefeed.WillbeusedthroughouttheprintTextstringtoallowcorrect
formattingofthereceipts.
NETSNorwayAS
Page20of43
7.4
0xC=Separatorendoftext.Willbeusedattheveryendof
everystringtoindicatetheendoftext.
0xE=Separatorcutter(optional).Canappeariftheproperty
CutterSupportisset.CanbeusedanywhereintheprintTextstringtoindicatearequestto
cutthereceipt.
OnLocalMode
public delegate void LocalModeEventHandler(object sender,

LocalModeEventArgs args);
Signalstheapplicationthatafinancialoradministrativetransactioniscompleted.
LocalModeEventArgscontent:
LocalModeResultData:string
Thisparametercontainsthecompletelocalmodereplyfromtheterminalinrawformat.
Result:int
Thisistheresultofthetransaction:
0:FinancialtransactionOK,accumulatorupdated
1:AdministrativetransactionOK,noupdateofaccumulator
2:Transactionrejected,noupdateofaccumulator
3:TransactionisLoyaltyTransaction
99:Unknownresult.Lostcommunicationwithterminal.Baxihasgeneratedthislocal
mode.
AccumulatorUpdate:int
H20=indicatesstandardupdateofaccumulator.H21=Notusedincurrentsoftwareinthe
ITU.H22=indicatestransactionisfinalisedasOfflinetransaction.
H23..H2F=Reservedforfutureuse.TheECRshallfinalisethetransactionasOK.
Accumulatortypeisuncertainforthetimebeing.
H30=indicatesnoupdateofaccumulator.
IssuerId:int
ThisisthecardissuerID.
TruncatedPan:string
Thisparametercontainscardinformation.Theformatisthecardnumberwithlengthupto
19digits.
Timestamp:string
Thisparametercontainsthetimestampofthetransaction.
TheformatisYYYYMMDDHHMMSS
VerificationMethod:int
Thisisacodeforcardholderverificationmethod(CVM).Thecodesare:
0:TransactionisPINbased(default)
NETSNorwayAS
Page21of43
1:Transactionissignaturebased
2:NoCVM.Withorwithoutamountconfirmationby
cardholder.
3:TransactionisLoyaltyTransaction
Forthecode3,localmoderesultwillalwaysbe3.
TotalAmount:int
Usedin:
RestaurantorHotelenvironmentwhereTIPisaddedtothepurchaseamountonthe
ITU.UsedinthePurchaseorAdjustmenttransaction.
Transactionswithsurcharge.Thistotalamountwillcontainthesumoftheoriginal
amountplusthesurchargeamount.
SessionNumber:string
Thisparametercontainsthesessionnumberofthetransaction(3bytesnumericdata).This
numberisglobalforasiteandgetsincrementedafterareconciliation.
StanAuth:string
Thisparametercontainsthetransactionreferencenumber.Thelengthis12characters
SequenceNumber:string
4bytesnumericdata(H30..H39).ThisisthecustomernumberifthetransactionwasPre
Authtransaction.MustbeusedasreferenceinTransferAmountAdjustmenttransaction.
TotalAmount:int
ThisparameteristheTotalITUtransactionamountusedinRestaurantorHotelenvironment
whereTIPisaddedtothepurchaseamountontheITU.Itsalsousedifasurchargefeeis
addedtothepurchaseamountontheITU.
RejectionSource:in
Thisparameterindicatesthesourcefortherejection.Fixedlength,2characters.Thisfield
isoptional.Rejectionsourceswillbeaddedastheyareneeded.
Ifarejectionsourceispresent,therewillalwaysalsobearejectionreasonpresent.
RejectionReason:string
Thisparameterindicatesthereasonforarejection.Variablelength,maximum20
characters.Thisfieldisoptional.
Rejectionreasonswillbeaddedastheyareneeded.
Ifarejectionreasonfieldispresent,therewillalwaysalsobearejectionsourcepresent.
TipAmount: int
ThisparameterisusedinRestaurantorHotelenvironmentwhereTIPisaddedtothe
purchaseamountontheITU.
SurchargeAmount:int
ThisparameterisusedifsurchargefeeisaddedtothepurchaseamountontheITU.
TerminalID:string
ThisparameteristheterminalID.
AcquirerMerchantID:string
ThisparameteristheSiteID.
NETSNorwayAS
Page22of43
CardIssuerName:string
ThisparameterwillbeApplicationLabelincaseofchipcards
ResponseCode:string
ThisparameterwillcontainPSPresponsecodesincaseofonlineapprovedtransactions&Y
codesfromterminalforofflineapprovedtransaction.
TCC:string
ThisparameterisTransactionConditionCode.3bytealphanumericdata.
Eachbyteindicatesasfollowing:
TCC[0]=CardDataEntryMethod
TCC[1]=CVMMethod
TCC[2]=AuthorizationMethod
AID:string
ThisparameterisChipCardApplicationIdentifier
TVR:string
ThisparameterisChipCardTerminalVerificationResult
TSI:string
ThisparameterisChipCardTerminalStatusInformation
ATC:string
ThisparameterisChipCardApplicationTransactionCounter
AED:string
ThisparameterisChipCardApplicationEffectiveData
IAC:string
ThisparameterisChipCardIssuerActionCode
OptionalData:String
Variablefieldlength,max1024ASCIIcharacters.
Thecontext,contentsandformatofthisfieldisspecifiedandmaintainedby
NetsTerminalIT.SeeECRChapter13AppendixCOptionalData.
7.5
OnError
public delegate void BaxiErrorEventHandler(object sender, BaxiErrorEventArgs

args);
OnErrorsignalstotheapplicationthatanerrorhasoccurred.
BaxiErrorEventArgscontents:
ErrorCode:int
AlistoferrorcodesisavailableinAppendixA.
NETSNorwayAS
Page23of43
ErrorString:string
Ashorttextualdescriptionoftheerror.
7.6
OnTLDReceived
public delegate void TLDReceivedHandler(object sender, TLDReceivedArgs args);
ThiseventreceiveaTLDtagdatastringfromtheterminal.Seeref1fordetails.
TLDReceivedArgscontents:
TldType : string
SpecifiestheTLDtagtype.
Possiblevaluesare:
RESP
STATUS
INFO
TldData:byte[](arrayofbytes)
ATLDfield
7.7
OnJsonReceived
public delegate
void OnJsonReceived(object sender, JsonReceivedArgs args);
ThiseventreceiveaJsontagdatastringfromtheterminal.Seeref.
JsonReceivedArgscontents:
JsonString: string
7.8
OnStdRsp
public delegate void StdRspReceivedHandler(object sender,

StdRspReceivedArgs args);
Thisisanoptionalspecialpurposeevent.Ittriggerseachtimetheterminalsendsaresponseframe
toBAXI.AuserwantingtomakequickconsecutivecallstoBAXIcanusethiseventtofindout
whenBAXIhasfinishedprocessingthelastcall.
Exampleofuse:
1. TransferAmount();
2. WaitforOnStdRsp()event.
3. SendTLD();
StdRspReceivedArgscontents:
Response: string
Theresponsecodefromtheterminal.Always00pertoday.
NETSNorwayAS
Page24of43
7.9
OnTerminalReady
public delegate void TerminalReadyEventHandler(object sender,

TerminalReadyEventArgs args);
WARNING:Thisfunctionalityisonlysupportedonterminalversions07.1Xandhigher.Itmust
beturnedoffforolderreleases.
Thisisanoptionalspecialpurposeevent.Ittriggerseachtimetheterminaldeterminesthatithas
completedterminalmanagement.Typically,thiswilloccurastheterminalgoesintoidleafteran
activity,likeapurchase.
Afterthiseventhastriggered,theterminalshouldalwaysbereadytohandleanewfunction,suchas
TransferAmount.OneotheruseisforperformingaCloseOpensequencewithoutdisrupting
terminalcommunicationtowardshost,suchasswappingbetweentwoinstancesofBAXI.
TerminalReadyEventArgscontents:
ThereisnocontentsofarforthisEventArgsobject.
7.10 OnLastFinancialResult
Public delegate void LastFinancialResultEventHandler( object sender,
LastFinancialResultEventArgs args);
Thisisaspecialpurposeevent.ItissentbytheITUwhentheECRinvokesthemessage
Admin(SendLatestFinancialResult(0x313D)).
ThecontentsareidenticaltothecontentsofaLocalModemessage,butitcontainstheresultsofthe
last/latestfinancialoperation.Thisdatacanbeusedtodeterminewhathappenedtoatransactionin
caseofcommunicationserrorsorothercausesofalossoftransactionresult.
NETSNorwayAS
Page25of43
8 Baxi.ini file
Thebaxi.inifilecanbeusedtosetuptheenvironmentforBAXI.Itshouldbeplacedinthesame
directoryastheapplicationexecutablerunningBAXI.
Allthetagentriescanalsobesetviaproperties.Ifthereisaconflictbetweenatagentryanda
property,thepropertyalwaysoverridestheinitfile.
Ifalltheinitfiletagentriesaresetbyproperties,baxi.iniisredundantandcanberemoved
altogether.
Thebaxi.inifileentriesmaps11tothewritableproperties.Seecorrespondingwritepropertyfor
details!
NETSNorwayAS
Page26of43
9 Common Use Cases

Herefollowsalistofexampleusageofthecurrenttransactiontypes.
BasicfunctionsthatshouldalwaysbeintegratedinaPOSapplicationare:
Purchase
Purchasewithcashwithdrawal
Reversal
Returnofgoods
Reconciliation
Itisimportanttoimplementreversalbecauseitwillbenecessarytocancelatransactionifsignature
controlfailsorasimilarsituation.
US=0x1F
RS=0x1E
9.1
Transactions
9.1.1 Purchase
Normalpurchasetransactionrequest(10.00kr):
TransferAmountArgs a = new TransferAmountArgs();
a.OperID = 0000;
a.Type1 = 0x30;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
a.ArticleDetails = ;
a.PaymentConditionCode = ;
a.AuthCode = ;
int result = Baxi.TransferAmount(a);
Normalpurchasetransactionrequest(10.00kr) withVAT(3kr):
a.OperID = 0000;
a.Type1 = 0x30;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x32;
a.Amount3 = 300;
a.HostData = ;
a.AuthCode = ;
NETSNorwayAS
Page27of43
Normalpurchasetransactionrequest(10.00kr) withloyaltyinfo(abcdefg):
a.OperID = 0000;
a.Type1 = 0x30;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = abcdefg;
a.AuthCode = ;
Normalpurchasetransactionrequest(10.00kr) withpaymentconditioncode2:
a.OperID = 0000;
a.Type1 = 0x30;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
a.PaymentConditionCode = 2;
a.AuthCode = ;
9.1.2 Return of goods

a.OperID = 0000;
a.Type1 = 0x31;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
NETSNorwayAS
Page28of43
a.AuthCode = ;
9.1.3 Reversal
Reversalofthelasttransaction(10kr).
a.OperID = 0000;
a.Type1 = 0x32;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
a.AuthCode = ;
9.1.4 Purchase with Cashback

Purchasetransactionrequest(10.00kr) withcashback(2kr):
a.OperID = 0000;
a.Type1 = 0x33;
a.Amount1 = 1200;
a.Type2 = 0x30;
a.Amount2 = 1000;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
a.AuthCode = ;
9.1.5 Balance inquiry

a.OperID = 0000;
a.Type1 = 0x36;
a.Amount1 = 0;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
NETSNorwayAS
Page29of43
a.AuthCode = ;
9.1.6 Deposit
Canbeusedforexampletodepositmoneyongiftcards.
a.OperID = 0000;
a.Type1 = 0x38;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
a.AuthCode = ;
9.1.7 Cash withdrawal

a.OperID = 0000;
a.Type1 = 0x39;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
a.AuthCode = ;
9.1.8 Force Offline

Forceanofflinepurchaseofamount1000withauthcodeofABC.
a.OperID = 0000;
a.Type1 = 0x40;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
NETSNorwayAS
Page30of43
a.AuthCode = ABC;
9.2
TopUp
Thesearetypicallyusedtoloadamobilephonewithmorecalltime.Seeref1fordetails.
TheEANnumberofthetransactionisspecifiedinthearticleDetailsparameter.
BuyaNetCom150TopUpcode:
a.OperID = 0000;
a.Type1 = 0x3B;
a.Amount1 = 1000;
a.Type2 = 0x30;
a.Amount2 = 0;
a.Type3 = 0x30;
a.Amount3 = 0;
a.HostData = ;
a.ArticleDetails = 07021940002810 + "\x1e"; // record separator
a.AuthCode = ;
ReceivethetopupcodefromtheOnTLDReceivedevent,TLDReceivedArgscontents:
RS=\x1e,US=\x1f
TldType:INFO
TldData: 4005 + US + 00066 + US +
07021940002810 + US + 00000000833 + US + 7146417457411 + US + 000000426694-79 + US + 0015000 + RS
9.3
Gift Card
Giftcardisimplementedasatwotransactionsolution.
1. Firstdoanormalpurchasewiththecustomercard.
2. Doadepositwiththesameamountasthecustomerpurchase.
3. Sendthetrack2contentofthegiftcardwiththeTransferCardData()function.
Theterminalwillfinishthedepositonthegiftcard.
9.4
Group ID
GroupIDisafunctionusedtoseparatecardswithinthesamerangebasedonvaluesreturnedfrom
thecard.ThisfunctionalityiscurrentlyonlysupportedbyBBScards.Thisfunctionalityisusedin
situationswhereyouwanttogivedifferentpricestocustomerswiththesametypeofprepaidBBS
cards,typicallyincanteensusedbymorethanonecompany,whereemployeesfromthedifferent
companiesgetsdifferentprices.
NETSNorwayAS
Page31of43
ToretreivetheGroupIDusethefollowingsequence:
CallthefunctionSendTLD()specifyingaGroupIDrequest:
SendTldArgs a = new SendTldArgs();
a.TldType = REQ;
a.TldField = 3000;
Baxi.SendTLD(a);
GetthegroupIDfromtheOnTLDReceivedevent,TLDReceivedArgscontents:
TldType:RESP
TldData:3000 + US + 0005 + US + 12345 + RS
9.5
Get encrypted card data
CallthefunctionSendTLD()specifyingarequestencryptedcarddata:
a.TldType = REQ;
a.TldField = 3007;
Baxi.SendTLD(a);
ReadtheencryptedcarddataintheOnTLDReceivedevent,TLDReceivedArgscontents:
TldType:RESP
TldData:3007 + US + 0015 + US + 000000000000000 + RS
9.6
Get encrypted card data and issuer ID
CallthefunctionSendTLD()specifyingarequestencryptedcarddataandissuer:
a.TldType = REQ;
a.TldField = 3008;
Baxi.SendTLD(a);
ReadtheencryptedcarddataintheOnTLDReceivedresponse,TLDReceivedArgscontents:
TldType:RESP
TldData:3008 + US + 0015 + US + 000000000000000 + RS
9.7
Send a track 2 card swipe to the terminal:
TransferCardDataArgs a = new TransferCardDataArg();

a.TrackType = 0x32;
a.TrackData = 9571921000000000236;
Baxi.TransferCardData(a);
NETSNorwayAS
Page32of43
9.8
TIP
Tobeabletousetip,theservicehastobeenabledfortheterminal.Thiscanbeorderedfromyour
dealer.
IftheamountreceivedintheamountfieldintheLocalModemessagefromtheterminalislarger
thantheamountsenttotheterminalintheTransferAmountmessage,thedifferenceshouldbe
treatedastip.
9.9
Check host connection
CallthefunctionSendTLD()specifyingarequestforhostconnectionstatus:
a.TldType = REQ;
a.TldField = 1012;
Baxi.SendTLD(a);
ReadthehostconnectstatusintheOnTLDReceivedresponse,TLDReceivedArgscontents:
Exconnectedtohost:
TldType:RESP
TldData:1012 + US + 0001 + US + 0 + RS
9.10 Set terminal language

CallthefunctionSendTLD()specifyingsettingterminallanguage.
Ex English:

a.TldType = CMD;
a.TldField = 1014 + US + 0002 + US + en + RS;
Baxi.SendTLD(a);
9.11 Receive a card inserted status event

Theterminalcanbesettosendeventswhenacardisinsertedorremoved.Readthestatusinthe
OnTLDReceivedfunction.
Excardinserted:
TldType:STATUS
TldData:1013 + US + 0001 + US + 1 + RS
9.12 Get Customer Info

NETSNorwayAS
Page33of43
WARNING:Thisfunctionalityisonlysupportedonterminalversions
07.1Xandhigher.Itmustbeturnedoffforolderreleases.
ThegenericTLDformatisdefinedin[1].
TheECRinvokestheGetCustomerInfobysendingaTLDrequestwiththefollowingtagsinthegiven
order:
2000 + US + 0003 + US + 001 + RS +
2002 + US + 0003 + US + 001 + RS +
2001 + US + 0000 + US + RS
Thetagsmustbeintheorderabovefortherequesttowork.
TheITUtypicallyreturnsthecustomerinformationfromtheaboverequestinthefollowingmanner:
2000
2002
2001
2003
+
+
+
+
US
US
US
US
+
+
+
+
0003
0003
0032
0002
+
+
+
+
US
US
US
US
+
+
+
+
001 + RS +
001 + RS +
00987654
00 + RS
+ RS +
WhentheITUsendsaTLDStatusCardinsertedwithIssuerIDmessage,ittypicallycontainsthe
following(foraBankAxeptcard,issuer30):
1013 + US + 0001 + US + 1 + RS +
3002 + US + 0010 + US + 0000000030 + RS
ToreceivetheissuerIDtaginthecardstatusmessage,theparameterforsendingissuerIDwithcardstatus
mustbeenabledintheITU.
Thereare2normalusecasesfortheCustomerInfofunctionality.
1. The ECR always initiates a GetCustomerInfo, before the purchase. (Automatic
retrieval of Customer Info is turned on in the ITU). It is then the ITU which
decides if there should be a request to the host, based on Issuer ID and terminal
configuration.
2. The ECR receives card inserted with issuer ID from the ITU and based on
issuer ID elects to initiate a customer info request or not.
Belowarethese2usecasesdescribedindetail.Thedatawithinthemessageswilltypicallybeas
describedabove.
1. ECRinitiatesGetCustomerInfo.
Theparameterforsendingcardstatusmessagesshouldbedisabledforthisscenario.Thisis
becauseitisnotneededbytheECRanditcanalsoincreasetheriskofcollisionsand
retransmissions.
Automatic customer info retrieval is enabled.
Sequence:
The ECR will always initiate a transaction with a GetCustomerInfo request to

the ITU through a TLD Request.
The terminal goes into Bank Mode.
The terminal will either ask for a card, or start processing if a card is already
inserted or swiped.
NETSNorwayAS
Page34of43
The terminal will return the Customer Info to ECR

through a TLD Response and remains in bank mode.
It is awaiting a TransferAmount transaction.
The ECR processes the Customer Info and initiates a transaction. It is also
possible to send an Admin Cancel (or Admin finish, see below) at this stage,
if the ECR is not interested in any additional actions other than the customer
info data.
The ITU will complete any transaction or cancellation with a Local Mode
message.
2. ECRreactstoCardInserted
Automaticcustomerinforetrievalisdisabled.CardstatusmessageswithIssuerIDis
enabledintheITU.
Sequence:
The ITU will send a TLD Status message with Card inserted and Issuer ID to
the ECR, when the customer inserts or swipes a card in the ITU.
ECR processes the Issuer ID and decides if it should send a Get Customer
Info request or not.
ECR sends a Customer Info TLD Request.
The ITU goes into Bank Mode.
The ITU requests the customer info from the host and sends a TLD Response
with Customer Info to the ECR.
The ITU then awaits further action from the ECR and remains in Bank Mode.
The ECR processes the Customer Info and normally sends a TransferAmount
message to the ITU.
The ITU will handle the transaction like normal and complete it with a Local
Mode message.
9.13 Get Customer Info with Admin Finish.

FortheGetCustomerInfodialoguesoranyotherTLDrequestdialogue,theterminalcanremain
inBankModeandexpectafinaltransactiontotakeplace.Thereareoccurrenceswheresucha
transactionwillnottakeplaceandtheECRwishestoforcetheTerminaloutofbankmodeand
backtoidle.Thiseffectivelycompletestheoperation/dialogueandmakestheterminalreadyfora
newoperation/dialogue.
ThishasbeenachievedwithAdminCancelinthepast.Thishastheunwantedbehaviourofthe
terminalabortingthetransactioninfull,includingdisplaytextsandshowingCancelledby
operatorinitsdisplayetc.
TheAdminFinishcommandisanalternativetoAdminCancelinthesecases,whereitisbetterfor
theterminaltosilentlyabortandreverttoLocalModeandshowinganidlescreen.
9.14 Investigating results of last financial transaction.

Ifanerroroccursinthemiddleofatransaction,BAXIwillreturnanerrorandalocalmoderesult
ofUnknown.Ifsuchanerrororothererrorsmaketheresultofatransactionunavailableor
incomplete,onecanusetheAdministrationfunctionsPrintLatestFinancialTransactionReceipt
andSendLatestFinancialTransactionResulttofetchtheresultfromtheITU.Thisisa
NETSNorwayAS
Page35of43
complementtothemanualroutinestoprovideanintegratedsolutionfor
thisproblemforECRvendors.
Letusassumethatatransactionisunknown.Toretrieveallnecessaryinformation,theECRwill
havetoperformthefollowing:
int result = Baxi.Administration(new AdministrationArgs(0x313C, 0000));
ThisresultsinaPrintTextevent,whichwillcontainacopyreceiptofthelatestfinancialtransaction
result.ThisisidenticaltoenteringtheITUmenuandmanuallyprintoutthecopyreceipt.
AftertheLocalmodeisreceived(administrationisdone),theECRcansendthenextadministration
messagetogettheLatestFinancialtransactionresult,whichcontainstheLocalmodedatafromthe
lastfinancialtransaction.
int result = Baxi.Administration(new AdministrationArgs(0x313D, 0000));
ThisresultsinaLastFinancialTransactionResultevent,whichcontainsthelocalmodeidenticaldata
fromthelastfinancialtransaction.Theadministrationoperationisthencompletedwithalocal
modemessage.
NETSNorwayAS
Page36of43
Best practice implementation of

security in the ECR interface.
ThesearerecommendationsconcerningsomeofthesecurityfunctionsofferedwithBaxiandBBS
terminals.Recommendedpracticeistoimplementallfunctionswithhighsecurity.
Theserecommendationsarebasedonexperiencedskimmingpracticeswhichmainlyhavebeen:
1. Skimming equipment is mounted on the terminal when the shop is closed.
2. The shops terminal is replaced with a terminal with skimming equipment
mounted.
Powercyclecheckisdesignedtocounterscenario1,whiletheotherfunctionsaredesignedto
counterscenario2.
Function
Lowsecurity
Mediumsecurity
VendorInfo
extendended.
Identificationofpos
applicationsupplierin
thevendorinfoextended
string
Identificationofpos
Identificationofpos
applicationsupplierand applicationsupplierand
Identificationofsitein uniqueIdentificationof
thevendorinfoextended POSinthe
string
vendorinfoextendedstring
Turnedoff
Turnedon
Turnedoff
Turnedon
Datareportedby
ECRtoterminal.
ReadablebyBBS.
Powercyclecheck
Checkswhenthe
terminalhasbeen
tunedonandoff.
Tidcheck
Highsecurity
Actiondemandedfromthe
POSoperatoronthe
OnDisplayTextgenerated
TurnedoffinBaxi.ini,but
implementedtidcheckinthe
POSapplicationwithaction
ChecksiftheTID
requiredfromthepos
(TermianlD)ofthe
operatorontidchange,
terminalhas
Preferablewithoperator
changed.
authentication.
Noserialnumbercheck.
Implementserialnumber
Implementserialnumber
Serialnumber
checkinthePOS
checkinthePOSapplication
check
applicationwithaction withactionrequiredfrom
requiredfromthepos theposoperatoronserial
Checksifthe
operatoronserial
numberchangewith
physical
number.
operatorauthentication.
serialnumberofthe
terminalhas
changed.
NETSNorwayAS
Page37of43
10Deprecated Functions
Thesefunctionswillbesupportedforbackwardscompatibility.
11 Removed Functions
Thesefunctionshavebeenremovedentirelyandarenolongersupported
11.1 TransferAmount_V2
ReplacedbyTransferAmount_V4.
SameasTransferAmount_V4butwithouttheparameterPaymentCardConditionandAuthCode.
ReplacedbyTransferAmount_V4.
SameasTransferAmount_V4butwithouttheparameterAuthCode.
11.4 Administration( int admCode, string OperId)
ReplacedbythenewArgstypeinterfaceAdministration(AdministrationArgsargs).
11.5 SendTLD( string typeString, byte[] tldField)

ReplacedbythenewArgstypeinterfaceSendTLD(SendTldArgsargs).
11.6 TransferCardData( int trackType, string trackData)

ReplacedbythenewArgstypeinterfaceTransferCardData(TransferCardDataArgsargs).
11.7 BiBAdministration( int AdmCode, string OperID)

ReplacedbythenewArgstypeinterfaceBiBAdministration(BiBAdministrationArgsargs).
11.8 BiBTransaction( int amount, string transactionData)

ReplacedbythenewArgstypeinterfaceBiBTransaction(BiBTransactionArgsargs).
NETSNorwayAS
Page38of43
12Appendices
12.1 Appendix A Status codes
12.1.1 Error codes
Error code
2011
6006
7001
Error code
2100
2101
2102
2103
2104
2105
2106
Description
Error when sending message
Baxi locked
Unknown Error
MsgRouter errors
MsgRouter Error Range starts with 2100, this code is not used.
General msgrouter error
Msgrouter timeout
Socket error
Message length error
Sending of message failed
Connection error
7005
7007
7008
7009
7010
7011
7012
7013
7015
Open rejected
Obsolete terminal version
No host contact.
No response from terminal
Create log directory fail
Open IO fail
Unexpected frame
Close rejected
Unknown terminal frame
12.1.2 Method reject codes

Method
Reject
code
Description
General cases
7100
7101
7102
7103
7104
Processing previous command

Unable to process
Already Open
Not Active
Terminal busy, administration
Property bad values

7401
7402
7403
7404
7405
7406
7407
7408
7409
7410
Log file prefix

Log file path
Host IP address
Vendor info extended
Trace level
Baud rate
COM port
Host port
Indicate EOT transactions
Cutter support
NETSNorwayAS
Page39of43
Method
Reject
code
7411
7412
7413
7414
7415
7416
7420
7421
7422
7423
7424
7425
7426
7427
Description
Printer width
Display width
Power cycle check
TID supervision
Auto get customer info
DeviceString
Terminal ready
UseDisplayTextID
MsgRouterIpAddress
MsgRouterOn
MsgRouterPort
DoNotSplitDisplayText
DisplayTextInLM
Function argument bad values

7501
7502
7503
7504
7505
7506
7507
7508
7509
7510
7511
7512
7513
7514
7515
7516
Only track 2 support

Invalid track length
Transfer amount invalid type
Transfer amount data too long
Transfer amount article details too long
Invalid operator ID
Invalid administration code
TLD unknown type
TLD bad field value
TLD could not build
Transfer amount PCC too long
Transfer amount PCC not alphanumeric
Transfer amount AuthCode too long.
Transfer amount AuthCode not alphanumeric.
JSON Bad field value
Transfer amount Optional Data too long.
NETSNorwayAS
Page40of43
12.2 Appendix B Sequence diagrams

12.2.1 Initialisation
12.2.2 Successful purchase
NETSNorwayAS
Page41of43
12.2.3 Unsuccessful purchase
NETSNorwayAS
Page42of43
12.2.4 Purchase with an error situation
NETSNorwayAS
Page43of43

BAXI

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

BAXI

Uploaded by

Copyright:

Available Formats

BAXI.

net Application Programmers

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

General work flow...................................................................6

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

General note on parameters..................................................13

General note on events..........................................................19

Common Use Cases............................................................26

Get encrypted card data........................................................31

Get encrypted card data and issuer ID....................................31

Send a track 2 card swipe to the terminal:..............................31

Check host connection...........................................................32

8.10 Set terminal language...........................................................32

Best practice implementation of security in the ECR interface.. .36

4 Procedures for using BAXI

General work flow

USB rs232 support

General note on parameters.

PARAMETER: TransferAmountArgs args

PARAMETER: AdministrationArgs args

2. On success, wait for OnDisplayText, OnPrintText,

PARAMETER: TransferCardDataArgs args

2. Call TransferCardData(). If the function returns 0,

RETURNS: 1 on success, sometimes local mode, depending on TLD tag range

byte[] wantedTldTag, byte[] tldBuffer, byte[] wantedTldTagValue

RETURNS: 1 on success, no local mode

General note on events

public delegate void DisplayTextEventHandler(object sender,

public delegate void PrintTextEventHandler(object sender,

public delegate void LocalModeEventHandler(object sender,

public delegate void BaxiErrorEventHandler(object sender, BaxiErrorEventArgs

public delegate void TLDReceivedHandler(object sender, TLDReceivedArgs args);

void OnJsonReceived(object sender, JsonReceivedArgs args);

public delegate void StdRspReceivedHandler(object sender,

public delegate void TerminalReadyEventHandler(object sender,

9 Common Use Cases

int result = Baxi.TransferAmount(a);

9.1.2 Return of goods

9.1.4 Purchase with Cashback

9.1.5 Balance inquiry

9.1.7 Cash withdrawal

9.1.8 Force Offline

Get encrypted card data

Get encrypted card data and issuer ID

Send a track 2 card swipe to the terminal:

TransferCardDataArgs a = new TransferCardDataArg();

Check host connection

9.10 Set terminal language

SendTldArgs a = new SendTldArgs();

9.11 Receive a card inserted status event

9.12 Get Customer Info

The ECR will always initiate a transaction with a GetCustomerInfo request to

The terminal will return the Customer Info to ECR

9.13 Get Customer Info with Admin Finish.

9.14 Investigating results of last financial transaction.

Best practice implementation of

11.5 SendTLD( string typeString, byte[] tldField)

11.6 TransferCardData( int trackType, string trackData)

11.7 BiBAdministration( int AdmCode, string OperID)

11.8 BiBTransaction( int amount, string transactionData)

12.1.2 Method reject codes

Processing previous command

Property bad values

Log file prefix