# PERS Terminology Dictionary

This dictionary explains key concepts, entities, and processes within the PERS platform.

## 1. Connect - System Setup & Architecture

First, we set up all of the key components you need for your system to operate.

**Tenant:** You and your organization's program instance. Each tenant operates independently with complete data isolation and custom configuration within the PERS multi-tenant architecture.

**User:** Your customers who engage with the tokenization system through your front-end applications, mobile apps, or partner interfaces.

**Admin:** Administrative users with elevated permissions to manage tenant-level operations, configurations, and system oversight.

**Platform:** A third-party platform, software, or system that integrates with your PERS operations. Examples include CRM systems, booking platforms, EPOS systems, or e-commerce platforms.

**Integration:** The seamless communication layer between your existing platforms and PERS. Compatible with any system that supports REST APIs, webhooks, or standard authentication protocols.

**API:** RESTful application programming interfaces that enable secure communication and data exchange between PERS and external systems.

**Project Key (Context ID):** A Public unique identifier for your Tenant/Project context. It ensures that your requests are routed to the correct isolated environment. Required for all API calls but does not provide authentication.

**Trigger Source:** A specific activation point that can initiate campaign flows. Trigger sources are reusable, agnostic entities that represent how campaigns can be triggered:

- **QR Code:** Physical or digital QR codes at specific locations (e.g., store entrance, product display)
- **NFC Tag:** Near-field communication tags embedded in physical touchpoints
- **API Webhook:** Integration endpoints for external system events (e.g., purchase completion, booking confirmation)
- **GPS Geofence:** Pure location-based triggers activated when users enter defined geographic areas
- **Transaction:** Blockchain transaction events that trigger campaign flows


Each trigger source can be assigned to multiple campaigns and supports type-specific configuration through metadata. **All trigger source types support optional geographic coordinates** (`coordsLatitude`, `coordsLongitude`) to enable location-based proximity validation - for example, a QR code that only works when scanned within 50 meters of its physical location, or an API webhook that validates the event occurred at a specific business location. Location coordinates can be set directly on the trigger source or inherited from an associated business location.

**Campaign Trigger:** The business rules and conditions that determine when and how a trigger source activates a campaign. Campaign triggers define:

- Activation frequency limits (max per day, max per user, cooldown periods)
- Geographic proximity requirements (`maxGeoDistanceInMeters` for location-based validation)
- Required user information and custom conditions
- Completion thresholds and multipliers
- How multiple trigger sources combine (`sourceLogic`: ANY or ALL)


The separation between trigger sources (physical/technical activation points) and campaign triggers (business rules) allows flexible reuse of trigger sources across different campaigns with varying constraints.

**Business:** A real-world touchpoint or partner location within your PERS ecosystem. Examples include retail stores, restaurants, service providers, or any physical/digital location where users interact with your loyalty program. Business entities include geographic coordinates (`coordsLatitude`, `coordsLongitude`) that serve as fallback locations for geofence trigger sources when trigger-specific coordinates are not provided.

## 2. Create - Loyalty Program Design & Configuration

Define the actions you want to encourage and the rewards you'll offer by creating the strategic frameworks for user engagement.

**Token:** PERS operates with flexible token types designed to optimize your loyalty strategy. The platform supports various token categories:

- **Credits/Points:** Basic digital currency tokens for standard transactions and accumulation
- **Rewards:** Tokens representing real-world experiences, products, or services (e.g., free beverages, exclusive experiences, merchandise)
- **Status Tokens:** Digital representations of achievements, memberships, or special recognition levels. Increasingly also used as **personalised vouchers** — because these tokens are unique, each one can carry individual metadata (recipient name, seat number, custom artwork, expiry) making them ideal for single-use reward redemptions, event tickets, and exclusive offers.


**Campaign:** Strategic marketing initiatives that define available tokens, participation requirements, and reward distribution. Each campaign is composed of:

- One or more **Trigger Sources** (the activation touchpoints — QR codes, NFC tags, webhooks, geofences, or transaction events)
- A single **Campaign Trigger** (the rule set that governs who can claim, how often, and under what conditions)
- One or more **Campaign Tokens** (what gets rewarded when a claim succeeds)


Campaigns can be structured as:

- **Public Campaigns:** Discoverable by all users without authentication
- **Targeted Campaigns:** Specific to user segments, controlled via trigger conditions on metadata
- **Time-Limited Campaigns:** Active for defined periods with `startDate`/`endDate`
- **Event-Based Campaigns:** Activated by external events delivered via API webhook or transaction trigger sources


