Tournament Prize

Tournament Prize Distribution

Draft Feature

Important: This feature is currently in draft and not ready for implementation. It will be released soon. Please do not attempt to integrate these APIs until official release notification.

Info

The Tournament Prize API is used to distribute prizes to winners when a tournament concludes. This endpoint handles the prize allocation from Groove to the casino operator.

Overview

When a tournament ends and winners are determined, Groove sends Tournament Prize requests to the casino operator to distribute the prizes. The casino processes these requests by validating the tournament details, checking for duplicates, and updating the player’s balance accordingly.

Warning

**Important:** Tournament Prize requests implement idempotency controls. This means the same prize request should only be processed once. If a duplicate request is received, the system must return the original response with status code 200 and the "Success - Duplicate" status.

Flow Diagram

sequenceDiagram participant Groove as Groove Platform participant Casino as Casino Operator participant Player as Player Account Groove->>Casino: Tournament Prize Request Casino->>Casino: Validate Signature Casino->>Casino: Check Idempotency Casino->>Casino: Validate Tournament ID Casino->>Casino: Validate Player ID Casino->>Casino: Process Prize alt Prize Type: Amount Casino->>Player: Credit Prize Amount else Prize Type: Other Casino->>Casino: Process Non-Monetary Prize end Casino->>Groove: Prize Response

Casino Responsibilities

The casino platform must perform the following operations when processing a Tournament Prize request:

  1. Signature Validation

    • Validate the X-Groove-Signature header
    • Calculate signature using the request body (instead of query parameters)
    • Reject the request if signature validation fails

  2. Idempotency Check

    • Check if a request with the same transaction_id has been processed before
    • If duplicate, return the original response with status “Success - Duplicate”

  3. Tournament Validation

    • Verify the tournament exists and is valid
    • Confirm the player participated in the tournament
    • Validate prize details match tournament configuration

  4. Prize Processing

    • For monetary prizes (prize_type = 1): Credit the prize amount to player’s balance
    • For non-monetary prizes (prize_type = 2): Process according to operator’s implementation
    • Store transaction details for auditing

Request Details

Endpoint

The casino URL can be either:

  1. The URL specified in the tournament definition
  2. If the tournament URL is empty, use the default wallet endpoint URL (same as regular game play)

{casino_URL}?request=tournamentWin

Request Method

POST

Request Headers

Header Required Description
X-Groove-Signature Yes Signature calculated using the request body instead of query parameters
Content-Type Yes Application/json

Request Body Parameters

Parameter Data Type Required Description
tournament_id String(UUID) Yes Unique tournament identifier
Example: 123456-13456-123456-123456
transaction_id String(255) Yes Unique transaction identifier
Example: 123123
tournament_start_date DateTime Yes Tournament start date and time
Format: YYYY-MM-DD HH:MM:SS
tournament_end_date DateTime Yes Tournament end date and time
Format: YYYY-MM-DD HH:MM:SS
tournament_position Integer Yes Player’s final position in the tournament
Example: 1 (for first place)
template_id Integer Yes Template ID defined on tournament configuration
Example: 1
prize_type Integer Yes Prize type:
1 - Monetary amount
2 - Other (non-monetary)
player_id Integer Yes Player’s unique identifier
Example: 12345
casino_id Integer Yes Casino/Brand identifier
Example: 12345
prize_value Decimal(32,10) No Prize amount (nullable for non-monetary prizes)
Example: 100.50
total_rounds Integer Yes Total number of rounds played in the tournament
Example: 10
total_bets Decimal(32,10) Yes Total amount wagered during the tournament
Example: 100
total_wins Decimal(32,10) Yes Total amount won during the tournament
Example: 2
timestamp DateTime Yes Request timestamp
Format: YYYY-MM-DD HH:MM:SS

Example Request

POST {casino_URL}?request=tournamentWin
Content-Type: application/json
X-Groove-Signature: f6d980dfe7866b6676e6565ccca239f527979d702106233bb6f72a654931b3bc

{
  "tournament_id":         "123456-13456-123456-123456",
  "transaction_id":        "123123",
  "tournament_start_date": "2025-08-27 00:00:00",
  "tournament_end_date":   "2025-08-27 00:00:00",
  "tournament_position":   1,
  "template_id":           1,
  "prize_type":            1,
  "player_id":             12345,
  "casino_id":             12345,
  "prize_value":           100.50,
  "total_rounds":          10,
  "total_bets":            100,
  "total_wins":            2,
  "timestamp":             "2025-08-27 00:00:00"
}

Response Details

Response Parameters

Parameter Data Type Required Description
transaction_id String(UUID) Yes Unique transaction identifier
Example: 11111-11111-11111-11111
code Integer Yes Response code (see below)
Example: 200
status String Yes Response status message
Example: Success - Duplicate
timestamp DateTime Yes Response timestamp
Format: YYYY-MM-DD HH:MM:SS

Example Success Response

{
  "transaction_id": "11111-11111-11111-11111",
  "code": 200,
  "status": "Success",
  "timestamp": "2025-08-27 00:00:00"
}

Example Duplicate Response

{
  "transaction_id": "11111-11111-11111-11111",
  "code": 200,
  "status": "Success - Duplicate",
  "timestamp": "2025-08-27 00:00:00"
}

Response Codes

Success Codes

Code Status Description
200 Success Prize successfully processed
200 Success - Duplicate Prize already processed (idempotent response)

Error Codes

Code Status Description
1 Internal Error Internal server error or general processing error
110 Operation not allowed Operation not permitted for various reasons:
• Invalid tournament
• Player not eligible
• Invalid prize details
• Account restrictions
Tip

Error codes follow the same standard as other transaction endpoints. For additional error codes that may apply, refer to [Appendix A: Transaction Response Status Codes](/appendix-a-transaction-response-status-codes/).

Implementation Notes

  1. Idempotency Handling:

    • Always store transaction IDs to identify duplicate requests
    • Return the original response for duplicate transactions with the same transaction ID
    • Maintain prize distribution records for auditing

  2. Signature Validation:

    • Unlike other endpoints that use query parameters, tournament prize uses the request body for signature calculation
    • Calculate signature using the entire JSON request body as a string
    • See Signature Validation for detailed implementation

  3. Prize Processing:

    • Monetary prizes should be credited to the player’s real balance
    • Non-monetary prizes require custom implementation based on operator requirements
    • Always validate prize amounts match tournament configuration

  4. Error Handling:

    • Return appropriate error codes based on validation results
    • Log all prize distribution attempts for auditing purposes
    • Include detailed error messages for troubleshooting

Security

Signature Calculation

For tournament prize requests, the signature is calculated differently than other endpoints:

  1. Use the entire request body JSON as a string (not query parameters)
  2. Append the security key to the JSON string
  3. Calculate SHA256 hash of the combined string
  4. Include hash in the X-Groove-Signature header

Signature Example

For the request body:

{
  "tournament_id": "123456-13456-123456-123456",
  "transaction_id": "123123",
  "tournament_start_date": "2025-08-27 00:00:00",
  "tournament_end_date": "2025-08-27 00:00:00",
  "tournament_position": 1,
  "template_id": 1,
  "prize_type": 1,
  "player_id": 12345,
  "casino_id": 12345,
  "prize_value": 100.50,
  "total_rounds": 10,
  "total_bets": 100,
  "total_wins": 2,
  "timestamp": "2025-08-27 00:00:00"
}

With security key "test_key", calculate:

  1. Take the exact JSON string (minified, no extra spaces)
  2. Append the security key
  3. Calculate SHA256 hash
  4. Result: X-Groove-Signature: [calculated_hash]