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)

Follow the guide here

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.