POS / Kiosk / Pay-on-the-Go Integrations

Description

Point-of-sale (POS), kiosk, and pay-on-the-go systems are used to take orders in the store, apply redemptions and discounts, and pay for the order. They are on dedicated hardware devices in the store and are usually operated by a store employee, and sometimes operated by an end-user customer. These kinds of integrations use mostly Punchh POS APIs.

The common workflow in each of these kinds of systems looks like this:

1. Build order - In this scenario, the user builds an order of goods and services to buy.

2. Pay - In this scenario, the user pays using a payment card of some kind.

When integrating with Punchh, the workflow needs some extra steps:

1. Sign up / look up user - In this scenario, the user identity is validated with the POS using a loyalty sign up or look-up. This identity is attached to the order and payment to help the loyalty system assign loyalty credits to the user for making a purchase. This workflow must occur before the order is paid.

2. Query redemptions - In this scenario, the POS checks the order against loyalty offers and adjusts the order with discounts from the loyalty orders, thus turning them into redemptions. This workflow occurs after the order is built and the loyalty user is authenticated, and before the order is paid.

3. Commit redemptions - In this scenario, which occurs after the order has been paid, the redemptions are committed and removed from the user’s loyalty account.

4. Check in - After the order is paid, the order is sent to the loyalty system so loyalty credits for the order can be properly credited to the loyalty user.

Information Resources

Study the following to learn about integrations that use Punchh POS APIs.

1. Start with Getting Started With POS API Integrations.

2. Read Make Your First POS API Call. This guide includes a state machine flow of how order creation works on a POS, and how to create payloads for redemptions and check-ins. This is the first of many adjacent documents that you can read on the PAR Developer Portal to understand how Punchh POS APIs work.

3. For detailed use cases and example scenarios for getting started with Punchh POS APIs, see POS API Certification Tutorials.

4. If you are implementing single-scan flows, see Single Scan Flow.

5. The sign-up and user look-up flows authenticate a user and result in the acquisition of an access token that enables other API calls to be made on behalf of the user. These require the following API calls:

• a. Send OTP - Sends a one time password (OTP) to the user via email or SMS message using Advanced Authentication to sign up / sign in.

• b. Verify OTP - This verifies the OTP token and returns an access token for that user.

• c. Create New User - This enables the creation of a new loyalty user. This is a legacy method for user authentication and is not recommended for new applications.

• d. User Look-up and Fetch Balance - For existing loyalty users, this confirms that a user is valid, and checks the credits, rewards, and offers available to the user.

6. There are many APIs related to redemptions, but the success path of query and activate redemptions (Redemptions 2.0) flows requires calls to the following APIs:

• a. Discount Look-up (Redemptions 2.0) - This looks up available discounts (rewards or redemptions) for a user based on the current order.

• b. Add Selection to Discount Basket (Redemptions 2.0) - This adds selected discounts to a basket (i.e., a virtual shopping cart).

• c. Batch Redemption Process (Redemptions 2.0), with the query parameter set to True - This confirms the redemptions for the order. The integration adds these confirmed redemptions as extra line items to the order before it is paid.

• d. Batch Redemption Process (Redemptions 2.0), with the query parameter set to False - This commits the redemptions for the now-paid order. The Punchh side removes these from the user’s credits.

7. The check-in process requires the following API calls:

• a. Create Check-in - This API is called to send the order (which may contain additional line items for redemptions) to Punchh.

• b. Store Receipt Details from POS - This API is called when a customer has a receipt with a proper Punchh EAN-13 barcode (with embedded Punchh key) from the POS, but has no loyalty assignment registered to Punchh. This API is the first step in enabling a loyalty user to accrue credits after the POS interaction is complete.

Sample Applications

• POS Punchh Key and Barcode Generator - This document shows a working example of how to properly generate Punchh keys and barcodes required for POS Punchh check-ins.

• API Payload Generator - This online application shows how to generate and validate payloads for redemptions and check-ins. The POS version is COMING SOON.

Postman Collections

• Various use cases for POS APIs are documented in the Postman collection for POS APIs.

• Advanced Authentication use cases are documented in the Postman collection for Advanced Authentication.

Examples

These are examples of POS, kiosk, and pay-on-the-go Punchh integrations:

• PAR POS
• PixelPoint
• NCR Aloha