Seamless Wallet/win

Win (credit)

Callback · Provider → Operator

POST{callback_url}/win

When a round produces a win, Boss Hub calls this endpoint so you can credit the amount to the player’s balance. A win is final: if no reply arrives, the round is not cancelled and the request is retried on a schedule.

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

Body parameters

transaction_idstringrequired

Unique transaction ID, the idempotency key. It looks like tx_<round>-w1 for a game win and -j1 for a jackpot payment; do not parse it.

round_idstringrequired

Game round. Links the bet/win transactions of the same round.

session_idstringrequired

The game session opened by launch.

player_idstringrequired

The player ID on the operator side.

game_idstringrequired

Game code, e.g. sultans-ember.

amountdecimal(18,2)required

Amount to credit, in the session currency; a JSON number with two decimals. 0 for a round with no win. A free round win may already be capped by the campaign’s win limit: credit what is sent.

currencyISO 4217required

USD (default), EUR, TRY.

site_idstring

Site code, e.g. site_mrd01. Tells apart sites that share one callback address.

round_closedboolean

If true, the round closes with this win. The value when the call was created; it does not change on retries.

created_atdate-time

When the transaction was created (UTC).

is_freeroundboolean

If true, this is a free round win; credit it as usual. campaign_id is set.

campaign_idstring | null

The free round campaign.

freeround_grant_idstring

Free round wins only: the ID of the player’s grant in the campaign.

jackpotobject | null

Set on a jackpot payment (a Boss Hub pool or the provider’s jackpot): pool_id and level. If no Boss Hub pool matches, pool_id is the provider’s link code. A jackpot payment is a separate win (-j1); a Boss Hub pool drop has round_closed false, a provider jackpot win may carry true.

promoobject | null

Set when this is a promotional credit: type (tournament), id (tournament ID) and rank. null for a game win.

Idempotency: When a request arrives again with the same transaction_id, do not credit the balance again; return the first response as is, not the current balance. This applies to processed results only: if an ID you rejected comes back, evaluate it afresh.

Token expiry: Accept the win even if the player’s token or session has expired; do not answer INVALID_TOKEN. Otherwise the player never receives the money they won.

POST /bossgaming/win HTTP/1.1
Content-Type: application/json
X-Operator-Id: op_meridyen
X-Timestamp: 1762344004
X-Signature: 41c9de…7a30
X-Request-Id: req_01HF3KA7
X-Api-Key: pk_test_…

{
  "transaction_id": "tx_01HF3K9QZ2-w1",
  "round_id": "rnd_01HF3K9QZ2",
  "session_id": "ses_01HF3K7M",
  "site_id": "site_mrd01",
  "player_id": "u_88213",
  "game_id": "sultans-ember",
  "amount": 5.00,
  "currency": "USD",
  "is_freeround": false,
  "campaign_id": null,
  "jackpot": null,
  "promo": null,
  "round_closed": true,
  "created_at": "2026-11-05T14:22:09.480Z"
}

200Successful response

{
  "status": "OK",
  "balance": 153.60,
  "currency": "USD",
  "operator_tx_id": "op_tx_9921845"
}

200A rollback arrived first for this transaction

{
  "status": "ERROR",
  "code": "TRANSACTION_ROLLED_BACK",
  "balance": 150.60
}

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.

Retry schedule

Attempt	Time	Note
1	T0	First call
2	T0 + 30 s
3	T0 + 2 min
4	T0 + 10 min	If this also fails, the round becomes stuck, a reconciliation item opens and round.stuck is sent; retries continue
5	T0 + 30 min	Last attempt. After that, manual resolution in the portal or through the API

The body and X-Request-Id are the same on every attempt; only X-Timestamp and X-Signature change. An OK within the schedule closes the stuck item on its own.

Zero win

If none of the round’s wins carried round_closed: true, Boss Hub sends a win with amount: 0 and round_closed: true when the round closes. This is a best-effort notice: the balance does not change, so answer OK. Your reply does not affect the round or the invoice: a rejection is not retried, and an uncertain reply is retried on the schedule and then dropped without opening an item.

Promotional credits such as tournament prizes also arrive on this endpoint. A promotional credit comes in a round with no bet: promo is set, round_closed: true, is_freeround: false, jackpot: null. Credit the amount to the player’s balance like a win. One transaction_id is sent per prize; idempotency, the retry schedule and stuck round rules are the same. Promotional credit is not part of GGR or the invoice; daily reconciliation counts it under wins.

Manual payment

To pay a stuck win by hand, first press Resolve in the portal. Once the lock opens, post the amount to your own ledger with the same `transaction_id`, then choose operator paid. If you use another ID, a late win pays out a second time.

Error codes

Code	Meaning	Boss Hub behaviour
PLAYER_BLOCKED	Player restricted / self-exclusion	No retry, the round becomes stuck (win_rejected). Can be resent with the same ID once the block is lifted
LIMIT_EXCEEDED	Responsible gaming limit exceeded	No retry, the round becomes stuck (win_rejected)
INVALID_TOKEN	Contract violation: a win is not rejected over a token	No retry, the round becomes stuck (win_rejected)
INSUFFICIENT_FUNDS	Outside the contract: a win is not rejected over the balance	No retry, the round becomes stuck (win_rejected)
TRANSACTION_ROLLED_BACK	You hold a cancellation record for this transaction	Treated as rejected, the round becomes stuck (win_rejected), a warning is raised
DUPLICATE_TRANSACTION	Same transaction with different content	The schedule stops, goes to manual review (duplicate_conflict)
INVALID_SIGNATURE	Signature could not be verified	Treated as uncertain: the schedule continues, an alarm is raised. Rotating a secret does not lose wins
INTERNAL_ERROR	Operator error	Treated as uncertain: the schedule continues

If an earlier attempt stayed uncertain, your rejection also counts as uncertain and the schedule continues. How every reply is classified: Error codes.

← Previousbet Next →rollback