EFTPOS Tray Monitor & File Format

The EFTPOS Tray Monitor is used to integrate your Point Of Sale applications to work with the Payment Express Pinpads.

Installation Instructions

The Tray Monitor version of the Payment Express EFTPOS software can be found below -

Installer http://sec.paymentexpress.com/EFTPOS/PXEftInstaller_Tray.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.

EFTPOS Tray File Submission

The following is the file format to include in *.req files that you place into the directory that is monitored by the EFTPOS Tray application.

*.req Input Files

Each line of the *.req document will have an input property and is divided into sections.

The input file is used to trigger and EFTPOS payment. When it is detected, the EFTPOS software will process the file and start the payment process. The input file contains only one section. Because of this the section name is ignored, and the section marker line may be omitted completely. The following fields are defined:

[Fields] section

Parameter Description
TxnType The type of transaction to perform. Either the initial or the full word can be used. "P" or "Purchase" "R" or "Refund"
TxnRef A reference ID for the transaction. This can be used as a search term in the web reporting framework.
AmtPurchase The total amount of the goods/services that the customer is paying for. This value should include a decimal point. If no decimal point is found the two right-most digits will be used as the cents value.
AmtCash The amount of cash that the customer is withdrawing as part of their payment. This value should include a decimal point. If no decimal point is found the two right-most digits will be used as the cents value.
EnablePrintReceipt True (1) or False (0). Default: False
EnablePrintSlip True (1) or False (0). Default: False
EnableBacklight True (1) or False (0). Default: False
EnableTestMode True (1) or False (0). Default: False

Sample Data:

*.evt Output Files

Each line of the *.evt document will have an output/settlement property and is divided into the following sections. It will also tell you how many lines you should expect in the document and are always in order.

[Fields] section

Parameter Description
TxnRef A reference ID for the transaction. This will be the same as the reference ID from the input file.
TxnType The type of transaction performed. This will be the same as the transaction type from the input file.
ReCo Two-character response code indicating the outcome of the EFTPOS payment. Successful responses are: 00 - Accepted 08 - Accept with signature
ResponseCode Same as ReCo. Provided for compatibility with POS software written for use with PC EFTPOS.
ResponseText Description of the response code.
Date Date on which the transaction was processed. The format of this number is yyyymmdd.
Time Time at which the transaction was processed. The format of this number is hhmmss.
DateSettlement Approximate date on which the funds should be settled. The format of this number is yyyymmdd.
CardType The type of card used for the payment. Common values are: Visa Mastercard EFTPOS
AmtPurchase The total amount of the goods/services that the customer is paying for.
AmtCash The amount of cash that the customer is withdrawing as part of their payment.

[Receipt] section

Width The number of characters on each line of the receipt.
Lines The number of lines of receipt data present.
1...N Data to be printed on the EFTPOS portion of the receipt. N is the total number of lines as reported by Lines.

Sample Data:

DDE Support

DpsEftTray registers DDE service with name "DpsEftTray" and handle all DDE requests for this service. Clients expecting to connect to a DDE topic and then use established connection to process subsequent transactions. DDE topic and DDE item are free form text meaningful for DDE client. However, transactions having same DDE topic and DDE item will be considered the same transaction. So, to avoid clashes and to simplify tracking, it is recommended to use unique DDE topic for each instance of DDE client and unique DDE item for each transaction.

It is possible to specify list of allowed topics. In this case DpsEftTray will accept connections to listed topics only and will reject any connection attempts to a topic that is not in the configured list. If such a list has not been configured, DpsEftTray will accept any topic.

To process a transaction client sends a request file as ANSI text (CF_TEXT) with a DDE_POKE command. DpsEftTray stores received file locally and process as usual. When the transaction is processed, DDE client can retrieve response file using a DDE_REQUEST specifying the same DDE topic and item. Response file is returned as ANSI text (CF_TEXT). Note that DpsEftTray will respond with DDE_FNOTPROCESSED if asked for unknown transaction or before results are ready.

