PointWareConnect

(PointTerminal)
Document Type
Version
Date
Confidentiality
By

: Technical Interface Specification

: 3.4.02
: 30-07-2012
: NONE
: Udvikling

This Document is the property of Point Transaction Systems A/S. It is transferred under the conditions of
Active Non-Disclosure.
Use of this document is subject to the terms of this NDA (Non Disclosure Agreement).
This document will be returned under request to Point Transaction Systems A/S.

PointTerminal OCX
Side 1

Index
1. POINTTERMINAL

2. INTERFACE

2.1 Types
2.1.1 Configuration id Types
2.1.2 Return Codes
2.1.3 Terminal Return Codes
2.1.4 Transaction Types
2.1.5 Currency Codes
2.1.6 Card Transaction Return Codes
2.1.7 Administration Types (functions)
2.1.8 Callback Types (event ids)
2.1.9 Token Data Types
2.1.10 Properties Command Types
2.1.11 Extended Amount
2.1.12 Key Entry of carddata

8
8
8
8
9
9
9
9
10
11
11
11
11

2.2. Methods
2.2.1 SetConfiguration
18. Contactless
19. SetAuthCode
2.2.2 OpenTerminal
2.2.3 CloseTerminal
2.2.4 DisconnectTerminal
2.2.5 CardTransaction
2.2.6 AbortTransaction
2.2.7 Administration
2.2.8 SelectAdministration
2.2.10 PreviousTransaction
2.2.11 AboutBox
2.2.12 VersionInfo
2.2.13 PrintFile
2.2.14 PrintLatestReceipt
2.2.15 GetLatestReceiptIndex
2.2.16 ReadToken
2.2.17 AdminProperties

12
12
18
18
19
20
20
21
23
24
25
27
27
27
28
28
28
29
29

2.3 Event interface

2.3.1 CallBack
EventID 0: Date ready for print.
EventID 2: Cardnumber available.
EventID 3: Set Amount (changing amount after receiving cardnumber).
EventID 4: Transaction result.
EventID 5: Set Amount Fee
EventID 6: Get Amount Fee
EventID 7: Get extra receipt information
EventID 8: Cardnumber and stan available
EventID 9: Transaction status
EventID 10: Dll timer event
EventID 12: Get Transaction Token Reference
EventID 13: Put Transaction Token Reference
EventID 14: Put Authorization Code
EventID 15: Terminal ID

31
31
32
32
32
32
33
33
33
34
34
34
35
35
35
36

PointTerminal OCX
Side 2

EventID 16: PreResult status

EventID 18: Administration result.
EventID 19: Change Extended Amount.
EventID 20: Receive Amount.
EventID 21: Change Currency.
EventID 255: Dialog Closing

3 HOW TO IMPLEMENT THE ACTIVEX CONTROL

3.1 ActiveX registration
3.2 Windows 64-bit

4. FLOW
4.1 Transaction Flow
4.2 External Card Transaction flow

36
37
37
37
37
39

40
40
40

42
42
43

APPENDIX A, PRINTING

45

APPENDIX B, CUSTOMISING DIALOGS.

46

APPENDIX C, TOKENS

47

APPENDIX D, TRACE

48

PointTerminal OCX
Side 3

1. PointTerminal
This section describes the interface between Point payment terminals using PointTerminal.
PointTerminal is an ActiveX control for application implementation in the Windows XP (32-bit)
environment, developed and supported by Point A/S, and its main purpose is to simplify the
interface to the SMASH/XENTA terminal, and comply with the PBS OTRS 2.5 specifications.
PointTerminal ActiveX interface handles the certification requirements regarding:
Populate and display terminal dialog-interfaces.
Enabling the user to abort a transaction.
Handles advanced issues like verify signature and advice transfer flag.
Handles token transactions e.g. Original Authorization transaction
Can optionally do the receipt printings.
Implements an optional transaction preresult callback to ensure the application is alive.
PointTerminal includes a method that can call user selected administrative functions.
In addition PointTerminal also include a management method that supports all administrative
functions available in the terminal.
The objective for PointTerminal is to give the ECR access to do the basics:
Make different types of transactions.
Handle administrative functions e.g. to do the end of day settlement.
Create reports
Handle printing and backup of receipts

PointTerminal OCX
Side 4

New since version 2.2.00

New methods VersionInfo, PrintReceipt, PrintLastReceipt, GetLatestBackupIndex.
Configuration of receipt backup.
Improved Autoprint (approved by PBS), with receipt backup, printer translation table, header
and footer.
User configurations of dialog buttons, backgrounds and colour.
New aboutbox.
Improved Open and No receipt state reported.
General code cleanup.
New since version 2.3.0.0
Stronger typelib added
Status dialog bitmap button status error corrected.
Gratuity bug corrected
New status dialog timeout set-up parameter.
CFileException report error bug corrected
Status dialog timeout configuration
New Forced Offline, Capture/Reversal NoPrint transaction types
New since version 2.4.0.0
New Key Purchase, Refund, Signature and Authorisation transaction types.
New Card Data Callback
Added index to Authorization Code Callback (ID14)
Method TransactionStatus renamed to PreviousTransaction
Changes to typelib definitions and additional receipt information
Secondary transaction result code in Callback (ID4) is hex as in the OTRS table.
DCC support
New since version 2.5.0.0
Minor bug fixes, additional Printer configuration.
Adding of File5 (Advice) functions
PCI DSS certification (key transactions removed, cardnumber (pan) X-padded)
New since version 2.5.3.0
Language support.
Support for PSAM handled MSC track2 local cards
Additional administrative functions and properties
New since version 3.0.00
Support for PSAM handled MSC track2 local cards
New since version 3.1.00
Typos corrected, administrative functions added, setCardData mandatory

New since version 3.3.00

Lock receipt discontinued.
KeyEntry of transaction type
Support for EIE

New since version 3.4.00

Removed descriptions of LOCK RECEIPT (INGEN KVITTERING) since this state no
longer appears from terminal SW version 3.4.

PointTerminal OCX
Side 5

PointTerminal OCX
Side 6

2. Interface
The ActiveX control communicates with the user ECR application using a dispatch map and a
number of methods and an event interface.

PBS
(Dialog)
ECR
Application

dll lib

Terminal

Control

Engine

ActiveX

Process Overview

The overview shows that the terminal connects to the ActiveX Engine part through the
FlexDriver.dll (implemented as a lib). The Engine communicates with the ActiveX Control part
through the dispatch map.
The Control part is controlled by the user ECR application through the methods, the event
interface, and handling of the dialogs.
Note that the Engine runs in its own windows thread (normal priority), and that the Control part
runs in the user ECR applications thread.
Since the dialogs are displayed in the user thread and are required to be displayed a number of
seconds; the user ECR application must make sure the Control code can execute proper.
With the addition of a stronger typelib from version 2.4.x.x, type check for e.g. transaction type,
administration functions and callback ids must be added to application code.
Some methods and functions require that the terminal is configured to include these. E.g. the
extra receipt information (binary receipt) is only transmitted from the terminal if configured to
transmit the extra overhead information. The terminal and/or NETS and/or the credit/payment
card do not support all transaction types. Consult Point, NETS and/or the card issuer for more
information.

PointTerminal OCX
Side 7

