Referral System Development: Codes, Attribution, Payouts

Referral System Development: Codes, Attribution, Payouts

Imagine: you launch a referral program, and a week later you see hundreds of registrations from a single IP with the same referral code. Without proper attribution and fraud protection, such abuse eats your budget and demotivates real users. We design and implement referral programs that turn your customers into acquisition agents — with unique code generation, reliable cookie-based attribution, and multi‑layer fraud protection. Over five years we have built more than 30 such solutions for e‑commerce, SaaS, and educational platforms. Here is how the technical implementation looks.

Data Model and Code Generation

The database schema includes four key tables: referral_codes, referral_clicks, referrals, and referral_rewards. Each unique code is generated for a user once and remains unchanged. We use readable codes based on name or a mix of letters and digits — so users easily remember and share them. For fast lookup we add indexes on code and user_id.

CREATE TABLE referral_codes ( id BIGSERIAL PRIMARY KEY, user_id BIGINT REFERENCES users(id), code VARCHAR(32) UNIQUE NOT NULL, type VARCHAR(32) DEFAULT 'personal', created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE referral_clicks ( id BIGSERIAL PRIMARY KEY, code_id BIGINT REFERENCES referral_codes(id), ip INET, user_agent TEXT, landed_at TIMESTAMPTZ DEFAULT NOW(), converted BOOLEAN DEFAULT FALSE ); CREATE TABLE referrals ( id BIGSERIAL PRIMARY KEY, referrer_id BIGINT REFERENCES users(id), referred_id BIGINT REFERENCES users(id), code_id BIGINT REFERENCES referral_codes(id), status VARCHAR(32) DEFAULT 'pending', qualified_at TIMESTAMPTZ, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE referral_rewards ( id BIGSERIAL PRIMARY KEY, referral_id BIGINT REFERENCES referrals(id), recipient_id BIGINT REFERENCES users(id), type VARCHAR(32), amount DECIMAL(14,2), currency CHAR(3) DEFAULT 'RUB', status VARCHAR(32) DEFAULT 'pending', paid_at TIMESTAMPTZ ); 

How Referral Attribution Works

Attribution starts with a middleware that intercepts the GET parameter ?ref=CODE and stores it in the session. Even if the user does not register immediately, the code remains tied to the session for the entire visit. Upon registration we check the code and create a record in referrals with status pending. Next, we log the click and mark it as converted. The session lifetime is configurable — by default 24 hours for accurate attribution.

// Middleware: ReferralTracker class ReferralTrackerMiddleware { public function handle(Request $request, Closure $next): Response { $code = $request->query('ref'); if ($code && !session()->has('referral_code')) { $referralCode = ReferralCode::where('code', $code)->first(); if ($referralCode) { session(['referral_code' => $code]); ReferralClick::create([ 'code_id' => $referralCode->id, 'ip' => $request->ip(), 'user_agent' => $request->userAgent(), ]); } } return $next($request); } } // In UserRegistrationService public function register(array $data): User { $user = User::create($data); $referralCode = session()->pull('referral_code'); if ($referralCode) { $code = ReferralCode::where('code', $referralCode)->first(); if ($code && $code->user_id !== $user->id) { Referral::create([ 'referrer_id' => $code->user_id, 'referred_id' => $user->id, 'code_id' => $code->id, 'status' => 'pending', ]); ReferralClick::where('code_id', $code->id) ->where('converted', false) ->latest('landed_at') ->first() ?->update(['converted' => true]); } } return $user; } 

Qualification Conditions and Reward Types

A referral is considered qualified only after performing a target action — for example, first payment or profile completion. We implement this through an event system. Comparison of reward types:

Fixed rewards are simpler to implement, but percentage rewards scale with average order value. A two‑sided program (bonus to both referrer and new user) gives an extra push to registrations. In practice, percentage schemes are 2x better than fixed rewards for attracting active referrers.

How to Choose Reward Type?

It all depends on the average order value and monetization model. If the product is low‑priced, a fixed amount of a few hundred works well. For subscriptions with high LTV, percentage is more advantageous — for instance, 10% of the first payment motivates more than a one‑time bonus. We always analyze the economics and propose an optimized scheme. In one project, switching from fixed to percentage bonus cut the CPA almost by half (from $15 to $8) while maintaining referrer motivation.

Why Fraud Protection Matters

Without protection, the referral program becomes an easy target for abuse. We implement basic checks: self‑referral prohibition, limit on registrations from one IP (no more than three in seven days), and flags for manual review of suspicious chains. Session validity is also configured to prevent attribution months after a click. According to our data, fraud protection reduces losses by 80% compared to having none, saving clients $5,000–$15,000 annually.

What's Included in the Work

• Documentation of the data schema and description of API endpoints for the referrer dashboard.
• Admin interface to manage referral programs and view statistics.
• Unit tests for attribution and reward accrual.
• Deployment on a server or in a container (Docker).
• Integration with a payment system for batch payouts.
• Connection to CRM via REST API for partner data sync.

Process Overview

1. Analysis — we examine the target audience, monetization model, qualification conditions.
2. Design — choose topography (single‑level/MLM), draw ERD, agree on attribution logic.
3. Implementation — write code on Laravel 11 / Next.js 14 (React), configure queues for deferred payouts.
4. Testing — verify chains: click → registration → purchase → accrual → payout.
5. Deployment — push to staging, perform load testing (guarantee 10k concurrent clicks), then launch to production.

Timeline

The cost is calculated individually: it depends on scheme complexity, CRM integration needs, and fraud protection requirements. Typical budgets range from $5,000 to $20,000. Contact us to discuss your referral program — we'll find the optimal solution. Get a consultation on reward scheme selection, based on our experience with thirty projects. Source: Referral marketing effectiveness study, 2023.