Player Management

The Player Management APIs enable casino operators to register players for tournaments, handle rebuys, manage player sessions, and track tournament participation.

Player Registration

Register Player for Tournament

POST /api/tournaments/12345/players
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "user_id": "USER_12345",
  "display_name": "TestPlayer",
  "entry_payment_details": {
    "payment_id": "PAY_67890"
  }
}

Response:

{
  "player_id": "456",
  "internal_player_id": "TP_12345_456_789",
  "tournament_id": "12345",
  "status": "registered",
  "crash-classic": {
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "game_url": "https://games.casino.com/crash?jwt=eyJ0eXAi..."
  },
  "message": "Player registered successfully"
}

JWT Token & Game Access

The JWT token contains tournament and player information needed for game platform authentication. Tokens are valid for the duration of the tournament.

Game Access Structure: Game access information is keyed by the game slug (e.g., crash-classic). Each game object contains:

{
  "crash-classic": {
    "jwt": "eyJ0eXAi...",
    "game_url": "https://games.casino.com/crash?jwt=eyJ0eXAi..."
  }
}

Usage:

Game Key: Object key matches the tournament’s game slug
jwt: Token for game platform authentication
game_url: Direct link to launch the tournament game (includes JWT as query parameter)

JWT Payload Structure:

{
  "tournament_id": "12345",
  "internal_player_id": "TP_12345_456_789",
  "external_user_id": "USER_12345",
  "display_name": "TestPlayer",
  "operator_id": "op_123",
  "iat": 1642086000,
  "exp": 1642089600
}

Player Rebuy System

Process Player Rebuy

Handle additional entries for players during tournament:

POST /api/tournaments/12345/players/456/rebuy
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "additional_entries": 1
}

Response:

{
  "rebuy_approved": true,
  "new_entry_count": 2,
  "total_paid": 30,
  "additional_entries": 1,
  "entry_statistics": {
    "total_players": 25,
    "total_entries": 48,
    "average_entries_per_player": 1.92
  },
  "message": "Rebuy processed successfully"
}

Rebuy Validation

Rebuys are subject to tournament configuration limits and timing restrictions. The API will validate all rebuy attempts.

Rebuy Conditions:

Tournament allows rebuys (rebuy_enabled: true)
Player hasn’t reached maximum entries (max_entries_per_player)
Tournament is in valid status for rebuys (in_progress)
Player has sufficient balance for rebuy fee

Multiple Entry System: Players can purchase additional tournament entries up to the configured limit. Each entry acts as a separate “life” or chance in the tournament. Rebuy Fee Calculation:

First entry: Entry fee (e.g., $10)
Additional entries: Rebuy fee (e.g., $20 each)
Total for 3 entries: $10 +$ 20 + $20 =$ 50

Advanced Rebuy Scenarios

Multiple Entries
Default Behavior
Validation Errors

Request multiple entries at once:

{
  "additional_entries": 2
}

Response includes updated statistics:

{
  "rebuy_approved": true,
  "new_entry_count": 3,
  "total_paid": 50,
  "additional_entries": 2,
  "entry_statistics": {
    "total_players": 25,
    "total_entries": 52,
    "average_entries_per_player": 2.08
  }
}

No additional_entries specified defaults to 1:

{}

Equivalent to:

{
  "additional_entries": 1
}

Exceeding maximum entries:

{
  "error": "Would exceed maximum entries per player",
  "current_entries": 2,
  "max_entries": 2,
  "additional_requested": 1
}

Tournament not allowing rebuys:

{
  "error": "Rebuys are not enabled for this tournament"
}

Invalid tournament status:

{
  "error": "Rebuys are not allowed in current tournament status"
}

Player Session Management

Get Tournament Players

Retrieve list of players registered for a tournament:

GET /api/tournaments/12345/players?status=active&limit=50
Authorization: Bearer {your-api-key}

Response:

{
  "players": [
    {
      "playerId": "tp_player_456",
      "userId": "player_123", 
      "displayName": "PlayerName",
      "status": "active",
      "entryCount": 2,
      "totalPaid": 20.00,
      "currentPosition": 15,
      "points": 1250,
      "registeredAt": "2024-01-15T19:30:00Z"
    }
  ],
  "pagination": {
    "total": 87,
    "limit": 50,
    "offset": 0
  }
}

Player Status Values

Status	Description	Available Actions
`registered`	Player registered, tournament not started	Remove, Update
`active`	Player participating in tournament	Rebuy, View Status
`advancing`	Player advanced to next round	View Status
`eliminated`	Player eliminated from tournament	View Final Results
`withdrawn`	Player left tournament voluntarily	View Final Results

Remove Player

Remove a player from tournament (before tournament starts):

DELETE /api/tournaments/12345/players/tp_player_456
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "reason": "player_request",
  "processRefund": true
}

Response:

{
  "playerId": "tp_player_456",
  "removed": true,
  "refundProcessed": true,
  "refundAmount": 20.00,
  "reason": "player_request"
}

Player Data & Statistics

Get Player Details

Retrieve detailed information about a specific player in a tournament:

