Operator API documentation (v1)

St8 is a Game Aggregator that provides unified APIs to simplify workflow of casino Operators when managing their content portfolio.

St8 provides the following APIs for Operator to use (in accordance with this documentation):

1. Game Launch API
2. Query API
3. Bonus API
4. Transfer Wallet API

Should Operator choose to use Seamless Wallet, it is expected that the Operator will provide Seamless Wallet API generated in accordance with the given documentation.

When using Seamless Wallet Operator is responsible for holding information about player current balance (i.e. Operator is holding the wallet)

This solution suggests that the Operator itself should perform all actions with the funds such as checking the balance, increasing/decreasing amounts.

The benefit of such approach is that Operator controls wallet state and doesn't need to rely on anyone else for this matter, as well as possibility for player to play multiple games from different providers at the same time.

The downsides would be:

• Operator’s involvement and required technical proficiency to implement all callbacks according to Seamless Wallet API definition

• Amount of network communication between Aggregator’s platform and Operator's platform.

In regions with high network latency, this amount of network calls is the most widespread reason for poor player experience such as slower spin time, bet lags, not being able to place a bet in time and straight up transaction fails due to occasional timeouts.

By implementing Transfer Wallet solution Operator allows Aggregator to hold information about player's balance and perform corresponding changes (i.e. Operator transfers wallet to Aggregator to manage it on Operator's behalf) With such approach Operator has to implement Transfer Wallet API calls to be able to transfer balance in and out of aggregation platform.

The benefit of such approach would be very little network communication: Operator only needs to send requests for transfering money in and out of St8 system. And even if there have been thousands of game rounds played in between deposit and withdraw, Operator doesn't need to do anything to process them, because St8 system does it on their behalf.

The downsides would be:

• Operator needs to transfer certain amount of money from player's balance to aggregation platform. Until the money gets withdrawn back by operator, it can be used only to play games provided by St8.io

• If the Operator wants to know what player has used his balance for, then Operator needs to query transactions or consume Apache Kafka topic.

To authenticate requests going in and out of St8 system we use ECDSA signature (Elliptic Curve Digital Signature Algorithm).

Request author has to sign payload with his private key and receiving party has to validate signature with corresponding public key.

We reserve the right to add new fields in payloads of our requests and responses without prior notification. Therefore, Operator has to develop integration keeping this in mind. This also applies to signature verification: Operator has to verify signature of the whole payload and not only from the known fields ( This will be verified during integration acceptance testing).

The diagram below illustrates how St8 and Operator generate and exchange keys during setup phase and signature validation later during operation phase.

Generate private Elliptic Curve key

openssl ecparam -genkey -name prime256v1 -noout -out ec.key

You should have now file ec.key with content similar to this:

  -----BEGIN EC PRIVATE KEY-----
  MHcCAQEEIIBEdi1kkP+IAIVmbke0EP8XSyEAaEi82dwLUwr9HuY9oAoGCCqGSM49
  AwEHoUQDQgAE1yliYVgjr28KYkDD0QYkGa9Y11folImZkMrOiNdmz01Eq7a1y9G8
  l/KlnaDluWnKEpm0IBpNy1D+Y5jXIivvbQ==
  -----END EC PRIVATE KEY-----

Retrieve public key from private

openssl ec -in ec.key -pubout -out ec.pub

You should have now file ec.pub with content similar to this:

  -----BEGIN PUBLIC KEY-----
  MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1yliYVgjr28KYkDD0QYkGa9Y11fo
  lImZkMrOiNdmz01Eq7a1y9G8l/KlnaDluWnKEpm0IBpNy1D+Y5jXIivvbQ==
  -----END PUBLIC KEY-----

Generate Signature

Let's assume that "test" is our payload which we want to sign. In this case we would sign it with our private key from ec.key file and then encode it into base64. Note that we've added -n after echo so it wouldn't add new line (\n) in the end of our payload.

echo -n "test" | openssl dgst -sha256 -sign ec.key -binary | base64 > sign.txt

Now you should have a sign.text file with contents similar to:

MEQCIGyMAz34xzIpMr+wTT40L/uIe+n6Tw0L0dli4/TfrA40AiA+AUzgt57yAvrkUqVQSmNMdD0ODdr6imTVYeBJY1kwrw==

Validate Signature

Now we need to decode signature from base64:

base64 -D -i sign.txt -o sign.bin

And feed it back into OpenSSL to validate (Note that we are using public ec.pub key for validation):

