Skip to main content

Authentication

Every request to the Cheers Loyalty API requires authentication headers. Depending on the endpoint, up to three headers are needed.

Headers​

X-API-Key (required on all endpoints)​

Identifies and authorizes the POS terminal. Each physical terminal has its own API key. This key determines who the device is and what permissions it has.

X-API-Key: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...

X-Transaction-Key (required on preview)​

A one-time-use 32-character hex code generated dynamically by the user's Cheers app (via QR code). It authorizes the POS to act on behalf of the user for this transaction.

X-Transaction-Key: 5ccd7850844b415091071c027930101f

Format: Must match the regex ^[0-9a-fA-F]{32}$

The QR code the cashier scans contains this value. Each Transaction Key can only be used once and has an expiration window.

Reading the key: QR code or NFC card​

The Transaction Key can come from two sources:

  • QR code — the dynamic QR generated in the Cheers app. The QR payload is the key.
  • NFC card — a physical Cheers card. Readers typically return the card value without leading zeros, so it can be shorter than 32 characters.

In both cases, left-pad the scanned value with zeros to 32 characters before sending it:

const transactionKey = scannedValue.padStart(32, "0");

This is plain left zero-padding — no other transformation. QR payloads are already 32 characters, so padding them is a no-op. Apply it unconditionally to both sources and your POS needs only one code path.

X-Idempotency-Key (required on preview)​

Prevents duplicate transactions if the same QR code is accidentally scanned twice. Must be unique per terminal per transaction.

X-Idempotency-Key: a7e454c6-17ab-4fee-b823-c595bf3adb4a

Format: 1--255 characters, unique per device.

Environments​

EnvironmentBase URL
Sandboxhttps://api.dev.votesess.com
Productionhttps://api.uniqpon.com

POS Requirements​

Your POS must expose a product query endpoint so Cheers can synchronize product data for discount validation. Each product must include:

  • Name
  • Product ID
  • Gross price
  • VAT rate