Articles in this section

POSitouch v2 Punchh Integration Instructions (dashboard POS Type=POSitouch)

Avatar
Scott Morgan
Updated Print PDF

This guide is only for brands with POSitouch locations that are using the “POSitouch” 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)

TCP Port 5614 (Default Port)

POS Terminals

The PC hosting the Punchh service.

PunchhUI.exe (POS Terminals)

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. The v2 integration requires POSitouch to be version 6.41.0 or later. Please do the following steps on the back-office PC to check the 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

Create the “cell type 12" discount item

Note: A “cell type 12” item represents a loyalty discount. These discounts will get applied to checks whenever a loyalty discount is successfully redeemed.

  1. Open Back Office Setup > Menu Editor > Menu Items & Recipes.

  2. Click "Add Record". Enter an item ID, then click OK:

  3. In the Descr field, enter a name for the loyalty discount.

  4. Select a Major Cat and Minor Cat.

  5. Enter 0.00 for Price 1, Price 2, and Price 3.

  6. Under Tax Eligibility, check all of the taxes that you want the loyalty discount to apply to.

  7. Make a note of the Item ID (i.e. 97). You will need it in later steps.

  8. Click Save.

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

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

  11. On this form, make the following changes:

    1. Cell name: "AMOUNT"

    2. Cell type: "3-General mult (xx.xx)"

  12. Verify the settings highlighted below, then click Save
    (The rest of the settings may be left with their default values)

  13. Back on the "cell selector" form, select another empty cell.

  14. Click the "Lookup" button, then click "Search by #".

  15. Enter the item ID of the "DISCOUNT" item you just created, then click OK.

  16. Click "Select".

  17. On this form, make the following changes:

    1. Cell type: "12-Discount"

    2. Check "Open Dollar?"

    3. Prep Cat: "None required"

  18. Click the "Add" button near the bottom-right.

    1. Option type: "3-MAY SELECT"

    2. Screen #: Select the screen that the "AMOUNT" cell is on.

    3. Check "AMOUNT"

    4. Verify with the below image, then click OK.

  19. Verify the information with the below image, then click Save.

  20. OPTIONAL: If you want to restrict what the loyalty discount can be applied to at the POS level (i.e. preventing alcohol items from getting discounted), then follow these steps:

    1. Open Back Office Setup > Discounts & Surcharges.

    2. Click Add:

    3. For Discount Name, enter “LOYALTY DISCOUNT”.

    4. For Inventory Number, enter the Item ID of the cell type 12 item that was recently created.

    5. Select the taxes that you want the loyalty discount to be applicable to.

    6. Check the “'Open dollar' discount?” checkbox, along with the checkbox beneath it.

    7. Make a note of the Discount Number, you will need it later.

    8. Click Ok

    9. Open Back Office Setup > Menu Editor > Edit An Order Screen. Re-open the cell type 12 item that was recently created.

    10. Check the “Discount eligibility?” checkbox.

    11. Click the Lookup button.

    12. Under the “Discounts” button, check the checkbox for the Discount Number (i.e. 6, from the Discounts & Surcharges menu).

    13. Click Save, then Exit.

    14. Click Save.

    15. For all the items that you don’t want the loyalty discount to be applied to, edit the items so that the checkbox under the Discount Number is unchecked:

      1. Note: You can bulk edit items via the “Multi.Rec.Change” button.

    16. For all the items that you want the loyalty discount to be applied to, edit the items so that the checkbox under the Discount Number is checked:

      1. Note: You can bulk edit items via the “Multi.Rec.Change” button.

  21. Back Office Setup > Immediate System Change

     

Configure settings to enable the user program button

  1. Back Office Setup > Restaurant Misc Data > System

  2. Back Office Setup > Payment > Payment System Options 1 > More Flags

  3. Back Office Setup > Hardware > Terminal Stations

    1. Verify that this value is unchecked:

  4. Back Office Setup > Restaurant Misc Data > XML I/O > More Flags

  5. Back Office Setup > User Privilege Codes > Assign Privileges 1-8

  6. 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 2 lines:

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

  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 back-office PC, login as an administrator, and run the SetupPunchh.msi installer:


  2. After installation, you can see that the Punchh service is now running:

