Skip to main content

C.6 Partner / Invite / Trader Attribution

Partner / Invite / Trader Attribution enables brokers to implement comprehensive affiliate and referral programs with multi-level tracking, automated commission calculations, and detailed attribution reporting. This module provides the foundation for broker partner ecosystems and trader acquisition programs.

Overview​

The Partner / Invite / Trader Attribution module enables:

  • Multi-level partner and referral program management
  • Automated trader attribution and commission tracking
  • Referral link generation and management
  • Partner performance analytics and reporting
  • Commission calculation and payout workflows

Prerequisites​

Before implementing Partner / Invite / Trader Attribution, ensure completion of:

  • Part A: All foundation requirements
  • Part B: B.1 (Full SSO) - Required for partner identification and attribution

Note: This module requires B.1 Full SSO as partner attribution occurs during user creation flow.

Architecture​

Attribution Models​

  1. Direct Referral: Single-level partner attribution
  2. Multi-Level IB: Multi-tier partner attribution
  3. Campaign Attribution: Marketing campaign attribution
  4. Hybrid Models: Combination of multiple attribution models

Partner Types​

  • Individual Partners: Individual traders referring other traders
  • Introducing Brokers (IBs): Professional partner organizations
  • Affiliate Marketers: Marketing-focused partners
  • Campaign Partners: Campaign-specific attribution partners

Implementation Flow​

Flow 1: New Partner Registration​

Stage 1: Partner Registration​

  1. User registers as partner

    • Registration: User completes partner registration in broker CRM
    • Verification: Partner identity and compliance verification
    • Agreement: Partner agreement and terms acceptance
    • cTrader ID: If no cTrader ID, passes through user creation flow

  2. Partner setup in broker CRM

    • Partner Profile: Create partner profile and configuration
    • Commission Structure: Define commission rates and tiers
    • Tracking Parameters: Set up tracking parameters and codes
    • Payment Details: Configure payout methods and details

Stage 2: Partner ID Assignment​

  1. Broker assigns partner ID

    • Unique ID: Generate unique partner identifier
    • Level Assignment: Assign partner level/tier
    • Tracking Setup: Configure tracking mechanisms
    • Link Generation: Generate referral link templates

  2. Partner ID registration with cTrader

    • API Call: 3.6 - Set New Partner Identifier
    • Endpoint: /ctid/users/{userId}/partnerId or /ctid/traders/{traderId}/partnerId
    • Authentication: Manager token
    • Parameters: partnerId, level (user or account)

  3. cTrader backend confirms assignment

    • Confirmation: Partner ID assignment confirmation
    • Storage: Store partner ID in cTrader backend
    • Return: Return userId or ctidTraderAccountId

  1. Partner generates referral links

    • Link Generation: Partner creates referral links in cTrader
    • Customization: Customize links for specific campaigns
    • Tracking: Links include partner ID for attribution
    • Sharing: Multiple sharing options (social, email, etc.)

  2. Link distribution and tracking

    • Distribution: Partners share referral links
    • Click Tracking: Track link clicks and conversions
    • Campaign Tracking: Track campaign-specific performance
    • Analytics: Real-time performance data

Flow 2: Existing Partner cTrader Integration​

Stage 1: cTrader ID Creation​

  1. Existing partner requests cTrader ID
    • Request: Partner requests cTrader account creation
    • Recognition: Broker recognizes existing partner status
    • Link Generation: Generate new partner-specific referral link
    • Integration: Integrate with existing partner profile

Stage 2: Partner ID Assignment​

  1. Partner ID assignment
    • API Call: 3.6 - Set New Partner Identifier
    • Context: Assign partner ID to existing partner
    • Level: User or account level assignment
    • Confirmation: Confirm successful assignment

Stage 3: Referral Operations​

  1. Referral link operations
    • Link Generation: Generate new referral links with updated partner ID
    • Link Migration: Migrate existing links if needed
    • Tracking Continuity: Ensure tracking continuity
    • Analytics: Maintain historical analytics

Flow 3: Trader Attribution​

Stage 1: Referral Click and Registration​

  1. Referred user clicks referral link

    • Link Click: User clicks partner referral link
    • Parameter Capture: Capture partnerId parameter
    • User Context: Store referral context for attribution
    • Redirect: Redirect to registration/login screen

  2. User registration with partner attribution

    • Registration: User completes registration form
    • Partner ID: Include partnerId in registration request
    • User Creation: Pass through standard user creation flow
    • Attribution: Attribute user to partner during creation

Stage 2: Attribution Confirmation​

  1. User creation with attribution

    • API Integration: Include partner ID in user creation API calls
    • Attribution Logic: Apply attribution rules and logic
    • Commission Setup: Set up commission tracking
    • Notification: Notify partner of new referral

  2. Attribution confirmation

    • Confirmation: Confirm successful attribution
    • Partner Notification: Notify partner of new referral
    • Commission Setup: Initialize commission tracking
    • Analytics Update: Update partner analytics

