Sportsbook - Bet By Batch

Sportsbook Feature - Bet By Batch

Overview

The Bet By Batch transaction is a sportsbook-specific feature that allows processing multiple wagers in a single API call. This is particularly useful for sports betting scenarios where players need to place multiple bets simultaneously (such as parlays, accumulators, or system bets), improving performance and reducing the number of individual API calls required.

Info

Bet By Batch is a sportsbook-optimized endpoint for handling multiple wagers in a single request. Each bet in the batch is processed independently with its own transaction ID and round ID. This feature is essential for complex sports betting scenarios.

Request Format

Endpoint

POST {casino_url}?request=wagerbybatch&request_id=XXXXXXX&gamesessionid=YYYYYY&gameid=TTTTTTT&apiversion=1.2

HTTP Method

POST (Unlike other transaction endpoints that use GET)

Query Parameters

Parameter Type Required Description
request string Yes Must be set to “wagerbybatch”
request_id string Yes Unique identifier for this batch request
gamesessionid string Yes The game session identifier
gameid string Yes The game identifier
apiversion string Yes API version (e.g., “1.2”)

Request Body (JSON)

Field Type Required Description
account_id string Yes Player’s account identifier
game_id string Yes Game identifier (should match query parameter)
game_session_id string Yes Game session identifier (should match query parameter)
device string Yes Device type (e.g., “Desktop”, “Mobile”)
bets array Yes Array of bet objects

Bet Object Structure

Field Type Required Description
frb_id string No Free Round Bonus ID if applicable
amount decimal Yes Wager amount for this bet
round_id string Yes Unique round identifier for this bet
transaction_id string Yes Unique transaction identifier for this bet

Request Example

POST {casino_endpoint}?request=wagerbybatch&request_id=batch_001&gamesessionid=1501_aea2b5b4-e066-4561-a16b-a187a6435a64&gameid=82602&apiversion=1.2

{
    "account_id": "24",
    "game_id": "82602",
    "game_session_id": "1501_aea2b5b4-e066-4561-a16b-a187a6435a64",
    "device": "Desktop",
    "bets": 
    [
            {
            "frb_id": "",
            "amount": 0.01,
            "round_id": "groove_test_00000000000000008",
            "transaction_id": "groove_test_00000000000000008"
            },
            {
            "frb_id": "",
            "amount": 0.02,
            "round_id": "groove_test_00000000000000009",
            "transaction_id": "groove_test_00000000000000009"
            },
            {
            "frb_id": "",
            "amount": 0.03,
            "round_id": "groove_test_00000000000000010",
            "transaction_id": "groove_test_00000000000000010"
            }
    ]
}

Response Format

Success Response

{
  "status": "Success",
  "code": 0,
  "message": "OK",
  "bets": [
    {
      "provider_transaction_id": "groove_test_00000000000000008",
      "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
      "bonus_money_bet": "0.00",
      "real_money_bet": "0.01"
    },
    {
      "provider_transaction_id": "groove_test_00000000000000009",
      "transaction_id": "123e4567-e89b-12d3-a456-426614174001",
      "bonus_money_bet": "0.00",
      "real_money_bet": "0.02"
    },
    {
      "provider_transaction_id": "groove_test_00000000000000010",
      "transaction_id": "123e4567-e89b-12d3-a456-426614174002",
      "bonus_money_bet": "0.00",
      "real_money_bet": "0.03"
    }
  ],
  "balance": "1234.51",
  "real_balance": "1234.51",
  "bonus_balance": "0.00"
}

Response Fields

Field Type Description
status string Response status (“Success”, “Failed”)
code integer Response code (0 for success, error code for failure)
message string Response message
bets array Array of individual bet results
balance decimal Player’s total balance after all batch bets are processed
real_balance decimal Player’s real money balance after batch processing
bonus_balance decimal Player’s bonus money balance after batch processing

Individual Bet Result Fields

Field Type Description
provider_transaction_id string Transaction ID from the game provider (maps to request transaction_id)
transaction_id string Unique transaction identifier in the wallet system
bonus_money_bet decimal Amount of bonus money used for this specific bet
real_money_bet decimal Amount of real money used for this specific bet

Error Handling

Error Response

When the batch request fails:

{
  "code": 1006,
  "status": "Out of money",
  "message": "Insufficient funds to process batch"
}

Common Error Codes