Configuration

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

  2. Enter the location key (API_Key) and Business Key:

  3. Set the POS_Type to POSitouch:

  4. Click on the POSitouch.cfg tab.

    1. PathToChecks, PathToIn, PathToInOrder, and PathToSC: If the default paths for these don’t look correct, then edit these values. Refer to the this section for more details on these paths.

      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 this section for more details.

    3. PunchhDiscountItemNum: Set this value to the Item ID of the cell type 12 discount item that was created in this section.

    4. MemoItemNum:

      1. Leave as default value.

    5. QRCodeItemNum:

      1. Leave as default value.

    6. UsePunchhSecurePOSType:

      1. Important: Set this value to False.

    7. UseV1PosiIntegration: Leave this as False.

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

Create the user program button

For each POSitouch terminal: Copy the Punchh GUI + edit the WINTERM.INI

  1. Copy the Punchh GUI to each POSitouch terminal:

    1. Create a new folder named “Punchh” somewhere on the terminal.

    2. From the back office, copy the C:\Program Files (x86)\Punchh\PunchhUI_Win32.zip file to the terminal, then extract the zip file to the recently created “Punchh” folder on the terminal.

  2. In the Punchh folder on the terminal, open the file PunchhUI.cfg in Notepad. On the third line, enter the terminal ID as defined in the back office (Back Office Setup > Hardware > Terminal Stations).

  3. Save the file and close Notepad.

  4. Open the WINTERM.INI file on the POSitouch terminal (i.e. C:\SC\WINTERM.INI) in Notepad, and edit the file as follows:

    1. In the [WINTERM] section, add:

      1. UserProg_1="","USER PROG"

      2. UserProg_2="PATH_TO_PUNCHHUIEXE",Punchh

        1. Replace PATH_TO_PUNCHHUIEXE with the local path to the PunchhUI.exe on the terminal PC. Ex: If you extracted the zip file to the folder C:\Punchh, then the path would be C:\Punchh\PunchhUI.exe.

        2. The text after the comma (i.e. “Punchh“) is the label of the user program button. Edit this if you don’t want the button to be named “Punchh”.

      3. UserProgMinimize=NO

      4. UserProgPositermMaximize=NO

      5. UserProgOnTop=YES

  5. Back Office Setup > Immediate System Change

For each POSitouch terminal: Create the Macro for the user program button

  1. On the POSitouch terminal, go to SpcWin, and press CTRL+Q.

  2. Follow the prompts:

    1. Enter Macro number: Type “1”, then hit Enter.

    2. Enter Macro button label: Type the label of the button, followed by “^2“ (i.e. "Punchh^2"), then hit Enter.

      1. Note: The button label entered here (i.e. “Punchh”) needs to match the button label entered in the WINTERM.INI (UserProg_2).

    3. Enter terminal number: Type the terminal number, then hit Enter.

  3. Go to POSiTerm, and click the "USER PROG" button twice (once to add the name to the button, and once to signal a touch of the button).

  4. Go back to SpcWin, and press CTRL+Q again to finish the macro.

  5. The button should now have the label that you entered:

  6. Restart SpcWin and POSiTerm, then ring in an order and try clicking the user program button. It should display the PunchhUI:

  7. If the PunchhUI is not displaying, then try creating the macro again. If still having trouble:

    1. Download this MACROS.XML file into the C:\SC folder

    2. Open the MACROS.XML file in Notepad, and replace the string “Punchh” with the button label that you’d like.

    3. Restart SpcWin and POSiTerm.

    4. Try clicking the button again.

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.

  2. When an internal discount is applied after a Punchh discount, the tax is calculated incorrectly. This issue does not occur if the internal discount is applied before the Punchh discount.

  3. Performing an "Overring Transaction" or "Refund, Items Prepared" on a transaction with Punchh discounts will not immediately update the subtotal to reflect the voided discounts ("Exit" button needs to be clicked, then the subtotal will update correctly).