PERS Terminology Dictionary

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

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.

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.

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

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.