Documentação

English

Português
Español

English

Português
Español

Appearance

Rewards Club — Missions ​

Access prerequisites

  • Permission (module): viewRewardsProgram (to read) / manageRewardsMissions (to create/edit/activate/recalculate)
  • License/Feature: REWARDS_CLUB
  • Menu container: GENERAL → group Rewards Club

What it is / when to use ​

Manages the club's missions: event-driven rules that, when fulfilled, grant a reward (asset + amount) and/or points. The listing is card-based with filters by status, frequency, and event; creation/editing uses a 4-step wizard (Trigger → Identity → Reward → Validity).

Use it to design gamification: "first paid order earns X", "daily login gives Y points", "invest in crowdfunding gives Z", etc. The catalog covers 28 supported events, grouped by category (Financial, Registration & KYC, Referral, Crowdfunding, Marketplace & NFT, Staking, Volume & Streak, Level Change).

Pre-conditions ​

  • Permission: viewRewardsProgram to read; manageRewardsMissions to edit (dual permission: CPM enum + dynamic module in the DB).
  • License/Feature: REWARDS_CLUB.
  • Dependencies from other screens: the reward asset must exist; if the mission does not define one, the payout uses the default asset from the Program. For missions where missionPoints count toward the tier, the Program must use the POINTS metric.

Step by step ​

  1. Go to the menu Rewards Club → Missions (/rewards-club/missions).
  2. Filter by status (all/active/inactive), frequency, event, or free text.
  3. Click New to open the wizard.
  4. Step 1 – Trigger: choose the event from the catalog (tabs by group + explanatory cards). Apply condition_json examples or edit conditions field by field.
  5. Step 2 – Identity: name (auto-generates the code/slug), description, icon.
  6. Step 3 – Reward: asset, amount, points, frequency, and anti-fraud caps.
  7. Step 4 – Validity: dates, "requires approved user", minimum level.
  8. Save. To re-apply the rule to past events, use Recalculate.

Fields ​

FieldWhat it isRequired?System/backend effect
Event (event)Mission trigger (1 of the 28 in the catalog)YesDefines when the mission is evaluated (e.g.: DEPOSIT_CONFIRMED, ORDER_EXECUTED, USER_LOGIN_DAILY).
Conditions (condition)Event-specific filtersNoJSON editable field by field (e.g.: thresholdFiat, minAmountFiat, everyN, assetFilter). Restricts when the mission pays out.
Name (name) / Code (code)Display name and unique slugYesThe code is generated as a slug from the name (on creation) and is stable across replays — the basis of idempotency.
Icon (icon)Card iconNoMaterial Icons; quick-picker with suggestions.
Reward asset (rewardAssetId)Asset paid on completionYes in wizard (step 3)If empty in the final model, the payout uses the Program's defaultRewardAsset.
Amount (rewardAmount)How much is paidYesBigNumber string; step 3 requires > 0.
Points (missionPoints)Points granted on completionNoInteger ≥ 0 (default 0). Count toward the tier when the Program uses the POINTS metric.
Frequency (frequency)Payment cadenceYesONCE_PER_USER (once in a lifetime), ONCE_PER_DAY, ONCE_PER_MONTH, EVERY_N_OCCURRENCES (pays every N — requires everyN).
Every N (everyN)N occurrences to trigger paymentConditionalRequired when frequency is EVERY_N_OCCURRENCES.
Max per user (maxPerUser)Absolute ceiling per userNoundefined = unlimited (still limited by frequency).
Anti-fraud cap/user/day (maxPayoutsPerUserPerDay)Max payouts in 24h per user for this missionNo0 = no limit. Recommended > 0 for event-driven missions that trigger repeatedly.
Validity (activeFrom / activeTo)Mission validity windowactiveFrom yesOutside the window the mission does not pay.
Requires approved user (requiresApprovedUser)Only pays APPROVED usersNo (default true)When enabled, payout only occurs for users with status === 'APPROVED'.
Minimum level (lockedUntilTier)Restricts the mission to a tier or aboveNoThe mission only triggers for users who have reached the indicated tier.
Active (isActive)Enables/disables the mission—Inline toggle in the listing.

Actions and modals ​

  • Save (wizard): POST (new) or PUT (edit) at /v1/rewards-club/admin/missions. Requires step-up (password + MFA). missionPoints is normalized to integer ≥ 0.
  • Toggle active/inactive: PATCH .../missions/:id/toggle. On error, the toggle reverts.
  • Recalculate: POST .../missions/:id/recalculate. Asks whether to run for all users or a specific userId, and shows {evaluated, payoutsTriggered} at the end. Requires step-up (the interceptor responds to the 428 challenge automatically). This is the proactive recompute tool: re-evaluates the mission against already-captured events.

Business rules / cautions ​

Caution

  • Event-driven missions that can trigger many times should have maxPayoutsPerUserPerDay > 0 to contain abuse/bot behavior.
  • The code is the idempotency anchor — do not change the code of a mission in production, otherwise replays/recalculations may duplicate grants.
  • missionPoints only influence the level when the Program uses the POINTS metric. With a financial metric, points are informational only.

Irreversible

  • Recalculate can trigger real retroactive payouts. Review the scope (all vs. one user) before confirming; the operation grants real rewards.
  • Financial values: rewardAmount is a BigNumber string — no rounding.
  • Idempotency: payouts via FinLib are idempotent by externalId; error E00021 ("already processed") is success (grant already applied), not failure — which is why proactive recompute is safe against duplication.
  • APPROVED status: with requiresApprovedUser enabled, only approved users receive rewards.

Examples ​

Scenario 1 — First order paid in token (once per user)
  1. Trigger: ORDER_EXECUTED.
  2. Identity: "First order" (code FIRST_ORDER).
  3. Reward: asset tBRL, amount 5, optional missionPoints.
  4. Frequency: ONCE_PER_USER.
  5. Validity: from today; requiresApprovedUser enabled.
  6. Save (step-up). Each approved user receives it once in their lifetime.
Scenario 2 — Daily login gives points (points-based club)
  1. Trigger: USER_LOGIN_DAILY.
  2. Reward: missionPoints = 50; monetary amount can be 0.
  3. Frequency: ONCE_PER_DAY; maxPayoutsPerUserPerDay = 1.
  4. Save. With the Program on POINTS metric, the points feed the tier.
Scenario 3 — Every 10 orders, bonus
  1. Trigger: ORDER_EXECUTED, condition everyN: 10.
  2. Frequency: EVERY_N_OCCURRENCES, everyN = 10.
  3. Reward: asset + bonus amount.
  4. Save. The mission accumulates occurrences and pays every 10.