# Fizzy Bubbly Provider API OpenAPI file: https://provider.fizzybubbly.com/source.yaml ## Description This is version `1.0.0` of this API documentation. Last update on Sep 17, 2026. This document describes the process of integrating a game provider with the Fizzy Bubbly system. - **Wallet API**: API implemented by Fizzy Bubbly - **Games API**: API implemented by the provider - **Free spins API**: API implemented by the provider ## Terms and abbreviations | Term | Description | | :--- | ---: | | Fizzy Bubbly | Games operator | | Provider | Game provider | | Staging | Environment where integration is tested | | Private key| Secret key to generate HMAC_SHA256 hash | | Public key | Plain text API key | ## Outline of the integration flow 1. *Fizzy Bubbly* provides *provider* - Endpoint for Wallet API - Public key - Private key - Outgoing IP addresses for whitelisting - Testing environment details (site, test users) - Configuration details (max exposure, enabled currencies) 2. *Provider* implements Games API and provides *Fizzy Bubbly*: - Endpoint for Games API - Outgoing IP addresses for staging environment - Games list 3. *Fizzy Bubbly* and *provider* perform testing and sign-off in staging environment 4. Ready for production deployment ## Authentication Authentication is handled via public api key and request signing. Every request must contain two HTTP Headers: `Public-Key`: Public key provided by *Fizzy Bubbly* `Signature`: Signature computed using private key provided by *Fizzy Bubbly*. See *Request signing* for more details. ## Request signing Information to generate the request signature: - Request body - HTTP Method (POST) - HTTP URI - Private Key **Signature must be computed on the raw request body, before any serialization of the request.** Pseudo-code to generate the signature: ``` String md5 = MD5.generate(requestBody).toUpperCase(); String toSign = String.format("%s\n%s\n%s", httpMethod, httpUri, md5); String signature = HMAC_SHA256.generate(toSign, privateKey); ``` Test-case for generating signature: ``` Private key: XmsbLjUNrT4Ktj5YCBFdXvrR3EA6dMpB Method: POST Uri: https://api.casino.com/n2/wallet/balance Body: {"sessionId":"HyvN1Sd2Pm3LAAzd9HV5","playerId":"b2996ddb9a51","currency":"EUR"} MD5 of body: E3760D425889FB7F9DF770FEEFF2018C toSign: POST https://api.casino.com/n2/wallet/balance E3760D425889FB7F9DF770FEEFF2018C Expected signature: 1fa24ceaff03a97aff58c23d5a41b72a6c24c2abe20dcfb41a03c5e4c9bd939c ``` ## Request idempotency Wallet API **withdraw**, **deposit** and **rollback** requests are handled idempotently on the Fizzy Bunnly platform. All these requests have a field `transactionId`. Requests with same `transactionId` are processed only once and in case of retries the original response is returned. ## Session handling Validation of the active session is performed for all *withdraw* requests. *Deposit* and *rollback* requests are accepted without having an open session to ensure reconciliation. ## Retry The default expected behaviour for retries is following: - *withdraw*: Errors are not retried, rollback will be called. - *deposit*, *rollback*: Requests are first retried 3 times with 1500ms delay, after that requests are retried with 20 second intervals until successful response is returned. ## Error handling Errors are handled via HTTP status codes and custom error codes. All requests with HTTP status code 200 OK are expected to be handled successfully. All other HTTP status codes are expected to have body with following structure: ``` { "code": "{Error Code}", "message": "{Message to describe the error in more detail}", "traceId": "Internal id to track the request-response" } ``` | Error Code | Description | | :--- | ---: | | `ERROR_UNKNOWN_ERROR` | General error codes for errors without specific code | | `ERROR_BAD_REQUEST` | Request body is invalid | | `ERROR_BAD_REQUEST_PLAYER_BLOCKED` | Player is blocked | | `ERROR_INVALID_PUBLIC_KEY` | Request public key header is invalid | | `ERROR_INVALID_SIGNATURE` | Request signature is invalid | | `ERROR_INVALID_SESSION` | Invalid session id is provided | | `ERROR_SESSION_EXPIRED` | Session has expired | | `ERROR_TIMEOUT` | Handling the request took too long time | | `ERROR_TRANSACTION_DUPLICATE` | Duplicate transaction id was provided with new parameters (amount, currency, gameRoundId, playerId | | `ERROR_TRANSACTION_WITHDRAW_NOT_FOUND` | Withdraw transaction not found for deposit request | | `ERROR_TRANSACTION_INSUFFICIENT_FUNDS` | User wallet has insufficient fund for a withdraw request | | `ERROR_TRANSACTION_LIMIT_EXCEEDED` | Player has exceeded any kind of playing limit | | `ERROR_ROLLBACK_TRANSACTION_NOT_FOUND` | Withdraw transaction not found for rollback request. If such rollback was sent, further withdraw requests with the same transactionId (originalTransactionId in rollback request) are declined with ERROR_BAD_REQUEST error code. | ## Game client communication Game client API is an HTML wrapper that embeds a game client into iframe and acts as a middleware to facilitate in-browser communication between the game client and a casino web page to provide better game experience. Communication is handled via Window object. See [https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) for more details. ### Game client exposed messages All game client exposed messages have the following structure: ``` { "messageType": "{messageType}", "payload": {} } ``` | Message Type | Description | Payload | | :--- | --- | ---: | | n2.pr.balanceUpdated | In-game balance has changed. | `{ "balance": 100.00 }` | | n2.pr.roundStart | Game round started. | `{ "amount": 100.00 }` | | n2.pr.roundEnd | Game round has ended (animations finished). | `{ "amount": 100.00 }` | | n2.pr.loadEnd | Game client is fully loaded and playable. Must also be re-sent as the reply to every `n2.op.handshake`. | `{}` | | n2.pr.error.insufficientFunds | Player attempted to play with insufficient funds. | `{}` | ### Game client consumed messages All game client consumed messages have the following structure: ``` { "messageType": "{messageType}", "payload": {} } ``` | Message Type | Description | Payload | | :--- | --- | ---: | | n2.op.pingBalance | Notify game to fetch new balance from the wallet. | `{}` | | n2.op.stopAutoPlay | Stop game auto-play. | `{}` | | n2.op.handshake | Probe for game readiness: if already loaded, reply with `n2.pr.loadEnd`; ignore otherwise. | `{}` | | n2.op.pause | Pause all gameplay and sounds. | `{}` | | n2.op.resume | Resume normal play after `n2.op.pause`. | `{}` | ## Servers - BASE_URL: BASE_URL () ## Topics ## Endpoints ### [Free spins](https://provider.fizzybubbly.com/group/endpoint-free-spins.md) - [Get bet values](https://provider.fizzybubbly.com/operation/operation-betvalues.md) - [Cancel free spins campaign](https://provider.fizzybubbly.com/operation/operation-cancelcampaign.md) - [Create free spins campaign](https://provider.fizzybubbly.com/operation/operation-createcampaign.md) ### [Games](https://provider.fizzybubbly.com/group/endpoint-games.md) - [Get game round replay](https://provider.fizzybubbly.com/operation/operation-gameround.md) - [Generate a game launch URL](https://provider.fizzybubbly.com/operation/operation-gameurl.md) ### [Wallet](https://provider.fizzybubbly.com/group/endpoint-wallet.md) - [Fetch user balance](https://provider.fizzybubbly.com/operation/operation-walletbalance.md) - [Deposit](https://provider.fizzybubbly.com/operation/operation-walletdeposit.md) - [Rollback a withdraw request](https://provider.fizzybubbly.com/operation/operation-walletrollback.md) - [Withdraw](https://provider.fizzybubbly.com/operation/operation-walletwithdraw.md) [Powered by Bump.sh](https://bump.sh)