Rewards and payouts

How an earned commission becomes wallet balance — the payout threshold, the KYC gate, which wallet the money lands in, duplicate protection, and what a referral programme does to your profit reporting.

7 min readUpdated 3 August 2026rewards, payouts, claim, kyc, accounting

A reward row is an entitlement, not money. Nothing has moved when one is created: mlm_referral_reward holds an amount, the condition it came from, the referrer who earned it and an isClaimed flag. The wallet credit happens later, when the member presses Claim.

That separation is deliberate. It means a misconfigured condition creates paperwork rather than an unrecoverable payout, and it means you can review or delete an unclaimed reward before it costs anything.

From activity to reward row

Two paths create rewards — the event-driven path at the moment of the transaction, and the hourly evaluator for everything else. Both end in the same place, and both are protected against paying twice.

Idempotency. Every reward carries an optional sourceId with a unique index on it. The hourly evaluator builds a deterministic key of condition_referrer_referred_period, so re-running the job — including its deliberate re-scan of the previous calendar period — can never create a second reward for the same qualifying activity. Under a multi-level structure each level gets its own key, suffixed :L1, :L2 and so on, so five levels of sponsors are five distinct rewards rather than four blocked duplicates.

When a caller supplies no sourceId there is a fallback: a reward for the same referrer, condition and amount inside the last 60 seconds is treated as a retry and skipped. Matching the amount matters — without it, two genuine qualifying deposits a minute apart would have earned one commission.

Wallet pre-creation. When the hourly job creates a reward it also creates the referrer's payout wallet if they do not have one, empty. It is best-effort and never blocks the reward. The point is that a wallet-creation failure shows up in the cron log rather than as a 500 the moment a member presses Claim.

Claiming

A member opens Affiliate → Rewards and claims an unclaimed row. Four gates run, in this order.

KYC. The withdraw_affiliate feature — labelled Affiliate Payouts in the KYC level builder — is enforced server-side. If your KYC levels require it and the member has not passed, the claim is refused and the screen shows a verification notice instead of the button.
Payout threshold. If Admin → Affiliate → Settings → Payout Threshold is greater than zero, the member's total unclaimed balance must reach it. This is a threshold on the balance, not on the individual reward — once a member is over the line they can claim rewards one at a time, including ones smaller than the threshold. Below the line the error names both numbers.
Wallet resolution. The condition decides where the money goes: rewardWalletType and rewardCurrency. The wallet is found or created on the spot. ECO uses the Ecosystem addon's wallet logic when it is installed and falls back to a generic wallet row when it is not.
The credit itself, inside a database transaction with the reward row locked. The wallet is credited with idempotency key affiliate_reward_<reward id>, an offsetting platform loss is recorded, and the reward is marked claimed. Either all three happen or none do.

The member sees the balance immediately. The transaction appears in their history as a REFERRAL_REWARD operation.

A member with 4 USDT of unclaimed rewards and a threshold of 50 cannot withdraw anything, and there is no partial or scheduled payout to rescue them. If your commission rates are small percentages of small transactions, set the threshold low or leave it at zero — otherwise most of your programme's liability sits permanently unclaimed on your books.

Which wallet the money lands in

Set per condition, not per member and not globally. Newly seeded conditions pay USDT into a SPOT wallet, which is the unit a Bicrypto install actually trades in.

`rewardWalletType`	Where it lands	Notes
`SPOT`	the member's spot wallet	The default. Tradeable and withdrawable through your normal spot flow.
`FIAT`	a fiat wallet	Only useful if you have a fiat gateway configured; otherwise the member cannot get the money out.
`ECO`	an Ecosystem on-chain wallet	Needs the Ecosystem addon for a real address. Without it you get a wallet row with nothing behind it.

Because the currency is read from the condition at claim time, editing a condition's currency re-denominates every unclaimed reward against it — a reward of 20 stops meaning "20 USD" and starts meaning "20 USDT". Check the unclaimed exposure before you change a live condition's currency.

What it does to your books

A referral commission is money the platform pays out, so it is recorded as a platform loss, not merely as an absence of revenue. On every successful claim the system writes a negative profit entry of type REFERRAL_REWARD and debits the treasury best-effort, capped at the treasury's balance so a thin treasury can never block a member's claim.

Without that entry the profit report would accumulate the fees you captured and never the commissions you paid against them: gross revenue displayed as net. An operator running a generous programme could be losing money while the dashboard showed a healthy positive number.

Two consequences worth knowing:

Unclaimed rewards are invisible to profit reporting. The loss is recorded at claim, not at accrual. Your true liability is the sum of unclaimed rewards, which you can read off the Rewards screen but which no profit figure includes.
An admin who flips isClaimed by hand records no loss and moves no money. See below.

Admin control over rewards

Admin → Affiliate → Rewards can create, edit, mark claimed and delete reward rows. All of it is bookkeeping on the reward table — none of it moves money.

The admin claimed-status action sets isClaimed = true and stops. No wallet is credited, no transaction is written, no platform loss is recorded. The member sees the reward disappear from their claimable list and receives nothing.

Use it only to close out a reward you have settled some other way — never as a way to pay someone. To actually pay, let the member claim, or credit their wallet through the normal admin wallet tools and then mark the reward claimed to keep the two in step.

Creating a reward by hand is the way to run a bonus that no condition covers: pick the referrer, pick a condition to hang it off (which determines the payout currency and wallet), enter the amount. The member can then claim it through the normal flow, with the threshold and KYC gates applying as usual.

Editing changes reward and isClaimed only. Deleting is a soft delete by default — the row keeps its unique sourceId, so the periodic evaluator will not recreate a reward you removed for the same period.

Notifications

When a commission is created the referrer gets an in-app notification titled Referral Reward Earned, with a View Rewards action linking to /affiliate/reward.

The code also fires an admin notification for every processed reward, addressed to a permission named View MLM Rewards. Permission names on this platform are dot-form keys like view.affiliate.reward, so that string matches no permission row and the notification reaches nobody.

Do not build a workflow on it. Watch the Rewards screen, or the hourly job's output in Admin → System → Cron, which logs every reward it creates.

Reviewing what you have paid

The admin Rewards list is the ledger of the programme: every reward, its condition, its referrer, its amount and whether it has been claimed. Members see the same data filtered to themselves, with their condition's currency and wallet type attached.

Three numbers worth watching regularly:

Total unclaimed — your outstanding liability, absent from profit reporting.
Rewards per condition — the fastest way to spot a rule that is paying far more often than you expected, usually because of an overlap.
Rewards per referrer — a single account collecting an unusual share is the signature of self-referral through secondary accounts. The platform blocks literal self-referral, but not a member registering their own second account.

Next: What members see, or Running the programme.