**Campaign Tags:** Organizational labels that categorize campaigns for easier discovery and management across your loyalty program catalog.

**Campaign Tokens:** Specific reward configurations linking token types and amounts to campaign participation outcomes.

**Campaign Trigger (Trigger Rules):** The rule set attached to a campaign that governs *who* can claim and *how often*. A campaign has exactly one trigger configuration, which defines:

- **Conditions:** Custom validation rules evaluated against user metadata (e.g. `role EQUALS premium`). Conditions are stored inline on the trigger and can be toggled per key.
- **Frequency Limits:** `maxPerUser`, `maxPerDayPerUser`, `maxPerDayTotal`, `maxTotal`, `minCooldownSeconds`, `maxPerSource`
- **Geographic Constraints:** `maxGeoDistanceInMeters` — maximum distance between the user's location and the trigger source (or business) coordinates at claim time
- **Completion Threshold:** Number of engagements required before a reward is issued (`completionThreshold`)
- **Source Logic:** How multiple trigger sources on the campaign combine — currently `ANY` (any single source can activate the campaign)
- **Claim Type:** `CLAIM_BY_USER`, `CLAIM_BY_BUSINESS`, or `CLAIM_BY_SYSTEM`


See the **Campaign Trigger** entry in the *Connect* section for the infrastructure-level definition.

**Campaign Engagements:** *(Deprecated)* Previously used for B2B multi-business collaboration. Business participation is now managed by assigning a `businessId` directly to a **Trigger Source**, then associating that trigger source with the campaign.

**Redemption:** Exchange mechanisms that define how users can convert accumulated tokens into rewards, products, or services. Redemptions support complex rules including exchange rates, eligibility requirements, and partner network availability.

## 3. Reward - Active Program Operations & User Engagement

With your loyalty system live and campaigns active, all user engagement is automatically tracked and rewarded within PERS.

**Balance:** Real-time tracking of token holdings across all user accounts, supporting multiple token types simultaneously with instant updates from all transaction sources.

**Wallet:** Digital token storage where earned rewards are held. Each entity (users, businesses, tenants) maintains an isolated wallet with security controls.

**Transaction:** Comprehensive record-keeping system capturing all token movements and operations. Transaction types include:

- **Mint:** Creation of new tokens and addition to user accounts (reward distribution)
- **Transfer:** Secure movement of tokens between wallets (peer-to-peer, business-to-user, or user-to-business at point of sale)
- **Burn:** Permanent removal of tokens from circulation (e.g. a redeemed NFT ticket/stamp consumed at point of sale, or token expiration)


Every reward transaction also records an **Issuance Mode** describing *how* it was economically issued (delegated tenant mint, business-owned mint, or business balance transfer). At point of sale, spending an **ERC20** balance is a *transfer* to the business. Spending an **NFT** (ERC721/ERC1155) depends on the use case: a consumed ticket or stamp is *burned* (destroyed), while a personalised voucher transferred into business custody is a *transfer* (the NFT moves to the business wallet, preserving its metadata and provenance). See the dedicated [Tokenomics guide](/4.tokenomics) for the full model.

**Claim:** User participation in reward programs. Claim processing supports multiple access levels:

- **USER Claims:** Direct customer reward claims through authenticated user interfaces
- **BUSINESS Claims:** B2B reward processing with business context attribution
- **SYSTEM Claims:** Automated claims triggered by integrated platforms and APIs
- **ADMIN Claims:** Administrative oversight and manual claim processing for special circumstances


**Purchase:** Secure payment processing system enabling users to top-up account balances through various payment methods, supporting premium features and additional token acquisition.

**File Management:** Secure asset storage and delivery system for campaign images, user avatars, and program-related media with role-based access controls.

**Authentication & Authorization:** Multi-level security supporting USER, BUSINESS, ADMIN, and SYSTEM access levels with JWT-based authentication.

## Technical Infrastructure Terms

**Blockchain Integration:** Multi-chain support for token operations including network configuration, smart contract deployment, and cross-chain compatibility.

**Web3 Chains:** Blockchain network management supporting multiple networks simultaneously with real-time status monitoring and gas optimization.

**Smart Contracts:** Automated blockchain-based contracts managing token operations with upgrade capabilities and event monitoring.

**Webhooks:** Real-time event notification system enabling integration with external platforms through secure callback mechanisms.

**JWKS (JSON Web Key Set):** Security infrastructure providing public keys for JWT token verification across the platform ecosystem.

**All of this can be created and managed within your PERS dashboard and through RESTful APIs.**