2.1 Types
2.1.1 Configuration id Types
typedef enum Configuration {
Connection=0,
Printing,
Card,
SetAmount,
DialogOkTimeout,
Trace,
GetAmountFee,
SetAmountFee,
ExtendedReceiptInfo,
GetStanPan,
Timer,
SetAmountGratuity,
PreResult,
ReceiptBackup,
DialogErrorTimeout,
PrinterQueueDelay,
SetExtendedAmount,
GetExtendedAmount,
Contactless,
SetAuthCode,
SetEIEdataReceived,
SetEIEdata2Host,
} ConfigurationType;
2.1.2 Return Codes
typedef enum ReturnCode{
OK=0,
NotOK,
} ReturnCodeType;
2.1.3 Terminal Return Codes
typedef enum TerminalReturnCode {
Success=0,
Error,
FileReadError,
PortInitError,
SwVersionError,
NoResponseError,
ComPortError,
DatalinkError,
InternalError,
CommunicationTimeoutError,
LicenceError,
ConnectError,
SystemError,
NoReceiptState=19,
(will not appear from terminal SW version 3.4)
GeneralError=255,
} TerminalReturnCodeType;

PointTerminal OCX
Side 8

2.1.4 Transaction Types

typedef enum TransactionType
{
DefaultTransaction,
ForcedPin,
ForcedSignature,
Refund,
Offline,
OriginalPinAuthorisation,
OriginalSignatureAuthorisation,
SupplementalAuthorisation,
Capture,
Reversal,
ForcedSignaturOffline,
OfflineRefund,
Cancellation,
} TransactionTypeType;
2.1.5 Currency Codes
typedef enum CurrencyCode {
DKK = 208,
// DK Kroner
ISK = 352,
// IS Kroner
JPY = 392,
// JP Yen
NOK = 578,
// N Kroner
SEK = 752,
// S Kroner
CHF = 756,
// SW Francs
GBP = 826,
// GB Pound
USD = 840,
// US Dollar
EUR = 978,
//
Euro
} CurrencyCodeType;
2.1.6 Card Transaction Return Codes
typedef enum CardTransactionReturnCode {
Started=0,
ReceiptFileExist=11,
TransactionTypeError= 12,
LocalCardOK=16,
LocalCardNotOK=17,
OCXStateError = 254,
GeneralOCXError = 255
} CardTransactionReturnCodeType;

2.1.7 Administration Types (functions)

typedef enum AdminFunc {
AdministrationError,
EndOfDay = 1,
EndOfDayLog,
TerminalReport,
TotalReport,
LogReport,
OldLogReport,
LastReceipt,
PointTerminal OCX
Side 9

UnlockReceipt,
(not relevant from terminal SW version 3.4)
PbsSync,
PointSync,
SendLog,
ClearDataStore,
ProgramDownload,
ParameterDownload,
PanTableDownload,
TlcmdbTableDownload,
TlcmdbTableRestore,
ContrastUp,
ContrastDown,
RestartTerminal,
BackLightOn = 23,
BackLightOff,
NetworkReport,
DccRatesReport,
GratuityReceipt,
DeleteDataStoreAdvice,
AdviceForward,
File5StatusReport,
UpdateDccRates = 33,
UpdatePSAM,
IpRoutingIdel
UpdateSalt,
PctReport,
TcsReport,
TpropsCVSreport,
EventReport,
Idle,
} AdministrationType;
2.1.8 Callback Types (event ids)
typedef enum CallBack {
DataForPrint=0,
AcceptCard=2,
ChangeAmount,
TransactionResult,
ChangeAmountFee,
ReceiveAmountFee,
ExtendedReceipt,
StanPan,
TransactionStatus,
TimerTick,
ChangeAmountGratuity,
GetAuthorisation,
PutAuthorisation,
StopList,
TerminalId,
TransactionPreResult,
DccAmount,
AdminResult,
ChangeExtendedAmount,
ChangeCurrency,
PointTerminal OCX
Side 10

EIEdataReceived,
EIEdata2Host,
DialogIsClosing = 255,
} CallbackType;
2.1.9 Token Data Types
typedef enum TokenData {
Tokendata,
AdditionalData,
DccData,
} TokenDataType;
2.1.10 Properties Command Types
typedef enum PropertyFunc
{
PropsNone,
PropsGet,
PropsPrereceipt,
PropsdeleteDataStoreAdvice,
PropsInternal,
PropsAdviceReport,
PropsSetBatchNumber,
} PropertyCommandType;
2.1.11 Extended Amount
typedef enum ExtendedAmount
{
AmountAmount,
AmountFee,
AmountGratuity,
AmountVat,
} AmountType;
2.1.12 Key Entry of carddata
typedef enum KeyEntryT
{
KeyEntryOff,
KeyEntryOn=0x80,
} KeyEntryType;

PointTerminal OCX
Side 11

2.2. Methods
The PointTerminal.ocx ActiveX component implements a number of methods derived from
Windows ActiveX (OLE) environment, like ProductName, ProductVersion, CompanyName, and
its own methods described in the following.

2.2.1 SetConfiguration
SetConfiguration transfers required configuration parameters to the ActiveX Control. The user
application must configure all mandatory parameters, before using other methods of the ActiveX
control; otherwise the control process will fail. The parameters are outlined below, and they are
explained in further details in subsequent section. Bold indicates default setting.
If the SetConfiguration function returns false (0), then the process logs the event and the
parameters in the trace file.
NOTE: To enable trace it is important that the SetConfiguration Trace option is called as the first
SetConfiguration call in the start of the application. Using the following sequence ensure that
trace files are valid:
SetConfiguration(1,0,c:\\kasseXXXpath\\bon.txt,);
SetConfiguration(5,6,,);
Other SetConfiguration calls.
Method:

SetConfiguration - configure

Prototype: Long <ActiveX object_>SetConfiguration (

Conf_Id As Long,
parm1 As Long,
parm2 As String,
parm3 As String )
Input: Conf_ID - configuration id as ConfigurationType
parm1
- configuration parameter
parm2
- configuration parameter
parm3
- configuration parameter
Return: as ReturnCode
0 configuration error
1 configuration success

Conf_ID.
0: Connection parameters.
Connection to terminal using Serial interface (RS232) or Ethernet (TCP/IP).
This parameter is mandatory.
parm1
parm2
parm3

= 1: connect using RS232, 2: connect using = Ethernet

= ComPort number or IP address
= Baudrate or TCP/IP Port (2000 is default)

Examples:
PointTerminal OCX
Side 12

<ActiveX object_>SetConfiguration(0,1,COM1,19200) connect using RS232 serial

connection using COM1, 19.200 baud, 8N1.
<ActiveX object_>SetConfiguration(0,1,COM15,11500) connect using USB serial
connection using COM15.
<ActiceX object_>SetConfiguration(0,2,192.168.0.53,2000) connect to terminal on ip
address 192.168.0.53 using tcp/ip protocol on port 2000.
1: Printer options.
Set options for printing of receipts. When enabled the ActiveX component handles the
receipt printing, releasing the user application of this duty. The ActiveX will backup the
latest 4 receipts by default (note that e.g. a signature transaction generates two receipts),
and supports a user defined translate and code table for simple control of POS printers.
See appendix A.
When disabled the user application has to print the receipts. Normally this is done when
a transaction is completed, and the receipt is available in the receipt file.
If the user application handles receipt printing, it must delete the print file after use, or
before starting a new transaction, otherwise starting a new transaction will fail.
If the ECR handles printing and a verify signature state is raised by PBS or the
terminal, then the application will receive events signalling that receipts are ready to be
printed. In this case the application must print the receipts, then delete the receipt file,
and then set the event status to 1 for successful printing.
This parameter is optional.
parm1 = 0: Autoprint disabled, 1: Autoprint enabled, 3: Autoprint enabled (no printer check)
parm2 = Full path and filename of the receipt file, c:\bon.txt
parm3 = Full Windows Printer name as defined in printer settings, ScreenPrint
Example:
<ActiceX object_>SetConfiguration (1,0,C:\MyApplicationDir\Bon.txt,\\networkprinter\Axiohm A794)

