EFTPOS ActiveX Object

The ActiveX object is used to integrate your Point Of Sale applications to work with the Payment Express Pinpads.

Requirements/Downloads:

DpsEftX.ocx Integration Guide C# sample code Cpp sample code ActiveX Control Interface EFTPOS Service Configuration Settings Test Scripts to use before certification Test Card Information EFTPOS Response Codes - Non Bank Codes Test account. Apply online at https://www.paymentexpress.com/pxmi/apply FAQs Merchant FAQs Developer FAQs

Installation Instructions

The Payment Express EFTPOS software can be found below -

Installer

http://www.paymentexpress.com/EFTPOS/PXEftInstaller.exe

Files Installed/Updated

Filename	Description
dpseftx.ocx	ActiveX Control. Will be registered with the installer.
EftTray.exe	Tray application to handle capturing of input files. Also allows access to open the Config and Maintenance control panels. Optional install.
pxpp.exe	Pinpad Controller. NT service that is installed and started with the installer.
pxeftp.exe	Communication Server. NT service that is installed and started with the installer.
pxjview.exe	Journal Viewer. Standalone Journal Viewer of past transaction history.
dpseftxc.exe	Standalone EFTPOS client for non-integrated POS transactions.
uninst.exe	Starts the uninstaller process for removing the software.

Uninstalling PX EFTPOS

• Run uninst.exe - once the program is running click Remove. You can also use Add/Remove Programs in your Control Panel.

Using DPSEftx.ocx

ActiveX Methods, Events & Properties

Method Calls & Events

• Transaction (Request)
• Transaction (Response)
• Configuration Control Panel (Request)
• Configuration Control Panel (Response)
• Maintenance Control Panel (Request)
• Maintenance Control Panel (Response)
• Cutover & Enquiry (Request)
• Cutover & Enquiry (Response)
• Logon (Request)
• Logon (Response)
• Get Last Receipt (Request)
• Get Last Receipt (Response)
• Get Last Transaction (Request)
• Get Last Transaction (Response)
• Tipping & Hospitality (Request)
• Tipping & Hospitality (Response)
• Invisible Dialogs (Request)
• Invisible Dialogs (Response)
• ReadCard - loyalty cards (Request)
• ReadCard - loyalty cards (Response)
• Enter & Display Data - Fuel (Request)
• Enter & Display Data - Fuel (Response)
• Display Pinpad Temporary Messages (Request)
• Set Pinpad Idle Prompt (Request)
• Print Pending Receipt (Request)
• Print Pending Receipt (Response)
• Add Line Item - Fly Buys Cards (Request)
• Reset Line Items - Fly Buys Cards (Request)

Uncalled Events

• OnlineEvent (Response)
• StatusChangedEvent (Response)
• CapabilitiesChangedEvent (Response)
• Receipts (Response)

Properties

• ActiveX Properties

Software Configuration

• Printing Options
• ActiveX Exception Handling
• PinPad Simulator (Developer Testing)

EFTPOS Environments

• Kiosk / Vending Machines
• Tipping
• Hospitality
• Electronic Offline Voucher (EOV)
• Fly Buy Rewards
• Cheque Verification

Method Calls & Events

DoAuthorize (Request)

Start the transaction after setting appropriate properties. AuthorizeEvent will fire when complete with the result of the transaction. OutputReceiptEvent will also fire if there is any receipt data to be printed.

Input Properties

Parameter	Required	Description
Account	No*	The account number for settlement. 0ptions are 1-8. This is a compulsory parameter when using a multi-merchant setup.
Amount	Yes	Amount of Purchase or Refund in 1.23 format
AmountCashOut	No	Set the "Cashout" amount in 1.23 format
AmountCreditLimit	No	The POS can specify a CreditLimit parameter to decide whether payment of the specified Amount Payable is allowed using credit. Reserved
BillingId	No	Needs to be generated to add a card for recurring billing and sent again when rebilling transactions.
CardNumber	No	Card Number if using Manpan.
DateExpiry	No	Expiry Date on Card if using Manpan. The EnableManualPan property needs to be set to 1 (true)
ClientId	No	Reserved
ClientIp	No	IP address that the client application resides on
ClientType	No	Indicates transaction source (Web, vending machine etc)
CurrencyId	No	The currency to use for Dynamic Currency Conversion.
CurrencyRate	No	The rate of the foreign currency against the home currency.
Cvc2	No	Card Verification number. This number is found on the back of a credit card in the signature panel - it is different from the embossed card number and provides an additional safety check.
DialogX	No	Reserved
DialogY	No	Reserved
DialogType	No	Reserved
DeviceId	No	Reserved
EnableAddBillCard	No	Needed for recurring billing transactions when adding a card to the DPS system. Set element to 1 for true and 0 for false
EnableBackLight	No	Enhances the backlight brightness of the Pinpad display.
EnableBlockingMode	No	If set to 1 (true) DoAuthorize is forced to not return until the entire transaction has been run. Therefore AuthorizeEvent will not fire until this has happened.
EnableCurrencyConversion	No	If set to 1 (true) currency conversion can be used.
EnableCurrencyConversionPrompt	No	If set to 1 (true) the customer will be prompted on the Pinpad to choose a currency to transact in.
EnableIgnoreCardReadError	No	Ignore card read errors.
EnableInvisible	No	Disables ActiveX dialogs to allow you to create your own.
EnablePrintReceipt	No	Set to 1 (True) if using the Terminal Receipt printer or 0 (false) to let the client (POS) application take control.
EnablePrintSlip	No	If set to true (1) signature receipts will be printed by the control, if other receipts are sent to your own printer queue.
EnableTestMode	No	Compulsory for development purposes. Set to true to use the PIN Pad simulator for testing and development without a Hardware PIN Pad attached. Production systems must use the hardware PIN Pad.
LoyaltyRecipient	No	4 digit FlyBuys merchant number. This field can also be set in the PXPP configuration file. Reserved
MerchantReference	No	Reference field to appear on transaction reports
PrinterName	No	Name of the Windows Printer Driver that you are using to print receipts. Will go to the PrinterName set in the Pinpad configuration if not used.
ReceiptEjectCommand	No	Binary data to control your printer. Not usually used.
ReceiptResetCommand	No	Binary data to control your printer. Not usually used.
ReceiptSeparatorCommand	No	Binary data to control your printer. Not usually used.
ReceiptHeader	No	Message to be displayed on the header of the receipt
ReceiptTrailer	No	Message to be displayed on the footer of the receipt
SelectAccount	No	Reserved
StatusText	No	Reserved
Track1	No	Track 1 data from the magnetic strip. Can be used to do ManualPan transactions.
Track2	No	Track 2 data from the magnetic strip. Can be used to do ManualPan transactions.
Track3	No	Track 3 data from the magnetic strip. Can be used to do ManualPan transactions.
TxnRef	Yes*	Unique Transaction Id for the transaction. *Used to get last transaction details.
TxnType	Yes	Current values are "Purchase", "Refund", "Balance", "Tip", "Hospitality", "Topup", "XtraCharge" & "FlyBuy".
UnitId	No	ID of the Eftpos terminal
VersionEft	No	Version number of Eftpos unit
VersionPos	No	Version number of the POS software

