Articles in this section

POSitouch v1 Punchh Integration Instructions (dashboard POS Type=Punchh Secure)

Avatar
Scott Morgan
Updated Print PDF

This guide is only for brands with POSitouch locations that are using the “Punchh Secure” dashboard POS Type. If you are unsure of your dashboard POS Type, please reach out to your Customer Success Manager. 

Prerequisites

System requirements for the PC hosting the Punchh service (i.e. the back-office PC)

  • Minimum OS: Windows 7 (with SP1) and .NET Framework 4.6.1

Configure firewall/router

ALLOW:

FROM:

TO:

BY:
(Software Firewall on PC running Punchh processes)

TCP port 443

The PC hosting the Punchh service

pos.punchh.com
isl.punchh.com
loguploads.punchh.com - poslogs.punchh.com -

Punchh.exe (Back Office PC)

Details
pos.punchh.com - Punchh check-in and redemption transactions, Punchh application configuration & update server
isl.punchh.com - Punchh check and barcode details
loguploads.punchh.com - Punchh log file repository #1
poslogs.punchh.com - Punchh log file repository #2

Configure antivirus

  • Whitelist the EXE applications in the Punchh install folder: C:\Program Files (x86)\Punchh

Application Whitelisting

  • Whitelist all of the Punchh EXE in the Application Whitelisting Control to allow communication over network.

  • Whitelist all applications that are digitally signed by “Punchh, Inc.”

    • To allow updates without having to go back and “re-fingerprint” individual EXEs

Version and licensing requirements

  1. POSitouch version must be 6.41.0 or later. Here is how to check your POSitouch version:

    1. Open C:\SC\ERROR.LST in Notepad.

    2. CTRL+F, search for "Spcwin startup". Any lines that contain "Spcwin startup" will also contain the version number:

      1. 07/18/19 09:16:07 500 Spcwin startup: 6.41.0* 04/23/2019 05:56:42 3032576 bytes WINNT 6.1 (Windows 7) 64-bit

  2. Loyalty module must be licensed and enabled.

Printers

  • Check with your POSitouch dealer to ensure that your printers can print QR codes.

    • Note: If your printers can’t print QR codes, guests can still earn points by manually entering the 13 digit “punchh key“ printed at the bottom of receipts into the mobile app.

Create the “cell type 9” and “cell type 7” items

Create the “cell type 9” item

  1. Open Back Office Setup > Menu Editor > Edit An Order Screen

  2. Select a screen, then select an empty cell.

  3. On this form, make the following changes:

    1. Cell name: "MEMO"

    2. Cell type: 9-Memo

    3. Prep Cat: None required

    4. Opt Rtng: 0-with main item

  4. Click Save.

Create the “cell type 7” item

  1. Open Back Office Setup > Menu Editor > Edit An Order Screen

  2. Select a screen, then select an empty cell.

  3. On this form, make the following changes:

    1. Cell name: "LOYALTY QR CODE"

    2. Cell type: 7-Primary item, not taxed

    3. Prep Cat: None required

    4. Opt Rtng: 0-with main item

    5. “Exclude from check?” checked

  4. Click the Add button.

    1. Screen #: Select the screen where the “MEMO” cell is located.

    2. Option type: 3-MAY SELECT

    3. Check the checkbox next to “MEMO”.

  5. Click OK.

  6. Click Save.

  7. Back Office Setup > Immediate System Change

Define check footer

  1. Go to Back Office Setup > Hardware > Guest Check Headings > Headings 2.

  2. Add the following 5 lines.
    Note: For the third line, copy the contents of this file: third_line.txt

  3. Edit each line to have the same settings as the following:

    1. Check “Print on hard check?”

    2. Check “Print on soft check?”

    3. Check all the Cost Centers.

  4. Back Office Setup > Immediate System Change

Create the virtual XML Printer

  1. Go to Back Office Setup > Hardware > Prep Printers > Locations and Types.

  2. Click Insert.

  3. Enter the following:

    1. Printer Number: Enter the next sequential number (see image below).

    2. Printer Name: XML Printer

  4. Click Yes

  5. Select the new printer and click EDIT.

    1. Printer Type: 1- Virtual printer

    2. Device Location: 0- Normal-unmapped!

  6. Click Ok.

  7. Open C:\SC\SPCWIN.INI in Notepad. Edit the file as follows:

    1. In the [SpcWin] section, add:

      1. CC_SocketClose=YES

    2. In the [XML] section, add:

      1. XMLInPath=C:\SC\XML\IN

      2. XMLInOrderPath=C:\SC\XML\INORDER

    3. In the [VIRTUAL] section, add:

      1. VirtualPath11=C:\SC\XML\CHECKS

      2. Note: The number 11 in “VirtualPath11” is taken from the table as shown below (Back Office Setup > Hardware > Prep Printers > Locations and Types):

  8. Go to Back Office Setup > Restaurant Misc Data > XML I/O.

    1. Note: If other third party integrations are currently installed and utilizing XML I/O functionality, then specify folder paths that are unique to Punchh (ex: C:\SC\XML\Punchh\XYZ).

    2. Select our new "XML Printer" for the following XML types:

    3. Click the “XML Ordering“ Configure button and edit the info as follows:

    4. Click the “Open Checks Request“ Configure button and edit the info as follows:

    5. Click the “XML Services“ Configure button and edit the info as follows:

    6. Click the “Virtual Printer Path“ button and edit the info as follows:

  9. Back Office Setup > Immediate System Change

