Next Topic
Online Ordering Module 1a: Create User

Overview of Online Ordering API Certification Tutorials

The online ordering API certification tutorials are a set of conceptual modules that help you learn how to integrate your online ordering system with the Punchh server using the Punchh online ordering APIs. The online ordering integration with Punchh allows you to offer the Punchh loyalty program to your guests from your online ordering system.

Information Architecture

The online ordering tutorials have a consistent look and feel to help you quickly navigate and find the information in the modules. Each module contains the following main sections:

  • Goal
  • Prerequisites
  • Use Cases and Context
  • Workflow
  • Best Practices
  • Related Topics

Many modules also include example code (e.g., cURL and Python) that shows how to construct the related API calls.

Tutorial Modules - Sequence and Goals

The tutorial modules are based on the general flow of online ordering integration. In general, the sequence of the online ordering modules depicts the order in which you need to call the online ordering API endpoints to implement the Punchh loyalty program, as shown in the following table.

Tutorial Module Goal
Module 1a: Create User Create a new loyalty guest user in the online ordering system of a business via the website or mobile app.
Module 1b: Complete Sign-up for a POS "Dummy" Account Create and sign in a user via the online ordering system whose account was initially created at the POS.
Module 2: Sign-in Sign in a user via the online ordering system of a business via the website or mobile app.
Module 3a: Show Offers in Guest Account Look up information about offers available to a user so that the offers can be displayed in the online ordering system of a business via the website or mobile app.
Module 3b: Show Account Balance Look up the account balance information of a user so that it can be displayed in the online ordering system of a business via the website or mobile app.
Module 4: Update User Profile Update the values of fields in the profile of a loyalty guest user in the online ordering system of a business via the website or mobile app.
Module 5: Redemptions Implement Redemptions 2.0 (new redemptions framework) or Redemptions 1.0 (legacy redemptions framework) based on the requirements of the business.
Module 6: Check-in Create a check-in for a loyalty guest and send check-in details to Punchh to grant the customer a visit or loyalty points.
Module 7: Updating/Voiding Transactions Update the details of a transaction or cancel the transaction if “Pending Check-ins” is enabled.

Example Code - Prerequisites and Setup

Many tutorial modules also include example code (e.g., cURL, Python, and Ruby) that shows how to construct the related API calls. Before you can run the Python and Ruby example code in each tutorial module, you need to create the generate_signature file (.py or .rb) and the http_client file (.py or .rb) as described in the following sections. Before running the Python and Ruby example code in a tutorial module, save each code sample to a file (.py or .rb) in the same directory where the generate_signature file (.py or .rb) and the http_client file (.py or .rb) are located.

Generating x-pch-digest Header

An x-pch-digest header is required for all Punchh online ordering API calls. You can use the following example code to create the generate_signature file (.py or .rb), which is required in order to run the Python and Ruby example code in each tutorial module.

import hmac
import hashlib
import json

def generate_signature(body, path):
  # Secret for the environment that you are pointing the request to
  secret = 'SECRET_GOES_HERE'
  payload = ''.join((path,(body)))
  signature = hmac.new(bytes(secret, 'UTF-8'), bytes(payload, 'UTF-8'), hashlib.sha1).hexdigest()

  return signature
class GenerateSignature
    # Secret for the environment that you are pointing the request to
    SECRET = "SECRET_GOES_HERE"

    def self.generate_signature(body, path)
        payload = path + body
        signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), SECRET, payload)
        return signature
    end
end

Creating http_client Used To Make HTTP Requests

You can use the following example code to create the http_client file (.py or .rb) file, which is required in order to run the Python and Ruby example code in each tutorial module.

# You will need to install the Requests package before this code will work.
# To do so, see the installation instructions here: https://requests.readthedocs.io/en/latest/user/install/#install
import requests
from generate_signature import generate_signature

def send_request(path, http_verb, body):
  base_uri = "https://server-name-goes-here.punchh.com"

  url = base_uri + path

  signature = generate_signature(body, path)

  headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'x-pch-digest': signature,

    # A guest's access_token can be retrieved from the API response to a Sign Up or Sign In API call.
    # To get an access_token for use with our Online Ordering APIs, this will need to be configured on the Punchh Platform.
    # Please reach out to your Punchh representative in order to get that set up.
    # NOTE: Remove this Authorization header for requests where it is not listed as a required header (e.g., sign-up, login, etc.).
    'Authorization': 'Bearer ACCESS_TOKEN_GOES_HERE'
    
    # Example only - change the User-Agent header as outlined here in the documentation:
    # https://developers.punchh.com/docs/dev-portal-online-ordering/5a9dba2cf6dc0-user-agent
    'User-Agent': 'Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type'
  }

  response = requests.request(method=http_verb, url=url, headers=headers, data=body)

  if response.content:
    return response.text
  else:
    return response.status_code
class HttpClient
  require "json"
  require "net/http"
  require "openssl"
  require "uri"

  # Sandbox base URI:
  BASE_URI = "https://server-name-goes-here.punchh.com"

  def self.send_request(path, http_verb, body)
    begin
      concatenated_url = BASE_URI + path
      url = URI("#{concatenated_url}")

      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true

      request = ""
      case http_verb
      when "GET"
        request = Net::HTTP::Get.new(url)
      when "POST"
        request = Net::HTTP::Post.new(url)
      when "PATCH"
        request = Net::HTTP::Patch.new(url)
      when "PUT"
        request = Net::HTTP::Put.new(url)
      when "DELETE"
        request = Net::HTTP::Delete.new(url)
      else
        return
      end

      request["Accept"] = "application/json"
      request["Content-Type"] = "application/json"
      
      # A guest's access_token can be retrieved from the API response to a Sign Up or Sign In API call.
      # To get an access_token for use with our Online Ordering APIs, this will need to be configured on the Punchh Platform.
      # Please reach out to your Punchh representative in order to get that set up.
      # NOTE: Remove this Authorization header for requests where it is not listed as a required header (e.g., sign-up, login, etc.).
      request["Authorization"] = "Bearer ACCESS_TOKEN_GOES_HERE"

      # Example only - change the User-Agent header as outlined here in the documentation:
      # https://developers.punchh.com/docs/dev-portal-online-ordering/5a9dba2cf6dc0-user-agent
      request["User-Agent"] = "Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type"

      unless body.nil?
        request.body = body
      end
      puts "Request Body: #{request.body}"
      signature = GenerateSignature::generate_signature(request.body, url.path)
      request['x-pch-digest'] = signature

      response = http.request(request)
    end
    if valid_json?(response.body)
      puts "HTTP Status Code: #{response.code.to_i}|Response: #{JSON.parse(response.body)}"
    else
      puts "HTTP Status Code: #{response.code.to_i}"
    end
  end

  def self.valid_json?(json)
    JSON.parse(json)
    return true
  rescue JSON::ParserError => e
    return false
  end
end

Certification Process

Punchh provides APIs that third-party developers can consume to integrate their online ordering systems with the Punchh server to offer Punchh loyalty services to their customers. Punchh also supports certification of third-party developed integrations for online ordering systems. For more information, see Certification - Online Ordering.

Copyright © 2025 PAR Technology Corporation. All rights reserved.
PAR Technology Corporation 8383 Seneca Turnpike, Suite 3 New Hartford, New York 13413 (315) 738-0600 legal@partech.com. PAR Tech is a leading global provider of software, systems, and service solutions to the restaurant and retail industries.
You may learn about its product offerings here.
Before using this application, please read the Limited License Agreement and the PAR Tech Terms of Use.