Scribd
Upload
6 views

Referral System Technical Documentation

The referral system allows users to earn rewards by referring new users, with referrers receiving a 5% bonus of the service charge for each transaction made by referred users. The document details the technical architecture, including database schema modifications, core services, API endpoints, and implementation details for tracking referrals and processing bonuses. Future enhancements and a migration plan for integrating the referral system into the existing platform are also outlined.

Uploaded by

Muwaffaq Aliyu
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
6 views

Referral System Technical Documentation

The referral system allows users to earn rewards by referring new users, with referrers receiving a 5% bonus of the service charge for each transaction made by referred users. The document details the technical architecture, including database schema modifications, core services, API endpoints, and implementation details for tracking referrals and processing bonuses. Future enhancements and a migration plan for integrating the referral system into the existing platform are also outlined.

Uploaded by

Muwaffaq Aliyu
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 7

Referral System Technical Documentation

Overview
The referral system enables users to earn rewards by referring new users to the platform. When
a referred user completes transactions, the referrer receives a bonus equal to 5% of the service
charge for each transaction. This document outlines the technical implementation details of the
referral system.

Architecture
The referral system is integrated with the existing transaction flow, specifically with the escrow
transaction process. The system consists of the following components:

1.​ Database Schema Modifications


2.​ Core Services
3.​ API Endpoints
4.​ Integration Points

Database Schema
User Table Modifications

The following fields have been added to the user table:

prisma
model user {
// Existing fields
referral_code String? @unique @db.VarChar(10)
referred_by BigInt? @db.UnsignedBigInt
referrer user? @relation("UserReferrals", fields:
[referred_by], references: [id])
referrals user[] @relation("UserReferrals")
}

User Referral Bonus Table

The user_referral_bonus table has been modified to handle all transaction types:
prisma
model user_referral_bonus {
id BigInt @id @default(autoincrement())
@db.UnsignedBigInt
referrer BigInt @db.UnsignedBigInt
referee BigInt @db.UnsignedBigInt
transaction_id String
transaction_type String // ESCROW, WALLET_TRANSFER, etc.
service_charge Decimal @db.Decimal(10, 2)
bonus_amount Decimal @db.Decimal(10, 2)
status String @default("completed")
created_at DateTime @default(now())
completed_at DateTime?
currency String @db.VarChar(3)

// Relations
referrer_user user
@relation("user_referral_bonus_referrerTouser", fields: [referrer],
references: [id])
referee_user user
@relation("user_referral_bonus_refereeTouser", fields: [referee],
references: [id])
}

Core Services
ReferralService

The ReferralService handles the core functionality of the referral system:

1.​ Generating Referral Codes: Creates unique referral codes for users
2.​ Tracking Referrals: Connects new users with their referrers during sign-up
3.​ Reporting: Provides views of referred users and bonus history

WalletService

The WalletService has been extended to include the following functionality:

1.​ Processing Referral Bonuses: Calculates and awards bonuses based on transaction
service charges
2.​ Crediting Wallets: Updates wallet balances with earned referral bonuses

Implementation Details
Referral Flow

1.​ Referral Code Generation


○​ User requests a referral code via the API
○​ System generates a unique 8-character code
○​ Code is stored with the user record
2.​ User Sign-Up with Referral
○​ New user enters a referral code during registration
○​ System validates the code and establishes the referral relationship
○​ No initial bonus is awarded at this stage
3.​ Transaction Processing
○​ When a referred user completes a transaction:
■​ System calculates the service charge (3% for escrow, 1.5% for
non-escrow)
■​ 5% of the service charge is awarded as a referral bonus
■​ The bonus is credited directly to the referrer's wallet
■​ A record is created in the user_referral_bonus table

Integration Points

The referral system integrates with the existing codebase at the following points:

1.​ User Registration


○​ processReferralSignup function is called during user creation
2.​ Transaction Completion
○​ processReferralBonus is called in handleCompletedStatus method of
the EscrowService