Install & Configure the Punchh service

Installation

  1. On the PC that’s going to be hosting the Punchh service (i.e. the back-office PC), run the SetupPunchh_vX.X.X.X.exe, and complete the installation wizard.

  2. After installation is completed, confirm that the Punchh service is now running:

Configuration

  1. Navigate to the folder C:\Program Files (x86)\Punchh and run PunchhConfigurator.exe as administrator.

  2. Change API to: pos
    Enter the Location Key (aka API_Key) and Business Key:

  3. Set the POS_Type to POSitouch:

  4. Click on the POSitouch.cfg tab, then change the settings as follows:

    1. PathToChecks, PathToIn, PathToInOrder, and PathToSC: Refer to the “Create the virtual XML Printer” section of this guide to obtain the values for these settings.

      1. Note: If the POS Driver is hosted on another computer then replace "C:\" with the network path to the C drive on the POS Driver. Don't use mapped letters like "L:", it has to be full network path instead, for example like this: \\192.168.2.1\C\SC.

    2. Port: The default port is set to 5614. If this port is already in use by another application, then an error will appear in the log files. See the Troubleshooting section of this guide for more details.

    3. MemoItemNum: Set this value to the Item ID of the cell type 9 “MEMO” item that was previously created.

    4. QRCodeItemNum: Set this value to the Item ID of the cell type 7 “LOYALTY QR CODE” item that was previously created.

    5. UsePunchhSecurePOSType: Set this value to True.

    6. UseV1PosiIntegration: Set this value to True.

    7. Leave all other settings with their default values.

  5. Click Apply, then Exit.

  6. Restart the Punchh service.

  7. Click Exit or click the X in the upper-right to close the PunchhConfigurator tool.

Add custom credit card payment method for Punchh redemptions

Punchh redemption codes are accepted by POSitouch as 7-digit credit cards. This step is required to define this payment type.

  1. Go to Back Office Setup > Payment > Forms of Payment

  2. Add a new payment type named “PUNCHH”:

  3. Go to Back Office Setup > Credit Card > User Defined CC

  4. Add the following line as shown below:

  5. Click on More Flags and select the Loyalty Pay Type to be PUNCHH:

  6. Go to Back Office Setup > Credit Card > Forms Of Payment and check the following boxes:

  7. Go to Back Office Setup > Credit Card > Credit Card Types

  8. Define the Punchh Payment Type as shown below. Select unused channel 4, 5 or 6.

  9. Go to Back Office Setup > Credit Card > Merchant Data and click on the More 1 field.

    1. Define channel selected in the previous step as shown below. Modify the Port to match what’s specified in the Punchh Configurator (note: avoid ports 5002, 5003, 5025, 5026, 4444, and 3333). Specify the local IP address of the PC hosting the Punchh service.

  10. Back Office Setup > Immediate System Change

How to apply Punchh redemption codes

  1. Ring up an order

  2. Go to take payment and touch CC AUTH

  3. Enter the card number (i.e. 7-digit redemption code) and touch ENTER

  4. Touch LOYALTY REDEEM on the left

  5. Touch ENTER

  6. Punchh will then validate the redemption code. If successfully validated, the amount will be shown here. If not successfully validated, an error message with further details will be displayed.

  7. Touch PAYMENT and you will see the Punchh payment on the screen:

  8. Touch ENTER and then CASH to complete the sale:

Troubleshooting

If you are getting errors when applying redemptions or when trying to scan the QR code to earn points please check Punchh logs for errors. Logs are located here: C:\Program Files (x86)\Punchh\Logs

Log files are named by date, for example:

2017-0223-000050.log 

was created on Feb-23, 2017

Port conflict error

If the default port is already in use by another application, a port conflict error will occur. In the log file, please search for the text “Port conflict occurred”. If this text was found, then the error occurred. To resolve this error, please use the PunchhConfigurator tool to change the default port to an unused TCP port. Some suggested ports, usually not in use, are: 5619, 7482, 24473, 10123.

Known Issues

  1. Receipts displayed on the Punchh dashboard will show the price of modifier items as $0.00.