2: Card options.
The user application will receive the first eight digits of the card number and the crc as
an event during the transaction flow.
When set options for cards are enabled the user application can accept (return 1) or
reject the card number (return 0).
When disabled the ActiveX engine always replies accept to the terminal, and the PCI
padded cardnumber is saved in the specified card number file. This parameter is
optional.
parm1 = 0: card confirm disabled, 1= card confirm enabled.
parm2 = Full path and filename of card number file, c:\card.txt
parm3 = Not used
Example:
<ActiceX object_>SetConfiguration (2,1,C:\card.txt,)

PointTerminal OCX
Side 13

3: SetAmount.
Set options for transaction amount. If enabled the user application has the option to
change the transaction amount by returning a new amount value in event id 3.
This event arrives after the card number is available giving the option to change the
amount based on the card number and overrule the amount set in CardTransaction.
This parameter is optional.
parm1 = 0: set amount is disabled, 1: set amount is enabled.
parm2 = Not used
parm3 = Not used
Example:
<ActiveX object_>SetConfiguration(3,1,,)

4: TimeOutOK
Set dialog timeout of the transaction dialog for transaction OK (approved).
If not set the dialog will automatically close after 3 seconds.
If set to 0 (zero) the dialog will not close automatically. (See parameter 14 for timeout
when transaction not approved).
This parameter is optional.
parm1 = 3 (seconds).
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (4,3,,) (default 3 seconds)

5: Trace
Set trace options. If enabled trace files are generated.
PointOcxTrace2500.txt traces at the ActiveX level 1-3.
PtFxDrTr2300.txt traces on the dll level 2-3.
flxComTrace.txt traces the RS232/IP low level interface (if selected) 3.
Trace 4 enables traces trace files is reset by the OpenTerminal method.
Trace 5 enables traces appended to files (no reset).
Trace files are placed in the directory defined by printer options parm2.
This parameter is optional, but called as the first configuration parameter if used.
parm1 = 0: OCX Trace disabled (only PtFxDrTr2300.txt enabled, disable with 16)
1-3: Trace enabled,
4: Trace plus enabled (flxComTrace.txt append)
5: Trace plus append enabled (PointOcxTrace2500.txt append)
6: Trace plus (all files and append)
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (5,4,,)

PointTerminal OCX
Side 14

NOTE: The terminal must be configured to support trace ([FLXTRACE] in param.ini contact Point). For best result and traces for Point use Trace plus (4);

6: Get Amount Fee

Get amount fee options. If enabled the user application receives the fee calculated in the
terminal in event number 6.
This parameter is optional.
parm1 = 0: Get amount fee is disabled, 1: get amount fee enabled.
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (6,1,,)

7: Set Amount Fee

Set amount fee options. If enabled the user application can add a transaction fee,
overruling the fee generated by the terminal. The fee is returned in event number 5.
This parameter is optional.
parm1 = 0: Set amount fee is disabled, 1: set amount fee enabled.
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (7,1,,)
8: Get Extra Receipt Information
Get extra receipt information options. If enabled the user application receives extra
receipt information at the end of a transaction in event number 7.
Extra receipt information is also received on signature receipts and receipt copies.
This parameter is optional.
parm1 = 0: Get info disabled, 1: get info enabled.
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (8,1,,)

9: Get full card number and transaction reference

Get full card and transaction reference options. If enabled the user application receives
full card and transaction reference. The information is received in event number 8.
This parameter is optional.
parm1 = 0: Get info disabled, 1: get info enabled.
parm2 = Not used
parm3 = Not used
PointTerminal OCX
Side 15

Example:
SetConfiguration (9,1,,)
10: Get dll timer event
Get dll timer event implements a call-back from the low level communication layer in
event number is 10, and is intended to avoid total blocking in case of communication
errors (timeouts). If used the application must close and disconnect the terminal before
unloading the ocx object.
This parameter is optional.
parm1 = 0: Get timer event disabled, 1: get timer event enabled.
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (10,1,,)
11: Set Amount Gratuity
Set amount gratuity options. If enabled the user application can add a transaction
gratuity for OriginalSignatureAuthorization transactions in event number 11.
This parameter is optional.
parm1 = 0: Set amount gratuity is disabled, 1: set amount gratuity is enabled.
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (11,1,,)
12: PreResult option.
PreResult is used to tell the terminal that the user application (ECR) is alive before the
receipt is sent to the user application (ECR).
The application must send a response (161 decimal) to this event indicating alive;
otherwise the transaction will be rejected.
When disabled the ActiveX engine handles the response.
This parameter is optional.
parm1 = 0: preresult disabled, 1= preresult enabled.
parm2 = Not used
parm3 = Not used
Example:
<ActiceX object_>SetConfiguration (12,1,,)

13: Backup option.

PointTerminal OCX
Side 16

Backup is used to automatically backup receipts. Note that administrative reports (e.g.
terminal rapport) are treated as receipts.
If enabled the ActiveX will save a copy of the latest number of receipts in files named as
the receipt file concatenated with a number. If the receipt file is defined to, c:\bon.txt,
then the first backup file is c:\bon.txt1, next c:\bon.txt2 and so on.
At start-up the ActiveX will first overwrite the oldest backup file. The index to the latest
backup file is found using the GetLatestReceiptIndex() method.
If Autoprint is selected the minimum number of backupfiles is 4.
This parameter is optional.
parm1 = 0: Backup disabled, 1= backup enabled.
parm2 = Number of backups.
parm3 = Not used
Example:
<ActiceX object_>SetConfiguration (13,1,8,)

set backup to 8 files.

14: TimeOutError
Set dialog timeout of the transaction status dialog if an Advice is received.
The status dialog will automatically close after the specified time in seconds if set. If not
set the dialog will not close automatically.
This parameter is optional.
parm1 = 6 (seconds).
parm2 = Not used
parm3 = Not used

// 6 is specified in OTRS

Example:
SetConfiguration (14,6,,) (0 not allowed)

15: Printer Queue Delay

Set the delay for printing. If configured to handle receipt printing the ActiveX will test the
Windows print queue by sending an empty receipt before the actual receipt.
It will suspend operation (default 1000 milliseconds) between the two receipts to allow
the print queue to update.
This parameter is optional, if not set the default is 1000 milliseconds
parm1 = 1000 (1 second).
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (15,2000,,)

PointTerminal OCX
Side 17

16: Set Extended Amount

Set extended amount options. If enabled the user application can add extended
amounts (e.g. vat) 20.
This parameter is optional.
parm1 = 0: Set extended amount is disabled, 1: set extended amount is enabled.
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (16,1,,)
17: Get Extended Amount
Get extended amount options. If enabled the terminal will send amounts (e.g. user
entered gratuity) to the application.
This parameter is optional.
parm1 = 0: Get extended amount is disabled, 1: Get extended amount is enabled.
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (17,1,,)
18. Contactless
Support contactless transactions.
This parameter is optional.
parm1 = 1: Contactless enabled. 0: disabled
parm2 = Not used
parm3 = Not used
Example:
SetConfiguration (18,1,,)
19. SetAuthCode
Set authorization code (from PBS)
This parameter is optional. If used callback StopList is not activated.
parm1 = 0:
parm2 = <code>,<type>
parm3 = Not used
Example:
SetConfiguration (19,0,123456,0,)

PointTerminal OCX
Side 18

2.2.2 OpenTerminal
OpenTerminal connects the ActiveX control to the terminal and opens it, i.e. the terminal
displays change from Lukket to Terminalen er klar.
Best practice is that the application keeps track of the connection status of the terminal, and
issues the correct method sequence: OpenTerminal, CloseTerminal and DisconnectTerminal.
Its important in error handling situations not to include these methods in program loops.
(Note that if the terminal is not connected when the OpenTerminal function is called, then the
PointTerminal automatically tries to connect to the terminal). See Appendix C.
Method:

OpenTerminal -

Prototype: Long <ActiveX object_>OpenTerminal ()

Input: Return:

