Display Integration
With Display Integration, customers select tips and confirm the payment on a Tippy device (usually a tablet) provided to businesses by Tippy. We provide the UX and guide the customer through selecting the tips and confirming the payment. Additionally, the Tippy device is used as a customer facing screen whenever the POS system doesn't provide its own customer facing screen. The screen can be used to display a breakdown of all charges (products, services, packages purchased, discounts, taxes, etc.) Tippy will merge the tips data and present the customer with a full image of all charges.
Transactions#
To initiate a transaction, your POS system should call POST /v1/display/transaction/create
and pass it a tip intent. A tip intent is JSON object that represents the current
checkout summary along with a list of staff members who should be considered
for tips.
Once a checkout flow has been initiated, it should follow the diagram below:
Updating a Transaction#
Transactions can be updated in the middle of a checkout flow. For example, the front desk might notice that they forgot to include a service professional in the tip intent and want to update it.
To update a transaction, just call POST /v1/display/transaction/update. The device
will go back to the beginning of tip selection using the new data.
Canceling a Transaction#
If a payment fails for any reason, you should call POST /v1/display/transaction/reject.
The Tippy device will display that the payment has failed and wait for the
POS to be ready so that the payment can be attempted again.
If it turns out that the payment is not going to be possible, it should be
canceled by calling POST /v1/display/transaction/cancel. When this is
called, the device will go back to the home screen and be ready to accept the
next payment.
Retrieving a last incomplete Transaction#
If for any reason a POS needs to get an incomplete transaction for a device
it could be retrieved by calling POST /v1/display/transaction/last.
When this is called, the endpoint will return a transactionId, otherwise response will be empty.
Device Sync#
Some locations may have multiple stations which means multiple POS instances and therefor multiple Tippy devices. For us to know which POS device initiates the checkout flow on which Tippy device, the POS device and the Tippy device must be synced. One Tippy device can be synced to one or more POS devices. If a checkout flow is started while another one is still being completed, the Tippy device will process the next one as soon as it finishes with its current one.
There are two ways to sync POS and Tippy devices. You choose which one works better for you when you sign up.
Tippy Generating a Device Identifier#
The recommended way is to let Tippy generate a device identifier. This will
be an identifier (e.g.: 3XBD59) that you use to refer to our devices when calling api endpoints.
When a business first starts a Tippy device, they'll see that identifier on the screen.
They'll be instructed to input it into your POS system. Once completed, you should store the identifier and call POST /v1/display/devices/activate.
That way, we'll know the device is synced and the business can start using it.
POS Generating a Device Identifier#
You can also choose to generate device identifiers on your own if preferred. If your POS system is a desktop version, and every installation of it has a serial or license number, that can be used as a device identifier. If your POS system is a web app and has no notion of license numbers, we recommend you generate a unique identifier and save it in local storage on that browser. In this syncing flow, you'll display the identifier somewhere in your interface to the business. Once they start the Tippy device, they'll be prompted to enter it. After entering the device identifier, the device is synced and the business can start using it.