Section 7

Reporting

The relay keeps a record of every round and every money movement it relayed for a game provider. These reads serve reconciliation, support tickets and dispute handling.

Recorded data

Round

Created by a successful cash-out, settled by a cash-in. Holds the stake, the payout, the multiplier, the game's outcome label, and gameData and settlementData exactly as submitted.

Transaction

One per cash-out or cash-in attempt with a distinct transactionId. Written as PENDING before the casino is called, then SUCCESS with the returned balance, or FAILED with the error code.

A game provider token only ever sees its own game provider's records. Ids in the path are the game-generated ones plus the casino's providerId, because round and transaction ids are unique per casino, not globally.

Rounds

GET /api/v1/rounds?gameId=101&status=SETTLED&from=2026-09-21T00:00:00Z&to=2026-09-21T23:59:59Z&page=1&limit=50
Authorization: Bearer rly_acme_…

200 {
  "statusCode": 200,
  "message": "Rounds fetched successfully",
  "data": [
    {
      "id": "6702a1…",
      "roundId": "r-2026-09-21-000871-48213",
      "gameId": 101,
      "groupId": "66ffc0a1…",
      "providerId": "66ffba1337e994c3009ebf40",
      "playerId": "48213",
      "sessionId": "6f1e0d5c-…",
      "currency": "USD",
      "language": "en",
      "status": "SETTLED",
      "betAmount": 10,
      "betTransactionId": "bet-01J8Z1Q9K4X2Y7",
      "payoutAmount": 24.5,
      "appliedMultiplier": 2.45,
      "settleTransactionId": "win-01J8Z1S2M7P0Q3",
      "settleReason": "NORMAL_WIN",
      "outcome": "CASHED_OUT",
      "gameData": { "grid": 25, "mines": 3, "seedHash": "a9f3…" },
      "settlementData": { "revealed": [3, 7, 12], "multiplier": 2.45 },
      "openedAt": "2026-09-21T09:20:11.402Z",
      "settledAt": "2026-09-21T09:20:39.118Z",
      "createdAt": "2026-09-21T09:20:11.410Z",
      "updatedAt": "2026-09-21T09:20:39.120Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50, "totalPages": 1 }
}

Filter	Values
status	OPEN (bet taken, not yet settled) or SETTLED.
gameId, providerId, playerId, roundId, currency	Exact match.
from, to	Inclusive ISO-8601 range on createdAt.
sortBy	createdAt (default), openedAt, settledAt, betAmount, payoutAmount; sortOrder asc or desc.
page, limit	Defaults 1 and 20; limit at most 100.

Rounds still OPEN after the game considers them finished are the most useful signal: each one is a bet whose settlement never succeeded, and therefore a credit still owed or a loss never reported.

One round with its transactions

GET /api/v1/rounds/66ffba1337e994c3009ebf40/r-2026-09-21-000871-48213

200 { "statusCode": 200, "message": "Round fetched successfully",
      "data": { …round fields…, "transactions": [ { …cash-out… }, { …cash-in… } ] } }

Transactions

GET /api/v1/transactions?status=FAILED&category=CASH_IN&from=2026-09-21T00:00:00Z

200 {
  "statusCode": 200,
  "message": "Transactions fetched successfully",
  "data": [
    {
      "id": "6702b7…",
      "transactionId": "win-01J8Z1S2M7P0Q3",
      "previousTransactionId": "bet-01J8Z1Q9K4X2Y7",
      "category": "CASH_IN",
      "status": "FAILED",
      "groupId": "66ffc0a1…",
      "gameId": 101,
      "providerId": "66ffba1337e994c3009ebf40",
      "playerId": "48213",
      "sessionId": "6f1e0d5c-…",
      "roundId": "r-2026-09-21-000871-48213",
      "amount": 24.5,
      "currency": "USD",
      "language": "en",
      "reason": "NORMAL_WIN",
      "appliedMultiplier": 2.45,
      "betAmount": 10,
      "isRetry": false,
      "errorCode": "INTEGRATION_TIMED_OUT",
      "errorMessage": "provider did not answer within 10000 ms",
      "completedAt": "2026-09-21T09:20:49.300Z",
      "createdAt": "2026-09-21T09:20:39.100Z",
      "updatedAt": "2026-09-21T09:20:49.300Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 20, "totalPages": 1 }
}

Field	Meaning
category	CASH_OUT (debit, bet) or CASH_IN (credit).
status	PENDING (casino call in progress or abandoned), SUCCESS, FAILED.
balance	What the casino returned on success. This is also what a replay of the same transactionId returns.
errorCode, errorMessage	Why it failed. The code is one of the error catalogue.
isRetry	True when the attempt came through /api/balance/cash-in/retry.
completedAt	When the casino answered. Absent while PENDING.

Extra filters over the round list: transactionId, category, status. Sortable by createdAt, completedAt, amount.

One transaction

GET /api/v1/transactions/66ffba1337e994c3009ebf40/win-01J8Z1S2M7P0Q3

Reconciliation routine

1. List rounds?status=OPEN for yesterday. Every hit is an unsettled bet: settle it or investigate.
2. List transactions?status=FAILED&category=CASH_IN for yesterday. Every hit is a credit owed: each must be present in the retry queue.
3. List transactions?status=PENDING older than a few minutes. Those are attempts that never got an answer; repeat them with the same transactionId to resolve them.
4. Sum betAmount and payoutAmount of settled rounds per casino and currency, and compare with the game's own ledger.