Cheers Loyalty
Cheers Loyalty is a credit-based payment system. Users purchase credits (virtual currency) through the Cheers app and spend them at partner venues. The system automatically calculates and applies discounts configured by the venue.
The POS integration connects your point-of-sale system to the Cheers Loyalty execution engine, enabling credit payments and automatic discount processing.
How It Works
Payment Type Decision
Payment Types
| Type | Description |
|---|---|
CREDIT | The full amount is paid with credits. Use this when the POS does not support split payments. If the user doesn't have enough credits, the API returns INSUFFICIENT_CREDIT -- catch this and retry with EXTERNAL_PAYMENT. |
SPLIT_PAYMENT | Part of the amount is paid with credits, the rest with cash or card. Use this when the POS supports split payments. The outstandingBalance in the response indicates the amount to collect externally. |
EXTERNAL_PAYMENT | The full amount is paid externally (card/cash). Credits are not charged, but discounts still apply. |
Key Concepts
| Concept | Description |
|---|---|
| Credit | Virtual currency purchased by users through the Cheers app. 1 credit = 1 unit of the local currency. |
| Discount | Automatic price reduction configured by the venue. Applied per product during the preview step. |
| Outstanding Balance | The amount remaining after credits and discounts are applied. This must be collected externally (cash/card) in split payment scenarios. |
| Transaction Key | A one-time-use 32-character hex code generated by the user's Cheers app. Identifies the user for the transaction. |
| Idempotency Key | A unique key per device per transaction that prevents duplicate charges if the same request is sent twice. |
API Endpoints
All endpoints are documented in the POS API Reference. Here is a summary:
| Endpoint | Description |
|---|---|
POST /v3/.../preview | Create a transaction preview with discount calculation |
POST /v1/.../update | Add items to an existing preview (no discounts applied to new items) |
POST /v3/.../finalize | Finalize and execute the transaction |
POST /v1/.../cancel | Cancel an unfinalized transaction |
POST /v1/.../refund | Refund a finalized transaction (within 24 hours) |