API Reference

💳 Build a payment terminal integration

What you will build

This guide describes how to develop an integration for Payment terminal solution like Yavin or Order & Pay solution (e.g.: Sunday, Qodeup) that offers a payment only module.

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 good Payment Terminal Experience looks like

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 a video what we are looking for with payment terminal integration:

Images are often better than words, you can check our prototypes for:

  • Payment Terminal here
  • Pay App (for Order&Pay app with only payment module) here

📘

For Apps that offers Order and Payment system

If your Payment app also offers an ordering module, you can refer to the documentation on how to Build an order system integration

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 within your app

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.

Customers enlist or identify themselves with their phone number only.

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

👍

After the payment, Customers should have the possibility to authenticate in order to attach the order to the customer information.

Once the order / checkin is sent to our system, we will be able to attach the order / checkin the right customer through the phone number and attribute the loyalty point regarding the merchant loyalty program configuration.

2. Customers can see the amount of loyalty points they can earn before the payment

Most of our partners displays the amount of points the customer is about to earn before actually paying their order and sending the information to Pongo.

It creates an incentive that can increase the registration rate of the loyalty program.

In order to do so, you can use the endpoint GET user information.
It returns the loyalty program configuration in the partnerParameters.
With this configuration, you can calculate how many loyalty points the customer is about to earn with the order / payment.

3. 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.

4. Send orders / checkin 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.
⚠️ If you cannot access the order items from your terminal. You can use the POST checkin endpoint.

The response of the checkin or order endpoint gives you the amount of loyalty points earned by the customer that you can display in your interface.

👍

In case of split payments

If your application support a split payment for an order, you can send an order for each payment done by customer.
However if the split method is :

  • per item: join each item paid in the order payload by the customer
  • by amount: Create an order without items only the customers information and the amount is necessary to allow at least givin loyalty points.

👍

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.

❗

Ensure the payment was successfull before sending it to Pongo. We do not attribute loyalty point to an order that was not successfully paid.