AuthorizeEvent (Response)

Fires when processing is concluded for a transaction. The output properties are valid for a transaction when this event fires and remain valid until DoAuthorize is called to start a new transaction.

Output Properties

Parameter	Description
AccountSelected	Account that the customer selected. Options are 1 (Cheque), 2 (Savings A/C) & 3 (Credit Card)
AcquirerPort	Terminal ID used for the transaction
AuthCode	Authorisation code from the bank
Authorized	1 if transaction successful - 0 if declined or unsuccessful
CardNumber	Leading 6 and trailing 2 digits of the card number. All other digits are masked with zeros.
CardType	Card used (Visa, MasterCard, Bankcard etc)
DateSettlement	Date transaction will be settled to Merchant Bank Account in YYYYMMDD format
DateTimeTransaction	Time and Date the transaction was processed
DpsBillingId	Contains the BillingId generated by DPS when adding a card for recurring billing
DpsTxnRef	Unique transaction identifier returned for every transaction.
EnableCurrencyConversion	If set to 1 (true) currency conversion has been used.
Rid	The RID of the EMV transaction.
Pix	The PIX of the EMV transaction.
ResponseText	Response Text associated with the response code of the transaction
ReCo	2 character response code.
Stan	The System Trace Audit Number which identifies the transaction number processed through the merchant account.
Success	Indicates the success of a method call
TxnRef	Unique Transaction Id (TxnRef) that you used in your original transaction request.
OutputTrack1	Return the Track 1 data captured from the magnetic strip
OutputTrack2	Return the Track 2 data captured from the magnetic strip
OutputTrack3	Return the Track 3 data captured from the magnetic strip

DoConfig (Request)

This method configures the EFTPOS PINpad merchant parameters. It instantiates a control panel to set the following properties:
HostID (Nii), CAID, CATID.

The control panel will show Serial Number of the Pinpad connected and KVC of the device. The event ConfigDoneEvent is fired when the command completes.

ConfigDoneEvent (Response)

Fires when the EFTPOS Configuration control panel (HostID, CAID, CATID etc) is dismissed.

DoMaint (Request)

Instantiate a control panel for EFTPOS merchant functions (Settlement, Logon, Enquiry, Reprint Receipt etc). The event MaintDoneEvent is fired when the command completes.

MaintDoneEvent (Response)

Fires when control panel for EFTPOS merchant functions (Settlement, Logon, Enquiry, Reprint Receipt etc) is completed.

DoGetLastReceipt (Request)

This method retrieves the last receipt produced by the Pinpad. The event GetLastReceiptEvent is fired when the command completes.

There are no input properties required for this call.

GetLastReceiptEvent (Response)

Fires when a call is made to get the last receipt data.

Output Properties

Parameter	Description
Receipt	Receipt of the transaction that can be printed out for the customer.
ReceiptWidth	The width that the receipt will be formatted with. Range 1-30.

DoGetLastTransaction (Request)

This method retrieves the details of the last transaction processed by the PINpad. This method could be called by a POS application to determine whether a transaction was successful or not following a power failure whilst an EFTPOS transaction was in progress.

You will receive the same outputs as you did from the DoAuthorize call. The event GetLastTransactionEvent is fired when the command completes. You can only receive transaction information that have been sent to the banking network and received a Stan. Cancelled or timed-out transactions will not be found if searched for.

Input Properties

Parameter	Required	Description
TxnRef	Yes	Unique Transaction Id (TxnRef) that you used in your original transaction request.

GetLastTransactionEvent (Response)

Fires when a call is made to get the last transaction details.

Output Properties

