​
Overview

This document will align how to create a minimum viable integration with Thanx API services towards your POS or Kiosk device.

​
Credentials You Will Need

For this kind of integration, you will be provided the following credentials:
  • Client ID
  • Client Secret
  • Merchant ID
  • Merchant Key
  • Partner Token (only to be used against Create Access Token)

​
Endpoints We Will Be Using

In order to achieve the full POS integration, these are the endpoints your integration should interact with: Note that these are the minimum required endpoint interactions in order to build a successful and reliable Thanx integration. If more user data is needed, you can always ask which endpoints to consume to get the desired user data.

​
Postman API Collection

Here you will find the POS - Kiosk Integration API Postman Collection to import directly within your API testing tool. This collection is already completed and includes sample values for the credentials. Please replace them with the ones provided by your Thanx representative in order to achieve successful API calls.

​
API Interaction Workflow

​
POS Integration Flow

​
Interactions

  1. User Authentication at POS
    The user arrives at the POS and either:
    • Scans their QR code (if QR check-in is enabled), or
    • Provides their phone number or email to log in.
    • Reward QR Code case:
      Once scanned, the QR code will return a value in the format {user_id}|{reward_id}.
      • Use the user_id with the Create Access Token endpoint to generate an access token and make API calls on behalf of the user.
      • Use the reward_id to directly apply the discount to the order via the Create or Update Basket endpoint.
    The POS uses this information to request an access token via the Create Access Token endpoint using the user ID, email, or phone. With the acquired token, the POS calls the Get Account endpoint to retrieve user details and available rewards.
  2. Reward Selection
    • If it’s a cashier-assisted experience, the user is asked which reward they wish to redeem.
    • If it’s a kiosk, the user selects the reward directly from the list displayed.
  3. Basket Management
    During the purchase decision phase, the POS sends the current basket with "checkout" state to the Create or Update Basket endpoint. This call should be made any time the user updates their basket or reward selection, to ensure discounts are recalculated if necessary.
  4. Order Placement & Locking
    When the order is submitted, the POS updates the basket with the "placed" state to lock the reward.
    • Once a reward is specified at this stage, it becomes locked to the order.
    • If a points product is used, the corresponding points are deducted from the user’s balance.
  5. Billing & Completion
    When the user decides to pay, the POS calls the same endpoint with the "billed" state.
    • This indicates that the order has been transmitted to the POS and the user’s credit card has been charged.
    • Rewards are marked as used, and points or loyalty progress are accrued.
    (Recommended) After billing, the POS calls the endpoint with the "completed" state to indicate that the order has been handed to the customer.
  6. Order Cancelation or Refunds
    • (Recommended) If an order is canceled after being placed but before being billed, the POS should call the endpoint with the "voided" state.
      • Locked rewards are returned to the user.
      • Points spent on points products are not refunded, but the product reward remains available for future use.
    • If an order is refunded or canceled after billing, the POS should use the "refunded" state.
      • As with voided orders, locked rewards are returned, but spent points are not refunded.
      • The points product remains redeemable in future purchases.
  7. Lifecycle Tracking
    (Optional but Recommended) For full lifecycle tracking, the POS should consistently report state transitions for every order using the Create or Update Basket endpoint. This ensures loyalty data remains accurate and recoverable in case of disputes or technical issues.

​
Certification

Once your integration has been built and developed against the sandbox environment, please reach out to developer.support@thanx.com go through a lightweight but mandatory certification process. For basic integration use-cases, certification is quick and normally takes no more than a few days depending on the scope of integration. This process is mainly designed to ensure the integration is working as intended without risking any negative impact on live customers (merchant or consumer). Each net new integration use-case should be re-certified as new use-cases will very likely require different scoping. Launching new merchants on certified integration use-cases does not require re-certification. The certification process will start with a video call with members of our developer support team. On the call, your team will demo the integration and all the supported use-cases. After the demo of all support use-cases, our team will validate the following:

​
1 - Interactions

  1. authentication
  2. loyalty lookup, such as reward and points product
  3. order submission with or without loyalty redemption
  4. walk through examples of all supported loyalty types:
    • reward redemption workflow:
      • amount off rewards
      • item-based rewards
    • points redemption workflow:
      • amount off points products
      • item-based points products
  5. error message handling

​
2 - API

  1. requests must include all required headers
  2. requests must not be unnecessarily duplicated
  3. error messages should be handled gracefully for users
  4. requests should only be issued on a reasonable frequency and in response to end-user interactions (e.g. Don’t rapidly poll the API for changes)

​
3 - Product Capabilities

The following product capabilities are non-negotiable within our platform and must be supported in your POS–Kiosk integration. These features are crucial to the Thanx user experience.
  1. Reward Redemption
Users must be able to look up their available rewards (via the Get Account endpoint). They must also be able to redeem these rewards (via the Create or Update Basket endpoint).
  1. Points Product Exchange
Users must be able to view the products they are eligible to exchange based on their points balance (via the Get Account endpoint). They must also be able to submit those products as part of their basket to complete the exchange (via the Create or Update Basket endpoint).
  1. Refunds
Users must be able to request refunds for their transactions if needed. (via the Create or Update Basket endpoint). Refunds should be handled at the POS, ensuring that:
  • Any redeemed rewards are restored.
  • Any exchanged point products are reverted, and the corresponding points are credited back to the user.
  1. Automated Location Mapping
To ensure accurate tracking of purchases per location and proper filtering of location-specific rewards, baskets must be submitted with the correct Thanx Location ID in the location_uid attribute as specified here. To simplify this process, you can automate the mapping of your own location IDs to Thanx Location IDs by using the Get Locations endpoint from the Partner API. This allows your system to asynchronously communicate with the Thanx API, keeping location data up to date and ensuring seamless internal mapping between your locations and Thanx locations.