# Fizzy Bubbly Operator Transfer Wallet API ## Description This is version `1.0.0` of this API documentation. Last update on Jan 16, 2025. This document describes the process of integrating with the Fizzy Bubbly system. - **Transfer Wallet API**: API implemented by Fizzy Bubbly - **Games API**: API implemented by Fizzy Bubbly - **History API**: API implemented by Fizzy Bubbly. **NB: only gameplay transactions are returned in the response (transfer transactions are not returned)** - **Free spins API**: API implemented by Fizzy Bubbly - **Jackpot API**: API implemented by Fizzy Bubbly ## Terms and abbreviations | Term | Description | | :--- | ---: | | Fizzy Bubbly | Games provider | | Operator | Operator | | Brand | Operator site or sub-site | | 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 *operator* - Endpoint - Public key - Private key 2. *Operator* implements Wallet API and provides *Fizzy Bubbly*: - Testing environment details (site, test users) - Configuration details (max exposure, enabled currencies per brand) - Outgoing IP addresses 3. *Fizzy Bubbly* and *operator* 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 Request signing is used to ensure that the request is coming from the operator and that the request has not been tampered with. The signature is computed using the HMAC_SHA256 algorithm. Signature generation is required for all requests to the *Fizzy Bubbly* API and the signing algorithm is identical for all endpoints. Signature validation is required for all requests to the *Wallet* API. Information to generate the request signature: - Request body. This must be a raw HTTP request body bytes. - HTTP Method. The uppercase HTTP method of the request e.g. POST. - HTTP URI. The full URI of the request including scheme, host, port, path and query parameters if any e.g. https://api.casino.com/n2/wallet/balance. - Private Key. The secret API key provided by *Fizzy Bubbly*. **Signature must be computed on the raw HTTP request body bytes. This means that the request object should be serialized into bytes first and then the signature should be computed.** 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 Transfer Wallet API **withdraw** and **deposit** requests are idempotent. All these requests have a field `transactionId`. Requests with same `transactionId` will be processed only once and in case of retries the original response is expected. ## Free Spins Campaigns Free spins campaigns are managed via separate API. See *Free spins API* for more details. ## 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_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_INSUFFICIENT_FUNDS` | User wallet has insufficient fund for a withdraw request | | `ERROR_GAME_NOT_ACTIVE` | Problem with finding an active game. Message will contain an exact reason, why the game could not be fetched | ## 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. Support of client communication events can be different based on the game provider. Please confirm with us before using the supported events. Game client communication is an optional feature and will be enabled only when requested. ### 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 }` | ### 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. | `{}` | ## Servers - BASE_URL: BASE_URL () ## Endpoints and operations ### [Transfer Wallet](https://transfer.fizzybubbly.com/group/endpoint-transfer-wallet.md) - [Create wallet](https://transfer.fizzybubbly.com/operation/operation-createwallet.md) - [Fetch wallet balance](https://transfer.fizzybubbly.com/operation/operation-fetchwalletbalance.md) - [Transfer from/to wallet](https://transfer.fizzybubbly.com/operation/operation-wallettransfer.md) ### [Games](https://transfer.fizzybubbly.com/group/endpoint-games.md) - [Game list](https://transfer.fizzybubbly.com/operation/operation-gamelist.md) - [Get game round replay](https://transfer.fizzybubbly.com/operation/operation-gameround.md) - [Generate a game launch URL](https://transfer.fizzybubbly.com/operation/operation-gameurl.md) ### [Free spins](https://transfer.fizzybubbly.com/group/endpoint-free-spins.md) - [Get available bet values for game](https://transfer.fizzybubbly.com/operation/operation-betvalues.md) - [Cancel a free spins campaign](https://transfer.fizzybubbly.com/operation/operation-freespinscancel.md) - [Create a free spins campaign](https://transfer.fizzybubbly.com/operation/operation-freespinscreate.md) - [Get details of a campaign](https://transfer.fizzybubbly.com/operation/operation-getfreespinscampaign.md) - [Get details of a player campaign state](https://transfer.fizzybubbly.com/operation/operation-getfreespinscampaignplayerstate.md) ### [History](https://transfer.fizzybubbly.com/group/endpoint-history.md) - [Fetch transactions](https://transfer.fizzybubbly.com/operation/operation-getwallettransactions.md) - [Fetch transaction](https://transfer.fizzybubbly.com/operation/operation-getwallettransaction.md) ### [Jackpots](https://transfer.fizzybubbly.com/group/endpoint-jackpots.md) - [Get active jackpots](https://transfer.fizzybubbly.com/operation/operation-getjackpots.md) [Powered by Bump.sh](https://bump.sh)