Wallet callbacks

Bet

KOI calls your register endpoint to debit a stake before revealing the result.

http

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

Payload

Field	Type	Description
`action`	string	Always `bet`.
`provider_tx_id`	number	KOI transaction ID. Unique per bet. Use it as your idempotency key.
`user_id`	string	Your player ID from `request-access`.
`amount`	number	Stake to debit.
`currency`	string	Session currency.
`game`	string	Game slug.
`round_id`	string	KOI round ID. Shared by all bets of the same collective round.
`session_token`	string	KOI session token.
`mode`	string	`common` (manual) or `auto` (auto-bet). Free-bet rounds are never debited, so they send no bet.
`extra_data`	string \| null	The `extra_data` you sent in `request-access`.
`count_register`	number	Count of bets this player has registered in the game, kept by KOI. Informational.
`provider`	string	Always `koi`.
`aggregator`	string	Your KOI account ID. Lets aggregators route callbacks.

json

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

What to do

Verify X-Koi-Signature.
If you already processed this provider_tx_id, return the original result without debiting again.
Check the player, the session and the balance.
Debit amount and answer 200:

json

{ "old_balance": 100.0, "new_balance": 95.0, "operator_tx_id": "op-tx-9001" }

To refuse, answer non-2xx with a DENIED code. See Refusing a transaction.

KOI waits 10 seconds for a bet answer. On timeout or GENERAL_ERROR, KOI retries once with the same payload. If the outcome is still unknown, KOI sends a rollback for this bet. Details in Idempotency & retries.

Bet

Payload

What to do

Timeout