GET /api/tournaments/12345/players/tp_player_456
Authorization: Bearer {your-api-key}

Response:

{
  "playerId": "tp_player_456",
  "userId": "player_123",
  "displayName": "PlayerName",
  "status": "active",
  "registeredAt": "2024-01-15T19:30:00Z",
  "entryCount": 2,
  "totalPaid": 20.00,
  "currentStats": {
    "position": 15,
    "points": 1250,
    "currentRound": 3,
    "gamesPlayed": 8,
    "averageScore": 156.25
  },
  "sessionInfo": {
    "lastActiveAt": "2024-01-15T20:30:00Z",
    "connectionStatus": "connected",
    "gameRoomId": "room_abc123"
  }
}

Error Handling

Common Player Management Errors

Duplicate Registration

{
  "error": "player_already_registered",
  "message": "Player is already registered for this tournament",
  "playerId": "tp_player_456",
  "tournamentId": "12345"
}

Rebuy Limit Exceeded

{
  "error": "rebuy_limit_exceeded",
  "message": "Player has reached maximum entries limit",
  "currentEntries": 3,
  "maxEntries": 3
}

Tournament Full

{
  "error": "tournament_full",
  "message": "Tournament has reached maximum player capacity",
  "currentPlayers": 100,
  "maxPlayers": 100
}

Integration Examples

Player Registration Flow

// Register player for tournament
const registerPlayer = async (tournamentId, playerData) => {
  try {
    const response = await fetch(`/api/tournaments/${tournamentId}/players`, {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(playerData)
    });
    
    if (!response.ok) {
      throw new Error(`Registration failed: ${response.status}`);
    }
    
    const registration = await response.json();
    
    // Redirect player to game with JWT token
    window.location.href = registration.gameUrl;
    
    return registration;
  } catch (error) {
    console.error('Player registration failed:', error);
    throw error;
  }
};

Rebuy Processing

// Process player rebuy
const processRebuy = async (tournamentId, playerId, rebuyAmount) => {
  try {
    const response = await fetch(
      `/api/tournaments/${tournamentId}/players/${playerId}/rebuy`,
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer your-api-key',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ rebuyAmount })
      }
    );
    
    const rebuyResult = await response.json();
    
    if (rebuyResult.rebuyProcessed) {
      console.log(`Rebuy successful. New entry count: ${rebuyResult.newEntryCount}`);
      // Update player balance and UI
      updatePlayerStats(rebuyResult);
    }
    
    return rebuyResult;
  } catch (error) {
    console.error('Rebuy processing failed:', error);
    throw error;
  }
};

Best Practices

Registration Validation

Validate player eligibility before registration
Check tournament capacity and timing
Verify payment information before processing

Session Management

Monitor player connection status
Implement session timeout handling
Track player activity for analytics

Rebuy Handling

Validate rebuy conditions before processing
Provide clear rebuy limit information
Handle failed payment scenarios gracefully

Error Recovery

Implement retry logic for failed registrations
Provide clear error messages to players
Log all registration attempts for debugging

Next Steps

Results & Leaderboards

Access real-time tournament rankings and final results.

Webhooks & Events

Set up real-time notifications for player and tournament events.

External APIs

Events & Webhooks

Player Management

Player Management

Player Registration

Register Player for Tournament

JWT Token & Game Access

Player Rebuy System

Process Player Rebuy

Rebuy Validation

Advanced Rebuy Scenarios

Player Session Management

Get Tournament Players

Player Status Values

Remove Player

Player Data & Statistics

Get Player Details

Error Handling

Common Player Management Errors

Duplicate Registration

Rebuy Limit Exceeded

Tournament Full

Integration Examples

Player Registration Flow

Rebuy Processing

Best Practices

Registration Validation

Session Management

Rebuy Handling

Error Recovery

Next Steps

Results & Leaderboards

Webhooks & Events

​Player Management

​Player Registration

​Register Player for Tournament

​JWT Token & Game Access

​Player Rebuy System

​Process Player Rebuy

​Rebuy Validation

​Advanced Rebuy Scenarios

​Player Session Management

​Get Tournament Players

​Player Status Values

​Remove Player

​Player Data & Statistics

​Get Player Details

​Error Handling

​Common Player Management Errors

​Duplicate Registration

​Rebuy Limit Exceeded

​Tournament Full

​Integration Examples

​Player Registration Flow

​Rebuy Processing

​Best Practices

Registration Validation

Session Management

Rebuy Handling

Error Recovery

​Next Steps

Results & Leaderboards

Webhooks & Events

Player Management

Player Registration

Register Player for Tournament

JWT Token & Game Access

Player Rebuy System

Process Player Rebuy

Rebuy Validation

Advanced Rebuy Scenarios

Player Session Management

Get Tournament Players

Player Status Values

Remove Player

Player Data & Statistics

Get Player Details

Error Handling

Common Player Management Errors

Duplicate Registration

Rebuy Limit Exceeded

Tournament Full

Integration Examples

Player Registration Flow

Rebuy Processing

Best Practices

Next Steps