Kiosk Integration
Introduction
This guide covers how to build a loyalty integration for self-ordering kiosk software. Kiosks differ from traditional POS systems in several key ways: customers interact directly with the interface, input methods are limited (no keyboard for email entry), and the flow is typically self-service.
The flows below describe the typical integration patterns, but the exact implementation depends on your hardware and software capabilities.
In this tutorial
- 1. Main Loyalty Flow— Identify customers, view rewards & vouchers, redeem offers
- 2. Scan Voucher Flow— Scan and redeem vouchers directly without identification
- 3. Pay with Giftcard Flow— Accept giftcard payments at checkout
- 4. Pay with Prepaid Credit Flow— Accept prepaid balance payments at checkout
Main Loyalty Flow
This flow covers the core loyalty experience: identifying customers, displaying their rewards, and processing redemptions. Hover over the interactive previews to see which API endpoints are used at each step.
Identifying Customers
Identifying Customers
On a kiosk, customers identify themselves by scanning their loyalty card. Best practice is to prompt customers directly at the start screen of the kiosk.
Try it: Click the Next button on the kiosk screen to simulate a successful card scan.
There should be a button or prompt for a customer to scan their member card, preferably accessible at all times.
Unlike POS systems, entering email addresses is impractical on kiosk hardware, so identification is typically limited to scanning a QR code or entering a loyalty card number.
Customer Overview
Once identified, the customer sees their loyalty information: tier status, point balance, available offers (vouchers and collectable rewards), and redeemable rewards. Hover over each section to see which API endpoints provide this data.
Customer Overview
Once identified, the customer sees their loyalty information: tier status, point balance, available offers (vouchers and collectable rewards), and redeemable rewards. Hover over each section to see which API endpoints provide this data.
Displaying Rewards: Rewards are typically displayed as a list ordered ascending by required_credits, showing the reward title and required points.
- Show a "Redeem" button for each reward
- Disable the button if the customer has insufficient points
- On kiosks, consider larger touch targets for easier interaction
Redeeming Rewards
When a customer selects a reward, they see a confirmation screen. This is important on self-service kiosks to prevent accidental redemptions.
Redeeming Rewards
When a customer selects a reward, they see a confirmation screen. This is important on self-service kiosks to prevent accidental redemptions.
There are two common approaches for handling reward redemption. Neither is inherently better — the right choice depends on your Kiosk system's capabilities.
Option 1: Redeem → Reverse on Failure
- Create Reward Reception — subtracts points immediately
- Process payment
- On success: done!
- On failure: Reverse Reward Reception
Best when your Kiosk can easily handle failed orders but lacks post-success hooks.
Option 2: Pre-Redeem → Collect on Success
- Create Reward Reception with
reward.pre_redeemable: true— creates a Collectable Reward - Process payment
- On success: Collect Reward
- On failure: reward remains collectable for later
Best when your Kiosk can easily trigger an API call after a successful order. Allows customers to save rewards for later visits.
Redeeming Offers
When a customer selects a voucher or collectable reward, they see a confirmation screen. This is important on self-service kiosks to prevent accidental redemptions.
Redeeming Offers
When a customer selects a voucher or collectable reward, they see a confirmation screen. This is important on self-service kiosks to prevent accidental redemptions.
For kiosks, we recommend the Lock → Redeem approach:
- Check Voucher Validity , then Lock Voucher — reserves the voucher when customer confirms
- Customer completes their order and pays
- On success: Redeem Voucher
- On failure/timeout: Release Voucher (or let it expire automatically)
This prevents vouchers from being permanently consumed if the customer abandons their order.
Offers Applied
After payment, show the customer how many points they earned. When the customer was identified via their loyalty card, you can directly award points to their account.
Offers Applied
After payment, show the customer how many points they earned. When the customer was identified via their loyalty card, you can directly award points to their account.
Order Paid
After payment, show the customer how many points they earned. When the customer was identified via their loyalty card, you can directly award points to their account.
Order Paid
After payment, show the customer how many points they earned. When the customer was identified via their loyalty card, you can directly award points to their account.
The response from the Create and Process Order endpoint includes the points earned, which you can display to the customer.
If a voucher was used, make sure to call Redeem Voucher after the order is successfully placed to finalize the redemption.
When creating Orders, the best practice is to create the Order as completely as you can. This includes linking Products and any Leat-actions that may have been undertaken in the Order process (e.g. Reward Redemptions, Voucher Redemptions, Giftcard Transactions etc.). Some best practices to take into account:
external_identifier:This is the main identifier from your system, usually a UUID or GUID or some other. It's imperative this is unique across all Orders.order_amount, total_order_amount, total_discount_amount:These are mainly for visual and reference purposes. When Orders are using in Order Actions (to make Points Transactions, for instance), these values will be largely ignored. To account for product-specific exclusions and rules, the order amounts used in calculations and actions will be calculated using the line items, charges and discounts. Still, please ensure these match the content to prevent any confusion.line_items.external_identifier:This is the unique identifier of this line item. Another line item of the same product should have their own unique identifier.line_items.total_amount:The total amount of a line items ought to be the line items' price times the quantity, minus the discount amount. The total amount does not include the total amounts of any sub line items. They are counted separately.line_items.product:For a host of features in Leat, it's imperative the product is linked (if present). The external identifier counts as the main unique identifier of the product, which is of course static for the same product across multiple line items and orders. If no product yet exists for the external identifier, one will be created. However, to fully enable the Product filtering feature, it's highly recommended to create the entire product library, including categories, upon integration installation.line_items.sub_line_items:Line items may include sub line items, like modifiers. Note: the total amounts of the sub line items count separately from the line item's total amount. Example: a line item for a 'Pizza Margherita' with a total amount of 1200 ($12) may include a sub line item for 'Extra Cheese' with a total amount of 200 ($2), which would bring the total order amount to 1400 ($14). The $2 from the sub line item is not included in the total amount on the parent line item. Sub line items are to be linked to products in the same way as their parent line items.line_items.result:This is the 'Leat result' of this line item, if any exists. Examples of this is when a customer buys a Gift card or a Voucher. This would be reflected as a line item on the Order and the resulting Giftcard Transaction (usually created after payment has succeeded) can be linked as a result. Highly recommended to link if present.applied_discounts:If one or more discounts have been applied to the order, these should be added here. Discounts are either applied on an Order level, or on a (Sub)Line Item level. In the latter, the applied discount should also be reflected in the discount amount on the individual (sub) line item(s) and/or charges. In such a case, the specific items should also be linked to the discount via the line items, sub line items and charges parameters.applied_discounts.offer:If the applied discount was the result of a Leat offer (e.g. Reward Redemption, Voucher Redemption etc.), this offer should be added to the discount. Highly recommended to link if present.charges:Charges are costs that are applied after (sub) line items. Examples include gratuity, service charges, shipping, wrapping or taxes (all of these are default Charge Definitions). In the case of taxes, there are only a few use cases in which taxes are to be included as separate charges. Most often, it's preferable to include them in the line items price instead of as separate charges. Charge Definitions are what Products are to Line Items.payments:Currently, only Leat-specific payments can be added here. Payment methods like credit card or cash are not to be sent in. If (part of) the order was paid using Leat payment methods (Giftcards, Prepaid), these should be linked here.
If you have any questions about Orders, please reach out to your partnership manager or contact us at dev@leat.com.
Applying discounts to the order is often the most complex part of the integration. To enable your kiosk software to handle this correctly, you'll need to create custom attributes that define the discount logic.
Important: Custom attributes must be created on the correct entity:
- For Rewards: Create custom attributes on the Rewards entity
- For Vouchers: Create custom attributes on the Promotions entity (the parent of Vouchers)
Common custom attributes:
discount_type- Dropdown: percentage_discount, absolute_discount, or free_itemdiscount_value- Number field (e.g., 100 for 100% off = free item, or 5 for €5 off)product_code- SKU of the specific productcategory- If the reward applies to any product in a category
When an order is cancelled or returned, you'll need to correct the loyalty data. This involves correcting issued points and reversing any redeemed vouchers.
1. Correcting Issued Points
Use the Create and Process Order Return endpoint to subtract points that were originally awarded.
2. Reversing Redeemed Vouchers
Use Reverse Voucher Redemption to restore the voucher to its original state.
Scan Voucher Directly
Customers can scan a voucher QR code directly at the kiosk without first identifying themselves. This is useful for promotional vouchers received via email, flyers, or printed coupons.
Trigger Voucher Scan
Sometime during the ordering process, allow the customer to add a voucher. This is often done during the check-out step, but could also be at any other point before payment.
Trigger Voucher Scan
Sometime during the ordering process, allow the customer to add a voucher. This is often done during the check-out step, but could also be at any other point before payment.
This flow is typically used when a customer has a voucher code from an external source (email campaign, flyer, receipt) and wants to redeem it using the Voucher's QR-code.
Try it: Click the Add Voucher button underneath the order details to start the voucher scanning flow.
Scan Voucher QR Code
The customer scans the voucher QR code or enters the code manually. The system retrieves the voucher details using the Find Voucher endpoint.
Scan Voucher QR Code
The customer scans the voucher QR code or enters the code manually. The system retrieves the voucher details using the Find Voucher endpoint.
Try it: Hover over the scan area and click to simulate scanning a voucher QR code.
Apply Voucher
The system displays the voucher details and the customer confirms they want to apply it to their order.
Apply Voucher
The system displays the voucher details and the customer confirms they want to apply it to their order.
When the customer clicks "Apply", use Lock Voucher to reserve it. After successful payment, call Redeem Voucher to finalize the redemption.
Note: The Promotion linked to the Voucher should contain custom attributes (like discount_type and discount_value) that enable the kiosk to apply the correct discount.
Some vouchers may not be linked to a customer account (e.g., promotional vouchers from flyers). When redeeming these:
- The voucher can still be redeemed without customer identification
- If you want to track the redemption, prompt the customer to scan their loyalty card and pass the
contact_uuidto the Redeem Voucher API call - Points can still be awarded if the customer identifies themselves during checkout
Consider offering to link the voucher to the customer's account for a better experience on future visits.
Voucher Applied
Add the discount logic to the Order.
Voucher Applied
Add the discount logic to the Order, then finalise the redemption once the order was successfully paid.
Note: If the order wasn't yet linked to a contact at this point, use the contact linked to the Voucher and link it to the order.
Before applying a voucher, validate that:
- The voucher hasn't expired (check
expires_at) - The voucher hasn't already been redeemed (check
state) - The voucher is valid for the current location (if applicable)
- The order meets any minimum requirements (e.g., minimum order value)
Display clear error messages if the voucher cannot be applied.
Paying with Giftcards
Customers can use their giftcard balance to pay for (part of) their order at the kiosk. This is typically offered as a payment option during checkout.
Select Giftcard Payment
At checkout, the customer selects "Giftcard" as their payment method. This triggers the giftcard scanning flow.
Select Giftcard Payment
At checkout, the customer selects "Giftcard" as their payment method. This triggers the giftcard scanning flow.
Try it: Click the Giftcard payment button to start the giftcard payment flow.
Scan Giftcard
The customer scans their giftcard QR code or enters the code manually. The system retrieves the giftcard balance using the Find Giftcard endpoint.
Scan Giftcard
The customer scans their giftcard QR code or enters the code manually. The system retrieves the giftcard balance using the Find Giftcard endpoint.
Try it: Hover over the scan area and click to simulate scanning a giftcard.
Confirm Payment
The system displays the giftcard balance and calculates how much will be deducted. The customer confirms the payment.
Confirm Payment
The system displays the giftcard balance and calculates how much will be deducted. The customer confirms the payment.
Upon confirmation, the system calls Create Giftcard Transaction with a negative amount to deduct from the balance.
Note: If the giftcard balance doesn't cover the full order, the remaining amount can be paid with another payment method (card, cash, etc.).
If the order is cancelled or fails after the giftcard transaction has been created, use the Reverse Giftcard Transaction endpoint to restore the giftcard's balance.
Paying with Prepaid Credit
Customers who have prepaid credit on their account can use it to pay for (part of) their order. Since prepaid is tied to their account, the customer must be identified first (typically through the loyalty flow).
Select Prepaid Payment
At checkout, if the customer has been identified and has prepaid credit, the "Prepaid" payment option becomes available. The customer can see their available balance before selecting this option.
Select Prepaid Payment
At checkout, if the customer has been identified and has prepaid credit, the "Prepaid" payment option becomes available. The customer can see their available balance before selecting this option.
Try it: Click the Prepaid payment button to start the prepaid payment flow.
Note: Unlike giftcards, prepaid credit requires customer identification. On kiosks, this typically happens through the loyalty card scan in the main flow.
Confirm Payment
The system displays the customer's prepaid balance and calculates how much will be deducted. The customer confirms the payment.
Confirm Payment
The system displays the customer's prepaid balance and calculates how much will be deducted. The customer confirms the payment.
Upon confirmation, the system calls Create Prepaid Transaction with a negative amount to deduct from the balance.
Note: If the prepaid balance doesn't cover the full order, the remaining amount can be paid with another payment method (card, cash, etc.).
If the order is cancelled or fails after the prepaid transaction has been created, use the Reverse Prepaid Transaction endpoint to restore the customer's balance.