Wallet callbacks

How the wallet works

KOI never holds player funds. Every stake and every payout moves through your wallet, in real time, by signed HTTPS callbacks.

Callbacks

Callback	Endpoint type	`action`	Purpose
Bet	`register`	`bet`	Debit the stake before the result is revealed.
Win	`rewards`	`win`	Credit a payout, or close a losing bet with `amount: 0`.
Bonus win	`rewards`	`bonus_win`	Credit the total win of a free-bet bonus, once, when it ends.
Rollback	`rollback`	`rollback`	Revert a previously debited bet.
Balance	`balance`	—	Read the player's current balance.

Every debited bet is settled by a win or reverted by a rollback. A loss is a win with amount: 0. Free-bet rounds send no bet or win; see Free bets.

Lifecycle of a round

The player places a bet in the game.
KOI sends Bet to your register endpoint.
You debit the stake and answer with the new balance. If you refuse, the bet is cancelled and the player sees an error.
KOI produces the result.
KOI sends Win to your rewards endpoint with the payout, or with amount: 0 if the bet lost. You credit the amount.

In crash games the win is sent when the player cashes out; bets still open when the round crashes get amount: 0. In slots it is sent immediately after the spin.

Request format

Every callback is an HTTPS POST with a JSON body and these headers:

http

Content-Type: application/json
X-Koi-Signature: <hex HMAC SHA-256>

Always verify X-Koi-Signature before touching the wallet. See Signature verification.

Successful response

Answer bet, win, bonus win and rollback callbacks with HTTP 200 and:

Field	Type	Description
`old_balance`	number	Player balance before this transaction.
`new_balance`	number	Player balance after this transaction.
`operator_tx_id`	string	Your transaction ID. KOI stores it for reconciliation.

json

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

Refusing a transaction

To refuse, answer with a non-2xx status (for example 400 or 402) and:

json

{ "status": "DENIED", "code": "INSUFFICIENT_FUNDS" }

`status`	`code`	Meaning	KOI behaviour
`DENIED`	`INSUFFICIENT_FUNDS`	Not enough balance.	Bet cancelled, no retry.
`DENIED`	`BET_DENIED`	Bet refused by your rules (limits, self-exclusion…).	Bet cancelled, no retry.
`DENIED`	`SESSION_EXPIRED`	Session no longer valid on your side.	Bet cancelled, no retry.
`DENIED`	`GAME_NOT_ALLOWED`	Player may not play this game.	Bet cancelled, no retry.
`ERROR`	`GENERAL_ERROR`	Temporary failure.	Retried. See Idempotency & retries.
`ERROR`	`INVALID_REQUEST`	Temporary failure.	Retried on wins and rollbacks. On bets: treated as a refusal.

A bet answered with any other non-2xx status, or without one of these bodies, is treated as refused.

Amounts and currency

Amounts are decimal numbers in major currency units with at most two decimals: 5.0 is five reais.
currency is the value you sent in request-access, unchanged.
Return balances as numbers. Negative or non-numeric balances are stored as 0.