as TerminalReturnCode
0 Connect/open successful
1 file error
2 file read error
3 Port initialising error
4 Software not compatible
5 Terminal not responding
6 Com port already open error
7 Datalink error (no connection)
8 Internal function error
9 Communication timeout
10 Connect licence available in terminal
11 Internal connect error
12 System Error (e.g. No PSAM)
19 Terminal Open but in No receipt state (not relevant
from terminal SW version 3.4)
255 - General internal OCX connect/open error

PointTerminal OCX
Side 19

2.2.3 CloseTerminal
CloseTerminal closes the terminal, i.e. the terminal display change from Terminalen er klar to
Velkommen.
Method:

CloseTerminal

Prototype: Long <ActiveX object_>CloseTerminal ()

Input: Return:

as TerminalReturnCode
0 Connect/close successful
1 Connect/close error.
12 SystemError (e.g. no PSAM)

2.2.4 DisconnectTerminal
DisconnectTerminal disconnects the ActiveX control from the terminal, i.e. the terminal display
change from Velkommen to Lukket.
Method:

DisconnectTerminal

Prototype: Long <ActiveX object_>CloseTerminal ()

Input: Return:

as TerminalReturnCode
0 Disconnect successful
1 Disconnect error
12 SystemError (e.g. no PSAM)

PointTerminal OCX
Side 20

2.2.5 CardTransaction
CardTransaction is the method to initiate and start a payment transaction.
Transaction type 0, 2, 3, 4, and 10 are mandatory. If KeyEntryOn is added to the transaction
type, the terminal will ask for card data card number, expiration date and card verification.
Method:

CardTransaction

Prototype: Long <ActiveX object_>CardTransaction (

type As Long,
amount As Long,
currency As Long,
ref As Long )
Input: type
- transaction type as TransactionType
amount - transaction amount
currency - currency code as CurrencyCode
ref
- user application reference number
Return:

as CardTransactionReturnCode
0
Transaction started successful
11 Receipt file exist
12 transaction type not valid
254 OCX state error
255 General OCX state error.

type:
The following transaction types are supported for the debit/credit applications.
The OCX translates the type to defined OTRS transaction-type and merchant-initiative.
See the OTRS 2.5 specification for further descriptions of transaction-type, merchant-initiative
and transaction tokens.
0: Default EMV Transaction
Transaction-type = 0x00, merchant-initiative = 0x00
1: Forced PIN Transaction
Transaction-type = 0x00, merchant-initiative = 0x81
2: Forced Signature Transaction
Transaction-type = 0x00, merchant-initiative = 0x82
3: Refund Transaction
Transaction-type = 0x01, merchant-initiative = 0x00
4: Offline Transaction
Transaction-type = 0x00, merchant-initiative = 0x60
5: Original PIN Authorization Transaction
Transaction-type = 0x02, merchant-initiative = 0x00
6: Original Signature Authorization Transaction
Transaction-type = 0x02, merchant-initiative = 0x82
PointTerminal OCX
Side 21

7: Supplemental Authorization Transaction

Transaction-type = 0x03, merchant-initiative defined by transaction token
8: Capture Transaction
Transaction-type = 0x04, merchant-initiative defined by transaction token
9: Reversal Transaction
Transaction-type = 0x05, merchant-initiative defined by transaction token
10: Forced Offline Signature Transaction
Transaction-type = 0x00, merchant-initiative = 0xE2
11-18: For internal use

19: Offline refund

Transaction-type = 0x01, merchant-initiative = 0x60
20: Cancellation
Transaction-type = 0x06, merchant-initiative = 0x00
Amount:
Amount is always a positive value in the smallest currency unit (re for DKK). Its recommended
that the application do not use float or double value.

Currency:
ISO 4217 Currency code:
DKK = 208
ISK = 352
JPY = 392
NOK = 578
SEK = 752
CHF = 756
GBP = 826
USD = 840
EUR = 978

// DK Kroner
// IS Kroner
// JP Yen
// N Kroner
// S Kroner
// SW Francs
// GB Pound
// US Dollar
// Euro

If the transaction is started successful the immediate return code is 0, then the final transaction
result is returned in the CallBack event function with eventId 4.
NOTE: It is important that the ECR implementation do not display dialogs during the transaction.

PointTerminal OCX
Side 22

2.2.6 AbortTransaction
AbortTransaction is the method for the user application to abort a transaction previously started
with the CardTransaction method. Only during the first part of the transaction flow, aborting is
possible. This method is handled by the ActiveX control status dialog, and only exposed to the
user application for historical reasons.
Method:

AbortTransaction -

Prototype: boolean <ActiveX object_>AbortTransaction ()

Input: Return:

true
false

operator wish to abort

operator wish not to abort

PointTerminal OCX
Side 23

2.2.7 Administration
Administration is the method for the user application to initiate administrative functions on the
terminal. All the listed administrative functions are implemented in this method.
Functions 1, 12 and 20 are mandatory in the user application. The rest are optional but consider
which ones are practical for everyday use.
Method:

Administration -

Prototype: Long <ActiveX object_>Administration (Function As Long)

Input: function administrative function as AdministrationType
Return:

as ReturnCode
0 function successful
1 function error
65539 Terminal in No receipt state (not relevant
from terminal SW version 3.4)

Function:
1 :
2 :
3 :
4 :
5 :
6 :
7 :
8 :
9 :
10 :
11 :
12 :
13 :
14 :
15 :
16 :
17 :
18 :
19 :
20 :
21-22:
23 :
24 :
25:
26:
27:
28:
29:
30:
31:
32:
33:
34:
35:
36:
37:

Do a advice transfer, also known as an end of day transaction.

Same as in function 1, but with a transaction log attached.
Get Terminal Report.
Get the current transaction totals sumarized per card- and currency type.
Get the current transaction log.
Get the previous transaction log.
Get last receipt from terminal.
Get last receipt and unlock terminal (not relevant from terminal SW version 3.4)
Do clock syncronisation towards PBS.
Do clock syncronisation towards Point.
Send the different logs to Point for further analysis.
Clear (delete) the datastore. Irrevisible - must be password protected.
Download new program version if any.
Download terminal configuration parameters.
Download local Card Pan table.
Download TLCMDB configuration settings.
Restore TLCMDB to the default settings.
Set contrast on PinPad (terminal) up
Set contrast on PinPad (terminal) download
Restart terminal
Not used.
Turn on backlight on PinPad (terminal)
Turn off backlight on PinPad (terminal)
Get Network Report
DCC Rates Report
Gratuity receipt
Delete Data Store Advice
Advice Forwarding
File5 Status Report
Install/Update PSAM (ip routing and timer callback active)
Not used
Update DCC Rates
Update PSAM
Update Fee table
Ip Routing Idle (used with ip routing and update)
Update SALT (used with e-kvittering)

PointTerminal OCX
Side 24

38:
39:
40:
41:
42:

Pct Report
Tcs Report
Tprops CVS report
Print EventReport
Idle

NOTE: It is important that the implementation do not display dialogs during an administrative
procedure. If extra receipt information is enabled its event will include information for function 7
and 8, and zero for functions creating reports.
RECOMENDATION: Install all functions its a great help during instalation and in case of service
on a terminal. Hide the more technical functions from the daily user, allowing only superusers,
service users or tech. users access to all functions.
2.2.8 SelectAdministration
The SelectAdministration method implements the selection of an administrative function listed
above, as a dialog including a combo-box list that include all administrative functions.
Implementing this function unlocks all administrative functions for the user.
Use the Administrative method if some administrative functions should remain locked (password
protected) for the user.
Method:

SelectAdministration

Prototype: Long <ActiveX object_>SelectAdministration ( )

Input: Return:

as AdministrationType
0 - no or nonexistent function selected
Selected function as listed above.