Stage 3: Ongoing Tracking​

  1. Commission tracking

    • Trading Activity: Track referred user trading activity
    • Commission Calculation: Calculate commissions based on activity
    • Tier Management: Manage partner tier progression
    • Payout Processing: Process commission payouts

  2. Performance reporting

    • Analytics: Provide comprehensive performance analytics
    • Reporting: Generate detailed reports for partners
    • Trends: Show performance trends and insights
    • Optimization: Provide optimization recommendations

API Specifications​

Broker CRM Endpoints​

Partner Registration​

POST /api/partners/register
Content-Type: application/json
Authorization: Bearer {managerToken}

Request Body:

{
    "userId": 12345,
    "partnerType": "individual",
    "level": "basic",
    "commissionStructure": {
        "revenueShare": 0.25,
        "cpa": 100.00,
        "tiers": [
            {"level": 1, "rate": 0.25, "minVolume": 0},
            {"level": 2, "rate": 0.30, "minVolume": 1000000}
        ]
    },
    "contactInfo": {
        "email": "partner@example.com",
        "phone": "+1234567890"
    },
    "paymentDetails": {
        "method": "bank_transfer",
        "account": "123456789"
    }
}

Referral Analytics​

GET /api/partners/{partnerId}/analytics
Authorization: Bearer {managerToken}

Response Example:

{
    "partnerId": "partner_12345",
    "analytics": {
        "totalReferrals": 156,
        "activeReferrals": 89,
        "totalCommission": 15678.90,
        "currentMonthCommission": 1234.56,
        "referralDetails": [
            {
                "referredUserId": 67890,
                "registrationDate": "2023-01-15T10:30:00Z",
                "status": "active",
                "totalVolume": 2500000.00,
                "commissionEarned": 625.00,
                "lastActivity": "2023-06-15T14:20:00Z"
            }
        ],
        "performanceMetrics": {
            "conversionRate": 0.15,
            "averageReferralValue": 100.50,
            "retentionRate": 0.85,
            "monthlyGrowth": 0.12
        }
    }
}

cTrader Backend Endpoints​

Set Partner Identifier​

PUT /ctid/users/{userId}/partnerId
Content-Type: application/json
Authorization: Bearer {managerToken}

Request Body:

{
    "partnerId": "partner_12345",
    "level": "user"
}

Response Example:

{
    "userId": 12345,
    "partnerId": "partner_12345",
    "level": "user",
    "assignedAt": "2023-01-01T12:00:00Z"
}

Get Partner Referrals​

GET /ctid/partners/{partnerId}/referrals
Authorization: Bearer {managerToken}

Response Example:

{
    "partnerId": "partner_12345",
    "referrals": [
        {
            "referredUserId": 67890,
            "referredUserEmail": "referred@example.com",
            "registrationDate": "2023-01-15T10:30:00Z",
            "status": "active",
            "firstDepositDate": "2023-01-16T09:15:00Z",
            "totalDeposits": 5000.00,
            "totalVolume": 2500000.00,
            "commissionEarned": 625.00
        }
    ],
    "summary": {
        "totalReferrals": 156,
        "activeReferrals": 89,
        "totalCommission": 15678.90,
        "pendingCommission": 234.56
    }
}
https://app.ctrader.com/signup?partnerId=partner_12345&lang=en
https://app.ctrader.com/signup?partnerId=partner_12345&campaign=summer2023&source=email&lang=en
https://app.ctrader.com/signup?partnerId=partner_12345&level=2&ibTier=premium&lang=en
https://app.ctrader.com/signup?partnerId=partner_12345&product=copytrading&lang=en

Implementation Requirements​

Broker CRM Requirements​

Partner Management​

  • Partner Registration: Comprehensive partner registration workflow
  • Profile Management: Partner profile and configuration management
  • Commission Engine: Flexible commission calculation engine
  • Tier Management: Multi-tier partner level management

Attribution Engine​

  • Attribution Logic: Complex attribution rule engine
  • Cookie Tracking: Browser cookie tracking for attribution
  • Cross-Device Tracking: Cross-device attribution capabilities
  • Attribution Windows: Configurable attribution time windows

Reporting System​

  • Real-time Analytics: Real-time performance analytics
  • Custom Reports: Customizable report generation
  • Commission Statements: Detailed commission statements
  • Tax Reporting: Tax reporting and documentation

Frontend Requirements​

Partner Portal​

  • Dashboard: Comprehensive partner dashboard
  • Link Management: Referral link generation and management
  • Analytics: Performance analytics and insights
  • Commission Tracking: Real-time commission tracking

User Registration​

  • Partner Attribution: Seamless partner attribution during registration
  • Partner Display: Display referring partner information
  • Confirmation: Registration confirmation with partner details
  • Welcome Flow: Partner-specific welcome flow

Commission Models​

