cTrader Invite

cTrader Invite enables brokers to implement affiliate and referral programmes with multi-level tracking and attribution reporting.

Overview

The cTrader Invite 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 cTrader Invite, ensure completion of:

• Prerequisites: All foundation requirements
• Identity options: SSO User creation and authorisation - Required for partner identification and attribution

Note: This module requires SSO User creation and authorisation 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

3. 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

4. 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)

5. cTrader backend confirms assignment

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

Stage 3: Referral Link Generation

6. Partner generates referral links

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

7. 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

2. 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

3. 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

3. 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

4. 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

5. 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

6. Performance reporting

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

API specifications

cTrader backend endpoints

Set a new partner identifier

Method	URL
PUT	/oauth2/ctid/referral

Assigns a partner identifier from the broker's backend to an existing user or account in cTrader. Append the Manager Token as ?token={webservToken} (see Authentication of API calls).

Request body

Key	Required?	Data Type	Description
brokerCrmName	Yes	string	The broker's CRM name as provided by Spotware.
partnerId	Yes	string	The partner identifier string to assign.
userId	No (required if assigning to a user)	integer	The unique ID of the user.
ctidTraderAccountId	No (required if assigning to an account)	integer	The unique ID of the linkage between a user and a trading account.

Expected status code: 200

Read a partner identifier

Method	URL
GET	/oauth2/ctid/referral

Retrieves the partner identifier assigned to a specific user or account. Append the Manager Token as ?token={webservToken}.

Query parameters

Parameter	Required?	Data Type	Description
brokerCrmName	Yes	string	The broker's CRM name as provided by Spotware.
userId	No (required if the partner is a user)	integer	The unique ID of the user.
ctidTraderAccountId	No (required if the partner is an account)	integer	The unique ID of the linkage between a user and a trading account.

Output

Key	Data Type	Description
userId	integer	The unique ID of the user.
ctidTraderAccountId	integer	The unique ID of the linkage between a user and a trading account.
partnerId	string	The partner identifier string assigned to the entity.

Expected status code: 200

Delete a partner identifier

Method	URL
DELETE	/oauth2/ctid/referral

Deletes the partner identifier attached to a specific user or account. Append the Manager Token as ?token={webservToken}.

Query parameters

Parameter	Required?	Data Type	Description
brokerCrmName	Yes	string	The broker's CRM name as provided by Spotware.
userId	Yes	integer	The unique ID of the user.
ctidTraderAccountId	No	integer	The unique ID of the linkage between a user and a trading account. If unspecified, only the user-level record is deleted.

Expected status code: 200