Settlement Corrections

A settled bet is corrected in one of two ways, and the difference decides which transaction your wallet receives:

Resettle adjusts the payout directly. The direction depends on the change — a bigger payout arrives as a deposit, a smaller one as a withdrawal. No further settle transaction follows.
Cancel settle reverts the settlement entirely. It is always a withdrawal, the bet returns to the unsettled state, and a new settle transaction with the corrected result follows afterwards.

See Cancel Settle vs Resettle for the full comparison, including how it applies to freebet and bonus bets.

Caution

Neither of these is a rollback. A rollback reverses a bet placement and carries context.parentId; a settlement correction carries none and must never return decline.parent.*. See Place Bet - Rollback.

Flow

Responses

All three corrections below share the same envelopes, so only their requests differ.

On success, the bet is corrected. A 400 is final: the correction fails and the bet stays in its previous state. A 429, a 5XX or a timeout is retried instead — see Rollback and Retry Logic. If the player no longer has the funds the correction asks for, see Negative balances.

Correction success response (withdrawal shown; deposit is identical apart from type)


{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "100",
          "bonus": "0",
          "locked": "0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "100",
          "bonus": "0",
          "locked": "0"
        }
      }
    }
  },
  "alreadyProcessed": false,
  "currency": "USD",
  "platform": "sport",
  "id": "id",
  "type": "withdrawal",
  "initiatedAt": "2021-01-20T00:00:00Z",
  "createdAt": "2021-01-20T00:00:00Z",
  "context": {
    "product": "sportsbook",
    "betId": "4494226fa9c24b978b975823e353616b"
  },
  "amountBreakdown": {
    "cash": "10"
  }
}

The error envelope is the same as for bet placement — see Wallet Error Codes for the codes.

Withdrawal resettle

A withdrawal is used whenever the new payout is less than the previous one:

Previous result	New result
win	lose / return / techreturn / return025 / return075 / deadheat
return	lose / return025 / return075 / deadheat
deadheat	lose / return / techreturn / return025 / return075

Withdrawal resettle transaction


{
  "currency": "USD",
  "platform": "sport",
  "id": "id",
  "type": "withdrawal",
  "initiatedAt": "2021-01-20T00:00:00Z",
  "createdAt": "2021-01-20T00:00:00Z",
  "context": {
    "product": "sportsbook",
    "reason": "resettle",
    "betId": "4494226fa9c24b978b975823e353616b"
  },
  "amountBreakdown": {
    "cash": "10"
  }
}

Deposit resettle

A deposit is used whenever the new payout is greater than or equal to the previous one:

Previous result	New result
lose	win / return / return075 / return025 / deadheat
return	win / techreturn / deadheat
return025 / return075	techreturn / return
deadheat	win / return / return075 / return025

Deposit resettle transaction


{
  "currency": "USD",
  "platform": "sport",
  "id": "id",
  "type": "deposit",
  "initiatedAt": "2021-01-20T00:00:00Z",
  "createdAt": "2021-01-20T00:00:00Z",
  "context": {
    "product": "sportsbook",
    "reason": "resettle",
    "betId": "4494226fa9c24b978b975823e353616b"
  },
  "amountBreakdown": {
    "cash": "20"
  }
}

Cancel settle

Unlike resettlement, cancel settlement is always a withdrawal transaction, regardless of the previous settlement result: the whole previous payout is taken back and the bet returns to the unsettled state. A new settle transaction with the corrected result follows afterwards. If the previous result was lose, the previous payout was 0, so the withdrawal is still sent, but with a zero amount.

Previous settlement result: win / lose / return / techreturn / return025 / return075 / cashout / deadheat
New settlement result: unknown

Withdrawal cancel settle transaction


{
  "currency": "USD",
  "platform": "sport",
  "id": "id",
  "type": "withdrawal",
  "initiatedAt": "2021-01-20T00:00:00Z",
  "createdAt": "2021-01-20T00:00:00Z",
  "context": {
    "product": "sportsbook",
    "reason": "cancelsettle",
    "betAmount": 10,
    "betId": "4494226fa9c24b978b975823e353616b"
  },
  "amountBreakdown": {
    "cash": "10" // if the previous result is Lose - "cash": "0"
  }
}

Negative balances

A correction can ask your wallet to take back money the player no longer has: the settlement paid out, the player spent or withdrew the funds, and only afterwards did the result change. When the withdrawal arrives, the cash balance is already smaller than the amount to be returned.

This is the one place in the wallet flow where a player’s cash balance can end up below zero.

Which transactions can cause it

Transaction	Type	Reason	Where
Withdrawal resettle	`withdrawal`	`resettle`	Withdrawal resettle
Cancel settle	`withdrawal`	`cancelsettle`	Cancel settle
Partial resettle (negative)	`withdrawal`	`partial resettle`	Partial Cashout
Partial cancel settle	`withdrawal`	`partial cancelsettle`	Partial Cashout

A deposit correction never produces a negative balance. Neither does bet placement — an unaffordable bet is simply declined with decline.lowbalance.

Two ways to handle it

Both are accepted by GR8 Tech; the trade-off is yours to make.

Apply the correction in full. Answer 200 and let the cash balance go negative. The bet ends up in the same state on both sides, and the shortfall is carried as player debt in your wallet.

Decline it with decline.lowbalance. Answer 400. The correction fails, the bet stays in its previous state on the GR8 Tech side, and the transaction is not retried — a 400 is a final answer. Your system and GR8 Tech now disagree about the bet’s result, and the overpaid amount stays with the player until someone reconciles it manually.

Note

Keeping player balances at or above zero is preferable where your ledger and licence allow it. Nothing breaks on the GR8 Tech side if a balance does go negative — weigh that against the reconciliation cost of declining a correction.

Accepting a negative balance

Correction success response with a negative cash balance


{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "-15",
          "bonus": "0",
          "locked": "0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "-15",
          "bonus": "0",
          "locked": "0"
        }
      }
    }
  },
  "alreadyProcessed": false,
  "currency": "USD",
  "platform": "sport",
  "id": "8c1f0a6e-2d44-4b9a-9f77-0b3e51ad92c4",
  "type": "withdrawal",
  "initiatedAt": "2026-03-11T14:02:07Z",
  "createdAt": "2026-03-11T14:02:07Z",
  "context": {
    "product": "sportsbook",
    "reason": "cancelsettle",
    "betAmount": 10,
    "betId": "4494226fa9c24b978b975823e353616b"
  },
  "amountBreakdown": {
    "cash": "25"
  }
}

Balance values stay strings, as everywhere else in the structure — a negative one just carries a leading -.

Important

Only cash may go below zero. bonus, locked and retract must never hold a negative value — bonus funds are tracked per campaign, and a negative bonus balance breaks the wagering calculation. See Understanding Balance Types.

Warning

Never answer 5XX because the balance is insufficient. A 5XX or a timeout is treated as an unknown outcome and puts the correction into the settlement retry budget: 1000 attempts, one per minute. Use 200 to accept or 400 with decline.lowbalance to decline — both are definitive. See Rollback and Retry Logic.

While the balance is negative

Bet placement is your decision. The usual approach is to decline placement with decline.lowbalance until the balance is back at or above zero.
Recovery is entirely on your side. GR8 Tech has no transaction for settling a negative balance — it is cleared by your own wallet, typically on the player’s next deposit.

Requests Flow Overview - How the stages fit together
Settlement - The settle transaction being corrected
Transaction Types Reference - Complete type and reason mapping
Wallet Error Codes - Complete error code reference
Rollback and Retry Logic - Retry budget for settlement transactions