Overview

POS Integration / Getting Started

Integrating LevelUp into your Point-of-Sale solution is an easy way to add a powerful mobile loyalty and payment solution to your offering. The key elements to the integration process:

1. Internet Connectivity
2. Authentication
3. Hardware
4. Orders & Rewards
5. Gift Cards
6. Documentation, Error Handling & Support

Internet Connectivity

LevelUp requires an active Internet connection (i.e., there is no “offline mode”). In order for LevelUp mobile loyalty and payment to operate successfully, the POS system must be able to reach the LevelUp platform via the Internet using the following URI: https://api.thelevelup.com.

All API requests must be made over HTTPS and secured via Transport Layer Security protocol (TLS) 1.2 or later.

If a network firewall is in use, it must allow secure HTTP (TCP destination port 443) to the fully qualified domain name (FQDN), api.thelevelup.com. It is not possible to provide a static list of IP addresses that the LevelUp FQDN resolves to. The firewall must be capable of dynamically filtering traffic using the fully qualified domain name (FQDN), api.thelevelup.com. It is recommended to allow TCP traffic to destination port 443 for the wildcard domain, *.thelevelup.com.

Authentication

To authenticate, simply ask the merchant to enter their LevelUp credentials (email and password). Now query LevelUp for an access_token and retrieve a list of locations. The merchant should select the appropriate location. Now, with the location set and the access_token retrieved, you’re ready to start making transactions.

Hardware

In order for customers to be able to scan their phone for loyalty/payment, your POS needs to be ready to read the LevelUp 2D (QR) codes. Any standard 2D barcode reader should do the trick but we also offer custom-built LevelUp scanners that can function over USB (HID or Serial) or Bluetooth (HID). You should also allow cashiers to manually enter a customer’s code in case there is a hardware malfunction or the code is unreadable, for example due to a cracked screen.

Orders & Rewards

Once you’ve got the customer’s payment code, you’re ready to process the loyalty rewards and payment.

  1. Create a proposed order and apply (as a discount) any potential rewards the customer has earned.
  2. Complete the order and apply LevelUp gift cards, tips and tenders.
  3. In response to your order creation request, you’ll receive either an approval or a failure.

A) An approval will come back with an approved amount, gift card amount, gift card tip and a LevelUp tip amount.

B) If the user has a limited balance, you may receive a partial approval. You should apply the applicable payment amount to the check as a tender. If this payment brings the check balance to $0, go ahead and close the check. If not, any remaining balance should be requested from the customer.

C) A failure will come back with a human readable error message which should be displayed to the cashier.

Need to do a refund? You can use our Refund endpoint to entirely refund the payment and reverse the charge to the customer.

Gift Cards

Most LevelUp merchants also choose to offer physical and digital gift cards through LevelUp. Merchants can sell physical gift cards in-store with LevelUp, but often also digital gift cards through the LevelUp app, or even their own app running on the LevelUp platform.

Redeeming gift cards is easy - it’s just like any other LevelUp payment. However you’ll want to add both “sell/activate” and “check balance” functions so that they can sell gift cards at their register. Just make sure you don’t activate the gift card until the check has been tendered.

Documentation, Error Handling & Support

The final step in completing a successful LevelUp integration is to provide us with installation documentation, FAQ’s, support contacts and any other relevant information for us to share with our mutual partners. We’ll also want to run the integration through our QA suite to make sure there aren’t any wacky edge cases that cause unintended behavior. Once this process is complete, we’ll feature your integration on our partners page and publish the setup instructions for merchant self-service.