Fieldpine Logo  

Eftpos Pinpads Roadmap

All Roadmaps Documentation

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

Response CodeDescription
00Success, transaction accepted
08Success, transaction accepted with signature
12Invalid transaction, tran not allowed. The bank declined the transaction. A common cause is pressing "cheque" or "Saving" when using a credit card
51Insufficient funds. If getting this error repeatedly, verify your EFT system is online, and/or contact the card issuer
52Account error. The account the user selected, cheque, savings, credit, is not valid for this card.
54Card has expired.
55Incorrect PIN
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.

Smartpay eftpos transaction status

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.

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
Date/TimeR/W flag.
W means we wrote to the pinpad
Number of bytesActual data, purchase of 369.90 in this case
3/12/2010 12:39:22 p.m. W 8 = .CAN,1.R
Date/TimeR/W flagNumber of bytesActual data, Cancel transaction
3/12/2010 12:39:29 p.m. R 324 = RETAILER XYZ
THE PLAZA
PALMERSTON NORTH
Date/TimeR means we read data from the pinpadNumber of bytesActual data received

Notes

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.


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

Eftpos Failure

This internal failure handling requires fpenzv5.dll Version 1.0.3.23 or higher

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