Transaction API

Overview

The Transaction API enables your games to communicate with Groove for all wallet and gaming operations. Your game sends transaction requests to Groove, which then handles the actual wallet operations with the casino operators.

This standardized API allows your games to work with any casino operator connected to Groove without needing individual integrations.

Transaction Flow

When a player starts your game:

1. Your game calls Groove’s GetAccount endpoint to validate the session
2. Your game calls Groove’s GetBalance to retrieve the player’s current balance
3. During gameplay, your game sends Wager requests to Groove when players bet
4. Your game sends Result requests to report wins or losses
5. If needed, your game can send Rollback requests to correct transactions

API Configuration

• Groove Transaction Endpoint: {GrooveEndpoint}/groove (Groove will provide this)
• Request Method: GET
• Response Format: JSON
• Authentication: HMAC-SHA256 signature in Authorization header ( see Signature Validation)

Transaction Sequence Diagram

Transaction Types

Authentication & Session Management (Your Game → Groove)

• GetAccount - Validate player session and get player details
• GetBalance - Retrieve current player balance

Core Gaming Transactions (Your Game → Groove)

• Wager - Process a bet when player places a wager
• Result - Report the outcome of a game round
• Wager and Result - Process bet and result in a single transaction

Correction & Special Transactions (Your Game → Groove)

• Rollback - Cancel or reverse a previous transaction
• Jackpot - Report a jackpot win to Groove

Security (Groove → Your Game)

• Signature Validation - Validate HMAC-SHA256 signatures on requests

Implementation Requirements for Your Game

Making Requests to Groove

• All requests from your game to Groove use GET method with URL parameters
• Session ID from game launch must be included in all transactions
• Transaction IDs must be unique for each transaction
• Handle timeouts appropriately (recommended 30 second timeout)

Handling Groove Responses

• Check response codes - 200 means success, others indicate errors
• Store transaction IDs for potential rollback scenarios
• Retry logic should respect idempotency (use same transaction ID)
• Balance updates should be reflected in your game UI immediately

Balance Management

For CMA-compliant games, additional fields are required:

• game_mode: Combined real and bonus modes (1 = Real, 2 = Bonus)
• order: Type of order (cash_money, bonus_money)
• Separate tracking of real_balance and bonus_balance

Error Handling

Standard Response Structure

{
    "code": 200,
    "status": "Success",
    "apiversion": "1.2",
    // Additional fields based on transaction type
}

Error Response Structure

{
    "code": 1,
    "status": "Technical error",
    "message": "Technical error",
    "apiversion": "1.2"
}

Common Error Codes

Best Practices for Game Providers

1. Session Management: Store the Groove session ID from game launch and use it for all transactions
2. Unique Transaction IDs: Generate unique IDs for each wager and result to enable proper tracking
3. Error Handling: Implement comprehensive error handling for all Groove responses
4. Balance Synchronization: Always update your game UI based on balance returned by Groove
5. Logging: Maintain detailed logs of all transactions for debugging and reconciliation
6. Timeout Handling: Implement appropriate timeouts and retry logic
7. Currency Precision: Always use decimal format with maximum of two decimal places

Security Considerations

• Implement HMAC-SHA256 signature validation for all incoming requests ( see Signature Validation)
• Use HTTPS for all communications
• Validate session tokens properly
• Implement rate limiting to prevent abuse
• Log all transactions for audit purposes
• Store Access Keys securely (never in code)

Integration Steps for Your Game

1. Implement session validation - Call GetAccount when game loads
2. Add balance retrieval - Call GetBalance to show player’s funds
3. Process bets - Send Wager requests when players place bets
4. Report results - Send Result requests after each game round
5. Handle corrections - Implement Rollback for error scenarios
6. Support jackpots - Send Jackpot requests for special wins

Continue to GetAccount API →