API Reference

🖥️ Build a Kiosk integration

What you will build

This guide describes how to develop an integration for Kiosks (e.g.: Tabesto, Belorder)

This guide shows you:

  • How to build the best experience with our loyalty program
  • How to set up authentication, add customers to loyalty programs, handle orders and more
  • The requirements we look at for our Quality Assurance review

🌟 What a Kiosk Experience looks like with Pongo

The following presents the different capabilities a C&C or Order & Pay integration must do in order to deliver the best loyalty experience.

Images are often better than words, you can check our prototype here

Merchant Experience (Administration and configuration)

1. A merchant can connect with Pongo from your interface

One of the most important aspect of our experience is to enable our respective clients (a.k.a. the merchant) to connect your software with Pongo autonomously.

For that reason, we developed an Oauth2 authentication System that we host on our server and that you can implement to let the merchant configure by themselves the connexion with Pongo.

You only have to implement the authentication system in your backend and provide a button that redirect to our OAuth form from your admin panel.

👍

Giving the merchant autonomy to connect with Pongo is required to ensure the best security and operational efficiency.

2. How to ensure your system locations and Pongo's location are properly synced

The merchant's locations (or stores in Pongo) are used for many features in Pongo. It is mainly used to understand in which location a customer have been and help them to better engage with them.

All orders sent to Pongo requires a loyalty_store_slug. Once the merchant has linked its Pongo account with your system through Oauth, you can retrieve the list of the merchant's location with the GET stores endpoint.

You will need to make sure the right loyalty_store_slug is passed with the POST create order call.

Customer Experience

1. Customers can enlist / identify themselves on your Kiosk

In order to maximize the adoption of our loyalty program by Customers, it is upmost important to give them the possibility to enlist from your app.

You can find all the documentation to retrieve or create a customer here

📘

Authentication options

A customer have two way to authenticate themselves on their loyalty program:

  • With their phone number
  • By scanning their Digital Pass (from their loyalty App or Wallet), the QR code of their pass returns the public_idof the customer

👍

At the beginning of the ordering experience, Customers should have the possibility to authenticate in order to access their loyalty program details and rewards.

Think about the experience to be like the one on a kiosk at MacDonalds for exemple.

2. Customers must provide their opt-in option for email and SMS

📘

When a customer enlist to the loyalty program, it is mandatory to ask the customer for their opt-in for Email and SMS communication.

Merchants use Pongo to send marketing communication with their customers and it is utterly important to collect the customers opt-in consent.

Once you collect the customer opt-in options, you can pass it to the POST create order or the POST/PATCH customer calls in the has_optinattribute.

3. Identified customers can see their loyalty program details

To deliver the best experience with our loyalty program, Customers should be able to see the following details of their loyalty program:

  • Rewards available on the merchant's program. They can be retrieved from the GET rewards endpoint
  • Total of loyalty points the customer possess. Customers loyalty points are accessible from the GET customer endpoint
  • Distinct, the rewards there are already purchased from the others. You can obtain the rewards purchased by a customer with the GET rewards won by a customer endpoint

4. Identified customers can redeem a reward from your Kiosk

Customers must be able to redeem a reward from your app. To do so, you can use the endpoint POST Buy a reward

⚠️

Make sure the user interface is refreshed to display the rewards purchased by a customer properly

5. Identified customers can add their redeemed rewards to the order

Customers should be able to add a redeemed reward to their order from your app.

Depending on the reward type, you will find:

  • An external_id field for the reward type free_product: it must contain the identification for the product that will be added to the order in your system. This ID can be added on the reward by the merchant in our Dashboard.

📘

How to manage external ids / SKUs

  • Each reward has an SKU field where the merchant can add one or multiple external ids.
  • Each SKU/External ID is separated by commas.
  • If the merchant add one SKU, it means it is a single product or menu.
    If the merchant add multiple SKUs, it is a list of product or menu.

🚧

Cautions

  • Ensure the customer choosing a reward corresponding to a product with paid option can choose any options. The options should not be offered to the customer and must be paid.
  • The external_id field can returns multiple SKUs from multiple partner. So you need to filter the SKUs to retains only the one matching in your system.
  • A coupon_code field for the reward type voucher_*: it contains a unique voucher code generated when the customer redeemed the reward. You must create a voucher in your system with the same code and apply it to the order.

📘

The different type of rewards are documented here.

Let us know if your system do not support voucher code or product catalog to deactivate them.

6. Send orders to Pongo

In order for us to attribute the loyalty point to a customer, Pongo must retrieve the order that was closed. To do so, you can use the POST create order endpoint.

👍

Confirm a reward has been used

To confirm a reward has been used by a client, you can pass the Pongo reward_id in the lines object of the Create Ordercall.

Alternatively, if you are not able to indicate if a reward has been used when you send the order to Pongo, you can use the PATCH use a reward enpoint to update the customer's reward status.

🚧

When the order is sent to an external system for payment

If the order is sent to another system for payment and closing (such as a POS), you might have to handle the following scenarios:

  • The system cannot manage the reward (ex: voucher code)
    In that case, customers must be prompt that the rewards will be removed from the order if they don't pay on your system
  • The external system is not able to tell you if the order was successfully closed/paid by the customer
    In that case, do not send the order to our system, the external system will need to be connected with Pongo to ensure the customer can obtain the loyalty points and/or use the rewards.

❗

Ensure the order was successfully closed / paid by the customer before sending it to Pongo. We do not attribute loyalty point to an order that was not successfully paid.

When the order is sent to an external system for payment (like a POS), you can only send the order to Pongo if the system can give you a callback to confirm the order was successfully closed.