Win

Called to register the result of a bet. For winning bets, add the win amount to the player's balance. For losing bets, the amount will be 0.

Endpoint

POST /win

Request

POST /win HTTP/1.1
Host: your.game.api
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "transactionId": "9ea48131-3a0f-4067-94d0-3212e7e25abb",
  "referenceTransactionId": "ea0240f5-483d-434b-a8d4-04dabf61cde3",
  "clientSessionId": "0k3cz83bb3h2vn53ocnc7pxw9",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "roundId": "17cc81fd-df13-4ca4-857d-de0f766dc372",
  "gameId": "f1c0b104-f29d-44a9-ae93-e8afcbe3feb9",
  "amount": 1000000,
  "currency": "USD",
  "roundClosed": true
}

Request Fields

Field	Type	Description
`requestId`	string	Unique request identifier (UUID)
`transactionId`	string	Unique transaction identifier for this win
`referenceTransactionId`	string	The original bet transaction ID
`clientSessionId`	string	The player's session identifier
`clientPlayerId`	string	The player's unique identifier
`roundId`	string	The game round identifier
`gameId`	string	The game identifier
`amount`	integer	Win amount (0 for losses) with 5-digit precision
`currency`	string	ISO 4217 currency code
`roundClosed`	boolean	Whether this transaction closes the round (see below)

Round Lifecycle

The roundClosed field indicates whether this is the final transaction for a round:

roundClosed: true - This is the final transaction. No more bets, wins, or rollbacks will occur for this round.
roundClosed: false - More transactions may follow for this round (e.g., multi-bet rounds).

Use roundClosed to finalize round records in your system. When true, you can safely mark the round as complete for reporting and reconciliation purposes.

Win vs Loss

Win: amount > 0 - Add this amount to the player's balance
Loss: amount = 0 - No balance change needed (bet was already deducted)

Success Response

HTTP/1.1 200 OK
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "status": "SUCCESS",
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "currency": "USD",
  "balance": 1000000
}

Response Fields

Field	Type	Description
`status`	string	`"SUCCESS"`
`requestId`	string	Echo back the request ID
`clientPlayerId`	string	Echo back the player ID
`currency`	string	ISO 4217 currency code
`balance`	integer	New balance after win/loss (5-digit precision)

Error Response

HTTP/1.1 200 OK
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "status": "UNKNOWN_ERROR",
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy"
}

Error Statuses

Status	Description
`UNKNOWN_ERROR`	Win could not be registered
`DUPLICATE_TRANSACTION_ERROR`	Transaction ID already exists with different payload

On this page