POS Integration

This section of the PepperHQ Developer Documentation provides both an overview and a detailed guide for developers who are planning to implement an integration between the PepperHQ technology and a 3rd Party Point-of-Sale (PoS) system.

This document assumes the reader has an understanding of the Pepper offering. For a demo of the Pepper product, please contact your Pepper representative. If you don't know who your Pepper representative is, please get in touch via info@pepperhq.com.

For detailed descriptions of how to integrate in the supported scenarios, please see:

• Loyalty-at-POS Guide
• Pay-at-POS Guide
• Pre-Order Guide

Integration Nodes

In order to implement the end-user scenarios described in the guides, there are several possible points of integration between PepperHQ and the 3rd Party PoS.

The points of integration that are relevant for a specific integration are determined by the needs of the Merchant as well as the constraints of the 3rd Party PoS.

The possible points of integration are:

• Pepper Application - running on the end-user's smartphone.
• Pepper Platform - exposed as a REST API (at https://api.pepperhq.com/).
• Pepper POS API - Part of the Pepper REST API's exposed over the Internet as an API for consumption by the Pepper Platform on a POS specific subdomain (https://{POSName}.pepperhq.com/order).
• PoS provider API - An API run by the POS provider for Pepper to connect to, for fetching menus, creating and managing orders.
• PoS Application - running locally in the Merchant's venues.

Scenarios

Different journeys and use cases in the Pepper Product use distinct Scenarios. These are used in a number of places, including:

• When retrieving a menu, Scenario is used to identify the correct menu to display.
• When creating or updating an order, the scenario is used to control expected behaviour of the order.
• When viewing Action Data, the scenario is used to distinguish order types and allow filtering of reports.

Pepper API structure

The features of the PepperHQ Platform are made available to developers via a number of different RESTful API's:

Host	Description	Documentation
https://api.pepperhq.com	Customer, Awards and Location resources	Platform API
https://order.pepperhq.com	Order resources	Order API V2
https://content.pepperhq.com	App CMS resources	Content API
https://menu.pepperhq.com	Menu resources	Menu & Settings API
https://{POSName}.pepperhq.com/order	Pepper POS API	Pepper POS API

UAT endpoints are also available with the prefix beta- in front of each host. For example: https://beta-api.pepperhq.com

Authentication & header values

POS Integrators should use the auth-token authentication scheme. Please contact support@pepperhq.com to request a token for a merchant. You will need to use a separate token for each merchant.

In addition, calls should include the following header values:

• An x-application-id code for that merchant. This will also be provided to you by Pepper.
• A user-agent value, set to the integrators service name eg AbleCRM so that Pepper can easily identify callers.

Example:

GET https://api.pepperhq.com/users
Authorization: Token <token-provided-by-pepper>
x-application-id: <merchant-code>
Accept: application/json
Accept-Encoding: gzip, deflate

200 OK
{ ... }

Versioning

The Pepper API endpoints are continuously evolving, so we support endpoint api versions in a custom header x-api-version. The api version required for each endpoint will be detailed in the API reference.

Endpoints are forward compatible with new versions, so it is safe to use the highest api version you support across all endpoints within 1 host. So if one endpoint has version 8 as the highest version, and another has version 4, you call both with version 8. You do not need to call each endpoint with a different api version unless you specifically wish to downgrade the call.

Example:

GET https://api.pepperhq.com/users
Authorization: Token <token-provided-by-pepper>
x-application-id: <merchant-code>
Accept: application/json
Accept-Encoding: gzip, deflate
x-api-version: 8

200 OK
{ ... }

Version Deprecation

In order to provide ongoing improvements, Pepper has a policy of deprecating old endpoint versions and then removing them.

You will receive a deprecation notice of an endpoint version at least 3 months in advance of its scheduled removal.

Paging

All calls that return a collection of resources enforce paging to prevent responses that are too large.

A collection response will return a page field. If the nextKey value is populated, then use it as the startKey in the next request for the next page in the response.

For example: 1st call

GET https://api.pepperhq.com/users?limit=100include=credentials
Authorization: Token <token-provided-by-pepper>
x-application-id: <merchant-code>
x-api-version: 8
Accept: application/json
Accept-Encoding: gzip, deflate

200 OK
{
  "items": [
    {
      ...
    }
  ],
  "page": {
    "limit": 100,
    "count": 100,
    "startKey": "xxxxxxxx",
    "nextKey": "yyyyyyy"
  }
}

Next paged call:

GET https://api.pepperhq.com/users?limit=100include=credentials&startKey=yyyyyyy
Authorization: Token <token-provided-by-pepper>
x-application-id: <merchant-code>
x-api-version: 8

200 OK
{
  "items": [
    {
      ...
    }
  ],
  "page": {
    "limit": 100,
    "count": 100,
    "startKey": "yyyyyyy",
    "nextKey": "zzzzzzz"
  }
}