Wallet callbacks

Rollback

KOI calls your rollback endpoint to return a stake it previously sent to register.

When KOI sends a rollback

The player cancels a pending bet before a collective round starts.
A bet callback failed and its outcome is unknown after the retry.
A round is cancelled by the platform before it settles.
A win could not be delivered after repeated reconciliation attempts; KOI returns the stake instead.

Payload

Field	Type	Description
`action`	string	Always `rollback`.
`provider_tx_id`	number	KOI transaction ID of this rollback.
`linked_tx_id`	number	`provider_tx_id` of the bet to revert.
`user_id`	string	Your player ID.
`amount`	number	Stake to return. Equal to the original bet amount.
`currency`	string	Session currency.
`game`	string	Game slug.
`round_id`	string	Round of the original bet.
`session_token`	string	KOI session token.
`extra_data`	string \| null	The `extra_data` from `request-access`.
`provider`	string	Always `koi`.
`aggregator`	string	Your KOI account ID.

json

{
  "session_token": "b3e1f6d2c9a84f0e",
  "provider_tx_id": 104240,
  "linked_tx_id": 104233,
  "user_id": "player-123",
  "round_id": "r-7f3a2c",
  "game": "amazonia-adventure",
  "action": "rollback",
  "extra_data": "brand=acme;device=mobile",
  "currency": "BRL",
  "provider": "koi",
  "amount": 5.0,
  "aggregator": "7"
}

What to do

Verify X-Koi-Signature.
Find the bet by linked_tx_id.
If the bet was never debited, record the rollback and answer 200 without moving funds.
If the bet was already rolled back, answer 200 with the current balance. Rollbacks must be idempotent on linked_tx_id.
Otherwise return amount to the player and answer 200.

Timeout

KOI waits up to 80 seconds. A failed rollback goes to reconciliation and is resent with the same schedule as wins. See Idempotency & retries.