Seamless Wallet/balance

Balance inquiry

Callback · Provider → Operator

POST{callback_url}/balance

When the game asks for the player’s current balance, Boss Hub calls this endpoint. The call only reads: the balance does not change and no transaction is recorded.

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 the request. This call is not retried
X-Api-Key	The API key whose secret signed the callback. Selects the right secret when you have several keys

Body parameters

player_idstringrequired

The player ID on the operator side.

currencyISO 4217required

Session currency: USD, EUR, TRY.

session_idstring

The game session opened by launch.

site_idstring

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

Reply: balance and currency are required; currency must be the currency of the request. Answer ERROR for a player you do not know (e.g. INVALID_TOKEN). This call does not need operator_tx_id.

Single attempt: This call is not retried. On any reply other than OK, on a timeout, or on a reply other than HTTP 200, no balance reaches the game; the error code is not passed on to the game.

POST /bossgaming/balance HTTP/1.1
Content-Type: application/json
X-Operator-Id: op_meridyen
X-Timestamp: 1762344000
X-Signature: 7be014…c5d8
X-Request-Id: req_01HF3K8P
X-Api-Key: pk_test_…

{
  "player_id": "u_88213",
  "currency": "USD",
  "session_id": "ses_01HF3K7M",
  "site_id": "site_mrd01"
}

200Successful response

{
  "status": "OK",
  "balance": 150.60,
  "currency": "USD"
}

200Error (HTTP 200 + code)

{
  "status": "ERROR",
  "code": "INVALID_SIGNATURE"
}

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.

Error codes

Code	Meaning	Boss Hub behaviour
INVALID_SIGNATURE	Signature could not be verified	The balance does not reach the game; shown as an error on the Wallet health screen of the portal
INVALID_TOKEN	Session invalid or expired, or unknown player	The balance does not reach the game
PLAYER_BLOCKED	Player restricted / self-exclusion	The balance does not reach the game
INTERNAL_ERROR	Operator error	The balance does not reach the game; shown as an error on the Wallet health screen

The signature scenarios of the test suite (SIG-01…04) and REQ-02 call this endpoint. See Test suite.

← Previousauthenticate Next →bet