RECOMENDATION: Always password protect this function, only super users, service users or
tech. users, should be allowed to access all administrative functions.

PointTerminal OCX
Side 25

2.2.9 CompleteExtCardTransaction
The CompleteExtCardTransaction method completes an external (local) card transaction.
Method:

CompleteExtCardTransaction

Prototype: Long <ActiveX object_>CompleteExtCardTransaction(result As Long)

Input: result - 0 approves the transaction
1 rejects the transaction
Return:

as ReturnCode
0 - method completed successful
1 - method not completed successful

PointTerminal OCX
Side 26

2.2.10 PreviousTransaction
The PreviousTransaction method (called TransactionStatus in earlier versions) returns the
status of a previous transaction.
This method is used in conjunction with the SetConfiguration id 9, Get card number and
transaction reference.
For terminals configured with PSAM version 50 and later, data of the last eight approved
transactions are saved in the PSAM. The data of these transactions are retrieved using the
unique transaction reference (stan), as search key.
The data are returned as event, CallBack, id 9.
Method:

PreviousTransactionStatus -

Prototype: Long <ActiveX object_>PreviousTransaction(keyT As bool, key As String)

Input: keyT - 1 key is stan
Return:

as CardTransactionReturnCode
0
Command started successful
12 KeyT error
254 OCX state error
255 General OCX state error.

2.2.11 AboutBox
AboutBox displays the About dialog with version information.
Method:

AboutBox -

Prototype: Void <ActiveX object_>AboutBox()

Input: Return:

2.2.12 VersionInfo
The VersionInfo method returns the version number of the ActiveX as an integer, where the
most significant 8 bits is the product version MS, etc. E.g. version 2.3.0.0 is returned as hex
value 0x02030000, or decimal 33751040.
Another method to get version information is to use the inherited windows method
ProductVersion that returns a string with version information.
Method:

VersionInfo -

Prototype: Long <ActiveX object_>VersionInfo()

Input: Return:

version as integer

PointTerminal OCX
Side 27

2.2.13 PrintFile
The PrintFile method is active when Autoprint is enabled. Use PrintFile to print a generated
receipt or report file. The file encoding shall be in the ISO-8859-15 format.
Method:

PrintFile Prototype: Long <ActiveX object_>PrintFile(filename as String, Header

as String, Footer as String)

Input: filename - name of receipt file to print

Header - Header to add to print
Footer - Footer to add to print
Return:

true method successful

false error

2.2.14 PrintLatestReceipt
The PrintLastReceipt method is active when Autoprint is enabled, or when Backup is configured.
The receipt is always printed with the Header **** KOPI ****.
Method:

PrintLastestReceipt Prototype: Long <ActiveX object_>PrintReceipt(Index as integer, Footer

as String)

Input: Index
- index to backup receipt file (0 for all)
Footer - Footer to add to print
Return:

true - method started successful

false error

2.2.15 GetLatestReceiptIndex
The GetLatestReceiptIndex method returns the index to the latest receipt backup.
Method:

GetLatestBackupIndex -

Prototype: Long <ActiveX object_>GetLatestBackupIndex()

Input: Return:

latest backup index as integer

PointTerminal OCX
Side 28

2.2.16 ReadToken
The ReadToken method reads a token from a file and returns its data as a comma-separated
string. The token is identified by its filename not its reference number. See Callback event id 12.
Get Token reference number for an explanation about token reference and token filename.
Method:

ReadToken Prototype: ReadToken (what TokenDataType, TokenFile as String) as

String

Input: what
Tokendata returns data from token format:
<type>,<ver>,<pan|aid>,<amount>,<curr>,<exp>,<VPKca>,
<VK>,<ALGH>,<Merchant>,**
AdditionalData returns additional data from token format:
<pan>,<cvm>,<OriginalRef>,
DccData returns dcc data from token (if any)
<dccamount>,<dccamountfee>,<dccamountextra>,
<dcccurr>,<exp>,<dccrate>,<clerkid>,
tokenfile filename of token

Return:

string (empty string if token not found or error)

Example:
TokenData: 'EMV,1,A0000000031010,457,USD,2,02,01,01,0107601100,'
AdditionalTokenData: '4761739001010010,4,000468,'
DccData: '1903,0,0,DKK,2,0.1880,0,'
** See OTRS for more information

2.2.17 AdminProperties
The AdminProperties method extends the Administration method and is used when it is
necessary to get or set properties.
Method:

AdminProperties Prototype: Long AdminProperties (cmd PropertyCommandType, Props as

String)

Input: cmd
Props for cmd
PropsGet
PropsPrereceipt
PropsDatastore

- csv ascii string

: : <AMOUNT>,<CURRENCYCODE>
: <PSAMID>,<RECORDID>,<FILENUMBER>,<STAN>

PointTerminal OCX
Side 29

PropsInternal
PropsAdvice
PropsSetBatchNumber
PropsSendEventLog
PropsRemoveEventLog

:
:
:
:
:

<PARAM1>,<PARAM2>,..,<PARAMX>
<ADVICE_FILE_INDEX>
<BATCHNR>,<CURRENCY or DCC>
<IPADDRESS>
<IPADDRESS>

Return: ReturnCodeType

PointTerminal OCX
Side 30

2.3 Event interface

The ActiveX component supplies only one event interface.
2.3.1 CallBack
Communicates from the ActiveX component is done using an event interface.
The interface is a Call-back function labelled CallBack.
In the ActiveX control this function is presented as an event related to the control in the form.
Method:

CallBack - event interface

Prototype: Private Sub <ActiveX object_>CallBack (

ByVal EventID As Long, as CallBackType
ByVal Code As Long,
ByVal Text As String,
pResult As Long )
Input: EventID - unique event id
Code
Text
- variable contains any text related to the
specific event.
pResult - return value to <ActiveX object> from user
application

Not all events are optional. In any case all events must give a return (pResult) value, e.g. use
default or else in select or switch statements, and return 1 if not otherwise stated.
An implementation using a select (or switch) statement is recommended.
In this VB example a DoEvents is called to avoid blocking other threads.
Private Sub PointTerminal1_CallBack( _
ByVal eventID As Long, _
ByVal code As Long, _
ByVal text As String, _
pResult As Long)
On Error Resume Next
DoEvents
Select Case eventID
Case 0 'Data ready for print
Case 2 'PCI padded Cardnumber available
.
Case 255 'Dialog is closing
Case Else
End Select
Exit Sub
ErrorHandler:
End Sub

PointTerminal OCX
Side 31

EventID 0: Date ready for print.

A receipt is ready to be printed, and placed in the specified file. The file must be
removed before starting a new transaction. If AutoPrint is selected then this event is not
used.
Text contains a copy of the receipt, as in the specified file.
Code equal 1: all receipts received; 3: - received receipt needs (signature) verification.
pResult is set to 1 if the receipt is accepted (its mandatory to print the receipt before
returning pResult), and to 0 if not.
EventID 2: Cardnumber available.
The event is used to return the cardtype, cardnumber and crc (card reconciliation code)
to the user application. For EMV transactions only the first 8 PCI padded digits of the
card number is available. The crc can be used to select a transaction fee.
If CardConfirm is configured to active, the application can accept or reject the card.
Text contains the PCI padded cardnumber; CRC (Card Reconciliation Counter id)
Code is 0 if the card is a PBS handled card type. In this case pResult is set to 1 if the
cardnumber is accepted and the transaction continues, if set to 0 the transaction is
aborted.
Code is 1 if the card is perceived as a local card, and the intention is that the backend
system does the subsequent transaction processing.
In this case pResult is set to 1 to accept the cardnumber. Note that in this case after the
transactions is completed the CompleteExtCardTransaction is must be called to
complete the local card transaction.
If pResult is set to 3 then cardholder is asked to confirm the amount on the terminal
display, and the transaction is completed when this confirmation is done.
pResult set to 0 aborts the transaction.
EventID 3: Set Amount (changing amount after receiving cardnumber).
If Set Amount is configured to active, this event is used to return the amount of the
transaction, by setting pResult to the amount. This amount value will overrule the value
given in the cardtransaction function, and is mandatory if SetAmount is configured
active.
EventID 4: Transaction result.
Result code of the transaction. Se also result codes for CardTransaction.
Text can contain a secondary result code.
Code holds the result code of the transaction.
0 : transaction successful
1 : transaction not successful
16: local card transaction started with success
17: local card transaction
text:
If present text is either a transaction return code from PBS, or a system specific return code
from the driver/terminal. The PBS specific return codes are a long range of codes like a hexnumber for Incorrect PIN (1221), Stolen Card (1509), etc. These codes are not
documented in the OTRS documentation for ASW1 ASW2 - and PSAM status codes.
PointTerminal OCX
Side 32