Parameter	Description
AccountSelected	Account that the customer selected. Options are 1 (Cheque), 2 (Savings A/C) & 3 (Credit Card)
AcquirerPort	Terminal ID used for the transaction
AuthCode	Authorisation code from the bank
Authorized	1 if transaction successful - 0 if declined or unsuccessful
CardType	Card used (Visa, MasterCard, Bankcard etc)
DateSettlement	Date transaction will be settled to Merchant Bank Account in YYYYMMDD format
DateTimeTransaction	Time and Date the transaction was processed
DpsBillingId	Contains the BillingId generated by DPS when adding a card for recurring billing
DpsTxnRef	Unique transaction identifier returned for every transaction.
Pix	The PIX of the EMV transaction.
Rid	The RID of the EMV transaction.
Rrn	Reserved
ResponseText	Response Text associated with the response code of the transaction
Receipt	Receipt of the transaction that can be printed out for the customer
ReceiptWidth	The width that the receipt will be formatted with. Range 1-30.
ReCo	2 character response code.
Stan	The System Trace Audit Number which identifies the transaction number processed through the merchant account.
Success	Indicates the success of a method call
TxnRef	Unique Transaction Id (TxnRef) that you used in your original transaction request.

DoEditTender (Request)

EFTPOS Support for Tipping and Hospitality.

The event EditTenderEvent is fired when the command completes.

Input Properties

Parameter	Required	Description
DpsTxnRef	Yes	The DpsTxnRef value returned by a successful DoAuthorize reequest.
TxnType	Yes	Tip:Tipping transaction. Hospitality: Hospitality transaction.
Amount	Yes	The original Amount used for the DoAuthorize request.
Amount2	Yes	The new amount to be charged (Original amount plus the value of the Tip).
MerchantReference	Yes	Optional Details (max 64 character alphanumeric) of operator altering the value of the transaction.

EditTenderEvent (Response)

Output Properties

Parameter	Description
Success	True (1) - Tender successfully changed False (0) - Tender not changed
ReCo	00 - Accepted F4 - Tip limit exceeded E2 - Transaction not found
ResponseText	Response Text associated with the response code of the transaction

DoSettlement (Request)

When this function is called you can get settlement cutover or Enquiry popup display. This will enable you to print Cutover and Enquiry receipts. Alternatively these buttons can be accessed via a DoMaint call. The event SettlementDoneEvent is fired when the command completes.

"Cutover" Performs a financial settlement with the banking switch. This can only be performed once per day. A receipt event fires with settlement totals.
"Enquiry" A receipt event fires with the settlement total for the inputted date(must be in the past).
"SubTotal" A receipt event fires with the totals for Purchase and Refund transactions since the last Cutover or SubTotal was performed. SubTotal values are reset to zero. Note: no financial settlement takes place.
"SubTotalEnquiry" a receipt event fires with the totals for Purchase and Refund transactions since the last Cutover or SubTotal was performed. SubTotal values are not reset to zero. Note: no financial settlement takes place.
"EOV" Uploads any stored offline transactions
"Tip" Uploads any stored Tip transactions

Input Properties

Parameter	Required	Description
Paramater1	Yes	Can take the following as data; "Cutover", "Enquiry", "SubTotal, SubTotalEnquiry", "Tip" & "EOV".
DateSettlement	Yes*	*Required if using Enquiry in Paramater1. Date of Enquiry period. Format YYYYMMDD.

SettlementDoneEvent (Response)

Fires when the call to DoSettlement is completed. You will be able to get a receipt from this call. This will be available when the OutputReceiptEvent fires.

Parameter	Description
ResponseText	Response Text associated with the response code of the transaction
ReCo	2 character response code.
Success	Indicates the success of a method call

DoReadCard (Request)

Call to put additional display message on screen and ready the PINpad to read card track data. This is useful if you are building a POS that includes white label or membership reward cards. This call should only be made to retrieve the track data from loyalty cards and other non-payment cards. The data returned when attempting to read a payment card may be partially obscured. The event CardReadEvent is fired when the command completes.

Input Properties

Parameter	Required	Description
DisplayLine1	No	Line 1 of the display on the Pinpad screen
DisplayLine2	No	Line 1 of the display on the Pinpad screen
EnableBackLight	No	Enhances the backlight brightness of the Pinpad display.

CardReadEvent (Response)

Fires when card is read: contains Track2 and (if available) Track1 and Track3 information.

Output Properties

Parameter	Description
OutputTrack1	Track 1 data captured from the magnetic strip
OutputTrack2	Track 2 data captured from the magnetic strip
OutputTrack3	Track 3 data captured from the magnetic strip
Success	Indicates the success of a method call.

DoEnterData (Request)

This function is used for displaying additional message prompts on the pinpad and receiving keystrokes pressed on the pinpad back to the POS application. Plain Text can be masked as well to be displayed on the Pinpad. This function is mainly used with vending and fuel POS. The event EnterDataEvent is fired when the command completes.

Input Properties

