Seamless Wallet/bet
Bet (debit)
Callback · Provider → OperatorPOST{callback_url}/bet
When a player starts a round, Boss Hub calls this endpoint so you can debit the bet from the player’s balance. Without a clean reply (timeout, 5xx, INTERNAL_ERROR) the request is retried at once: by default each attempt waits 3 s and there are 2 retries, all within at most 20 s. If there is still no result, the bet is cancelled and a rollback is sent.
Headers
| Header | Description |
|---|---|
| Content-Type | application/json |
| X-Operator-Id | Your operator ID |
| X-Timestamp | Unix seconds. Reject it outside ±30 s |
| X-Signature | hex(HMAC_SHA256(secret, ts + "." + "POST" + "." + path + "." + body)). path is the full path of your callback address, base path included, e.g. /bossgaming/bet. See Signing |
| X-Request-Id | The ID of this call. Stays the same across retries |
| X-Api-Key | The API key whose secret signed the callback. Selects the right secret when you have several keys |
Idempotency: Lock the player record, then look up transaction_id. If the ID comes again with the same body, do not debit again; return the first reply as is. If it comes with a different body, answer DUPLICATE_TRANSACTION. If a rollback for the ID arrived first, answer TRANSACTION_ROLLED_BACK and debit nothing. If an ID you rejected comes back, evaluate it afresh.
Currency: A player’s currency is fixed at their first launch; Boss Hub never sends a bet in another currency than the session’s. Still, if currency does not match your wallet, debit nothing and answer ERROR (test suite BET-03).
200Successful response
{
"status": "OK",
"balance": 148.60,
"currency": "USD",
"operator_tx_id": "op_tx_9921844"
}200Business rule error (HTTP 200 + code)
{
"status": "ERROR",
"code": "INSUFFICIENT_FUNDS",
"balance": 0.40
}Reply rules
- Answer every call with HTTP 200; a business rule error also goes out with HTTP 200, status: ERROR and a code. Any other HTTP status (3xx, 4xx, 5xx, a WAF page) counts as uncertain. The only exception is 409 TRANSACTION_NOT_FOUND on a rollback.
- In a status: OK reply, currency is required and must equal the currency of the request. If it is missing or different, the reply counts as uncertain and an alarm is raised.
- balance: the balance after the transaction; a JSON number or a number string, at most two decimals, no exponent (1e3). Required on balance; send it on the other calls too.
- Return your own transaction ID in operator_tx_id. If you put transaction_id in the reply, it must equal the one in the request.
- A body that cannot be parsed, an unknown status, or an error without a code counts as uncertain and raises an alarm. Ignore request fields you do not recognise.
- Amounts are JSON numbers with two decimals (2.00), not strings. Read the body without loss; do not use float.
Retries and automatic cancellation
- You choose the timeout and the number of retries on the Endpoints & wallet card of the portal: 3 s (default) or 5 s; 2 (default) or 3 retries. Retries go out without waiting; the body and X-Request-Id stay the same.
- The total time budget of a bet is at most 20 s (or the provider’s budget if shorter). Once it is used up, the remaining attempts are skipped.
- For a bet that ends uncertain, the rollback is sent after the last attempt’s timeout has passed. No rollback goes out for a bet that was never sent.
- INVALID_SIGNATURE and DUPLICATE_TRANSACTION are not retried: the bet stays uncertain, and the automatic rollback goes out once that attempt’s timeout window has passed.
- If an earlier attempt stayed uncertain, a later rejection (INSUFFICIENT_FUNDS etc.) also counts as uncertain: retries stop and a rollback is sent.
Error codes
| Code | Meaning | Boss Hub behaviour |
|---|---|---|
| INSUFFICIENT_FUNDS | Insufficient balance | Clean rejection: the round does not start, the code goes to the game, no rollback |
| LIMIT_EXCEEDED | Responsible gaming limit exceeded | Clean rejection: the round does not start, the code goes to the game |
| PLAYER_BLOCKED | Player restricted / self-exclusion | Clean rejection: the round does not start, the code goes to the game |
| INVALID_TOKEN | Session invalid or expired | Clean rejection: the round does not start, the code goes to the game |
| TRANSACTION_ROLLED_BACK | You hold a cancellation record for this ID | Treated as rejected, no rollback is sent, a warning is raised |
| DUPLICATE_TRANSACTION | Same ID with different content | No retry; an automatic rollback is sent and the item goes to manual review (duplicate_conflict) |
| INVALID_SIGNATURE | Signature could not be verified | No retry; automatic rollback, an alarm and a security event |
| INTERNAL_ERROR | Operator error | Uncertain: retried; without a result, automatic rollback |
How every reply is classified: Error codes.