New Developer Innovation: POS Punchh Key and Barcode Generator

“The POS Punchh Key and Barcode Generator is yet another high impact innovation by the PAR Punchh Developer Relations team. It is a fully functional standalone application that is easily converted into a code library and imported into 3rd party POS and Kiosk systems integrating with PAR Punchh. This tool has the potential to save weeks of complex software development effort. In fact, our findings suggest a reduction of 25% in overall development effort for POS and Kiosk systems. With reduced development costs, shorter time to market and increasing standardization, we’re enabling PAR customers and partners to accelerate their business outcomes.” Rahul Aurora, Director, Developer Relations @ PAR Punchh

The PAR Punchh loyalty system offers APIs for integration partners to integrate with Punchh. This enables Punchh integration partners to associate purchase transactions to loyalty transactions in Punchh (called check-ins). It works well because the integration partners can concentrate on fulfilling orders while Punchh software can focus on managing loyalty users and loyalty transactions such as points accruals and redemptions.

One key integration touchpoint used by integration partners is the point-of-sale (POS) terminal, which registers purchases and payments. Punchh provides APIs specifically for use in the POS system software to register loyalty transactions with Punchh. Two of the key parameters used by the POS system are the Punchh key and Punchh barcode. The barcode is printed on each order check (or receipt), while the Punchh key is used in Punchh API calls to register checkins related to that receipt. The barcode is simply a Punchh key with a parity digit appended to it as per the EAN-13 format. That barcode on physical receipts can be scanned at a later time into a POS system to enable physical receipts to accrue post-transactional loyalty credits for the loyalty user.

While this is an important feature for customers, it is also important to PAR Punchh to protect brands from fraudulent receipt activity which could expose POS owners to financial liability. Punchh and POS system vendors have jointly agreed to use a method which makes it difficult to generate fraudulent barcodes. We take the transaction number of a check (with numbering controlled by a POS system), a unique POS system identifier, and some random data (a.k.a. a “salt” in data security language), and use an algorithm to combine them into a barcode. There exist ways to validate the location and transaction number from a given barcode, which makes it difficult for criminals to generate useful fraudulent barcodes. So, for example, when a barcode from a physical check is scanned, the check number and POS system identifier can be extracted and validated against existing transaction data in the POS system to authenticate the check. The Punchh platform validates submitted barcodes to avert fraud.

Punchh integration partners must implement the Punchh key and barcode generation software as part of the Punchh integration, but other parts of the integration depend on a correct implementation of that software. For example, the registration of a loyalty transaction (check-in) with Punchh must contain a valid Punchh key and a transaction number. If the barcode generation software is not ready, it delays the integration of Punchh check-ins.

We recognize that our partner developers are stretched thin and the algorithm to build a valid Punchh Key/Barcode can be complex. There is documentation available along with code samples published on the Developer Portal. Furthermore, we want to help ensure development cycle timelines are met and developers have all the tools they need to independently work on their projects. This is why we built the POS Punchh Key and Barcode Generator tool. Software developers integrating Punchh check-ins can use the tool to generate correct Punchh keys when testing the integration of Punchh check-ins. This allows the integration of Punchh check-ins to be developed independently of barcode generation.

Such parallelization of software development allows integrations to be more reliably completed on time by removing internal project dependencies. It also allows integrations to be developed more quickly and efficiently by integration partners.

The POS Punchh Key and Barcode Generator is a command-line tool which allows the user to set the check number, POS system identifier (a.k.a. shortkey), the algorithm (e.g. map3), and optionally the salt. It then generates a Punchh key. The sample operation of the tool generating two Punchh keys for three different transactions (e.g. generate 3) is shown below:

The developer of the Punchh check-in integration can take these quantities and use them in the Punchh check-in API call to generate a proper Punchh check-in which will then correctly accrue and/or redeem Punchh loyalty credits.

This tool is distributed as a Docker program so that it can be used as-is on Windows, MacOS, and Linux. The code is intuitive and well-documented, and is available on the PAR Developer Portal for download. POS integrations can also use the Java class to generate barcodes instead of implementing the algorithm themselves.

This tool has been adopted by a number of POS and Kiosk integration partners already. Our findings suggest a reduction of 25% in overall development effort!

Are you interested in learning more? Please feel free to contact the PAR Punchh team here or via LinkedIn.