Parameter	Required	Description
EnableBackLight	No	Enhances the backlight brightness of the Pinpad display.
InputMask	No	Character to mask plain text input data, such as a password. Length is 1 character, such as "*".
KeyMask	No	Key Map Enabled Keys. Used when entering data from Pinpad keypad. Length can include up to 4 Hex numbers and can include values such as "1FF8" for all numbers key on the pinpad. Keymaps available are - F1 Bit 0 F2 Bit 1 F3 Bit 2 0 Bit 3 1 Bit 4 2 Bit 5 3 Bit 6 4 Bit 7 5 Bit 8 6 Bit 9 7 Bit 10 8 Bit 11 9 Bit 12 Cancel Bit 13 Clear Bit 14 Enter Bit 15
UserEnterMode	No	Set the pinpad input mode, it can be single Pinpad key input or multiple key combination string key input The maximum string length is 9. Values are - 1 - single Key input mode 2 - String keys input mode
EnterDataLen	No	Set the maximum data length of the UserEnterMode mode. Values are 0 - 9
DisplayLine1	No	Line 1 of the display on the Pinpad screen
DisplayLine2	No	Line 2 of the display on the Pinpad screen

EnterDataEvent (Response)

Fires when the call to DoEnterData is completed.

Parameter	Description
Success	Indicates the success of a method call.
OutputParameter1	Informs what keys were pressed during the DoEnterData method call. Will include character or string of characters if multiple buttons were pushed. A = Cancel key B = Clear key C = Enter key D = F1 key E = F2 key F = F3 key

DoPinPadDisplay (Request)

This call is used to display temporary messages on the Pinpad for a certain amount of time.

Input Properties

Parameter	Required	Description
DisplayLine1	Optional	Line 1 of the display on the Pinpad screen
DisplayLine2	Optional	Line 2 of the display on the Pinpad screen
EnableBackLight	Optional	Enhances the backlight brightness of the Pinpad display.
DisplayTimeout	Optional	Sets display timeout length. The default timeout is 3 seconds

DoSetIdlePrompt (Request)

This call is used to display the Idle message of the Pinpad. The default is "EFTPOS", which can be changed by using the DisplayLine1 & DisplayLine2 input properties.

Input Properties

Parameter	Required	Description
DisplayLine1	Optional	Line 1 of the display on the Pinpad screen
DisplayLine2	Optional	Line 2 of the display on the Pinpad screen

SetIdlePromptDoneEvent (Reserved)

No event currently fires for the DoSetIdlePrompt method call.

DoUserInterfaceAction (Request)

This function is used when you are using invisible dialogues, which is enabled by calling DoAuthorize with the EnableInvisible property set to true (1). Each time the UserInterfaceEvent fires you need to make an interaction through this method call to return a response to the dialogue.

Input Properties

Parameter	Required	Description
Parameter1	Yes	Data values can be "Ok", "Cancel", "Yes" & "No".

UserInterfaceEvent (Response)

Instead of dialogue boxes appearing to interact with, they will be available as outputs instead for you to then interact with by using the DoUserInterfaceAction method call with your intended responses to the dialogs.

Output Properties

Parameter	Description
OutputDisplayLine1	Display Line 1 of the dialogue.
OutputDisplayLine2	Display Line 2 of the dialogue.
OutputParameter1	Informs what buttons should be enabled for the user to interact with.

DoLogon (Request)

This method initiates an EFTPOS logon to the acquirer (bank), whether the PINpad is already logged on or not. Usually not used, as it will perform a logon automatically if a transaction is tried.

Input Properties

Parameter	Required	Description
Account	Yes*	Compulsory if using Multi-merchant

LogonDoneEvent (Response)

Instead of dialogue boxes appearing to interact with, they will be available as outputs instead for you to then interact with by using the DoUserInterfaceAction method call with your intended responses to the dialogs.

Output Properties

Parameter	Description
Success	Indicates the success of a method call.
ReCo	2 character response code.
ResponseText	Response Text associated with the response code of the transaction.

DoPrintPendingReceipt (Request)

Prints the pending Tip or hospitality receipt. PrintPendingReceiptEvent event will fire when after this call has been completed. OutputReceiptEvent event will fire if there is any receipt available.

Input Properties

Parameter	Required	Description
TxnType	Yes	Values are "Tip" or "Hospitality"
DpsTxnRef	Yes	The unique identifier of the Tipping or Hospitality transaction. For Tipping & Hospitality this is a combination of ther TerminalId & the Stan number.
EnablePrintReceipt	Yes	Set to true (1) to print receipt or false (0) to capture and print via the POS

PrintPendingReceiptEvent (Response)

Received in response to a DoPrintPendingReceipt request call.

Output Properties

Parameter	Description
Success	Indicates the success of a method call.
ReCo	2 character response code.
ResponseText	Response Text associated with the response code of the transaction.

DoAddLineItem (Request)

Adds items to be transmitted for Fly Buy Rewards. No event will fire. See Fly Buys Transactions for more information.

The method call is overloaded and the following properties are not part of the ActiveX property. DoAddLineItem( ProductCode, Amount, Quantity )

Overloaded Properties Needed

Parameter	Required	Description
ProductCode	Yes	Fly Buys product code for the retail item being added for reward points. String
Amount	Yes	Amount of item. String
Quantity	Yes	Quanitiy of item purhcased. Integer (Long)

ResetLineItems (Request)

Clears any items added for Rewards. There are no input properties required for this call. No event will fire. See Fly Buys Transactions for more information.

AboutBox

This call displays a pop-up box with information on the version of the DPS software.

Uncalled Events

OutputReceiptEvent

When fired: Under control of EFTPOS the POS needs to print the receipt contents.

Output Properties

Parameter	Description
Receipt	Receipt of the transaction that can be printed out for the customer.
ReceiptWidth	The width that the receipt will be formatted with. Range 1-30.
ReceiptIsSeparate	If set to 1 (true) then Receipt should be cut off ready for the final receipt to be printed next, as it will be a 'Signature Required' receipt.

