PepperHQ Developer

The PepperHQ Developer Hub

Hand crafted, customised and bespoke mobile experiences to suit your brand and needs.

Guides

Pay-at-POS

The Pay-at-PoS (point-of-sale) scenario allows Users to make payments and
earn and redeem rewards in-store at the point-of-sale; using their Pepper Powered App
account.

Introduction

"Checkin"

The Pay-at-PoS scenario revolves around the notion of a Checkin. At its highest level, a Checkin is the means by which a User announces to a Location that they are there. A checked-in user is attached to the basket in POS, allowing the transaction to be attributed to the correct customer, and rewards to be earned and redeemed appropriately.

Getting the user checked-in and attached to a basket can be achieved in a number of ways:

User triggered and automatic checkin

Check-ins can be generated in two ways:

  • Manually - by the User via their Pepper Powered app.
  • Automatically - by simply moving to within range of a Bluetooth iBeacon or within a
    geo-fence.

The PoS can then retrieve a list of Checked-In Users from the PepperHQ APIs and display this list with Profile Pictures to the PoS User. The front-of-house staff can use
the information displayed to enhance the service that they provide - such as welcoming them by
name, taking payment from them or redeeming rewards.

Additional information about the User can be displayed in the PoS to aid service. This
information is flexible and can contain their favourite product, their date of birth or
when they last made a purchase.

Users can opt-in to automated check-ins on a per-store basis and are automatically
checked out again when appropriate criteria have been met (e.g. they leave the
location, a specified time has elapsed or a purchase has been made).

Check-ins can be enabled and disabled on a Location by Location basis.

If the User has enabled auto-check-in at a Location, their in-store experience is
completely frictionless. They simply have to walk into the store, tell the front-of-house
that they are checked in with the app, tell the server what products they want, collect
their products and leave. The payments and the earning and burning of loyalty is
totally invisible and happens automatically.

Offline Checkin through Barcode

For Locations where the User triggered checkin may be impeded by poor network, or where it doesn't suit the operation, the Pepper Client App can present a Bar-Code containing the Pepper Unique ID. This can then be used by the PoS to create the Check-in for the user using the PepperHQ API, then attach the User to the basket.

Offline Checkin through User Search

It's possible that Users of the Pepper Powered App may lose access to the app, whether because their device is out of Battery, or they just don't have it with them. In this case, it's useful for a PoS user to be able to search for an App User from within the PoS.

Walkthrough

As an example, the video below takes you through how the integration between PepperHQ and the Revel Systems POS works.

Rewards

Please see the Rewards documentation for a complete description of how Rewards are handled in the Pay-at-POS scenario.

Integration

This section of the document provides more information about each Integration touchpoint between the PoS and the PepperHQ API.

Retrieving Checkins and Users

Checked-In Users

In order for a Merchant to interact with a User via the PoS in the Pay-at-PoS use scenario, the User must be ‘checked in’ to the Location. Users may check in manually or automatically using a Pepper powered app.

To get a list of the current Checkins at a Location, the PoS should make a request to the Pepper Platform API.

GET /locations/{locationId}/checkins

Please see GET locations/:id/checkins for a detailed description of how to request the currently checked in Users at a Location.

User Information

Additional useful information about a checked in User can be retrieved by the PoS from the Pepper Platform API.

The User object contains useful additional information about the User that is not available via the Checkin object itself; including their balance, loyalty points and favourite product.

GET /users/{userId}

Please see GET users/:id for a detailed description of how to request complete information about a User.

User Profile Photo

As a security measure, Users are only able to checkin to a Location if they have previously uploaded a profile photo to their account.

The User’s profile should be displayed in the PoS so that they can be visually identified by the front of house staff member serving them.

The URL for a profile photo is predictable and can be constructed as follows:

http://media.ssmctech.com/users/avatars/{userId}.jpg

Where userId is the userId property of a Checkin.

User Search

If a User is unable to check in themselves via the Pepper App, the PoS can create a Checkin for them on their behalf as described above. If a barcode scanner is not available, or the User is unable to present a barcode for any reason, the PoS can ‘search’ for the User by including a _name_ parameter to the URL. Once the correct User has been identified, a Checkin can be created for them.

GET /users?name={query}

e.g.

/users?name=Andrew%20Hawkins

Please see GET /users for a detailed description of how to search for Users.

Create User Checkin

If a User is unable to check in themselves via the Pepper App, the PoS may also create a Checkin for them on their behalf via the Pepper Platform API. Once the checkin has been created in this way, all scenarios that require a Checkin become valid.

POST /users/{userId}/checkins

Please see POST /users/{userId}/checkins for a detailed description of how to create a Checkin on behalf of a User.

A Pepper powered app can, optionally, show a barcode that contains the unique ID of the User. This ID can be used to construct the URL to create the Checkin via the Pepper Platform API.

Credit a User

