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

Eftpos Receipts Print/Don't Print

The printing of eftpos slips, such as the eftpos payment receipt, or "signature required" is controlled from several places, and varies according to the eftpos solution you are using.

Within Fieldpine, you can control the global printing options for eftpos. From your Store Server, click "settings" and then "Eftpos Terminals". Within the list of options you will see the following.

Print Eftpos Receipts This tells the POS to instruct the eftpos pinboard to print receipts or not. Most eftpos solutions do not have any ability for Fieldpine to tell them not to print, so in general this has no effect.

Print Eftpos Receipt Inline If the POS is able to print receipts, should it be printed "inline". An inline receipt means the eftpos payment details appear within the customer receipt beside the payment record. This means it appears in the lower part of the receipt, before any footer text

If you are using receipt templates (often used for A4 or email receipts) then inline printing is controlled by the template

If you change these settings, the values may need time to sync to the lanes, and you will need to restart POS as well

For all solutions, a receipt reprint (eg several hours later, after customer has gone) the printing is controlled by Fieldpine, and only if the eftpos solution was able to provide us a copy of the receipt

For more detail, read the specific notes per eftpos solution below

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

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

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

   force:SerialDevice.0.Port=\\.\COM23
   

   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.

3. 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.
4. 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.
5. 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.K
   

   The amount has been highlighted above and will show your amount.
6. 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.
7. 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.
8. 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).

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

Working Sometimes

1. Check if the COM port is being used by another program, or another feature inside the POS
   1. 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.
   2. If the port is in use and POS is not running, then another program on this computer has the port allocated.
   3. 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

1. 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.
2. 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.
3. 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.

Receipt Printing

Eftpos receipt printing is controlled by Smartpay, including the physical printing to their own printer.

• "Print Eftpos Receipts" has no effect, but we suggest setting it how you would like it regardless.
• "Print Eftpos Receipts Inline". For this the POS will chose "No" by default
• Fieldpine has no control over additional receipts and slips such as "signature required" or End of Day

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

Notes

• 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 lock forever.

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

Common Problems

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.

This message is displayed by the Eftpos software not Fieldpine. It is typically triggered to display when Fieldpine POS requests an Eftpos function. You should reboot Windows and contact Verifone as the message states.

This message indicates that Fieldpine already has a call outstanding to Eftpos, and we are attempting another call before that first one has completed. 99% of the time this is caused by users cancelling things, or trying to work around other errors.

Once this message starts to display, it generally continues for every subsequent call. Close the POS and restart it. This clears the outstanding "missing" call and allows it to proceed.

If this message comes back again quickly, then verify that the store does not have other issues before this happens - ie payments not going to the pinpad, or they are force closing windows and dialogs. If there is a cause like that, concentrate on that error - this recursive message is always caused by an event before displaying this message

If you believe there is no fault, then enable tracing and generate this error message. Send to Fieldpine that trace file and the ENZ journal.

Internal Failures

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 1.0.3.23 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 7.9.5.17
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 us $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 6.2.0.6
Getting Merchant Setup Information
UserDlg Online OK

Initiating transaction4

Dotran  ttype=1, amt=163.34, cash=0, ref=8709842-0, res=0 Disable=credit


SetAllowCredit 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

Payment Solutions

Windcave, (formally Payment Solutions, formally Direct Payment Solutions) is enabled by the setting EFTUseDps=1 typically this is present in the lane fpos.ctl file

force:EFTUseDps=1

You can use the quickcode "f760" to enable Windcave on a lane. This quickcode adds the line to fpos.ctl and disables other eftpos solutions.