System codes:
0x10000 (65536) Unknown error
0x10001 (65537) Terminal is not ready
0x10002 (65538) Connection is broken (unconnected)
0x10003 (65539) Terminal in no receipt state, not relevant from terminal SW version 3.4.
If code is 0 then the transaction completed successfully, but the
receipt is missing or not printed.
0x10004 (65540) Software is not compatible and the transaction not started
0x10005 (65541) No licence in terminal. Contact Point Customer Service
0x10006 (65542) Error in token transaction
0x10008 (65544) System error
0x10009 (65545) Internal state error
0x1000a (65546) Error in token
0x1000b (65546) Ip routing error (cannot connect)
Remark
As an option the PointTerminal can play a wav file in the transaction flow:
SoundOK.wav will play in case of a successful transaction.
SoundError.wav will play in case of a unsuccessful transaction.
SoundAlert.wav will play in case of question in the dialog during the transaction.
That is also the case of a advice transfer flag or verify signature request.
The sound files are optional, and only played if present in the same directory where the
ActiveX is excecuted.
EventID 5: Set Amount Fee
If Set Amount Fee is configured to active, this event is used to return the fee amount of
the transaction, by setting pResult to the fee amount. This amount value will overrule
the fee amount calculated by the terminal. The function is mandatory if SetAmountFee is
configured active.
EventID 6: Get Amount Fee
If Get Amount Fee is configured to active, this event returns the fee amount calculated
by the terminal, to the user application. The fee amount is presented as an ASCII string
in text, e.g. 50.
EventID 7: Get extra receipt information
If Get Extra Receipt Info is configured to active, this event returns extra receipt
information, to the user application. The information is returned as a separated string (;)
in text and includes the following tokens for each receipt:
Timestamp - Timestamp (the OCX time of transaction) yyyy-mm-dd hh:mm
PAN,
- PCI padded card number (primary account number)
Total,
- Total amount in smallest currency unit in merchant currency
Extra,
- Extra amount in smallest currency unit (not used)
Fee, - Fee amount in smallest currency unit in merchant currency
Gratuity, - Gratuity amount in smallest currency unit in merchant currency
Currency,- ISO 4217 Currency code if dcc the selected currency code
STAN, - Unique transaction reference number
PSAMCrator - PSAM Creator
PointTerminal OCX
Side 33

PSAM, - PSAM id
Action Code, - Transaction result code
Asw1Asw2 - PSAM return code
Cvm Status, - Cardholder verification method see EMV specs
Aut. Code, - PBS authorization code
Card Name, - Card name
Term Id, - Terminal identification number
Number, - Merchant PBS number
Name, - Merchant name
City, - Merchant city
Address, - Merchant address
Zip,
- Merchant zip code
Phone, - Merchant phone number
cvr,
- Merchant cvr number
Ref. Nr.
- User application reference number supplied with the CardTransaction method.
DCCrate - DCC rate if dcc used else rate is 1.0000.
CRC
- Card reconciliation number
Batch
- batch number
Cancel - cancellation of current transaction allowed or not
Vat
- Vat amount (if active) in merchant currency
eReceipt E receipt token (if active)
Note that the terminal must be configured to send extra receipt information, and that rejected
transactions creating no receipts generates empty strings, e.g. 1970-01-01 01:00;;0;0;0;0..

EventID 8: Cardnumber and stan available

If get Cardnumber and stan is configured to active, this event returns the PCI padded
cardnumber and the unique transaction reference number, stan, as a separated ASCII
string (;) in text.
stan,
- unique transaction number (issued by the psam) (System Trace Audit Number)
cardnumber - PCI padded cardnumber
timestamp - transaction time stamp received from PBS as DTHR (YYMMDDHHMM)
EventID 9: Transaction status
Result of the PreviousTransaction method.
If pResult is 0 the transaction was found in the PSAM and transaction data are returned
as a separated ASCII string (;) in text (e.g. 000100;1024;0208;02;0502281010) with
the following:
stan - unique transaction reference number, e.g. 000100
amount
- amount, e.g. 1024
currency - currency code, e.g. 0208 for DKK
exponent - currency exponent, e.g. 02 for DKK
timestamp - PBS transaction time stamp as DTHR, e.g. 0502281010 for 2005-08-22 10:10

EventID 10: Dll timer event

If the Dll timer event is configured to active, this event is used to interrupt the ActiveX
during timed functions in the low level interface to the terminal (see dll documentation).

PointTerminal OCX
Side 34

EventID 11: Set Amount Gratuity

