Wallet callbacks

Win

KOI calls your rewards endpoint once for every settled bet. A paying round sends the payout; a losing round sends a win with amount: 0, which credits nothing and closes the bet. Answer both the same way. Free-bet rounds never send a win: their total is paid once by a bonus win.

Payload

Field	Type	Description
`action`	string	Always `win`.
`provider_tx_id`	number	KOI transaction ID of this win. Use it as your idempotency key.
`linked_tx_id`	number	`provider_tx_id` of the bet being paid.
`user_id`	string	Your player ID.
`amount`	number	Amount to credit, stake included. `0` when the bet lost.
`currency`	string	Session currency.
`game`	string	Game slug.
`round_id`	string	Same `round_id` as the bet.
`session_token`	string	KOI session token.
`mode`	string	Mode of the original bet: `common` or `auto`.
`extra_data`	string \| null	The `extra_data` from `request-access`.
`provider`	string	Always `koi`.
`aggregator`	string	Your KOI account ID.

json

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

What to do

Verify X-Koi-Signature.
If you already processed this provider_tx_id, return the original result.
Credit amount, even if the session has expired. A win always belongs to the player.
Answer 200 with old_balance, new_balance and operator_tx_id.

Timeout

KOI waits up to 80 seconds. On timeout, GENERAL_ERROR or INVALID_REQUEST, KOI retries once and then hands the win to reconciliation, which resends it for up to 24 hours. See Idempotency & retries.