DDE client could check status of a transaction processing at any moment by making a status request to the DDE server. There are two ways of doing so: make a request with the same DDE item, but specifying special DDE format or by appending ".status" to the item name (format is CF_TEXT in this case). In both cases returned data block is '\0' terminated ANSI string, containing hexadecimal zero-padded representation of a 32-bit state. At the moment: 00000000 means transaction is processed and results are ready, 00000001 means transaction is still in process, FFFFFFFF (i.e. DWORD(-1)) means transaction is not found.

DpsEftTray will delete response file soon after sending results to the client. However, to avoid occasional data losses these files will be kept on disc for a preconfigured time interval. Client can re-request transaction results during this interval.

Note 1: To avoid file system related issues DDE topics and items are restricted to be made of alphanumeric, '.' (dot), '-' (minus) and '_' (underscore)and must contain at least one alphanumeric character. Please, stick with alpha-numeric where possible.

Note 2: DpsEftTray will respond with DDE_FBUSY for a DDE_POKE if there is a transaction with same DDE topic and DDE item still in progress or response file for such transaction is still on disk.

DDE Configuration

The Tray configuration file can take the following settings for the use of DDE. DDE related parameters for DpsEftTray application has to be stored in a subnode of node.

Setting Description

Directory Directory to be monitored for DDE temporary files.
Default: C:\Program Files\DPS\EFTPOS\DDE
KeepResultsTimeout Specifies (in seconds) how long to keep a response file after it is sent to the client. This should be kept as small as reasonably possible. Default: 10 seconds
Topic Allowed topics using paramaters such as the name. There could be multiple topics any ordering is irrelevant. Configuration file example if using DDE:

EFTPOS Tray application (DpsEftTray.exe)

This should be installed in your Eftpos installation directory and is configured with the file "dpsefttray_cfg.txt", which is documented below. This tray process gives access to control panels of the ActiveX, such as Config/Setup and Maintenance and access to the Payment Express EFTPOS client.

The Tray process also monitors folders for *.req files if a merchant is wanting to interact with the EFTPOS system by submitting our file format.

< Monitor >

Setting Description

InName Name of the file types to monitor and read. Default: *.req

OutName Name of the file type to output for the result. Default: %n.evt

Dir Directory to monitor for the input files and to place the output files. Default: C:\Program Files\DPS\EFTPOS\FileInterface

< HotKeys >

Setting Description

Enabled You can enable hotkeys by setting to true (1) or set to false to disable (0). Default: 1

Action This describes what happens when a hotkey is pressed. Values can be "Client", "Maint" &"Setup", which open up the corresponding applications or dialogs.

Key Key to press in conjunction with the Modifier key to access the HotKey. Usually F1-F12. Default: F9

Modifier Service Key to press in conjunction with the "Key" to access the HotKey. Values can be "Win", "Alt" or "Ctrl" and can have multiple modifiers per HotKey.

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.

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

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.

Properties

AmtPurchase (input) Datatype: BSTR Max 13 Bytes

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

AmtCash (input) Datatype: BSTR Max 13 Bytes

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).

Date (output) Datatype: BSTR Max 8 bytes

Date on which the transaction was processed. The format of this number is yyyymmdd.

DateSettlement (output) Datatype: BSTR Max 8 bytes

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.

EnablePrintSlip (input) Datatype: Boolean true/false

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

EnablePrintReceipt (input) Datatype: Boolean true/false

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.

Width (output) Datatype: LONG

The number of characters on each line of the receipt. Range 1-30.

Reco (output) Datatype: BSTR Max 2 Bytes

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

ResponseText (output) Datatype: BSTR Max 20 Bytes

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.

Success (output) Datatype: Boolean true/false

Indicates success or failure of a method call.

Time (output) Datatype: BSTR Max 8 bytes

Time at which the transaction was processed. The format of this number is hhmmss.

TxnRef (input/output) Datatype: BSTR Max 16 Bytes

A reference ID for the transaction. This can be used as a search term in the web reporting framework.

TxnType (input) Datatype: BSTR

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