Appearance
(Operator implements) Get a player's balance
GET
/getBalance
Called by hizi.io to read a player's balance. One or two balances may be returned; one of them has to be real, a bonus balance is optional and only required by some jurisdictions. When a bonus balance is returned, useBonusFirst should be returned as well so the game can display which funds are being used where regulation requires it.
If gameCode is supplied, return the free plays / tickets allocated to that player and game as well (see Appendix D).
On error, do not answer with HTTP 200 — return a 4xx/5xx together with an errorCode object.
Fields to sign (in order): secret, X-H-AUTH-ID, X-H-TIMESTAMP, playerId, currency, gameCode (if present).
Authorizations
hiziAuthId
Operator ID. Sent on every request in both directions, and part of every signature.
Type
API Key (header: X-H-AUTH-ID)
hiziAuthSignature
Signature of the request, sent on every request in both directions.
OpenAPI cannot express an HMAC-over-computed-string scheme natively, so this is modelled as an apiKey header. The value is not a static key: it is the base64-encoded SHA-256 HMAC digest of a defined, ordered set of request fields joined with a hash character (#).
The first three fields are always the shared secret, the X-H-AUTH-ID header and the X-H-TIMESTAMP header; the remaining fields differ per operation and are listed in each operation's description under "Fields to sign". For doTransactions the per- transaction hashes (and non-zero amounts) are appended in exactly the order the transactions appear in the payload.
The secret is retrieved by logging in to the hizi.io backoffice, which also provides sample implementations. Including the timestamp in the signature is what makes it safe to share the secret without ever sending it.
Type
API Key (header: X-H-AUTH-SIG)
hiziTimestamp
ISO 8601 timestamp of the request (UTC recommended, e.g. 2020-01-21T14:48:04Z). Sent on every request in both directions and always included in the signature.
Type
API Key (header: X-H-TIMESTAMP)
Parameters
Query Parameters
playerId*
ID that identifies the player at the operator site.
Type
Requiredstring
currency*
ISO 4217 currency code the call applies to.
Required
gameCode
ID of the game (same code as in getGameURL). If present, return free plays and/or tickets allocated to that game and player.
Type
string
externalSessionId
Reference to the session ID passed in the getGameURL call.
Type
string
Responses
The player's balance(s).
application/json
JSON "balances": [ { "type": "string", "amount": 1200, "currency": "EUR" } ], "discountInfo": { "text": "happy hour", "currency": "EUR", "discounts": [ { "stake": 1200, "absoluteDiscountAmount": 1200, "spinsRemaining": 0 } ], "campaignId": "string", "validFrom": "2020-01-21T14:48:04Z", "validTo": "2020-01-21T14:48:04Z" }, "useBonusFirst": true, "errorCode": { "id": 1, "msg": "player id unknown", "clientmsg": "You reached your daily betting limit!" }, "clientMessage": { "title": "string", "msg": "string", "buttons": [ { "label": "string", "url": "string" } ], "stopAutoPlay": true }
{
}