Free Round Bonus API

Overview

The Free Round Bonus (FRB) API enables your game platform to receive and process free spin bonus requests from Groove. When casino operators want to offer free spins to their players on your games, Groove sends requests to your FRB API endpoints.

Through this API, your platform will:

  • Receive bonus template creation requests from Groove
  • Process player bonus assignments sent by Groove
  • Track and validate free round usage during gameplay
  • Support multi-currency with automatic conversion from EUR base

Integration Flow

sequenceDiagram participant Casino as Casino Operator participant Groove participant YourAPI as Your FRB API participant YourGame as Your Game Server participant Player Note over Casino,YourAPI: Template Creation Casino->>Groove: Create bonus campaign Groove->>YourAPI: POST /create (bonus template) YourAPI-->>Groove: Template ID response Note over Casino,YourAPI: Bonus Assignment Casino->>Groove: Assign bonus to players Groove->>YourAPI: POST /assign (player list) YourAPI-->>Groove: Assignment confirmation Note over Player,YourGame: Free Round Usage Player->>YourGame: Play free rounds YourGame->>Groove: Wager with frbid Groove-->>YourGame: Transaction response

API Endpoints (Your Implementation)

Your platform must implement these endpoints to receive FRB requests from Groove:

1. Create Bonus Template

Method: POST
Endpoint: https://{your_domain}/frb/create (or your specified endpoint)
Purpose: Receive and process bonus template creation requests from Groove
Direction: Groove → Your Platform

2. Assign Bonus to Players

Method: POST
Endpoint: https://{your_domain}/frb/assign (or your specified endpoint)
Purpose: Receive and process bonus assignment requests from Groove
Direction: Groove → Your Platform

3. Get FRB Status

Method: GET
Endpoint: https://{your_domain}/frb/{version}/bonus
Purpose: Provide status information for a specific bonus assignment
Direction: Groove → Your Platform

4. Cancel FRB

Method: DELETE
Endpoint: https://{your_domain}/frb/{version}/bonus
Purpose: Cancel an active bonus assignment for a player
Direction: Groove → Your Platform

Key Features

Bonus Template Assignment and Currency Conversion

When Groove sends you bonus assignments:

  • Base Currency: All templates use EUR as the base currency
  • Automatic Conversion: Your system should convert EUR amounts to each player’s currency
  • Multiple Assignments: The same template can be assigned to multiple players
  • Currency Alignment: Each player receives the bonus in their account currency
  • Exchange Rates: Use current rates to convert from EUR to player currencies

Request/Response Format

  • Content-Type: application/json; charset=UTF-8
  • Method: POST for all FRB endpoints
  • All dates/times in UTC format
  • Currency codes in ISO3 format
  • Country codes in ISO3 format

Implementation Requirements for Your Platform

  1. Idempotency: Handle duplicate requests from Groove properly - return same response
  2. Template Storage: Store template IDs when Groove creates them
  3. Currency Conversion: Convert EUR base amounts to player currencies
  4. Bulk Processing: Handle multiple player assignments in single request
  5. Error Responses: Return appropriate error codes to Groove
  6. Session Validation: Validate Groove session IDs in bonus requests
  7. Audit Trail: Log all bonus operations from Groove

Error Response Format

All error responses follow this structure:

{
    "status": "Error Type",
    "code": 400,
    "templateId": null,
    "exceptionResponses": "Error description"
}

Common Error Codes

Code Status Description
200 Success Request processed successfully
400 General Error Invalid parameters or request
443 Wrong Game ID Game ID is not valid
444 Wrong Player ID Player ID is not valid
449 Invalid Parameters Parameter validation failed
500 Internal Error Server error occurred

Best Practices for Your Implementation

  1. Request Validation: Validate all parameters from Groove before processing
  2. Template Management: Store template details when Groove creates them
  3. Partial Success: Return detailed status for each player in bulk assignments
  4. Audit Logging: Log all incoming requests from Groove
  5. Currency Precision: Maintain proper decimal precision in conversions
  6. Expiry Handling: Track and enforce bonus expiration dates
  7. Duplicate Handling: Return original response for duplicate requests from Groove
  8. Session Security: Always validate Groove session tokens

Integration with Game Transactions

When a player uses free rounds in your game:

  1. Your game checks if the player has active free rounds
  2. Your game sends wager request to Groove with:
    • frbid: The unique assignment ID your platform generated in the assign response
    • betamount: Must be 0 (zero) for free round transactions
  3. Groove validates the bonus and processes the transaction
  4. Your game decrements the free round count after successful wager
Warning

**Important Transaction Rules for Free Rounds:** - **frbid**: Must be the unique `templateId` that YOUR PLATFORM generates and returns in the assign response - **betamount**: Must always be `0` for free round wagers - **Unique Assignment IDs**: Each assignment must return a new unique templateId, even for the same bonus template - **Multiple Grants**: The same template can be assigned multiple times to the same player - each with its own unique assignment ID

Integration Steps

  1. Set up FRB endpoints on your servers to receive Groove requests
  2. Implement template storage to save bonus templates from Groove
  3. Add assignment logic to process player bonus assignments
  4. Implement status tracking to provide real-time bonus status
  5. Add cancellation support to handle bonus cancellations
  6. Integrate with your games to track free round usage
  7. Test with Groove using their staging environment
  8. Monitor and log all FRB operations for reconciliation

API Documentation