API ActiveX Object

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

Installation Instructions

The Payment Express EFTPOS software can be found below -

Download Installer

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.

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 Payment Express 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
PrinterNam e 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 Payment Expresswhen 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 eventMaintDoneEvent 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.

DoConfig (Request)

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 Payment Express 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 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
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.

Output Properties

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)

Fires when the call to DoEnterData is completed.

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 theDisplayLine1 & 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 theEnableInvisible 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

Output Properties

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 Payment Express 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

OutputReceiptEvent

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 Payment Express always and any deviation from that, theStatusChangedEvent 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 theEnableTestMode 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

Authorized (output) Datatype: Boolean true/false

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

Amount (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

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

AmountCreditLimit (input) Datatype: BSTR Max 13 Bytes

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.

AuthCode (input) Datatype: BSTR Max 22 bytes

Authorisation code returned by the Bank for approved transactions.

The value can be numeric or alpha-numeric.

BillingId (input) Datatype: BSTR Max 32 characters

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

CardNumber (input/output) Datatype: BSTR Max 19 bytes

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

CardType (output) Datatype: BSTR

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.

Output Properties

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

ClientId Datatype: BSTR Max 8 bytes

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

ClientType (input) Datatype: BSTR Max 1 byte

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

CurrencyId (input) Datatype: LONG

The currency to use for Dynamic Currency Conversion.

Currency

Currency Id Currency Name
36 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
90 Solomon Islands Dollar

CurrencyRate (input) Datatype: BSTR

The rate of the foreign currency against the home currency.

Cvc2 (input) Datatype: BSTR Max 4 bytes

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:

DateExpiry (input) Datatype: BSTR Max 4 bytes

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

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.

DateTimeTransaction (output) Datatype: BSTR

Indicates when the transaction was processed. HHMMSS format.

DpsBillingId (output) Datatype: BSTR Max 16 characters

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.

DpsTxnRef (output) Datatype: BSTR Max 16 bytes

A unique identifier returned for every transaction.

EftStatus (output) Datatype:LONG

Reserved

EnableAddBillCard (input) Datatype: Boolean true/false

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

EnableBackLight (input) Datatype: Boolean true/false

Enhances the backlight brightness of the Pinpad display.

EnableBlockingMode (input) Datatype: Boolean true/false

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.

EnableIgnoreCardReadError (input) Datatype: Boolean true/false

Reserved

EnableInvisible (input) Datatype: Boolean true/false

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.

EnableManualPan (input) Datatype: Boolean true/false

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

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.

EnableTestMode (input) Datatype: Boolean true/false

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.

InProgress (output) Datatype: Boolean true/false

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.

InputMask (output) Datatype: BSTR

Reserved

KeyMap (output) Datatype: BSTR

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.

MerchantReference (input) Datatype: BSTR Max 64 bytes

Free text to appear on transaction reports.

OutputTrack1 (output) Datatype: BSTR

Display the Track 1 data captured from the magnetic strip

OutputTrack2 (output) Datatype: BSTR

Display the Track 2 data captured from the magnetic strip

OutputTrack3 (output) Datatype: BSTR

Display the Track 3 data captured from the magnetic strip

Ready (output) Datatype: BOOL

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.

ReadyLink (output) Datatype: BOOL

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

ReadyPinPad (output) Datatype: BOOL

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

ReadyState (output) Datatype: LONG

Reserved

ReceiptHeader (output) Datatype: BSTR

You can include your own header to appear on the receipt

ReceiptTrailer (output) Datatype: BSTR

You can include your own footer to appear on the receipt

Receipt (output) Datatype: BSTR

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

ReceiptIsSeparate (output) Datatype: BOOL

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.

ReceiptWidth (output) Datatype: LONG

You can specify the width that the receipt will be formatted with. 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. TheAuthorized 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.

Track1 (input) Datatype: BSTR

Capture track 1 data with the magnetic strip

Track2 (input) Datatype: BSTR

Capture track 2 data with the magnetic strip

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

Unique transaction reference 1-16 alphanumeric character.

TxnType (input) Datatype: BSTR

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

VersionEft (output) Data type: LONG

VersionPos (output) Data type: LONG

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 -

Eftpos Environments

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 DpsTxnRefreturned 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 -

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 toHospitality 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. TheCardnumber 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 haveOutputDisplayLine1 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 Amountproperty. 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)

Fuel Transactions (Reserved)

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

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 andDisplayLine2 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