Features

Round cancel and refunds

A paid round starts with a bet callback to your wallet. This page describes when the platform cancels a round, when it sends a refund callback, and how you cancel an unfinished round yourself.

When a round is cancelled#

Situation	What happens
Your wallet answers a `bet` with `INSUFFICIENT_FUNDS`	The round is rejected at once. Nothing was debited, nothing is played, no `refund` is sent.
Your wallet answers a `bet` with an HTTP 4xx status other than 408 and 429	A definitive refusal. The round is cancelled at once and a `refund` for the bet is queued, because the platform cannot know whether your system booked the debit.
The `bet` is still not confirmed after the cancel policy: 10 minutes by default (or 600 attempts)	The round is cancelled and a `refund` is queued.
You call `round_cancel`	The round is cancelled and a `refund` is queued.

Everything else is retried with the same transaction id and body: HTTP 5xx, 408, 429, timeouts, network errors and answers that are not valid. A bet is retried immediately for the first 4 attempts, then after 1 s, doubling up to 60 s. Retries of the callback itself are described in Wallet callbacks.

When a round is cancelled:

The bet is closed and never sent again.
A refund operation is created for the same amount, with meta.original_transaction equal to the bet's meta.transaction.
The refund is delivered until you answer ok (delays of 2 s, doubling, at most 5 minutes).

For the player the round ends as rejected: nothing is played, no result is revealed, a reload shows the same, and a new round can be started. The policy values are configured by the platform; ask your account manager if you need other values.

Your wallet's side#

Implement refund as described in Wallet callbacks. The two cases that matter:

the bet was debited (your answer was lost or was a 4xx after booking): credit it back once;
the bet was never received: record the transaction id as cancelled, answer ok, and refuse the bet if it arrives later (TRANSACTION_CANCELLED).

`round_cancel`#

POST/gameActions.domethodround_cancel

Cancels an unfinished round and refunds its debit. Repeating the call is safe.

Request#

curl

curl -s -X POST https://notell-api.com/gameActions.do \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cancel-b2a74c1e' \
  -d '{
    "method": "round_cancel",
    "partner": "demo-casino",
    "api_key": "YOUR_API_KEY",
    "round_id": "b2a74c1e-5d90-4f3a-8c21-0e9b7a6d4f12"
  }'

JSON

{
  "method": "round_cancel",
  "partner": "demo-casino",
  "api_key": "YOUR_API_KEY",
  "round_id": "b2a74c1e-5d90-4f3a-8c21-0e9b7a6d4f12"
}

Field	Type	Required	Description
`method`	string	yes	`"round_cancel"`.
`partner`, `api_key`	string	yes	Your project id and API key.
`round_id`	string	yes	`meta.round_id` of the round's wallet callbacks, or `round_id` from `report_rounds`. No other fields are accepted.

A round can be cancelled when

its bet is not confirmed yet, or
its bet is confirmed but the result has not been shown to the player and no win is being credited (for example a bonus round the player has not opened).

The optional Idempotency-Key header is supported (Conventions).

Response#

json

{
  "status": "ok",
  "round": {
    "round_id": "b2a74c1e-5d90-4f3a-8c21-0e9b7a6d4f12",
    "state": "cancelled",
    "result": "cancelled",
    "reason": "operator_cancel",
    "source": "operator",
    "refund": {
      "transaction": "c41e7a90-3b2d-4f68-8e15-9d0a6c2b7f34",
      "amount": "1.50",
      "status": "pending"
    }
  }
}

Field	Type	Description
`round.round_id`	string	The round.
`round.state`	string	`"cancelled"`.
`round.result`	enum	`cancelled` now, `already_cancelled` for a repeat.
`round.reason`	string	`operator_cancel` for this method, `wallet_unconfirmed` when the platform cancelled it.
`round.source`	string	`operator` or `worker`.
`round.refund.transaction`	string	Transaction id of the `refund` callback (`meta.transaction`).
`round.refund.amount`	money	Refunded amount; equals the bet.
`round.refund.status`	enum	`pending` until your wallet confirms the refund, then `confirmed`. Check it with `report_rounds`.

Errors#

Code	HTTP	When
`INVALID_REQUEST`	400	`round_id` is missing or not a string, or another field was sent.
`ROUND_NOT_FOUND`	404	The id is not a round of your project (including an id that is not a UUID).
`ROUND_NOT_CANCELLABLE`	409	A finished round, a win being credited, a result already shown, a rejected bet, or a free-spin round (nothing was debited).
`ROUND_BUSY`	409	A wallet call of the round is in flight. Retry in a few seconds.
`ROUND_CANCEL_UNAVAILABLE`	400	Round cancel is not available on this server.

Money rules#

One bet is refunded at most once; the refund amount always equals the bet.
Bet, win and refund are each sent with a unique transaction id and repeated unchanged: your wallet answers a repeat from its record.
report_ggr counts bets − refunds − wins.

Round cancel and refunds

When a round is cancelled#

Your wallet's side#

round_cancel#

Request#

Response#

Errors#

Money rules#

See also#

`round_cancel`#