📚 Documentation

Welcome to the Refferq documentation! This guide will help you get started with setting up and running your own affiliate platform.

💡 New to Refferq? Start with the Quick Start guide to get up and running in minutes.

🚀 Quick Start

Get Refferq running locally in 5 minutes:

1. Clone the Repository

git clone https://github.com/Refferq/Refferq.git
cd Refferq

2. Install Dependencies

npm install
# or
yarn install
# or
pnpm install

3. Set Up Environment Variables

Copy the example environment file and configure your settings:

cp .env.example .env

Update .env with your database and email credentials:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/refferq"

# JWT Secret
JWT_SECRET="your-super-secret-jwt-key-change-this"

# Email (Resend)
RESEND_API_KEY="re_xxxxxxxxxxxxx"
EMAIL_FROM="noreply@yourdomain.com"

# App URL (Production)
NEXT_PUBLIC_APP_URL="https://app.refferq.com"

4. Set Up Database

npx prisma generate
npx prisma migrate dev
npx prisma db seed

5. Run Development Server

npm run dev
✅ Success! Open https://app.refferq.com or your configured domain in your browser to see Refferq running.

💾 Installation

System Requirements

Database Setup

Refferq uses PostgreSQL. You can use:

Using Docker for PostgreSQL:

docker run --name refferq-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=refferq \
  -p 5432:5432 \
  -d postgres:15

⚙️ Configuration

Environment Variables

All configuration is done through environment variables in the .env file:

Required Variables:

Optional Variables:

👥 Affiliate Management

User Registration Flow

Refferq uses a passwordless OTP-based authentication system:

  1. User enters email and selects role (Admin or Affiliate)
  2. OTP code is sent to their email
  3. User enters OTP code to complete registration
  4. New affiliates start with PENDING status
  5. Admins must approve affiliates to change status to ACTIVE

Affiliate Statuses

⚠️ Note: Only ACTIVE affiliates can earn commissions. Make sure to approve new affiliates from the admin dashboard.

🎯 Tracking Setup

JavaScript Tracking Script

Refferq includes a lightweight JavaScript tracking library (refferq-tracker.js) that you can add to any website.

Step 1: Generate API Key

In the admin dashboard, go to Settings → Integration and click "Generate API Key". You'll receive:

Step 2: Add Tracking Script

Add this script tag to your website, just before the closing </body> tag:

<script 
  src="https://app.refferq.com/scripts/refferq-tracker.js"
  data-api-url="https://app.refferq.com/api"
  data-api-key="pk_your_public_key_here"
></script>

Step 3: Track Conversions

When a sale occurs, call the tracking function:

// Track a conversion
Refferq.trackConversion({
  orderId: "order_123",
  amount: 99.99,
  currency: "USD",
  email: "customer@example.com"
});

Server-Side Tracking

For more control, use the API directly:

POST /api/track/conversion
Content-Type: application/json
X-API-Key: sk_your_private_key_here

{
  "referralCode": "JOHN123",
  "orderId": "order_123",
  "amount": 99.99,
  "currency": "USD",
  "customerEmail": "customer@example.com"
}

💰 Commissions

Commission Types

Refferq supports flexible commission structures:

Percentage-Based

{
  "type": "PERCENTAGE",
  "rate": 20,  // 20% commission
  "minPayout": 50.00
}

Fixed Amount

{
  "type": "FIXED",
  "amount": 10.00,  // $10 per sale
  "minPayout": 50.00
}

Tiered Commissions

{
  "type": "TIERED",
  "tiers": [
    { "upTo": 10, "rate": 15 },      // First 10 sales: 15%
    { "upTo": 50, "rate": 20 },      // Next 40 sales: 20%
    { "upTo": null, "rate": 25 }     // 50+ sales: 25%
  ]
}

💸 Payouts

Payout Management

Track and manage affiliate payouts through the admin dashboard:

  1. View affiliate balances and pending payouts
  2. Set minimum payout thresholds
  3. Generate payout reports
  4. Mark payouts as completed
  5. Export payout history for accounting

Automated Payouts

Integrate with payment providers (coming soon):

🔐 Authentication

API Authentication

Refferq uses JWT tokens for authentication. Include the token in your requests:

Authorization: Bearer <your-jwt-token>

Getting a JWT Token

POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@example.com",
  "otp": "123456"
}

Response:

{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": "user_id",
    "email": "admin@example.com",
    "role": "ADMIN"
  }
}

📡 API Endpoints

Authentication Endpoints

Admin Endpoints

Affiliate Endpoints

Tracking Endpoints

🔔 Webhooks

Configure webhooks to receive real-time notifications:

Webhook Events

Webhook Payload Example

{
  "event": "conversion.created",
  "timestamp": "2025-10-12T10:30:00Z",
  "data": {
    "conversionId": "conv_123",
    "affiliateId": "aff_456",
    "amount": 99.99,
    "commission": 19.99,
    "orderId": "order_789"
  }
}

☁️ Deploy to Vercel

One-Click Deploy

Deploy Refferq to Vercel in seconds:

  1. Fork the Refferq repository on GitHub
  2. Connect your Vercel account to GitHub
  3. Click "New Project" and select the forked repository
  4. Add your environment variables
  5. Click "Deploy"
💡 Tip: Use Vercel's built-in PostgreSQL database or connect to an external provider like Supabase.

🐳 Docker Deployment

Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: refferq
      POSTGRES_PASSWORD: yourpassword
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://postgres:yourpassword@db:5432/refferq
      JWT_SECRET: your-jwt-secret
      RESEND_API_KEY: re_xxxxx
    depends_on:
      - db

volumes:
  postgres_data:

Run with:

docker-compose up -d

🖥️ VPS/Cloud Deployment

Deploy to Any VPS

Deploy Refferq to Digital Ocean, Linode, AWS, or any VPS:

  1. Set up server - Ubuntu 22.04 recommended
  2. Install Node.js - Use nvm or apt
  3. Install PostgreSQL
  4. Clone repository
  5. Configure environment
  6. Build application - npm run build
  7. Set up PM2 - Process manager
  8. Configure Nginx - Reverse proxy
  9. Set up SSL - Use Let's Encrypt

Using PM2

# Install PM2
npm install -g pm2

# Start application
pm2 start npm --name "refferq" -- start

# Save PM2 config
pm2 save
pm2 startup
🎉 Congratulations! You now have a fully functioning affiliate platform. Check out our GitHub Wiki for more advanced topics.

📞 Need Help?

Join our community and get support: