Fizzy Bubbly Provider API

1.0.0

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 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.	{}