There are several different Eftpos providers and solutions that can interface with Fieldpine POS. Before starting ensure you have correctly identified which solution is in use as the steps are specific to each interface
Pinpad Error Codes
When performing a transaction the EFT subsystem may return a bank response code giving more information. While the exact meaning of the code depends on which acquirer and EFT system you are using, the codes are broadly defined. Tip. If searching for a code that isn't shown below, search the internet for "eft response code NN".
We always suggest trying a second time when an error is returned. There are many components to an Eftpos transaction, so small glitches can compound to fatal sounding errors
|00||Success, transaction accepted|
|08||Success, transaction accepted with signature|
|12||Invalid transaction, tran not allowed. The bank declined the transaction. A common cause is pressing "cheque" or "Saving" when using a credit card|
|51||Insufficient funds. If getting this error repeatedly, verify your EFT system is online, and/or contact the card issuer|
|52||Account error. The account the user selected, cheque, savings, credit, is not valid for this card.|
|54||Card has expired.|
|TC T7||(Eftpos NZ) Transaction cancelled by operator or customer|
Smartpay (KeyLink Plus)
The Smartpay Keylink plus interface connects the POS via a serial cable, or USB to serial adapter. The interface is two-way, in that the POS reads the result from the Pinpad but staff do have the ability to manually override the transaction.
The interface to this EFT solution is inside the POS directly (fpos.dll) and does not require additional files
When a payment is sent to the Smartpay terminal, the Point of Sale displays a status screen as shown below. The buttons on this screen are initially locked for several seconds and will unlock after a preset timer. This intial locking is to stop staff from answering before the pinpad could possibly have worked or failed. The screen will close automatically as soon as payment details are received.
If this screen is not closing automatically, then the physical connection to the pinpad has been lost (cable fallen out, COM port changed) or pinpad is not in keylink plus mode.
Not working at installation
Installation of Keylink plus is not difficult, but does require all parts to be correct before it will come alive
- Edit fpos.ctl file and ensure the correct COM port is entered. Example
;;##SMARTPAY Keylink Plus SPECIFIC SETTINGS added june 13 2015 by JJ## force:SerialDevice.0.Type=keylink force:SerialDevice.0.Port=com1 force:SerialDevice.0.LogFile=keylink.out
If you change any settings in fpos.ctl you need to restart the Point Of Sale for the change to be effective.
- If the COM port number is greater than 9, then you must use the following format to specify the port name. The example below is showing
COM23. You can use this format for COM ports less than 9 too if you wish.
It can be difficult to be certain you have the correct COM port if more than one port is present in the computer. Unless you have specific testing hardware you will need to try each COM port in turn.
- Fieldpine Point of sale sets all the COM port parameters and you do not need to worry about the COM port settings in Windows device manager. To be specific the POS automatically sets all KeylinkPlus solutions to 9600 baud, 8 bits, no parity, no hardware flow control, no XON/XOFF flowcontrol.
- Ensure the pinpad is in keylink mode. They are usually configured to this already if it was specified at purchase time. Run through all other checks first and then Smartpay for guidance on doing this.
- Try a transaction and attempt payment by Eftpos. The pinpad should beep and show the amount to charge. If not,
open the keylink.out log file and go the end. You should see something like the following
13/08/2012 4:23:09 p.m. W 28 = .PUR,1,000191.92,000000.00.KThe amount has been highlighted above and will show your amount.
- If the log is showing payment requests but the amount is not being received by the pinpad, then the POS is writing to the COM port specified without errors. It is likely the problem is outside the POS application.
- If the log is not showing payment requests then the POS is not configured correctly or the com port to use is already in use. Try rebooting the PC and try again.
- If the Pinpad is receiving the payment, then after it is accepted or declined the POS is able to automatically read the
status. Complete the transaction on the pinpad but do NOT press yes or no until after the pinpad has finished printing. The
POS listens for the printing and does not get status information until after the EFT receipt has printed.
If this is NOT working, then the most common cause is the wrong cable. Smartpay have different cables for Keylink (one way mode) and Keylink Plus (two way mode).
- If you wish you can prove the POS is sending and receiving on the COM port (which tests the physical port and USB/serial adapter). You need to connect a RS232 loopback connector or connect pins 2 and 3. This is an advanced test and rarely required. (Everytime Fieldpine has tested using loopback connectors it has functioned correctly if the logs were also being written correctly)
- Check if the COM port is being used by another program, or another feature inside the POS
- Run the Windows program "Hypertrm" or equivalent. Try and connect using COMx. This program will give an error if the COM port is in use. Try both with POS running and not running.
- If the port is in use and POS is not running, then another program on this computer has the port allocated.
- If the port is in use only while the POS is running then check if
- A barcode scanner is also configured on this port
- If scales are configured on ths com port
- If Customer pole displays are configured on this com port
- Have you changed from one Eftpos vendor to another? Has the old vendor being fully removed from Windows? Payment express will open the com port when the POS is started if it was configured to use the same port.
Was working, now not working
- Ensure USB cable plugged into correct port still. Switching the cable to a different USB port can cause a new and different COM port to be allocated. Plugging the cable into the correct USB port will solve this without any changes to software or pinpad.
- Cable disconnected. Generally the USB cable and the cable that goes to the pinpad are two or even three cables that join together. Ensure all these joins are secure and tight. If the cables do not have proper locking clips then consider taping the cable connectors together to avoid them coming loose. Do not assume that there will be no movement as cables and PCs will be moved or pulled during the expected installation life.
- Verify the COM port is not in use by some newly installed software which prevents the POS from opening the COM port.
A symptom of this will be that the keylink.out trace file will no longer be writing payment request lines (see install problems above).
With version P1914, you can issue quickcode "120" to review chat messages. The Keylink interfaces adds a chat message if it cannot open the COM port.
Keylink Trace File
The POS maintains a log file of all data sent and received over the COM port to the pinpad. An example log file is:
3/12/2010 12:38:50 p.m. W 28 = .PUR,1,000369.90,000000.00.L 3/12/2010 12:39:22 p.m. W 8 = .CAN,1.R 3/12/2010 12:39:26 p.m. W 28 = .PUR,1,000369.90,000000.00.L 3/12/2010 12:39:29 p.m. R 324 = RETAILER XYZ THE PLAZA PALMERSTON NORTH *------EFTPOS------* TERMINAL 66724601 TIME 03DEC 12:41 TRAN 004179 SAVING CARD ....3053 VISA RID: A000000003 PIX: 1010 PURCHASE NZ$369.90 TOTAL NZ$369.90 INVALID TRANSACTION . DECLINED *------------------* CUSTOMER COPY
The lines can be decoded as follows
|3/12/2010 12:38:50 p.m.||W||28 =||.PUR,1,000369.90,000000.00.L|
W means we wrote to the pinpad
|Number of bytes||Actual data, purchase of 369.90 in this case|
|3/12/2010 12:39:22 p.m.||W||8 =||.CAN,1.R|
|Date/Time||R/W flag||Number of bytes||Actual data, Cancel transaction|
|3/12/2010 12:39:29 p.m.||R||324 =||RETAILER XYZ|
|Date/Time||R means we read data from the pinpad||Number of bytes||Actual data received|
- When operating, the POS user is given a screen to specify "Yes" or "No" to the payment progress. This screen
should not be required if everything is working correctly. It is provided only so that should something go wrong that the POS does not
To help prevent staff pressing yes or no prematurely the buttons are locked for a period. Fieldpine recommend this period is set to slightly longer than the normal transaction duration, but not so long that it is unbearable. About 20 seconds is reasonable. If you wish to alter this period, the setting EFTSerialLockDelay sets the number of seconds to leave the screen locked
- If the staff press yes or no wrongly (yes for no, or vice versa) then there is no option to change this. The staff have given an authoritive statement which cannot be altered without opening the potential for fraud.
Eftpos New Zealand
The Eftpos New Zealand interface connects pinpads directly to the computer, but Eftpos NZ also install a program into the PC to communicate to the POS and pinpad.
The interface is two-way and fully integrated which means that there is no operator discretion at any stage.
The minimum version of Eftpos NZ code that Fieldpine will support is V2.5.3.x (and OCX Version 220.127.116.11). Versions older than this should not be used. If you are running an older version the Point Of Sale will warn you on startup and advise you to contact ENZ for an update. You can still process and accept payments with older versions, but you cannot call Fieldpine support for any Eftpos payment related issues until you have upgraded to a supported version.
This interface requires the interface dll "fpenzv5.dll". If you are using Version 7 or higher of ENZ code, you must be using fpenv5.dll version 18.104.22.168 or higher.
If you are using Analyse Purchase functionality (eg Cardlink, etc), you must define the setting EftSendField48=1. This setting changed default from yes to no when version 7 of ENZ software was released, so you must now explicitly enable this functionality.
If the interface is not working or hanging, verify that the "Eftpos Client" is running. You should be able to see a green icon in the status bar if the client is functioning correctly. If the icon is red, click the icon to display the eftpos control panel and diagnose the problem. This client is part of the ENZ software so any questions should be directed to your eftpos service provider.
Often an Eftpos problem will be reported on the receipts printed, as shown to the left. Problems seen on receipts like this should be directed to Eftpos NZ support as they are reporting problems from the Eftpos sub system.
Comms Error The eftpos system failed to connect to the bank or acquirer. Verify your store has internet access, or phone lines are working.
In some rare circumstances the Eftpos subsystem will return a payment failure to the POS after the transaction. Specifically this is when the computer has lost connection to the pinpad. When this happens, the POS has not received a useable response from the Pinpad and human assistance is required.
The POS will stop and ask the user if the transaction worked or not, and their response is set as the actual payment status. If they say "yes" when payment was not actually received, the customer will not be charged. If they say "no" when the payment was received, the customer may be charged twice. We strongly urge you to capture the customer contact details in case repayment is required.
If you have these errors, the customer details entered are stored in the EnzTrace file of the machine. You should contact Eftpos NZ for further help as to the underlying cause of the problem
This internal failure handling requires fpenzv5.dll Version 22.214.171.124 or higher
Hanging on Payment
If the Point of Sale is hanging on the processing screen shown below, then the POS is waiting for a valid response from the Eftpos system.
When this happens the POS has initiated a transaction to Eftpos and needs to wait for a valid yes/no answer. There are a couple of known causes for this
Hidden message or prompt
Eftpos is prompting and the prompt screen is behind another screen. This is rare, and the user needs to use alt-tab to find the prompt/message and action it
Invalid Transaction identifier
Another possible cause is that Eftpos has responded with invalid information to the POS, and it is waiting for the correct information. To verify this is the cause open the file EnzTrace_date.out using a text editor such as notepad. Locate the transaction involved, which is generally at the end of the file. Look for the pattern and errors shown below. If you have this problem, please contact the payment provider and ask about disabling "Tru Ratings"
***** This is the Pos starting the payment, normal operation ***** 11-May-2021 12:43:49 DotranG ttype=1, amt=19, cash=0, ref=852321633-1049, res=0 Disable=credit SetAllowCredit OFF Setting Field48 310000010001900 Performing Transaction Modal wait for transaction **** Pos is restarting - presumably eftpos hung Normally at this point in the log we see print requests, payment accept/decline, etc, but not nothing **** Creating UserDlg 23/4/04 C at 11-May-2021 12:48:36 Loading Static Information into OCX.0006 Detected ENZ version is 126.96.36.199 Inserting mandatory sleep 3 seconds in case we are too fast for ENZ UserDlg Online OK Initiating transaction4 **** Pos attempting to recover payment. This is part of startup and normal **** 11-May-2021 12:48:40 DotranG ttype=5, amt=19, cash=0, ref=852321633-1049, res=1 Disable= SetAllowCredit ON Setting Field48 310000010001900 Recovering Last Transaction Modal wait for transaction Modal end for transaction Transaction Reference Ids differ (b) ******** BAD, Eftpos doesnt have our transaction details 852321633-1049 Recover sale packet not being sent: <eftpostxndata> <accounttype></accounttype> <amtcash>108879.1793</amtcash> *** really? They paid as $108,879 ? We requested $19 <amttip>108879.1793</amttip> <authcode></authcode> <caid></caid> <catid></catid> <tdate></tdate> <dateexpiry></dateexpiry> <datafield></datafield> <datesettlement></datesettlement> <enabletip>193974832</enabletip> <merchant>193974832</merchant> <pan></pan> <responsecode></responsecode> <responsetext></responsetext> <stan>193974832</stan> <totalcash>108879.1793</totalcash> *** ??? <track1></track1> <track2></track2> <txnref></txnref> <eftpostxndata> <accounttype></accounttype> <amtcash>108879.1793</amtcash> <amttip>108879.1793</amttip> <authcode></authcode> <caid></caid> <catid></catid> <tdate></tdate> <dateexpiry></dateexpiry> <datafield></datafield> <datesettlement></datesettlement> <enabletip>193974832</enabletip> <merchant>193974832</merchant> <pan></pan> <responsecode></responsecode> <responsetext></responsetext> <stan>193974832</stan> <totalcash>108879.1793</totalcash> <track1></track1> <track2></track2> <txnref></txnref> <txnsuccess>0</txnsuccess> <cardtype></cardtype> <cardname></cardname> <amtpurchase>108879.1793</amtpurchase> <messagetype>193974832</messagetype> <receipt></receipt> <txn_duration>829</txn_duration> </eftpostxndata> 11-May-2021 13:02:29 returned to pos status=0 ESuccess=2508288 EStan=1162691627 TxnRef=
Eftpos Trace File
The Eftpos NZ interface writes a log file of all interaction with the eftpos subsystem. The file is called EftTrace_YYYY_MMM.out If you believe you have a programming level issue, you can review this file to help isolate whether the program is POS side or Eftpos side.
Example Log File (colour added for explanation)
Creating UserDlg 23/4/04 C Loading Static Information into OCX.0006 Detected ENZ version is 188.8.131.52 Getting Merchant Setup Information UserDlg Online OKInitiating transaction4Dotran ttype=1, amt=163.34, cash=0, ref=8709842-0, res=0 Disable=creditSetAllowCredit OFF Setting Field48 310000010016334 Performing Transaction Modal wait for transaction Transaction Event Modal end for transaction<eftpostxndata> <txnsuccess>0</txnsuccess> <accounttype></accounttype> <amtcash>0</amtcash> <amttip>0</amttip> <authcode></authcode> <caid></caid> <catid></catid> <tdate></tdate> <dateexpiry></dateexpiry> <datafield></datafield> <datesettlement></datesettlement> <enabletip>0</enabletip> <merchant>1</merchant> <pan>498872......8454</pan> <responsecode>T7</responsecode> <responsetext>TRANSACTION CANCELLED</responsetext> <stan>0</stan> <totalcash>0</totalcash> <track1></track1> <track2></track2> <txnref>8709842-0</txnref> <cardtype></cardtype> <cardname></cardname> <amtpurchase>163.34</amtpurchase> <messagetype>0</messagetype> <receipt></receipt> <txn_duration>23</txn_duration> </eftpostxndata>
The section highlighted in green is added when the fpenzv5.dll is initialised. It shows the version of the User screens being used and initial configuration of the ENZ subsystem
The blue section is written when a transaction is requested from the Pos. The ttype parameter indicates the type of transaction being requested.
The red section shows the interaction of the Pos to the ENZ subsystem that performs the actual transaction
The section in yellow shows the data being returned to the Pos in order to apply the payment to the sale