Documentação

English

Português
Español

English

Português
Español

Appearance

Referral Program ​

Access prerequisites

  • Permission (module): viewIndicationProgram (to read) / manageIndicationProgram (to create/edit/delete)
  • License/Feature: None
  • Menu container: GENERAL → Referral Program group

What it is / when to use ​

Configures the referral programs (member-get-member): when someone referred by a user performs a covered action (invest in crowdfunding, execute an order, buy on the marketplace, stake, etc.), the referrer receives a commission. You define what the commission is based on (house fee or gross amount), the percentage, the covered events and caps per event/month.

The form includes presets (Conservative, Balanced, Aggressive), a live simulator and a narrative summary to validate the rule before saving.

Prerequisites ​

  • Permission: viewIndicationProgram to read; manageIndicationProgram to edit (dual permission: CPM enum + dynamic module in the DB).
  • License/Feature: None specific.
  • Dependencies on other screens: commissions generated by these programs appear in Referral Commission History.

Step by step ​

  1. Go to the menu Referral Program → Programs (/indication-program/programs).
  2. The list shows each program with covered events and percentage. Click New or click a program to edit it (dedicated page, not a drawer).
  3. (Optional) Apply a preset to pre-fill base, percentage, caps and events.
  4. Choose the calculation base (On the house fee / On the gross amount).
  5. Select the covered events (chips).
  6. Set the percentage and, optionally, a per-event cap and a monthly cap.
  7. Use the simulator (gross amount + fee%) to check the resulting commission and read the narrative summary.
  8. Save.

Fields ​

FieldWhat it isRequired?Effect on the system/backend
Name (name)Program nameYesIdentifies the program. Validated as non-empty.
Description (description)Free textNoInformational only.
Active (isActive)Enables/disables the program—An inactive program does not generate commissions.
Calculation base (baseKind)What the percentage is applied toYesSYSTEM_FEE = % of the fee the house charges (sustainable: never pays more than the fee; recommended). GROSS_AMOUNT = % of the gross amount of the operation (legacy; may exceed the fee and cause a loss).
Covered events (appliesTo[])Which actions trigger a commissionYesList of events (crowdfunding, order, marketplace, NFT, staking, deposit…). Validated: at least 1 event.
Percentage (percent)% applied to the baseYesBigNumber string; validated > 0.
Per-event cap (maxPerEventFiat)Limit per individual commissionNoCaps the value of each commission; applied in the calculation (the simulator respects the cap).
Monthly cap (maxPerMonthFiat)Monthly limit per referrerNoEach referrer receives at most this amount/month summing all commissions.
Currency (unitOfMoney)Asset credited in the commissionYes (default tBRL)Asset in which the commission is paid.

Actions and modals ​

  • New / Edit: dedicated page (/indication-program/programs/new and /programs/:id/edit).
  • Apply preset: fills in base, percentage, caps and events from the chosen template (preserves name/description/active).
  • Simulator: calculates via BigNumber the commission for a given gross amount and fee%, respecting the per-event cap. The narrative summary describes the rule in plain language.
  • Save: upsertProgram in CustomerProfileService (CPM). Validates name, ≥ 1 event and percentage > 0.
  • Delete: confirms and removes the program.

Business rules / cautions ​

Attention

  • Prefer the SYSTEM_FEE base: it is sustainable because the commission never exceeds the fee charged. The GROSS_AMOUNT base is legacy and may pay more than the house receives — use only in controlled campaigns.
  • The Aggressive preset intentionally has no monthly cap — it is intended for time-limited campaigns. Do not leave it active indefinitely.
  • All financial calculations use BigNumber (percentages and caps as strings) — do not round when reviewing.
  • Idempotency: generated commissions are settled by FinLib (idempotent by externalId); error E00021 ("already processed") is success.

Examples ​

Scenario 1 — Sustainable program (Balanced)
  1. Apply the Balanced preset: base SYSTEM_FEE, percentage 25%, cap/event 200, cap/month 2000.
  2. Events: crowdfunding, executed order, marketplace, staking.
  3. Simulator: R$ 1,000 operation with 2% fee → fee R$ 20 → commission R$ 5 (25% of the fee).
  4. Save. The referrer receives 25% of the fee in tBRL, limited by the caps.
Scenario 2 — Acquisition campaign (Aggressive, short window)
  1. Apply Aggressive: base SYSTEM_FEE, percentage 50%, cap/event 500, no monthly cap.
  2. Broad events (includes deposit and NFT purchase).
  3. Keep it active only during the campaign and disable it afterwards.
Scenario 3 — Commission on gross amount (legacy, with caution)
  1. Base GROSS_AMOUNT, low percentage (e.g. 1%), per-event cap mandatory to limit exposure.
  2. Confirm in the simulator that the commission does not exceed the fee for a typical operation.
  3. Save with full awareness of the risk that the commission may exceed the margin.