Revenue Share​

  • Percentage: Percentage of spread or commission revenue
  • Tiers: Multi-tier revenue share based on volume
  • Calculation: Real-time commission calculation
  • Payment: Scheduled commission payments

CPA (Cost Per Acquisition)​

  • Fixed Amount: Fixed payment per qualified referral
  • Conditions: Specific conditions for qualification
  • Triggers: Commission trigger events
  • Validation: Validation and verification processes

Hybrid Models​

  • Combined: Combination of revenue share and CPA
  • Flexibility: Flexible commission structures
  • Optimization: Optimized for partner performance
  • Scalability: Scalable commission models

Analytics and Reporting​

Partner Performance​

  • Referral Metrics: Number of referrals, conversion rates
  • Revenue Metrics: Commission earned, revenue generated
  • Activity Metrics: Partner activity and engagement
  • Growth Metrics: Growth trends and forecasts

Referral Quality​

  • Retention Rates: Referred user retention rates
  • Trading Volume: Referred user trading volume
  • Deposit Patterns: Deposit patterns and amounts
  • Profitability: Referred user profitability

Campaign Performance​

  • Campaign Metrics: Campaign-specific performance
  • Channel Analytics: Performance by referral channel
  • Conversion Funnels: Detailed conversion analysis
  • ROI Analysis: Return on investment analysis

Error Handling​

Partner Registration Errors​

{
    "error": "Partner Registration Failed",
    "message": "Unable to register partner due to validation errors.",
    "code": "PARTNER_REGISTRATION_ERROR",
    "validationErrors": [
        {"field": "email", "message": "Email already exists"},
        {"field": "phone", "message": "Invalid phone format"}
    ]
}

Attribution Errors​

{
    "error": "Attribution Failed",
    "message": "Unable to attribute user to partner.",
    "code": "ATTRIBUTION_ERROR",
    "partnerId": "partner_12345",
    "userId": 67890,
    "reason": "Partner not found or inactive"
}

Commission Calculation Errors​

{
    "error": "Commission Calculation Error",
    "message": "Unable to calculate commission for partner.",
    "code": "COMMISSION_CALCULATION_ERROR",
    "partnerId": "partner_12345",
    "period": "2023-06",
    "reason": "Invalid commission structure"
}

Security Considerations​

Partner Data Protection​

  • Data Encryption: Encrypt sensitive partner data
  • Access Control: Role-based access to partner information
  • Audit Trail: Complete audit trail for partner activities
  • Privacy Compliance: GDPR and privacy regulation compliance

Fraud Prevention​

  • Fraud Detection: Detect and prevent referral fraud
  • Validation: Validate referral quality and authenticity
  • Monitoring: Monitor for suspicious patterns
  • Prevention: Implement fraud prevention measures

Testing Requirements​

Functional Testing​

  • Partner Registration: Test partner registration workflow
  • Attribution Logic: Test attribution accuracy and timing
  • Commission Calculation: Test commission calculation accuracy
  • Link Tracking: Test referral link tracking and validation

Performance Testing​

  • Load Testing: Test with multiple concurrent partners
  • Analytics Performance: Test analytics query performance
  • Commission Processing: Test commission processing performance
  • Database Performance: Test database query optimization

Security Testing​

  • Data Protection: Test data protection measures
  • Access Control: Test access control mechanisms
  • Fraud Detection: Test fraud detection systems
  • Vulnerability Testing: Security vulnerability assessment

Business Benefits​

For Partner Acquisition​

  • Scalable Growth: Scalable partner acquisition platform
  • Automated Management: Automated partner management workflows
  • Performance Tracking: Comprehensive performance tracking
  • Incentive Optimization: Optimized incentive structures

For Revenue Generation​

  • Cost Effective: Cost-effective user acquisition channel
  • High Quality: Higher quality referred users
  • Predictable Costs: Predictable acquisition costs
  • Scalable ROI: Scalable return on investment

For Partner Relationships​

  • Transparency: Transparent reporting and analytics
  • Reliability: Reliable commission payments and tracking
  • Support: Comprehensive partner support
  • Growth: Partner growth and development tools

Best Practices​

Partner Management​

  • Clear Terms: Clear partnership terms and conditions
  • Regular Communication: Regular partner communication
  • Performance Support: Performance optimization support
  • Fair Compensation: Fair and competitive compensation

Attribution Accuracy​

  • Robust Tracking: Robust attribution tracking systems
  • Validation: Regular validation of attribution data
  • Transparency: Transparent attribution processes
  • Dispute Resolution: Clear dispute resolution processes

Commission Management​

  • Timely Payments: Timely and accurate commission payments
  • Detailed Reporting: Detailed commission reporting
  • Tax Compliance: Tax compliance and documentation
  • Flexible Options: Flexible payment options

This Partner / Invite / Trader Attribution integration provides a comprehensive foundation for broker partner ecosystems, enabling scalable user acquisition through referral programs while maintaining accurate attribution and fair compensation structures.