typescript
// In handleCompletedStatus of EscrowService
// Process referral bonus for both buyer and seller
await Promise.all([
// Process buyer's referral bonus
this.walletService.processReferralBonus(
BigInt(user.id),
escrow.amount,
serviceCharge,
escrow.unique_identifier
),
// Process seller's referral bonus
this.walletService.processReferralBonus(
BigInt(payload.sellerId),
escrow.amount,
serviceCharge,
escrow.unique_identifier
)
]);

API Endpoints
Referral Code
POST /referral/generate-code

Generates a new referral code for the user if one doesn't exist.

Request Body:

json
{
"userId": "123456"
}

Response:

json
{
"referralCode": "XYZ12345"
}

Referred Users
GET /referral/referred-users/:userId

Returns a paginated list of users referred by the given user.

Parameters:

●​ userId: ID of the user


●​ page (query, optional): Page number (default: 1)
●​ limit (query, optional): Items per page (default: 10)

Response:

json
{
"users": [
{
"id": "987654",
"fullName": "John Doe",
"username": "johndoe",
"signupDate": "2024-02-15T14:30:00Z",
"totalTransactions": 5
}
],
"pagination": {
"total": 25,
"pages": 3,
"currentPage": 1,
"limit": 10
}
}

Bonus History
GET /referral/bonus-history/:userId

Returns a paginated history of referral bonuses earned by the user.

Parameters:

●​ userId: ID of the user


●​ page (query, optional): Page number (default: 1)
●​ limit (query, optional): Items per page (default: 10)

Response:

{
"bonuses": [
{
"id": "123",
"amount": 25.50,
"currency": "NGN",
"transactionType": "ESCROW",
"transactionId": "TXN123456",
"referredUser": {
"username": "johndoe",
"fullName": "John Doe"
},
"date": "2024-02-20T10:15:00Z"
}
],
"pagination": {
"total": 15,
"pages": 2,
"currentPage": 1,
"limit": 10
}
}

Total Bonus
GET /referral/total-bonus/:userId

Returns the total referral bonus earned by the user, grouped by currency.

Parameters:

●​ userId: ID of the user

Response:

json
{
"totalReferrals": 25,
"bonuses": [
{
"currency": "NGN",
"total": 15000.00
},
{
"currency": "USD",
"total": 100.00
}
]
}

Bonus Calculation
The referral bonus is calculated as follows:

1.​ For escrow transactions:


○​ Service charge = 3% of transaction amount
○​ Referral bonus = 5% of service charge
2.​ For non-escrow transactions:
○​ Service charge = 1.5% of transaction amount
○​ Referral bonus = 5% of service charge

Example:

●​ Transaction amount: ₦100,000


●​ Escrow service charge: ₦3,000 (3%)
●​ Referral bonus: ₦150 (5% of ₦3,000)

Security Considerations
1.​ Referral Code Uniqueness: Each referral code is guaranteed to be unique via database
constraints
2.​ Validation: Referral codes are validated during sign-up
3.​ Error Handling: Referral processing is designed to be non-blocking for the main
transaction flow
4.​ Idempotency: The system prevents duplicate bonus awards for the same transaction

Future Enhancements
1.​ Tiered Referral Program: Different bonus rates based on user activity or tier
2.​ Time-Limited Campaigns: Special referral rates during promotional periods
3.​ Multi-level Referrals: Extending the program to second-level referrals
4.​ Notifications: Alerting users when they earn referral bonuses
5.​ Analytics Dashboard: Providing users with visual analytics of their referral performance

Migration Plan
The migration to implement the referral system requires:

1.​ Adding new fields to the user table


2.​ Modifying the user_referral_bonus table
3.​ Deploying the new services and controllers
4.​ Integrating with the existing transaction flow

Database migrations should be run during a low-traffic period to minimize disruption.

You might also like