It is possible to credit a User’s monetary or loyalty points balances arbitrarily. This can be used in customer services scenarios where it is desirable to give the User money or loyalty points. For example, when they are converting their physical stamp loyalty cards into digital ones.

POST /users/{userId}/credits

Please see POST /users/{userId}/credits for a detailed description of how to Credit a User with monetary or loyalty points value.

Creating Orders and Transactions

Create Order

Creates an Order for the User.

POST /users/{userId}/orders

Please note that if the PoS is creating an Order, it should include the scenario property with a value of PAYATPOS.

Please see the Create Order for User documentation for a detailed description of how to create an Order for a User.

Create Transaction

In The Pay-at-PoS User Scenario, the User is able to make a payment using their Pepper powered app account.

When a Transaction is created by the PoS via the Pepper Platform API, the User’s monetary and/or loyalty balances are updated accordingly.

Even if the actual payment is made using a non-app means (such as cash), a Transaction should still be created to earn and/or burn loyalty points appropriately.

POST /users/{userId}/transactions

Please note that the Transaction being created should be scoped by an Order (as identified in the orderId property of the Transaction. If a Transaction is created without an orderId property, then an Order will be generated on the caller's behalf and will be 'completed' immediately.

The User's app balance will only be adjusted if the paymentType property has a value of APP.

Please see POST /transactions for a detailed description of how to create a Transaction for a User.

Update Order

Updates an existing Order. This is used primarily when an Order is complete, all Transactions have been created and all relevant properties (e.g. basket and redemptions) are populated. In this case the state property is set to COMPLETE.

PUT /orders/{orderId}

Please note that there may be cases where the total Order value and the sum of the Transaction amounts are not the same. If the totalPrice property of the Order has been set then it will be used instead of the sum of the Transactions values.

Please see PUT /orders/{orderId} for a detailed description of how to update an Order.

Refund Transaction

If a User requires a previously generated Transaction to be refunded at the PoS, the PoS should update the Transaction via the Pepper Platform API

PUT /transactions/{transactionId}?refund=true

If the PoS does not have a record of the transaction id, the shortCode (the PoS’s own internal unique id for the transaction) can be used as a search parameter to find the transaction in the Pepper Platform API.

GET /transactions?shortCode=xxxxxxxx

Please see PUT /transactions/{transactionId}?refund=true for a detailed description of how to refund an existing Transaction.

Refunding a cash transaction, such that a user gets their spent awards back, is not something which is currently supported by the platform.

Example

This example captures the sequence of calls that should be made in a typical Pay-at-POS scenario.

  1. Get Checked in Users for the current Location
  1. Get additional information about a specific User (including an Awards summary)
  1. Create the initial Order on behalf of the User. Note that the basket and redemptions properties can be PUT to the Order at any time before it is 'Completed'.
{
  locationId: '111111111111111111111111',
  scenario: 'PAYATPOS',
  value: 10,
  shortCode: 'ABCDEFG',
  state: 'OPEN',
  basket: [
    {
      id: '1',
      category: '1',
      title: 'Flat White'
    }
  ],
  redemptions:[
    {
    	awardId: '111111111111111111111111',
	    token: '1234567890',
  	  quantity: 1,
      value: 2.50
  	}
  ]
}
  1. Create a Transaction and associate it with the Order.
{
	shortCode: "215418",
  subTotal: 2,
	totalTax: 0.5,
	totalPrice: 2.5,  
  totalTip: 0.5,
	totalPayment: 3,
  locationId: '111111111111111111111111',
	registerId: "222222222222222222222222",  
  orderId: '111111111111111111111111',
  paymentType: 'APP'
}
  1. When all Transactions have been created and all properties of the Order have been added, update the order state to be COMPLETED.
{
  totalPrice: 3.50,
  state: "COMPLETED"
}

Notifications

In addition to the PoS > Pepper integrations already described in this document, the Pepper Platform is able to 'notify' the PoS of certain activities.

For more information about the specifics of the mechanics of the Integration, please see the relevant section in the Introduction.

Checkin Notification

When a User checks in to a Location, the PoS can (optionally) be notified in real-time. This can be used to force a refresh of the in-PoS display of currently checked in Users or to update an in-PoS counter of the currently checked in Users. The means by which the PoS is notified (if at all) will depend on the capabilities and underlying technologies of the PoS.

notifyCheckin(data, options)

Please note that, unlike other requests, it is executed on a fire-and-forget basis and does not require a callback parameter.

See schema.pepperhq.io for the request and response schema:

Checkout Notification

When a User checks out of a Location, the PoS can be notified in real-time. As per the previous checkin notification feature, this can be used by the PoS to update the information that it displays about checked in Users.

notifyCheckout(data, options)

Please note that, unlike other requests, it is executed on a fire-and-forget basis and does not require a callback parameter.

See schema.pepperhq.io for the request and response schema: