Prerequisites
System requirements for the PC running the Punchh service (Punchh.exe)
Minimum OS: Windows 7 (with SP1) and .NET Framework 4.6.1
Gilbarco POS version 20.01.23.01A or higher
Network Firewall & Antivirus Setup
Using the Gilbarco Passport Data Flow and Firewall Setup guide configure the site’s network edge firewall to allow the PC running the Punchh proxy application (punchh.exe) to communicate to the Punchh service endpoints and to configure any software/AV/Application Whitelisting software running on the PC where the Punchh Proxy runs.
Before proceeding with install, verify from the PC running the Punchh Proxy that the firewall is properly configured by running the Check Firewall connection:
A properly configured site should show the following after running Check Firewall Connection
Network Firewall Validation Tests
From the PC running the Punchh service (Punchh.exe), please do the following tests:
Open a web browser and navigate to the following web pages
Each web page should return a plain white page with OK
If any page doesn't return OK, the firewall needs to be reviewed to ensure the correct firewall rules are in place.
Install & Configure the Punchh service
Run the Punchh provided SetupPunchh_version.exe
If prompted, allow elevated privileges:
Click Next
Leave the path as the default path. Click Next.
Click Install.
Click Finish.
In the System Tray, find the Punchh Watchdog Tray App. The icon should be a green checkmark, which indicates that the firewall & antivirus rules are setup correctly.
Note (Recommended): To make this tray icon visible in the system tray without having to click the up arrow, do the following:
Right click the taskbar > Taskbar Settings > Select which icons appear on the taskbar > switch PunchhWatchdogTrayApp to On:
Right click the Punchh Watchdog Tray App, then click Launch Punchh Configurator
Enter the location key (API_Key) and business key:
Set the POS_Type to Gilbarco:
Leave all other settings as their default values. Click on the Gilbarco.cfg tab.
DropChecksumDigitFromUPC:
True: Punchh will use an item’s UPC code (checksum digit not included) as the Punchh Item ID.
False: Punchh will use an item’s UPC code (checksum digit included) as the Punchh Item ID. Default is False.
Punchh recommends setting this to True if the brand is using different POS systems across their locations (ex. Gilbarco Passport at one location, and Verifone Commander at another location). Dropping the checksum digit will ensure that the item ID’s sent to Punchh are consistent across different types of POS systems.
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.
RewardReceiptDescLong: The text to be used on a 40-column Customer receipt to describe a loyalty reward discount. (max length is 24 chars)
RewardReceiptDescShort: The text to be used on a 20-column Customer receipt to describe a loyalty reward discount. (max length is 8 chars)
Click Apply
Click Exit
Configure Gilbarco Passport Back-Office
Loyalty Interface Configuration
On the Gilbarco Passport, login to the Manager Workstation, then click “Set Up” on the right hand pane.
Click Store
Scroll down and click Loyalty Interface
Click Add
Input the following, then click Save:
Loyalty Provider Name: punchh
Loyalty Provider Type: Generic
Go to General > Page 1
Loyalty Provider Name: punchh
Loyalty Provider Type: Generic
Enabled: Yes
Site Identifier: Enter a unique identifier for this store
note: It’s recommended to use the Punchh location Short Key:
Host IP Address: Local IP address of the PC running the Punchh service.
Port Number: The port as defined in the Gilbarco.cfg tab on Punchh Configurator
Allow manual entry outside: Yes
this allows the guest to enter their loyalty ID at the pump
Allow cashier to auth prepay only pump: Brand’s preference
If selected, and if the store is operating in prepay only mode, this will allow a cashier to authorize dispensers if customers enter their loyalty ID at the pump
Allow instant rewards outside: Yes
allows Punchh to apply instant loyalty rewards at the pump based on merchandise and method of payment
Send all transactions to loyalty provider: Yes
this allows both loyalty and non-loyalty transactions to get sent to Punchh. If No, then only loyalty transactions will get sent to Punchh.
Go to General > Page 2
Loyalty Interface Version: Gilbarco v1.1
24hr Loyalty period cut time: Leave as default, 00:00
Allow transponder as loyalty ID: Brand’s preference
allows the guest to use their transponder to identify their loyalty account
Loyalty Vendor: Select Punchh if available, else select Unknown
Go to Receipts
Always print inside loyalty receipt: Yes
Always print outside loyalty receipt: Yes
Inside offline receipt lines 1-3: Brand’s preference
If Gilbarco detects that Punchh is offline, these receipt messages will be used for inside transactions
Outside offline receipt lines 1-3: Brand’s preference
If Gilbarco detects that Punchh is offline, these receipt messages will be used for outside transactions
Go to Prompts
POS prompt at tender: Brand’s preference
whether to prompt for the loyalty ID at tender always, never, or only on fuel transactions. “Always” is recommended
Prompt for Loyalty Offline Inside: No
when Gilbarco detects that Punchh is offline, don’t prompt for loyalty ID inside
Prompt for Loyalty Offline Outside: No
when Gilbarco detects that Punchh is offline, don’t prompt for loyalty ID outside
Prompt customer to Insert Card Outside: No
Punchh does not support mag swipe loyalty cards
Go to Loyalty Card Mask
note: adding loyalty card masks is not required nor recommended by Punchh
Click Save
Other back-office configuration settings
Navigate back to “Set Up”, then click Register
Click “Register Group Maintenance”
For each register group, do the following:
Click Change
Click the Transaction Options tab, and make sure that the checkbox is checked for “A receipt is printed for each transaction“.
note: If this setting is unchecked, then receipts will only print when manually requested by the cashier.
Click Save
Right click the Punchh Watchdog Tray app, and click “Restart Punchh Service”.
Wait for 2 minutes, then open the latest log file in C:\Program Files (x86)\Punchh\Logs. Search for “GetLoyaltyOnlineStatusRequest“ and “GetLoyaltyOnlineStatusResponse“. If the log file contains those strings, then that means Gilbarco is properly communicating with the Punchh service.
example log entries:
9/23/2020 6:35:21 PM [Information]: Received request from client: 2432: <GetLoyaltyOnlineStatusRequest><RequestHeader><POSLoyaltyInterfaceVersion>1.1</POSLoyaltyInterfaceVersion><VendorName>Gilbarco</VendorName><VendorModelVersion>08.23.01.01K</VendorModelVersion><POSSequenceID>00-0^143797^</POSSequenceID><LoyaltySequenceID></LoyaltySequenceID><StoreLocationID>6421</StoreLocationID><LoyaltyOfflineFlag value="no"></LoyaltyOfflineFlag></RequestHeader></GetLoyaltyOnlineStatusRequest>9/23/2020 6:35:21 PM [Information]: Response content (without binary header): 2432: <GetLoyaltyOnlineStatusResponse><ResponseHeader><POSLoyaltyInterfaceVersion>1.1</POSLoyaltyInterfaceVersion><VendorName>punchh</VendorName><VendorModelVersion>6.9.23.0</VendorModelVersion><POSSequenceID>00-0^143797^</POSSequenceID><LoyaltySequenceID></LoyaltySequenceID></ResponseHeader><PromptForLoyaltyFlag value="yes" /></GetLoyaltyOnlineStatusResponse>
Configuring the Data Element Mapping CSV file
Punchh provides a way for the brand to map Product Codes to Punchh fields. To use this functionality, please follow these steps:
Download the data_element_mapping.csv file, located at the bottom of this section.
Open this file in Excel, or import to Google Sheets.
To map Product Codes (column D) to Punchh Item ID’s (column G):
Search column D for the product code that you want to map.
On the row of the product code, define the Punchh Item ID in column G.
Note: Here is the algorithm that determines what gets sent to Punchh as the item ID:
If the POS sends to Punchh the item’s UPC code: The UPC code will be used as the Punchh Item ID.
If the UPC code is not available: Punchh will look at this mapping file and if an Item ID is defined in column G, then that ID will be used as the Punchh Item ID.
If the UPC code is not available AND if no item ID is defined in column G: Punchh will use the Product Code (column D) as the Punchh Item ID.
Note: For Punchh Major Group, the Product Code will be used.
Note: For Punchh Family Group, the MerchandiseCode will be used.
MerchandiseCode: The POS defines this as the department or category to which the item belongs.
To map Product Codes (column D) to Punchh Item Types (column H):
Search column D for the product code that you want to map.
On the row of the product code, define the Punchh Item Type in column H.
Example: mapping Lottery product codes to the Service Charge item type (Type S):
Example: mapping Tax product codes to the Tax item type (Type T):
When done with mapping, save the file as a CSV, and name it “data_element_mapping.csv“.
Copy the file to C:\Program Files (x86)\Punchh on the PC running the Punchh service.
Right click the Punchh Watchdog Tray app, and click “Restart Punchh Service”.
Troubleshooting
Log files
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:
C:\Program Files (x86)\Punchh\Logs
or
C:\Program Files\Punchh\Logs
Log files are named by date, for example:
2017-0223-000050.log
was created on Feb-23, 2017
Port conflict error:
Identification:
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.
Resolution:
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.