OnlineEvent

Fires when the ReadyLink and ReadyPinPad are both ready.

Output Properties

Parameter	Description
Ready	Indicates whether both the Pinpad and communication link are ready. Will be false (0) if any aren't ready.
ReadyPinPad	Indicates whether the Pinpad connection is ready. Will be true (1) if the connection is fine.
ReadyLink	Indicates whether the communications link is ready. Will be true (1) if the connection is fine.
ReadyState	Reserved
InProgress	Indicates whether a transaction is in progress or not.
EftStatus	Reserved
StatusText	The text value of the status of the EFTPOS software. Values can be - Ready Pinpad Not Ready Link Failure Offline EFTPOS OFFLINE (Ready, but in EOV mode).
Capabilities	Lists the capabilities of the EFTPOS software. Functions will either be 0 (not capable) or 1 (capable). Values are - Auth=(0,1) Balance=(0,1) Cheque=(0,1) MultiMerchant=(0,1) Tipping=(0,1) Hospitality=(0,1) EnableEov=(0,1) EnableFlyBuy=(0,1)
EovOffline	Indicates whether EOV mode is being used. True for in use and false if not using EOV.

StatusChangedEvent

Fires when ReadyLink (Link to the Eftpos Network) or ReadyPinpad (Link to the Verifone Pinpad) change status (ready or not ready).

Output Properties

Parameter	Description
Ready	Indicates whether both the Pinpad and communication link are ready. Will be false (0) if any aren't ready.
ReadyPinPad	Indicates whether the Pinpad connection is ready. Will be true (1) if the connection is fine.
ReadyLink	Indicates whether the communications link is ready. Will be true (1) if the connection is fine.
StatusText	The text value of the status of the EFTPOS software. Values can be - Ready Pinpad Not Ready Link Failure Offline EFTPOS OFFLINE (Ready, but in EOV mode).
ReadyState	Reserved
InProgress	Indicates whether a transaction is in progress or not.
EftStatus	Reserved
EovOffline	Indicates whether EOV mode is being used. True for in use and false if not using EOV.

CapabilitiesChangedEvent

If the capabilities of the EFTPOS software change this event will fire. This can happen if the configuration file has changed.

Output Properties

Parameter	Description
Capabilities	Lists the capabilities of the EFTPOS software. Functions will either be 0 (not capable) or 1 (capable). Values are - Auth=(0,1) Balance=(0,1) Cheque=(0,1) MultiMerchant=(0,1) Tipping=(0,1) Hospitality=(0,1) EnableEov=(0,1) EnableFlyBuy=(0,1)

Software Configuration

Exception Handling

The Pinpad service checks whether it has a connection to DPS always and any deviation from that, the StatusChangedEvent event will change from false to true. This checks both the Pinpad connection and the network communication is fine. The event OnlineEvent only fires when the link is "ready" as well.

In the output of any transaction you have got the following outputs of the ActiveX: Ready, ReadyPinPad and ReadyLink. ReadyPinPad refers to the connection to the PinPad and ReadyLink refers to the communications to us. The "Ready" property will be a combination of the ReadyPinPad and ReadyLink, so if any of those has an error "Ready" will be 0 (false).

The AuthorizeEvent event will fire once the transaction has completed. The output properties remain valid until the DoAuthorize method is called again.

If there is no response in 30 seconds from the banking network, the transaction will timeout. The AuthorizeEvent event will fire and a communication error response code will be shown in the ReCo property (see response codes for more information) and the Success property will be "1" to indicate a successful method call, but the Authorized property will be "0", indicating a failed/declined transaction. A reversal transaction is automatically sent to the banking network to reverse the transaction.

The status of a transaction will therefore always be known with the ActiveX control, as there are always responses from the Pinpad service (PxPP), so no transaction can be lost.

Pin Pad Simulator

The PIN Pad Simulator allows development and testing of Integrated EFTPOS Client Applications, e.g.: Point Of Sale (POS) without requiring connection of specialised hardware for testing. To activate the pinpad simulator, ensure the EnableTestMode property is always set to true prior to calling any method.

Printing Options

POS Print Queue (Controlled by Client Application)

You will need to set EnablePrintReceipt to 0 (false) if wishing to control the printing through your own application.

Windows Print Queue (Controlled by Pinpad controller)

You will need to set EnablePrintReceipt to 1 (true) if you want the Pinpad controller to Print the receipt to your default printer. You can also use the PrinterName property if you are not using the default printer or it's not using a Generic/ Text Only driver and wish to use a specific driver through the Printer Name.

If your printer requires raw commands, then you can also set the following fields -
ReceiptEjectCommand
ReceiptResetCommand
ReceiptSeparatorCommand

You can also use the following printer options -
EnablePrintSlip
ReceiptTrailer
ReceiptHeader

Printing options can be preset in the Pinpad Configuration as well.

Properties

Indicates if the transaction was authorized or not. Either False (0) or True (1)

Set the amount to be charged or refunded (depending on the TxnType). Format is d.cc (d=dollars, c=cents). Max amount is 99999.99

Set the "Cashout" amount. Format is d.cc (d=dollars, c=cents). If no cash out is to be made, this property must be empty (blank).

Set the "Credit Limit" amount. Format is d.cc (d=dollars, c=cents).The POS specifies a CreditLimit parameter. If this credit limit is set to an amount that is less than the requested transaction amount, only non-credit accounts are permitted with an appropriate user message if the customer attempts to select a credit account.

