Wallet callbacks
Idempotency & retries
Networks fail. KOI resends callbacks until it knows their outcome, so your wallet will receive the same transaction more than once. Design for it.
Idempotency rules
| Callback | Idempotency key | On a repeat |
|---|---|---|
| Bet | provider_tx_id | Return the original result. Never debit twice. |
| Win | provider_tx_id | Return the original result. Never credit twice. |
| Bonus win | provider_tx_id | Return the original result. Never credit twice. |
| Rollback | linked_tx_id | Return the current balance. Never refund twice. |
A repeated callback has exactly the same body as the original, so its signature is identical too.
Timeouts
| Callback | KOI waits |
|---|---|
| Bet | 10 seconds |
| Win | 80 seconds |
| Bonus win | 80 seconds |
| Rollback | 80 seconds |
| Balance check before a bet | 3 seconds |
| Player balance request | 80 seconds |
Answer well within these limits. A slow answer is treated the same as a failure.
What KOI retries
KOI retries only technical failures: a timeout, a dropped connection, or an answer with status: "ERROR". A DENIED answer is final and is never retried.
Bets
| Your answer | KOI behaviour |
|---|---|
2xx | Bet accepted. |
DENIED with any code | Bet refused. No retry, no rollback. |
Timeout, or ERROR / GENERAL_ERROR | Same bet resent once after 100 ms. If that also fails, KOI sends a rollback. |
| Connection reset | KOI sends a rollback without resending. |
| Any other non-2xx | Bet refused. No retry, no rollback. |
The rollback carries linked_tx_id equal to the bet's provider_tx_id. If you never processed the bet, accept the rollback without moving funds.
Bets for the same player are sent one at a time, in order.
Wins
- KOI sends the win, and resends it once after 500 ms on a technical failure.
- If it still fails, the win becomes pending and enters reconciliation.
- Reconciliation resends it on a growing schedule: about 5 minutes, 30 minutes and 2 hours after the previous attempt, for up to 24 hours from the round.
- If the win still cannot be delivered, KOI sends a rollback that returns the original stake to the player, and closes the transaction.
Wins can therefore arrive long after the session ended. Always credit them.
Bonus wins
A bonus win follows the same steps 1 to 3 as a win. It is never rolled back: if it still cannot be delivered, it stays pending and KOI support follows up with you.
Rollbacks
Rollbacks that fail enter the same reconciliation schedule as wins.
Reconciliation
KOI keeps every transaction with its status (pending, success, canceled) and your operator_tx_id. When your records disagree with KOI's, send your account manager the provider_tx_id values involved; KOI support compares both ledgers.