Reward process status flow

The Reward Processor manages the complete lifecycle of player rewards — from creation and claiming to activation and expiration. The reward claiming process can be initiated in two ways: either through the user interface (UI) or by an administrator, both with the goal of awarding a reward to the player. Rewards can also be automatically granted through other gamification products such as Missions, Tournaments, Campaigns, or purchased directly by the player through the Reward Shop. When a claim is initiated, the system first checks whether the reward has already been claimed. If it has, the process ends there. If the reward is still available (Unclaimed), the process continues depending on its type and activation configuration.

🎁 Types of Rewards

Each reward type has its own logic during activation and claiming:

Reward Type	Description
Bonus Offer	Sends a promotional bonus to the player through the external Bonus System.
Tokens / XP	Grants virtual tokens or experience points directly to the player's account.
Boosters (Level, Mission, Token)	Temporarily multiply the player's progress or points. They may activate automatically or manually.
MiniGame	Unlocks special interactive mini-game rewards.
External	Rewards from external systems, directly marked as Granted.
Manual	Rewards manually created and assigned by administrators.

🔄 Reward Lifecycle

Rewards move through several stages to ensure full traceability and reliability:

Status	Description
Unclaimed	The reward is available but has not yet been claimed by the player.
Pending	Booster-type/Mini-Games rewards waiting to be activated.
In Progress	Reward activation is ongoing.
Granted / Completed	The reward was successfully delivered or used by the player.
Failed	An error occurred while processing the reward.
Declined / Deleted / Expired / Bounced	The reward was declined, removed, expired, or abandoned (e.g., mini-games).

⚙️ Claiming and Activation Flow

The reward claiming process can be initiated in two ways: either through the user interface (UI) or by an administrator, both with the goal of awarding a reward to the player. Rewards can also be automatically granted through other gamification products such as Missions, Tournaments, Campaigns, or purchased directly by the player through the Reward Shop.

When a claim is initiated, the system first checks whether the reward has already been claimed. If it has, the process ends there. If the reward is still available (Unclaimed), the process continues depending on its type and configuration.

Once validated, the system determines the type of reward and executes the appropriate flow:

• Automatic rewards are activated immediately after being created.
• Manual or player-activated rewards remain in Unclaimed or Pending status until the player or administrator triggers activation.
• Once activation starts, the reward transitions to In Progress and then to Granted or Completed depending on the result.
• If any error occurs during the process, the status changes to Failed, providing traceability for support and debugging.

This ensures that all rewards — whether earned, purchased, or manually granted — follow a consistent, transparent, and reliable process from creation to delivery.

🎯 Reward Processor (RP) – User Journey Overview

The Reward Processor (RP) manages the complete reward lifecycle — from creation to delivery — based on platform configuration.

Each reward goes through a set of statuses that describe its current state in the process.

How the reward moves between these statuses depends on two main configuration flags:

• PlayerShouldClaimRewards – determines if the player must manually claim the reward.
• AutomaticActivation – determines if the reward is automatically activated or needs manual activation.

---

🧭 User Journey Scenarios

Scenario 1 – Player Must Claim and Activate

Actors: 👤 Player → ⚙️ Reward Processor (RP) → 🧩 Mechanic or service
(Typical for boosters, mini-games, or rewards with expiration)

1. A new reward is registered in RP.
2. Since PlayerShouldClaimRewards = true, the reward is stored in the Chest → status: Unclaimed.
3. The player clicks Claim in the widget → status: Pending Activation.
4. The player then clicks Activate → RP validates expiration date.
5. If the reward expires before activation → status: Expired.
6. If valid → reward moves to In Progress and is delivered to the corresponding mechanic (e.g., Missions, Ranks).
7. The service processes the reward:
   • Applies effects (XP, multipliers, etc.)
   • Reports completion → status: Granted or Complete.
8. If any delivery error occurs → status: Failed.

---

Scenario 2 – Automatic Activation

(Typical for XP, Tokens, Bonus, External rewards)

1. A new reward is registered.
2. Since PlayerShouldClaimRewards = false, the reward goes directly to Pending Activation.
3. If the reward expires before activation → status: Expired.
4. If AutomaticActivation = true, the RP immediately delivers the reward to the mechanic.
5. Reward moves to In Progress, and after successful delivery → Granted.
6. If there’s a communication or system error → Failed.

---

🧩 Status Table

Status	Set When	Who Triggers It	Description
Unclaimed	Reward created and stored in chest	RP	Player must claim before activation.
Pending Activation	Player claims the reward or system schedules activation	RP	Waiting to be activated or automatically delivered.
In Progress	Reward delivery started	RP → Mechanic	Mechanic is processing or validating reward (XP, mission, bonus, etc.).
Granted	Reward successfully applied	Mechanic → RP	Reward applied to player (e.g., XP added, bonus granted).
Complete	Temporary reward finished	Mechanic → RP	Booster or timed reward expired after use.
Expired	Reward validity period ended before activation	RP	Reward is no longer valid.
Failed	Delivery or communication error occurred	RP	Mechanic could not process reward; flagged for retry or support.
Declined	Player rejects the reward	Player	Reward is canceled and not stored.

---

🎁 Reward Type Summary

Reward Type	Activation Method	Expires	Delivered To	Example / Description
XP	Automatic	❌ No	Ranks	Player receives experience points instantly; rank system updates player progress.
Tokens	Automatic	❌ No	Wallet / Token mechanic	Virtual currency or points are added automatically to the player balance.
Bonus	Automatic	❌ No	Bonus Service / Casino	External casino bonus granted directly (e.g., 10 € bonus).
External	Automatic	❌ No	Do nothing	—
Mission Booster	Player Manual	✅ Yes	Missions	Player activates a booster (e.g., ×2 contribution) valid for a set period (e.g., 3 hours).
Token Booster	Player Manual	✅ Yes	Tokens	Multiplies earned tokens for a time window (e.g., ×3 tokens for 1 hour).
Level Booster	Player Manual	✅ Yes	Ranks	Temporarily increases XP gain in rank progression.
Mini-Game	Player Manual	✅ Yes	Mini-Game Mechanic	Unlocks a game that must be played before expiration (e.g., spin-the-wheel).
Manual Reward	Admin Manual	❌ No	Defined by Admin	Administrator assigns reward directly to player.

---

✅ Quick Summary

• Automatic rewards: delivered immediately — no user action.
  (XP, Tokens, Bonus, External)

• Manual rewards: require player activation, may expire.
  (Mission Booster, Token Booster, Level Booster, Mini-Game)