If Set Amount Gratuity is configured to active, this event is used to return the gratuity
amount of the transaction, by setting pResult to the gratuity amount. The method is
mandatory if SetAmountGratuity is configured active. Note that the terminal must be
configured to use gratuity. Consult OTRS for more information on gratuity.
EventID 12: Get Transaction Token Reference
Some transactions output a transaction token e.g. performing an Original Authorization
outputs a token that is needed when a Capture of the transaction is performed (more
information in OTRS 3.3). This method is mandatory if performing token transactions.
Note that the terminal must be configured to use tokens.
The OCX stores the Tokens on the disk in the directory defined by SetConfiguration,
Printer options parm2 (default dir is C:\).
The file name of the token is made from the terminal id and the transaction reference
number (stan), e.g. 0099075_000200.tok, from terminal id 0099075, transaction
reference 000200.
The transaction reference number is also printed on the transaction receipt.
The event returns information about the token (a separated string)
e.g 000200;C:\0099075_000200.tok;1000;0208
TokenID, - unique reference to the token (transaction reference number (stan).
TokenFileName, - the full filename of the saved token
Amount,
- the original token amount
Currency - the currency code of the original token amount
It is the responsibility of the application to save this information for later retrieval of tokens.
CallBack pResult is set to 1.
If a token issued from one terminal id is used (e.g. with Capture) on a terminal with
another id, the token filename must me renamed to conform to the new terminal id.

EventID 13: Put Transaction Token Reference

Performing transactions that require a token as input (the card need not be present) will
generate this event ID 13. The TokenID (received in get Transaction Token event id 12,
and converted to a Long) shall be returned in the CallBack pResult.
This method is mandatory if performing token transactions.
EventID 14: Put Authorization Code
Performing an offline transaction will require that an Authorization Code is returned in
this event ID 14. The Authorization Code is issued by PBS, and a good practice is to get
the code before the transaction is started.
The code is six characters (a-z, A-Z , 0-9 and space) and two character status
separeted by comma (,) returned to the OCX by nine successive CallBack with event
ID 14, each returning one of the nine character in pResult, starting with the most
significant character.
Text holds the index (1 to 9) indicating which character in the string to return.
E.g if the code is TAST26,80 return T in the first CallBack.
The method also supports rejection of transaction if the ECR after stop list lookup return
the required status code, and it is mandatory if performing offline transactions. Consult
OTRS for more information of Authorization Code and Status codes.
See SetConfiguration SetAuthCode
PointTerminal OCX
Side 35

EventID 15: Terminal ID

The OpenTerminal() function if successful generates this event ID 15 with information
about the connected terminal ID, an eight character string, eg. 00990075, and other
properties in a comma separated string. (Contact Point for detailed info).
Text holds the connected terminal id and properties with this format:
<TERMINALID>,<RECEIPTTYPE><GRATUITYMODEL>,<DCC>,<TOKEN>,
<PREPAID>,<DUMMY>,<OFFLINE>,<IP ROUTING>,
<MERCHANTNUMBER>,<MERCHANTNAME>,
<MERCHANTCITY>,<MERCHANTADDRESS>,<MERCHANTZIP>
<MERCHANTPHONE>,<MERCHANTBRN>,<TRACE>,<LANGUAGE>,
<VAT>,<USERINPUT>,<COUNTRY>,<DEFAULTCURR>,<CONTACTLESS>,
<TERNINALTYPE>,<DCCMARKUP>,<TCS>,<TAPAVERSION>,<CDP>,
<PSAMCDP>,<HARDWARENAME>,<EIE>,<PSAMEIE>,<PSAM_IE_NONEMV>,
<PSAM_IE_EMV>,<PSAM_IE_TOTALNONEMV>,<PSAM_IE_TOTALEMV>
if terminalid is 00000000 the terminal id is unknown, or the connection failed.

EventID 16: PreResult status

Code is set to
0x00 (0) Success
0x01 (1) Success signature/refund transaction - operator accepted signature
0x80 (128) Rejected by PBS/PSAM
0x81 (129) Rejected signature/refund transaction operator rejected signature
0x82 (130) Rejected Other reasons
pResult must be set to 0xA1 (161 decimal) at all times to inform the terminal that the
user application is still alive. No matter the value of Code.
This method is mandatory if PreResult is enabled.

EventID 17: DCC amount

This callback is only valid if DCC is used and selected. (Consult Point for information
about DCC).
Code:
Amount;
Text:
<amount>,<currency>,<exp>
where:
<amount> is the converted DKK amount to the selected currency
<currency> is the selected currency
<exp> exponent of the selected currency
PointTerminal OCX
Side 36

e.g.: "1000,USD,2"

// USD 10.00

EventID 18: Administration result.

Result code of an administration command.
Text can contain a secondary result code.
Code holds the result code of the administration command
0 : successful
1 : not successful
text:
If present text is either a transaction return code from PBS, or a system specific return code
from the driver/terminal.
EventID 19: Change Extended Amount.
Terminal asks for an (extended) amount e.i. gratuity, fee, vat.
Code holds the extended amount type ExtendedAmount
pResult returns the amount;
EventID 20: Receive Amount.
Terminal sends an (extended) amount e.i. gratuity entered by user
Code holds the extended amount type ExtendedAmount
text holds the amount e.g. 2000;208 (20.00 DKK)
EventID 21: Change Currency.
Terminal asks for currency change (active with Change Extended Amount).
pResult returns the currency code (e.g. 208 for DKK)

PointTerminal OCX
Side 37

EventID 22: EIEdataReceived.

If the terminal is configured to use Extended Issuer Envelope (EIE) and PSAM version >
71.008 transaction flow will generate EIE data from the Issuer to the ECR.
The OCX stores the EIE data on the disk in the directory defined by SetConfiguration,
Printer options parm2 (default dir is C:\).
The file name of the EIE data is ReceivedEIEdata.eie
Format of the binary ReceivedEIEdata.eie file
struct
{
byte resp_mode; // 0x00 Empty not used allow memset 0x00 to be used
// 0x01 Request - Append EIE to PSAM
//
(PSAM start with empty EIE)
// 0x02 Advice - Clear EIE in PSAM before update with this
// 0x03 Advice - Append to EIE hold by PSAM
// 0x04 Advice - Clear EIE in PSAM only
// 0x05 - Request - Clear EIE in PSAM only
// 0x06 Response from Host to the Request EIE
int length_ie; // Length of SW IE part of data
int length_eie; // Length of EIE part of data
byte data[512]; // 0..length_ie+length_eie
} PACKED EIE_DATA_BLOCK; // Extended Issuer Envelope Data Block

Length might be just long enough to hold 1+4+4+length_ie + length_eie bytes or up to

521 bytes.
Observe: length_ie and length_eie is stored as little-endian.
TAGlength in data as big-endian.

It is the responsibility of the application to save this information for later retrieval of tokens.
CallBack pResult must be set to 1.
See OTRS 3.3 and Issuer documentation for more details.
This method is mandatory if performing EIE transactions.

PointTerminal OCX
Side 38

EventID 23: EIEdata2Host.

If the terminal is configured to use Extended Issuer Envelope (EIE) and PSAM version >
71.008 transactions will generate this event ID 23.
The OCX retrieve the data to be send to the Issuer from the file EIEdata2Host.eie the
ECR place on the disk in the directory defined by SetConfiguration, Printer options
parm2 (default dir is C:\). File EIEdata2Host.eie must be written before returning with
pResult set to 0x01.
Format of the binary EIEdata2Host.eie file
struct
{
byte resp_mode; // 0x00 Empty not used allow memset 0x00 to be used
// 0x01 Request - Append EIE to PSAM
//
(PSAM start with empty EIE)
// 0x02 Advice - Clear EIE in PSAM before update with this
// 0x03 Advice - Append to EIE hold by PSAM
// 0x04 Advice - Clear EIE in PSAM only
// 0x05 - Request - Clear EIE in PSAM only
// 0x06 Response from Host to the Request EIE
int length_ie; // Length of SW IE part of data
int length_eie; // Length of EIE part of data
byte data[512]; // 0..length_ie+length_eie
} PACKED EIE_DATA_BLOCK; // Extended Issuer Envelope Data Block

Length must be just long enough to hold

1+4+4+length_ie + length_eie bytes or up to 521 bytes
Observe: length_ie and length_eie is stored as little-endian.
TAGlength in data as big-endian.
It is the responsibility of the application to save this information for later retrieval of tokens.
The event will be called more times during a transaction;
First time will be data to be sent to the Issuer in the transaction request.
After event EIEdataReceived it will be data to be send to the Issuer in the transaction
advice.
See OTRS 3.3 and Issuer documentation for more details.
This method is mandatory if performing EIE transactions.

EventID 255: Dialog Closing

If a dialog in the OCX was called, usually using the CardTransaction or Administration
method, this event ID 255 is generated when the dialog is closing, e.g. Cancel or OK is
pressed, or when the defined dialog timeout expires (e.g. 6 seconds).
This event indicates when it is safe to display dialogs for the ECR application.

PointTerminal OCX
Side 39

3 How to implement the ActiveX Control

PointTerminal.ocx ActiveX is build using Microsoft Visual C++ 2005 77626-009-0000007-41206
32-bit.
3.1 ActiveX registration
To install PointTerimnal.ocx copy the file to an existing directory on your hard disk.
Chose Start Run and type cmd. In the command window type:
copy PointTerminal.ocx c:\Program Files\PointWare\*.*
where c:\Program Files\PointWare\ is the path of your choice.
You can choose to install the file in the same directory as your application, and it self register
when your application connects to it.
Note that windows searches cwd (current working directory), then whatever is in the register
database, or the system32 directory; (consult Windows documentation for more information of
registering an ActiveX component).
Do not rename the file.
If you want to manually register the ActiveX control element in Windows for use in your SDK
(software development kit), use the Regsvr32.exe program.
Chose Start Run and type cmd. In the command window type:
Regsvr32 c:\Program Files\PointWare\PointTerminal.ocx

To remove the ActiveX from Windows registry use

Regsvr32 /u c:\Program Files\PointWare\PointTerminal.ocx
Consult the Windows documentation for more information about registrations.

3.2 Windows 64-bit

Using the ocx in a 64-bit environment make sure your application is build for the x86 platform.

PointTerminal OCX
Side 40

3.2 Including the ActiveX Control element in the development project

Add a reference to the ActiveX Control element in your application.
In MS Visual Basic select the Project menu, Components and check PointTerminal Active X
Control module. The (P) icon will appear in the ToolBox.
This is illustrated in this figure showing the toolbar in Visual Studio 2005 and Visual basic 6.0.
PointTerminal is dragged onto the toolbox (or added as a reference). The SDK will create dlls
that wraps the ActiveX component to the SDK (e.g. AxInterop.PointTerminalLib.dll and/or
Interop.PointTerminalLib.dll).

From version 2.4 a stronger Type Library is added to the PointTerminal.ocx. If changing
application code and using the newer ActiveX version please change code to reflect the stronger
type check.
You may have to build a new Type Library, e.g. by remove the old ActiveX from your
development environment and adding the new. You may use the Microsoft utility OleView to
inspect the type library
You may also use the Windows Forms ActiveX Control Importer (Aximp.exe).
Consult your development environment documentation for more information.
The type check include these typedefs
ReturnCode, TerminalReturnCode, CardTransactionReturnCode, CallbackType,
ConfigurationType, TransactionType, CurrencyType, AdministrationType
and affect these methods
SetConfiguration, OpenTerminal, CloseTerminal, CardTransaction, Administration,
CompleteExtCardTransaction, SelectAdministration, TransactionStatus, DisconnectTerminal,
ConnectTerminal, CallBack

PointTerminal OCX
Side 41

4. Flow
4.1 Transaction Flow

PointTerminal OCX
Side 42

4.2 External Card Transaction flow

A Local Card Transaction is an option available only if activated through a parameter download,
meaning that the option requires a special setup in Points Terminal Management System, and
that these settings are downloaded into the terminal through a parameter download.
If a local pan-file is present in the terminal, and a card number used in a transaction match one
of the card ranges defined in this file, then the transaction is handled as a local card
transaction.
As an extra option the cardholder can be prompted to confirm the amount via the terminal
display. In this case the user application must return 3 in the CallBack EventId, otherwise the
application returns 1 for not acknowledge and 0 for acknowledge of the transaction.

PointTerminal OCX
Side 43

PointTerminal OCX
Side 44

APPENDIX A, Printing
The ActiveX is approved to handle Windows printers. The printer driver must be configured to
use the windows print spooler queue, to start printing immediately, and to use hardware
handshake. Note that Point cannot support drivers and some drivers are difficult to install.
When the ActiveX is configured to Autoprint the receipts, all output to the printer bypass the
printer driver and sends it directly to the defined local or networked printer. The ActiveX will
automatically backup the four latest receipts in files named as the receipt file, concatenated with
number 1 to 4, and an internal index will point to the latest (newest) file. E.g. if the receipt file
name is C:\bon.txt, the backup files are named C:\bon.txt1, C:\bon.txt2, C:\bon.txt3, and
C:\bon.txt4.
Note that administrative reports are treated as receipts, and also backed up and that some
transactions (e.g. signature) use two backup files.
The ActiveX uses character encoding according to ISO 8859-15. A translation and command
table is supported, intended for simplifying configuration of POS printers with simple control and
character translation. The table defines control commands (e.g. ESC/POS) send to the printer
before and after the receipt, and can translate the characters of the receipt text.
The table is named ExtendedAsciiPrint.txt and if present, it must be located in the same
directory as your ECR application, (the application using the ActiveX).
The table entries define entries for indexes > 127 to value (in hex) and sends value to printer.
Format: <index> <value>[,<value>,..] , where value is a two char hex value, 00 to FF.
If index is PRO (prologue) or EPI (epilogue) the value (up to 250 hex bytes, comma separated in
one line) is send (not translated) to the printer before (pro) and after (epi) the (translated) receipt
data.

This example shows the table contents for an Epson TM-T88III printer.

BD

PRO 1B,40,1B,74,10
EPI 1D,56,01,30
BC 8C ;
9C ;

The PRO part 1B, 40 (ESC, @) initialises the printer and 1B, 74,10 selects code table WPC1252.
The EPI part 1D, 56,01,30 execute a partial cut of the receipt.
The character entries BC 8C etc. defines character translation.
Since WPC1252 is similar to ISO 8859-15 these entries are only shown as an example, and are
not complete.

PointTerminal OCX
Side 45

APPENDIX B, Customising dialogs.

The ActiveX displays two dialogs; the Status Dialog is mandatory and the Administration Select
Dialog is optional. Note that the latter is also used with return transactions by cards that require
an application selection (e.g. Mastercard test card REQ01 M.AP.).
By default the dialogs uses the Point colour (RGB(102,122,179)) as background and Point
Xenta like button styles ButtonStop and ButtonOk with size 68x92 pixels.

The buttons and background of the dialogs are user configurable, by placing bitmap files in the
same directory as the ActiveX e.g. c:\Windows\System32\) and naming them:
PointTerminalOk.bmp

