Wallet callbacks

Bonus win

When a free-bet bonus ends, KOI calls your rewards endpoint once with the total win of its rounds. This is the only callback a bonus produces: its rounds never send bet or win callbacks.

http

POST <your rewards URL>
Content-Type: application/json
X-Koi-Signature: <signature>

The endpoint is the same as for Win. Tell them apart by action.

Payload

Field	Type	Description
`action`	string	Always `bonus_win`.
`provider_tx_id`	number	KOI transaction ID of this payment. One per bonus. Use it as your idempotency key.
`bonus_code`	string \| null	The `bonus_code` of the grant. `null` only for bonuses created by KOI promotions.
`user_id`	string	Your player ID.
`amount`	number	Total win of the bonus rounds, stake included. Can be `0`.
`currency`	string	Currency of the rounds.
`game`	string	Game slug.
`round_id`	string	`round_id` of the last round played.
`rounds_played`	number	Rounds played in this bonus.
`rounds_remaining`	number	Rounds left unplayed when the bonus ended (expired or cancelled). `0` when all were played.
`mode`	string	Always `free`.
`session_token`	string	KOI session token of the last round. The session may have expired.
`extra_data`	string \| null	The `extra_data` from `request-access`.
`provider`	string	Always `koi`.
`aggregator`	string	Your KOI account ID.

There is no linked_tx_id: a bonus win does not pay any bet you processed.

json

{
  "action": "bonus_win",
  "provider_tx_id": 208114,
  "bonus_code": "WELCOME-10",
  "user_id": "player-123",
  "amount": 12.5,
  "currency": "BRL",
  "game": "aviator-wars",
  "round_id": "0b6f1e7a-3c55-4f0e-9d0c-6a3f2b1c9e44",
  "rounds_played": 10,
  "rounds_remaining": 0,
  "mode": "free",
  "session_token": "b3e1f6d2c9a84f0e",
  "extra_data": "brand=acme;device=mobile",
  "provider": "koi",
  "aggregator": "7"
}

What to do

Verify X-Koi-Signature.
If you already processed this provider_tx_id, return the original result.
Credit amount, even if amount is 0 and even if the session has expired. Apply your own bonus rules (for example wagering requirements) to the credited amount.
Answer 200 with old_balance, new_balance and operator_tx_id.

KOI waits up to 80 seconds and retries exactly like a Win: once immediately on a technical failure, then through reconciliation with the same body and signature. If it still cannot be delivered, the payment stays pending and KOI support follows up with you. See Idempotency & retries.

Bonus win

Payload

What to do

Timeout and retries