If a token based billing transaction is to be created, a BillingId has to be supplied. This is an identifier generated by the merchant application that is used to identify a customer or billing entry and can be used as input instead of card number and date expiry for subsequent billing transactions. To add a BillingId in the transaction request the EnableAddBillCard element needs to be present and set to 1 (true). Upon rebilling this will need to be set to 0 (false).

The card number. No leading or embedded blanks are permitted. Must contain a numeric value.

The card type used for the transaction. Note that the list may be expanded as support for new cards is added. The CardName format is to capitalize the first letter with remaining letters in lowercase. CardType is returned by the acquirer and is subject to change.

CardType	Description
Eftpos	Eftpos Cards
VISA	VISA Cards
DINERS	DINERS Cards
AMEX	AMEX Cards
MCARD	MasterCard
BankCard	BankCards
ECard	ECards
ShellCard	Shell Cards

Uniquely identifies a client accessing DPSEft. This value is set by DPSEft COM object upon object instantiation.

The ClientType property describes the origin of the transaction, for example; Vending machine or from a Web Server.

The currency to use for Dynamic Currency Conversion.

Currency Id	Currency Name
036	Australian Dollar
242	Fijian Dollar
250	French Franc
280	Deutschemark
344	Hong Kong Dollars
548	Vanuatu Vatu
554	New Zealand Dollar
598	PNG Kina
702	Singapore Dollar
776	Tonga Pa�anga
840	US Dollar
882	Samoa Tala
826	Pound Sterling
756	Swiss Franc
710	South African Rand
978	Euro
458	Malaysian Ringgit
414	Kuwaiti Dinar
392	Japanese Yen
124	Canadian Dollar
090	Solomon Islands Dollar

The rate of the foreign currency against the home currency.

Card Verification Code 2 number. Some payment cards are issued with additional identifying information. These cards will have the account number printed on the signature panel of the card followed by a three or four digit value. This value is generated by the issuing bank and can be verified by the bank. Payment card brands have varying names for the value:

Indicates card expiry date. Format is MMYY where MM is month 01-12 and Year 00-99. do not insert "/" or other delimiter.

Indicates Date of settlement (when money will be deposited in Merchant bank account)  if this is supported by the Acquirer, otherwise contains the date the transaction was processed in YYYYMMDD format.

Indicates when the transaction was processed. HHMMSS format.

When output, contains the Payment Express generated BillingId. Only returned for transactions that are requested by the application with the EnableAddBillCard value set to 1 (true) indicating a token billing entry should be created.

A unique identifier returned for every transaction.

Reserved

To automatically add a card for subsequent billing purposes, set this to 1 (true). When generating a Billing Transaction for a previously loaded BillingId or DpsBillingId, EnableAddBillCard must be 0 (false).

Enhances the backlight brightness of the Pinpad display.

If set to 1 (true) DoAuthorize is forced to not return until the entire transaction has been run. Therefore AuthorizeEvent will not fire until this has happened. Default is false, as should work well without this property.

Reserved

Set to true on your form, so that no dialogs appear. Instead they will appear in OutputDisplayLine1 and OutputDisplayLine2. OutputParameter1 will inform you what buttons should be available for the dialog. All these events will be available everytime UserInterfaceEvent fires.

Reserved. For use with "Card not Present" merchant numbers.

If set to true (1) signature receipts will be printed by the control, if other receipts are sent to your own printer queue.

Set to true if the EFTPOS subsystem should use the receipt printer to print its own receipt. Set to false if the Client application will take responsibility for printing the EFTPOS receipt. In this case, the OnPrintReceiptEvent must be handled by the client application.

Set to true to use the PIN Pad simulator for testing and development without a Hardware PIN pad attached. Production systems must use a hardware PIN Pad.

States if the ActiveX control is already in use and busy processing a transaction. Will be 1 (true) if busy or 0 (false) if free.

Reserved

KeyMap Enabled Keys: 0123456789ABCXEU A-C = F1-F3, X = Cancel, L=cLear E=Enter. Used when entering data from PIN Pad keypad - may be plaintext or a enciphered PIN among other types of input.

Free text to appear on transaction reports.

Display the Track 1 data captured from the magnetic strip

Display the Track 2 data captured from the magnetic strip

Display the Track 3 data captured from the magnetic strip

Indicates whether both the Pinpad and communication link are ready. Will be false (0) if any aren't ready or true (1) if both are ready.

Indicates whether the communications link is ready. Will be true (1) if the connection is fine or 0 if there is a problem.

Indicates whether the Pinpad connection is ready. Will be true (1) if the connection is fine or false (0) if there is a problem.

Reserved

You can include your own header to appear on the receipt

You can include your own footer to appear on the receipt

Receipt of the transaction that can be printed out for the customer.

DIRECT PAYMENT SOLUTIONS
DIRECT PAYMENT
SOLUTIONS - TEST

*-----------EFTPOS-----------*
TERMINAL 00905302  TRAN 000321
TIME  10JUN 15:17  ACCT CHEQUE
                             503871....7361
PURCHASE                       NZ$1.00
TOTAL                             NZ$1.00
         INCORRECT PIN
             DECLINED
*-------------------------------*

If set to 1 (true) then Receipt should be cut off ready for the final receipt to be printed next, as it will be a 'Signature Required' receipt.

You can specify the width that the receipt will be formatted with. Range 1-30.

