Definition of Terms
Definition of Terms
Info
This glossary defines key terminology used throughout the Groove API documentation. Understanding these terms is essential for successful integration.
Groove
The gaming gateway platform that provides aggregation services connecting casino operators with multiple game providers.
Casino
The online casino operator that integrates with the Groove API to offer games to their players.
Game Provider
Any platform that provides games through the Groove system. The platform may produce games or only resell them.
Acronym: GP
Player Experience Modes
Demo Mode
A mode where players use virtual currency (fake coins) to play games. No real money transactions are sent to the casino.
Real Mode
A mode where players use real money to play games. The casino must approve every transaction request and change the player’s balance accordingly.
Identification Parameters
Operator ID
The unique identifier assigned to a Casino by Groove during the integration process.
Account ID
The casino’s unique player identifier. Must contain only alphanumeric characters (numbers or letters). No special characters are allowed.
- In demo mode, the account ID should be a dummy value, not null.
Session ID
A unique identifier generated by the casino each time a player opens a game. Maximum length is 64 characters.
- Format: The session ID should start with an operator ID prefix (e.g.,
11_f3dr42-j83h7-jd874n where 11 is the operator ID)
- In demo mode, the session ID and account ID must be
0
- This ID is sent to the casino during each game transaction (wager, result, rollback, etc.)
- For live games or GPs with a lobby, the “game id” can change during the session as players switch games
Transaction ID
A unique identifier for each transaction. Different game providers may have the same transaction ID, but one game provider cannot have duplicate transaction IDs.
Round ID
An identifier that groups related transactions within the same gameplay round. Every wager and result request must include this parameter.
- For games like Blackjack, a single round may include multiple wagers and results
- The round ID must be the same in all requests related to the same round
- Used for tracking all actions and ensuring proper round closure
Localization Parameters
Currency
The currency displayed in the game. Must be a valid ISO 4217 code (e.g., USD, EUR, GBP).
- The casino must provide Groove Gaming with a list of accepted currencies.
Language
The language used for the game interface. Must follow the format: ISO 639 language code followed by an underscore and an ISO 3166-1 alpha-2 country code (e.g., en_US, de_DE).
Country
The country where the player is located during login. Must be an ISO 3166-1 alpha-2 country code (e.g., US, DE).
Note
This parameter is only required when using real mode. In demo mode, a dummy country code is sent.
Compliance Parameters
Reality Check Elapsed
The amount of time, in minutes, that has elapsed since the player started the session before the Reality Check is displayed.
Acronym: realityCheckElapsed
Warning
This parameter is mandatory and required to comply with United Kingdom Gambling Commission (UKGC) regulations.
Reality Check Interval
The time interval, in minutes, after which the reality check popup is displayed to the player.
Acronym: realityCheckInterval
Warning
This parameter is mandatory and required to comply with United Kingdom Gambling Commission (UKGC) regulations.
Exit URL
The page URL that the player is redirected to after exiting through the reality check dialog.
Acronym: exitUrl
Warning
This parameter is mandatory and required to comply with United Kingdom Gambling Commission (UKGC) regulations.
Game Status Parameters
Game Status
A parameter included in result requests that indicates the state of the game round. Has two possible values:
pending: The round is still in progresscompleted: The round is closed
For each round ID, there can be multiple pending results but only one completed result.
Open Round
A scenario that occurs when a Game Provider sends a wager request without a corresponding result request, or sends multiple wagers and results with no ‘completed’ result status. To prevent open round issues, the last result’s status should be ‘completed’.
Transaction Concepts
Free Rounds Bonus
A promotional feature where players receive free spins. When a free spin is granted, the Game Provider typically sends transaction requests using one of these patterns:
- A wager request followed by multiple result requests (one for each free spin)
- A wagerAndResult request for each free round (wager amount = 0, result amount ≥ 0)
- A single wagerAndResult request after all free spins are used (wager amount = 0, result amount = sum of all results)
Acronym: FRB
Note
In Free Rounds Bonus, a result request can be sent without a preceding wager request.
Retry Policy
A mechanism triggered when a timeout or unknown error occurs during a transaction. Retry policies apply to wager, result, and rollback requests.
Idempotency
An operation property ensuring that multiple identical requests produce the same result without changing the system state.
- The transaction ID serves as the idempotency key for transaction requests
- If two requests with the same transaction ID are received, the second is a duplicate
- For duplicates, the original response must be sent with status code 200 and message “Success - duplicate request”
Rollback Policy
Rules governing when transaction reversals occur. Game providers may send a rollback request:
- For each failed wager or result
- When network issues or unknown errors occur during a transaction
- If no response was received for a wager or result
Transaction Flow Diagram
The following diagram illustrates how these terms relate to each other in a typical transaction flow:
graph TD
A[Player] -->|Uses| B[Account ID]
B -->|Creates| C[Session ID]
C -->|Initiates| D{Transaction Type}
D -->|Wager| E[Transaction ID]
D -->|Result| F[Transaction ID]
D -->|Rollback| G[Transaction ID]
E -->|References| H[Round ID]
F -->|References| H
G -->|References| H
H -->|Has| I[Game Status]
I -->|Completed or Pending| J[Open/Closed Round]
style A fill:#f5f5f5,stroke:#333,stroke-width:2px
style B fill:#e6f7ff,stroke:#333,stroke-width:2px
style C fill:#e6f7ff,stroke:#333,stroke-width:2px
style D fill:#ffe6e6,stroke:#333,stroke-width:2px
style E fill:#f0f0f0,stroke:#333,stroke-width:1px
style F fill:#f0f0f0,stroke:#333,stroke-width:1px
style G fill:#f0f0f0,stroke:#333,stroke-width:1px
style H fill:#e6f7ff,stroke:#333,stroke-width:2px
style I fill:#f0f0f0,stroke:#333,stroke-width:1px
style J fill:#ffe6e6,stroke:#333,stroke-width:1px