Code Status Description
1 Technical error Internal server error
110 Operation not allowed This error occurs when:
• The wager amount is negative
• Player account not found
• Account ID doesn’t match session ID
200 Success Batch processed successfully
200 Success - duplicate request Duplicate batch request (idempotency)
400 Transaction operator mismatch Transaction belongs to a different operator
409 Round closed or transaction ID exists The round is already closed or this transaction ID has been used
1000 Not logged on Player session is invalid or expired
1006 Out of money Insufficient funds to place the wagers
1019 Gaming limit Player has exceeded betting limits:
• Loss limit exceeded
• Overall bet limit exceeded
1035 Account blocked Player account is suspended or blocked
Info

**Note**: The Bet By Batch endpoint processes all bets atomically - either all bets succeed or all fail. Individual bet failures within a batch will cause the entire batch to be rejected.

Tip

For a complete list of error codes, refer to [Appendix A: Transaction Response Status Codes](/appendix-a-transaction-response-status-codes/).

Processing Logic

  1. Batch Validation: The entire batch is validated for structure and session validity
  2. Atomic Processing: All bets in the batch are processed as a single atomic transaction
  3. Balance Check: Total required amount for all bets is validated against available balance
  4. Transaction Recording: Each bet is recorded with its own transaction ID in the wallet system
  5. Balance Updates: Player balance is updated once after all bets are processed
Warning

**Important Considerations:** - Each bet must have a unique transaction_id (provider_transaction_id in response) - All bets must succeed for the batch to be accepted - The entire batch is rolled back if any individual bet fails - Balance is calculated considering both real money and bonus money - The response includes breakdown of real vs bonus money used for each bet

Idempotency

Each individual bet within the batch follows standard idempotency rules:

  • If a transaction_id has been processed before, return the original response for that bet
  • The batch request_id should also be unique for each batch submission
  • Resubmitting the same batch with the same request_id should return the original response

Use Cases

Sports Betting Scenarios

Parlay/Accumulator Bets

Multiple selections combined into a single bet:

{
  "bets": [
    {
      "amount": 10.00,
      "round_id": "parlay_001",
      "transaction_id": "match1_home_win"
    },
    {
      "amount": 10.00,
      "round_id": "parlay_001",
      "transaction_id": "match2_over_2.5"
    },
    {
      "amount": 10.00,
      "round_id": "parlay_001",
      "transaction_id": "match3_both_score"
    }
  ]
}

System Bets

Multiple combinations from selected events:

{
  "bets": [
    {
      "amount": 5.00,
      "round_id": "system_001",
      "transaction_id": "combo_1_2"
    },
    {
      "amount": 5.00,
      "round_id": "system_001",
      "transaction_id": "combo_1_3"
    },
    {
      "amount": 5.00,
      "round_id": "system_001",
      "transaction_id": "combo_2_3"
    }
  ]
}

Multiple Single Bets

Different bets on various sporting events:

{
  "bets": [
    {
      "amount": 20.00,
      "round_id": "single_001",
      "transaction_id": "football_match_1"
    },
    {
      "amount": 15.00,
      "round_id": "single_002",
      "transaction_id": "tennis_match_1"
    },
    {
      "amount": 10.00,
      "round_id": "single_003",
      "transaction_id": "basketball_match_1"
    }
  ]
}

Security

When Signature Validation is enabled:

  1. Include the X-Groove-Signature header
  2. Calculate signature using query parameters (excluding request)
  3. The request body is not included in signature calculation
  4. See Signature Validation for detailed implementation

Signature Example

For the request:

POST {casino_url}?request=wagerbybatch&request_id=batch_001&gamesessionid=1501_xyz&gameid=82602&apiversion=1.2

Query parameters for signature (alphabetically sorted):

  • apiversion: “1.2”
  • gameid: “82602”
  • gamesessionid: “1501_xyz”
  • request_id: “batch_001”

Concatenated values: 1.282602gamesessionid_valuebatch_001

Best Practices

  1. Batch Size: Keep batch sizes reasonable (typically < 100 bets)
  2. Transaction IDs: Use meaningful, unique transaction IDs
  3. Error Recovery: Implement proper error handling for partial failures
  4. Logging: Log both the batch request_id and individual transaction_ids
  5. Validation: Pre-validate bet amounts and balance before submission
  6. Timeout Handling: Set appropriate timeouts for larger batches
Tip

For optimal performance, group related bets that belong to the same game round into a single batch rather than making individual wager calls.