​
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.

​
API Interaction Workflow

​
Interactions

  1. 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.
    The POS uses this information to request an access token via the Create Access Token API using the user ID, email, or phone.

  2. With the acquired token, the POS calls the Get Account endpoint to retrieve user details and available rewards.

    • 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. 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. 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. 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.

  6. (Recommended) After billing, the POS calls the endpoint with the "completed" state to indicate that the order has been handed to the customer.

  7. (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.

  8. (Recommended) 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.

  9. (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.