The client application should not interpret the Response Code property contents - it is provided as informational only. The Authorized property determines if the the transaction was successful or not.

The Response Text is associated with ResponseCode. For successful transactions this is usually Approved and for unsuccessful transactions this can be a number of texts depending on why the transaction declined. For example it could be Card Expired, Declined, Invalid Card, REFER TO CARD ISSUER, DO NOT HONOUR. All acquirers have their own response texts and should be displayed for better understanding of why the transaction got declined.

Indicates success or failure of a method call.

Capture track 1 data with the magnetic strip

Capture track 2 data with the magnetic strip

Unique transaction reference 1-16 alphanumeric character.

Value Description Purchase Purchase - Funds are transferred immediately. Refund Refund - Funds transferred immediately.

Version of the POS software you are using

Eftpos Environments

Kiosk/Vending

For vending machines or kiosk environments, you can disable dialogs by enabling the EnableInvisible property. Dialog display messages will instead appear in OutputDisplayLine1 and OutputDisplayLine2 properties.

OutputParameter1 These properties will be available everytime UserInterfaceEvent fires and must be available if the property includes them.

You can interact with the dialogs by using the DoUserInterfaceAction method call with your intended responses to the dialogs. Paramater1 will contain the value of the button to be used. (Yes, No, Cancel or Ok). In the PinPad configuration you can also set EnableVendingMode to true to force signatures to be accepted and not prompt a dialog.

Tipping

Set the EnableCreditCardTipping property in PXPP_CFG.txt to true (1) to enable the EFTPOS software for Tipping transactions -

<EnableCreditCardTipping>1</EnableCreditCardTipping>

1) The first step of a Tipping transaction is to call the DoAuthorize method with the TxnType set to either "Tip". This will cause a Tipping receipt to be generated for Signature Required transactions.

The POS must store the DpsTxnRef property returned by a successful Tip transaction, so the merchant can add tips against the card.

2) The second step is to add tips to the card, which can be done through the DoEditTender method call with the DpsTxnRef returned in the first step and the new amount. EditTenderEvent will fire with the outcome of the tipping transaction. DoEditTender can be called repeatedly for tipping transactions if an amount needs to be adjusted.

The Amount2 field can only be incremented by 50% more than the Amount field.

Pending Tipping transaction receipts are available from the DoPrintPendingReceipt method call.

Tips aren't automatically settled with the banking network straight away. You will need to do the next step to settle the tips.

3) You need to force the upload & settlement of all Tip transactions by calling DoSettlement with Parameter1 set to "Tip". SettlementDoneEvent will fire after Tips are uploaded or cancelled. Alternatively, you could wait until settlement is done for the day. By clicking Settle you will be prompted to upload Tip transactions as well.

Voiding

You will need to set the Amount2 field to $0.00 in the DoEditTender call. You should have a entry password to this functionality on your POS, but isn't mandatory.

Hospitality

Set the EnableHospitality property in PXPP_CFG.txt to true (1) to enable the EFTPOS software for Hospitality transactions -

<EnableHospitality>1</EnableHospitality>

Hospitality

The first step of a Hospitality transaction is to call the DoAuthorize method with the TxnType set to Hospitality. This will give you a DpsTxnRef in the response to be used for the corresponding completion.

Pending Hospitality transaction receipts are available from the DoPrintPendingReceipt method call.

Pending Tipping transaction receipts are available from the DoPrintPendingReceipt method call.

Once the Hospitality transaction needs to be completed. You call DoEditTender method with the DpsTxnRef stored from the 1st transaction with the Amount (original amount) and Amount2 (final completed amount) fields and TxnType set to Hospitality again.

TopUps

For Topups you will not need to use DoEditTender to finalise the original Hospitality transaction you are topping up. Instead just go and do a TopupTopup on that original transaction using the DpsTxnRef.

Call DoAuthorize method with the TxnType set to Topup and use the DpsTxnRef of the original hospitality transaction and use the Amount field. There will not be a new DpsTxnRef.

Pending Hospitality transaction receipts are available from the DoPrintPendingReceipt method call.

To finalise you will need to call DoEditTender method with the DpsTxnRef stored from the 1st transaction with the Amount (original amount) and Amount2 (final completed amount) fields and TxnType set to Hospitality.

XtraCharge

For XtraCharge transactions call the DoAuthorize method with the TxnType set to XtraCharge and Amount. This will perform a manual entry transaction entry that will not need any original transaction reference or storage of the transaction. The Cardnumber and DateExpiry date is needed, so you will need to keep this data in your database.

No Charge

You are able to finalise the transaction using DoEditTender with any amount including $0.00, if you do not wish to charge/complete the transaction.

Electronic Offline Voucher (EOV)

What is EOV?

This transaction allows the terminal to authorise transactions in an offline mode. If there is a communication problem with the banking network or problems transmitting transactions, then the EFTPOS system will go into an offline mode to handle transaction processing until the system is able to resume it's normal status.

Conditions for going into EOV

• Receive a 99 Response Code to a financial transaction and its resulting reversal.
• Receive a 96 Response Code to two consecutive transactions.
• Settlement transaction suffering an exception.
• Reversal message suffering an exception.

The StatusText will be EFPTOS OFFLINE and the EovOffline property will be set to True as well. You will also be notified when doing an offline transaction with the dialog "Process Trans Offline? Y/N". Subsequently all transactions will have OutputDisplayLine1 with "Authorise excess offline amount? Y/N" when calling DoAuthorize. For the swipe card phase you will also have OutputDisplayLine2 with "EFTPOS OFFLINE".