echo -n "test" | openssl dgst -sha256 -verify ec.pub -signature sign.bin`

You should have received such result:

Verified OK

To simplify integration process St8 has prepared example code of signature generation in the following programming languages/frameworks:

• Python
• Erlang
• PHP
• Java
• C#
• JavaScript (Node.js)

St8 platform provides two methods for Operator to launch the game:

• Build launch URL themselves
• Request launch URL from St8 platform

With this approach Operator doesn't need to make extra calls to St8 platform to obtain game launch URL. Game URL is built according to schema described in this documentation and given to player to load it.

Using this solution Operator has to add only a few required params to the game URL, and the rest of the player session information will be requested by St8 system via the /check callback.

One of the required parameters in game launch URL is token and we will address it as "launch token". We recommended generating unique launch token for combination of player + game + currency. It is important to generate new token on each game launch and it is a good practice to expire this token after 15 mins

Validating game launch

It's important for Operator to validate all arguments of incoming /check call and match them with what is expected to be received (is the game_code matching the game launch token was issued for?). In case of the mismatch this game launch attempt may be classified as an attempted fraudulent behaviour and should be rejected.

In case of successful validation Operator has to reply with information about player and session. One of required fields in reply is token and we will address it as "wallet token". It's required that wallet token is not the same as launch token, since the original token has been already seen by player in the URL and can be abused by malicious player to launch different game.

Please, keep all wallet tokens available for at least couple months, since some /credit or /cancel calls might reference not the latest wallet token, but a week (or more) old. The following diagram describes the processes activated as soon as the player on Operator’s side starts playing a game provided by St8.

With this approach Operator has to make server-to-server /launch call to St8 system and provide all player session information as payload of this call. In response St8 will return game launch URL which player has to load to start playing.

Since there is no /check callback in this scenario and player never sees request payload, token in this request should be already wallet token.

Please, keep all wallet tokens available for at least couple months, since some /credit or /cancel calls might reference not the latest wallet token, but a week (or more) old.

The following diagram describes the processes activated as soon as the player on Operator’s side starts playing a game provided by St8.

Both approaches have one thing in common, which is optional /player_profile callback. St8 makes this request when player first time interacts with games provided by St8 or when Operator prompts St8 to do so (see documentation for /launch calls for details).

Returned player information will be used for selecting the best fitting game configuration. It will also be available in St8 back-office for player segmentation purposes.

Informational API that is designed to improve operational activity by providing list of available games, list of transactions or checking result of a round.

This is a set of APIs designed for Operators working in regulated markets to help them comply with local online gambling requirements.

Bonus API is designed to enable Operator’s promotional activities such as rewarding players, as well as sending out big reactivation/retention campaigns.

St8 delivers a logical solution to Operators where decoding the matching bet sizes across multiple games is no longer needed. St8 provides special API method “Offers” for querying available betting options for games making the entire process more flawless.

The following method “Offers” accepts list of games as an argument and returns offers that are compatible with all of the games.

We believe that the strategy of automatic adjustment of bet size to "match the game math", which is employed by certain game developers, should be improved. Otherwise the user might receive lower value of spins that has initially been advertised, thus creating bad user experience for both casino (and marketing) managers and especially players.

Therefore, this API method will show only offers which are exactly compatible with all of the games. The following approach might lead to empty response, when there are no common offers between requested games.

This could happen due to difference in game math (number of lines or coins) as well as game developer's API limitation where they don't allow creation of bonuses for multiple games at the same time. In such cases Operator should try decreasing selection of games or swapping some of the games for more compatible ones.

There are currently three types of offers:

1. Free bets. Player is awarded with the option of placing free bet(s) of predetermined size. Commonly used with slots products.
2. Free Money. Player is awarded with balance of predetermined size, which he can spend on bets of any size. Commonly used with live and RNG table games products.
3. Bonus Game. Player gets an access to bonus gameplay of selected games. Bonus games visually differentiate from regular spins and usually look more entertaining/attractive.

St8 provides Operator with API which allows creation of bonuses for multiple games and many users at the same time.

Usual scenario of bonus creation would consist of choosing supported bonus offer (maybe with help of offers method) and providing offer's details along with the list of players. If there are many players, creation process might take some time (response will say that bonus status is processing) and Operator has to come back later to get the final result.

Action sequence diagram:

Transfer Wallet API is designated to improve gameplay experience in high network latency areas. This is set of callbacks which Operator can use to manage balance of their players in St8 system.

The following diagram describes the processes activated as soon as the player on Operator’s side starts playing a game provided by St8.

This chapter covers set of callbacks which Operator has to provide to enable gameplay when opting for Seamless Wallet solution.

Here is the list of statuses that we expect Operator's platform to return in response to seamless wallet callbacks.

St8 appreciates the need of being more transparent with data which we receive from game providers. Original type (aka "kind") of transaction is one of many examples.

This transaction kind gives an insight into origin of transaction, as well as describes some specifics of its processing.

Below you can find the table of supported provider transaction kinds and their descriptions.

Please pay attention to correction_debit.

The following diagram describes the processes activated as soon as the player on Operator’s side starts playing a game provided by St8.