# Fizzy Bubbly Provider API

## Description
This is version `1.0.0` of this API documentation. Last update on Jul 17, 2025.
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 }` |

### 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
- [Free spins](https://provider.fizzybubbly.com/group/endpoint-free-spins.md)
- [Games](https://provider.fizzybubbly.com/group/endpoint-games.md)
- [Wallet](https://provider.fizzybubbly.com/group/endpoint-wallet.md)


[Powered by Bump.sh](https://bump.sh)