How EOV works

The permitted account types are cheque, savings and credit, any one of which, is selected by the cardholder by pressing the appropriate PINpad key. If the Credit Account is selected for the account type then the text message "CR FLR LMT APPLY" is to be displayed on the terminal for seven seconds or until "OK" is clicked. EOV is restricted to purchase transactions and allow only one transaction to be stored for any given card.

The EOV limit is set at the banking network and can be adjusted by contacting your banking representative. Maximum offline transactions is set to a default of 99 (max), but this can be altered by contacting support@paymentexpress.com. EOV mode is available for a maximum of 36 hours, thereafter only online transactions are able to be processed.

PX EFTPOS will wait ten minutes and then transmit an auto Logon and keep trying every 10 minutes.

Uploading EOV transactions

The terminal will do this automatically during off peak banking network times, which will be specified in the logon response message (1am is default). You can also upload at any given time by calling DoSettlement with Parameter1 set to EOV. This is a requirement for all POS software as an upload backup.

Fly Buys Transactions

To add reward points for your customers you can call DoAddLineItem method with the ProductCode, Amount & Quantity for each product sold. ResetLineItems method call can be called if you make a mistake and wish to clear any items added. It will also need to be cleared before submitting a new FlyBuys transaction. Once you have added all sale items via this call, you can proceed to the transmitting of the customers card along with their purchase information.

DoAuthorize is called next with TxnType set to FlyBuy along with the total amount which will need to be in the Amount property. The LoyaltyRecipient property needs to be filled with the merchant's FlyBuy 4 digit numeric code. Alternatively this can be done in the Pinpad configuration file.

The Pinpad will now display swipe card, so the customer/merchant can swipe their FlyBuys card. The Fly Buys will be transmitted at this point. The response will be given back by the event AuthorizeEvent.

Cheque Verification

A Cheque Verify transaction allows the merchant to authorise a cheque, to verify that funds are available to honour the cheque.

Using Cheque Verification entails setting TxnType to Cheque, setting the Amount property to the value of the Cheque and setting the Track2 property to include the Cheque number.

The format of the cheque number should include a space between the branch number and account number, account number and cheque serial number.
For example Track2 = "1234 12345678 999123".

To use Cheque Verification, you will need your merchant number enabled for it at the banking network. You will also need to set the EnableCheque property in PXPP_CFG.txt to true (1)

<EnableCheque>1</EnableCheque>

Fuel Transactions (Reserved)

To enable Fuel capability you will need to set the EnableFuelDispensing property in PXPP_CFG.txt to true (1)

<EnableFuelDispensing>1</EnableFuelDispensing>

Fuel transactions include authorisation and completion (financial advice) type transactions. To start your Fuel transaction you should call the DoAuthorize method with the TxnType set to Fuel. A prompt will allow you to Select Pump Number and then display the amount with PUMP X READY TO DISPENSE UP TO $50.00 or PUMP X READY FOR DELIVERY if the authorisation amount is greater than $50.00. Normal account selection and pin entry will follow.

AuthorizeEvent will give you a DpsTxnRef in the response to be used for the corresponding completion.

Once the Fuel transaction needs to be completed. You call DoEditTender method with the DpsTxnRef stored from the 1st transaction with the Amount (original amount) and Amount2 (final completed amount) fields and TxnType set to Fuel again.

DoEnterData can be used for Pinpad to display more Fuel message prompts. Customers can also interact with these messages by using the Pinpad keys. The EnterDataEvent will fire with the response of what keys were pressed.

DoEnterData can use the message prompts shown below by entering the corresponding IDs into DisplayLine1 and DisplayLine2 properties when using the function.

DoPinPadDisplay can be used to set temporary messages on the pinpad, which will expire after a certain amount of time set when calling the function. This method can be used in conjuction with the message prompts below as well.

Message Prompt Lookup Tables

ID	Message Prompt
55	SELECT PUMP AND
56	PUSH ENTER
57	REQUIRE RECEIPT
58	YES OR NO
59	LOAD USER ID
60	AND ENTER
61	LOAD CONTRACT NO
62	LOAD FLEET NO
63	LOAD VEHICLE NO
64	LOAD DRIVER NO
65	LOAD EMPLOYEE NO
66	LOAD PLANT NO
67	LOAD ODOMETER
68	LOAD ENGINE HRS
69	LOAD ODO ENG HRS
70	LOAD PRESET
71	GO TO PUMP
72	AND TAKE FUEL
73	WRONG SYSTEM
74	WRONG NETWORK
75	SYSTEM NOT READY
76	EXPIRED CARD
77	BAD CARD
78	CARD NOT ALLOWED
79	INVALID
80	IDENTIFIER
81	CARD ALREADY
82	IN USE
83	DOLLAR LIMIT
84	REACHED
85	INVALID PUMP
86	NUMBER
87	PUMP OFF LINE
88	PUMP IN USE
89	PUMP IN ERROR
90	PUMP UNAVAILABLE
91	RESTRICTED TIME
92	RESTRICTED FUEL
92	INVALID ENTRY
93	ODO ENTRY
94	OUT OF RANGE
95	PRINTER NOT
96	WORKING
97	PRINTER OUT OF
98	PAPER
99	NO RECEIPT TO
100	PRINT
101	NOT ACCEPTED