ButtonOk button in normal (up) state

PointTerminalOkD.bmp

ButtonOk button in disabled state

PointTerminalStop.bmp

ButtonStop button in normal (up) state

PointTerminalBackGround.bmp Dialog background for both Status Dialog and

Administration Select Dialog.

If present PointTerminal.ocx will use the button bitmap files during dialog painting, using a BitBlt
function, copying the button bitmap to the corresponding dialog button.
The dialog background is painted using a StretchBlt function. In the Status Dialog the
background of the four status lines are painted using the upper left quarter of the bitmap with a
StrechBlt function. The StretchBlt function stretches or compresses the bitmap to fit the size of
the dialog item.

Background example bitmap with Point watermark - size 536x172 pixel.

PointTerminal OCX
Side 46

APPENDIX C, Tokens
The output from an Authorization transaction (pin, signature, key or prepaid) is called a Token.
A Token is a string of data created by the PSAM for later use as input to the Capture
(Supplemental or Reversal) transaction. The first part of the token is in plaintext and includes the
necessary information that enables the ECR to handle the token. The actual token is enciphered
and signed.
The terminal adds additional information to the end of the token before sending the token to the
ECR, and removes this information before sending the token to the PASM. The additional
information includes extra information about the transaction including any dcc information.
The ActiveX saves the token automatically in the directory specified by configuration. The
filename is composed by combining the terminals id and the unique transaction reference
number to form a string like 00990198_000872.tok, terminal 00990198 and transaction
reference 000872.
When using the token for later capture (Supplemental or Reversal) the ECR uses the reference
number to identify the token, and the ActiveX compose the token filename using the terminals id.
If a token is used on another of the merchants terminal, the ECR must rename the token file to
include the new terminals id. E.g. rename to 0099199_000872.tok if used on terminal with id
0099199.
The ActiveX provide a method (ReadToken(..)) for reading the plaintext and additional data from
the token. The method uses the full tokenfilename to identify the token (not the transaction
reference number).

PointTerminal OCX
Side 47

APPENDIX D, Trace
Trace files is generated if the trace level is different from 16. Trace level is set by using
the SetConfiguration (5,4,,) method, or by configuring the terminals param.ini (contact
Point).
Value set in the terminal is overruled by value set in
SetConfiguration().
The table shows the trace file property for different levels.
File PtFxDrTr@XXXX.txt
flxComTrace.txt
Level
0
Cyclic
Inactive
Inactive
2
Cyclic
Reset
Inactive
3
Cyclic
Reset
Reset
4
Cyclic
Append
Reset
5
Cyclic
Reset
Append
6
Cyclic
Append
Append
16
Inactive
Inactive
Inactive

PointOcxTraceXXXX.txt

PointTerminal OCX
Side 48