20) Seamless interface F.A.Q.

Integration tips:

• please use game_hash_id for your game library, because it is the same between staging and production. game_id will be different between staging and production
• transaction id is unique per player! two different players can share the same transaction id in some cases. Always take the remote_id in consideration when processing transactions
• seamless requests from mobile game can have desktop game id

INTEGRATION FLOW:

Q: Details Basic flow

once a player clicks on a game he wants to play, you would need to send a playerExists request to our server, which will then either confirm or deny the players existance, if the player exists, cool, you send US a getGame request to OUR endpoint(stage.game-program.com/api/seamless/provider). If the player does not yet exist, you must first createPlayer and then proceed with sending the getGame request for game launch(which will return the game url which you then insert into an iframe via src='https://gameurl.com..', and it will start loading the game.

We send a BALANCE request to YOUR endpoint(you need to create an endpoint that will accept such requests), you respond to the BALANCE request with a json format {"status":"200","balance":250} <-- in this case, 250 is the users balance, which you keep on your side. Balance requests will come after the game launch URL is used/clicked on and the game has started to load(in most cases). 

The user makes a spin ingame for 5€, we will send a DEBIT(bet) request to YOUR endpoint(the one you need to set up), and you need to update the users balance accordingly(remove the bet amount from his balance) and respond with the updated balance as the response example above --> {"status":"200","balance":245}

After the debit request, a CREDIT(win) request will be sent to YOUR endpoint, and you need to update the users balance(if he didnt win anything, amount in request will be 0. If he wins 10€ anything, the amount will be set the win amount in the request), and respond with the updated users balance --> {"status":"200","balance":255}

Gameplay will cycle in this order, DEBIT request, CREDIT request, etc. and user can close the game whenever. 

If any error happens while processing DEBIT or CREDIT requests, you will receive a ROLLBACK request, which you have to process(search for the DEBIT or CREDIT in your database, and return/take money from the user, as if the transaction has never happened).

FREEROUNDS

Q: How will we see requests coming from free spins (not freerounds)?

A: Order of events in free spins (same as normal bet / win)

1. you receive a bet request for 0.20 (for example)

2. then no win comes because player starts free spins (let them be 5 for example)

3. player plays all the free spins - during this time no communication will be between 'gameserver' and your wallet

4. when all free spins are played (finished) you receive a single win request with sum accumulated from all free spins winnings

So based on this scenario your wallet will see single bet 0.20 and single win 1.50 at the end and all free spins will be transparent for you.

Q: How will we see requests coming from free rounds (not free spins)?

Bet coming from free rounds will have is_freeround_bet = true and win will have is_freeround_win = true

A: When the player receives free rounds, this will be the order of events on your wallet:

1. you receive bet with amount 0, type of bet 'freeRoundBet'

2. when the player is finished using free rounds, you will either receive a positive or a 0 win of type 'freeRoundWin'.

Q: How you can know if the request is Freerounds win?

You have “is_freeround_win” so you would know it was winning from free rounds you awarded to player

Q: Adding Freerounds for both version mobile and desktop

If you add freer spins for both version (mobile and desktop) and launch the desktop version of the game first, you will be able to take advantage of the free spins there. But if you then open the mobile version, you wont have them there anymore. So if it’s the same game, the freespins will appear on the version you run first

Q: min, mid, max values of each games that supports Freerounds

Min -> Minimum bet or bet around 0,10€

Mid -> around 1€

Max -> from 3-5€

But this is depends from provider to provider

Q: RemoveFreerounds

When you create a freespins promotion you get freeround_id under thath freeround_id, there can be single game or multiple. But when you user RemoveFreerounds method, you delete that freeround promotion for that player (or multiple player)

So if you want to remove single game, you’d need to delte whole freeround and create it again

Q: Freerounds: validTo / validFrom

validFrom -> is a date field which contains. The date where the freerounds will be available from, in most cases it will be the same day the freerounds will be awarded. So, as an example, you will receive addFreeRounds request with validFrom set to 5.4.2022 and validTo set to 6.4.2022 for instance. You must treat these freerounds like they are available from 5.4.2022 0:00, until 6.4.2022 23:59.

Q: Will we receive the gameid parameter on all requests?

A: The gameid should always be present except on rollback. In some rare exceptions for example when player enters the livecasino lobby and gameid is unknown, we will send the livecasino lobby gameid.

Q: In balance request, where will the gameid be sent, in which parameter?

A: The values are sent in key⇒value combination, the order itself is not defined.

Q: You specify various data types, but we received only strings.

A: Please expect string values, but they should be treated as type described.

Q: In the table with the json response, the transaction_id is described as mandatory, but in the example of the credit call, it is not mentioned in the response, is it mandatory?

A: It's not mandatory, but you can return it for future use. Use 'transactionid'.

Q: In all credit/debit examples, the transaction_id in the response does not match the transaction_id in the request, should it match?

A: That's just an example.

Q: The transaction_id's are described as being an integer, but all requests we received so far are prepended with 'gs-'. we assume that we can strip the non integer part and still receive unique id's, is this correct?

A: Unfortunately 'gs - ' is a provider prefix, and its there to ensure that we send you unique ids because we have a lot of providers. But if you can use this prefix as a provider name, and use the numeric part as transaction id and still handle it as unique, than this is ok.

Q: How should the response look like If we get the request with the transaction_id that was already processedon our side?

A: Example: If transaction_id = 61385912731123 response was {“status”:“200”,“balance”:“105793.30”,“transactionId”:“362984”}, the response on the request with the same transaction_id should be {“status”:“200”,“balance”:“105793.3000”,“transactionId”:“362984”} . Meaning that on a retry, the response of the transaction should be the same as on first request ..

Q: Can I successfully process the debit/credit request with the same 'transaction_id'?

A: No! The possibility that you will get such a case is close to 0, but you'll never know. If you receive the same transaction id, please return same response as on first request (balance field should indicate current player balance)

Q: Why does some requests take so long to proccess?

A: We have a timeout simulation enabled on staging, so one in 10 spins may be slower up to 60 seconds so we can test the wallet properly

Q: How will we see if the player has won a jackpot?

A: You will receive a normal bet, and the jackpot win will be sent tied to the same roundid but it will be of type 'jackpotWin'. is_jackpot_win will be true.

Q: Should the rollback be allowed even if 'round_id' parameter is not present?

A: Yes!

Q: Which amount value should we use in case of the rollback request? That one from the request or that from the transaction that is going to be rollbacked?

A: Second one. Use the amount from the transaction that is already stored on your side and not from the request.

Q: How should the response look like if we get the request(debit/credit) with the negative amount?

A: Please return something like {“status”:“500”,“msg”:“Negative amount not allowed!”}.

Q: Is 'roundId' unique per user per game? For example, if two players play roulette on same table at same time and place their bets, is their roundId different or same?

A: It can be same, or different, depending on provider honestly speaking. On slots it's always different, on livecasino it will be same. You shouldn't rely on it being the same across multiple players.

Q: What are the differences between NE, NP and NL?

A: For netent you have three types of games:

1. NE . normal netent games

2. NP - netent premium games (3% higher royalties)

3. NL - netent live casino

Q: My game is stuck on loading screen, it does not load further

A: Probably there's an error on your end, please check your logs and check your wallet implementation on your end. The game is making a balance request on your service and you're not returning the balance correctly

Q: Microgaming games are not running on development environment.

If Microgaming games are not working please add following lines to your host file:

41.223.121.106  WebServer8

41.223.121.106  WebServer8.bluemesa.mgsops.net

41.223.121.105 WebServer4

41.223.121.105 WebServer4.bluemesa.mgsops.net

Q: Authentication pops up on staging environment

On staging we are using additional AUTH with some providers. Use test / test to authenticate.

Q: Calling images to frontend

First you need to save all images, which you get from getGameList response into your database. And then you can show images on your website. You cant call directly from frontend to our API

Q: Which games can you test the integration on?

I recommend you try the integration in Habanero or GameArt games

Q: rollback the transaction that not exists. ERROR 404 expected

If the transaction is sent and an error occurs or the transaction fails, the same transaction is sent again. So in the second when the transaction is sent the status must be the same as in the first sent transaction

Q: Slat Key test wrong in “basic tests”

On this test with incorrect salt key, you can response status 403 and msg: “Hash Code Invalid” / “Wrong key”, etc… . The salt was given to you together with api username and password. In wallet requests you will find “key” parameter which is passed with each request. That key is generated with sha1 encoding and its build with salt and request query parameters. KEY = sha1([SALT KEY] + [QUERY STRING])

Q: How can i use check key in my code?

When you receive wallet requests for example balance, you first check that key parameter if is is correct continue… if its not correct return error

Q: What is Gameplay_final parameter?

The "gameplay_final" parameter in debit/credit requests will tell you if the round is finished or not. Debit requests will have gameplay_final -> 0, credits gameplay_final -> 1, meaning the round has finished. 

Q: Show custom messages for returning response (insufficient funds)

We currently dont support any way of displaying custom messages on insufficient funds error for instance, as it depends from provider to provider, some support such things, some don’t.

Q: Balance, Debit, Credit, Rollback 

Balance: requests users balance, you respond with status: 200, balance: 450.99 for instance

Debit: debit requests are called when user makes a bet, so its basically a bet request, which includes the amount used to lower player balance

requests users balance to be lowered(its a bet, so you deduce users balance by the bet amount in the request) and respond with status: 200, balance: 449.99 for instance

Credit: credit requests are called after the debit request, as a response/win. Includes amount to a credit to player

requests users balance to be added(its a win/end of round, so either the user wins something or doesnt) by the amount that is in the request, and you respond with status: 200, balance: 454.24

Rollback: Rollback are sent if any timeouts or other issues happened with debit/credit requests or response. For instance, we send you a debit request, you handle the debit request on your side and for some reasons we don't receive a response and the game crashes. A rollback request will be sent for the debit to player receives the balance back

Q: Main difference seamless and wallet 

Essentially, with wallet you only transfer balance before player goes in game from your agent to player, while with seamless you require database not just for balances but also for transactions, so you have to store all individual transactions and operate them - modify player balance based on the requests you get from us.

wallet is actually easier and more secure - considering that it is our game server directly in contact with the game provider.

seamless all balance is updated in real time, as we are communicating with you to update balance.

Q: game_id in the balance request isn't a mandatory parameter

place for game_id on balance requests is therefore incorrect as the request varies from provider to provider

Q: If the transaction 1 happens now and 10 minutes lates we get duplicate transaction again, there is any chance that can happen?

That could happen, I don’t believe its happening regulary with basic transaction bit it. But usually dupliacate transaction happen very quickly one after another as part of a retry

Q: Where I can test my integration?

We have tests online from the backoffice, which you can run for yourself

Instructions on the tests are available here (under entry - Testing form):

https://blueoceangaming.atlassian.net/wiki/spaces/iGPPD/pages/1209172042/Testing+tool+and+Form

Once you pass all the tests, i will have to retest and check that all the tests are successful, before the project moves to production

Q: LoginPlayer is not mentioned in the workflow and when its called also the logoutPlayer

Generally it is not needed, loginPlayer and logoutPlayer are used to set and unset playing sessions for players and can also be used in that regard to check if session is still active and reject whatever gameplay comes from unactive session, but we also gave it handled on our side

Q: createPlayer: Do we get the same remote_id for one username when we call the createPlayer or its always different?

You will receive a unique remote_id for a player once you create him using createPlayer method. If you calling that again for the same user you will receive a “Player already exists” error, so instead, you can call playerExists, which will return user data. I would  advise to do it like this: when user click on a game, call playerExists if you receive a response that the player doesn’t exist yet, call createPlayer, and

Q: CreatePlayer: How can i actualize balance of a player stored on your server?

Balance of a player is completely handled on your side, meaning you will have to take care of adding or reducing players balance. We only store player data like id, username, and some other meaningless info, while you have to keep track of the ids, usernames, balances, etc.

Q: createPlayer: If you get error: “Payer already registered under a different agent« -> (CreatePlayer And PlayerExits)

previously created player with same username but under different currency. Player usernames are unique on our side. 

If the user "test123" is created under the EUR, then you must set the currency parameter to the value that this user belongs to (in this case on EUR)

Q: When you need use GET or POST?

GET -> for balance , credit, debit, callback

POST -> for all other methods (getGame, createPlayer, etc.)

Q: How can I know which methods are necessary? Do you have a list of most necessary methods?

Functions marked with * are mandatory, other functions are optional

Q: Rollback question: if not passed amount in rollback transaction, user balance will be same?

No, you should keep track of transactions and transaction id’s on your side and when a refund/rollback request is received by you, you should find transaction in your database using only the transaction id from the rollback request, and return the amount to/from the player. But rely only on transaction id in the rollback request, take the amount and everything else from your side when you locate transaction

Q: Difference between getGame (play for fun) and getGameDemo

GetGame always return URL you should load directly. Is used for normal games: slots/livecasino/virtual etc. You can get demo version of slots/livecasino/virtual games by passing an additional parameter play_for_fun = 1 in getGame request. In play for fun mode player can spin and play slot, but he is not playing with real money. Here you have free credits. It is used mostly for slot games.

GetGameDemo is used for demo version of sportsbook. In this case player cannot place any bet or play game. He can just open and see how game looks like. It is used for sportbetting to open sportbetting and see what option he has to bet. Normally player can only select ticket in demo mode he would like to play, but he cannot place a bet until he does login as real player and only then he can place bet with his real balance.

Q: Which currency format you must use?

We use the standard EUR and USD… three character format

Q: Error fetching remote

Error fetching remote means that your endpoint is unreachable, meaning you'll have to take a look at the issue with your system administrators as its something related to the servers.

Q: How to to test the rollback?

Place a 10 second sleep in the code before responding to debit requests, and try to place a bet 

So you'll answer the debit request after 10 seconds, which should trigger a rollback

Also, please test this using Habanero provider, as it depends from provider to provider how everything is handled after a failed debit, Habanero should respond with a rollback if the debit is answered after 10 seconds 

Q: Can we have freerounds and free spins in the same request?

Depends from provider to provider . Some games providers send credit eaxh spin(also if winning is 0), others send only if there was win in spin (e.g. from 10 awarded spin 3 are winning – you will get 3 requests). Most of them send credit request only at the end (at last spin). So, you cannot rely on counting freespins

Q: Storing transaction on their side

You should store each transaction on your side anyway, you will need transaction data to resolve issues when players complain to you.

Q: How to integrate jackpot?

We don’t gave any such functionality implemented on out side, we suggest you fetch jackpot values once per day as incrementing based on no ingo isn’t accurate at all

Q: Possible bets level on your side?

Bet levels depends on provider. We do not have a list of possible bets

Q: Which crypto currencies we support?

Bitcoin, Mili Bitcoin (MBC), Micro Bitcoin (UBC), Mili BTC Cash(MBH), Ethereum, Litecoin

Q: Can integrate on stage Account providers, which not allow without license?

Usually if you don’t have provider in the contract, we don’t enable them for you on staging, as you wont need them, so  no, if you don’t gave license we wont enable them

Q: callback for production and stage can be the same?

I strongly suggest having different callbacks for production and staging environment, as if any mixup happens, it could be with real money or vice versa, or you could accidentally test something on production instead of staging etc.

Q: DIGITAIN

• Digitain how to launch the game: please use getGameDirect method to call the game with its own game id, and you will receive the full embed code as a response, which contains code with already filled parameters.
• CNAME has to be added on your side, where the site is hosted

• run through the JS code in documentation, it is not possible to launch with valid token

• What is CNAME? -> Your website name

Q: what is difference when you call getGameList with different currencies?

the currency parameter is used for filtering games which support it or not, so if a game/provider doesnt support for instance AED currency, it will not show up in the getGameList response with currency: AED used

Q: Rollback timeout. What is the usual flow if you get time out?

Depends from provider to provider, but usually it goes like this: provider sends a bet, you fail to respond correctly to the bet the provider sends a rollback request and you rollbaxk the bet. So, if request times out its counted as invalid/not processed so you should receive the rollback request, if the transaction was processed on your side you can handle the rollback request normally. If not you should not handle and just respond with status 404.

Q: Is the issue of expiring session tokens after 24 hours?

Yes that will be the problem, because provider can keep retrying transaction for more than 24hr in scenario where you do not accept transaction from provider and you expire token the transaction can be lost

Q: How long should our session last?

The session must not be closed. Especially when it comes to winning. And you must return 200 and balance on credit an debit

Q: what parts in your API we need to pay attention to so that we can distinguish between a regular bet and a free spin bet or, for example, a regular win from a jackpot win?

There is no difference between a regular bet and in-game free spins bet.

In the case of a jackpot, the jp cpntribution parameter is sent in the bet request. If the jackpot is a win, the value of is_jacpot_win request parameter is set to 1 and jackpot_win_amount->amount of the win

Q: Difference between "freespins" and "freerounds_supported" parameters

which give him 10 freespins. normally those pay out more than normal spin as it has some special feature

freerounds are what you award to player as "bet for free" ... so you give him 10 spins which are normal spins (not part of bonus game), just that bets for those spins are not deducted from player balance

Q: if the games you are seeing in getGameList on STG are available or you need to enable/configure something additional from your side

All the games you receive getGameList, are aviable for your API

Q: bonus_buy: how can I filter games who support bonus by?

We are sending bonusbuy: true / false on getGameList request, but you have add “show_additional” : true to the request to receive additional details, one of them being this bonus buy parameter. I believe not all games have this in info though

Q: How to know which games support specified currency

If you retrieve getGameList for USD currency, you will receive a response that contains games that support USD currency, if you call it for EUR currency, you will receive games that support EUR currency

Q: Which one should you use (GetGame, getGameDirect, getGameDemo) ?

GetGame -> is used for normal slot games, virtual games, live casinos etc.

getGameDirect -> is used for sportsbook providers as it returnes embed code

getGameDemo Is used for demo version of sportsbook

Q: How to get “megaways” games from getgamelist call

You can get games that are "megaways" with our getgamelist method. Add a parameter to the method call:

   "show_additional" : true. Here's how to do it:

   "api_password" : "api password",

    "api_login" : api name

    "method" : "getGameList"

    "show_systems" : 0,

    "show_additional" : true,

    "currency" : "EUR"

Q: cURL error 7: Failed to connect. Couldn't connect to server. Could the firewall be blocking it?

It is possible that a firewall is blocking the connection to the server “em-api.thegameprovider.com” on port 443.

A firewall is a security system that monitors and controls incoming and outgoing network traffic based on predetermined security rules. It can be implemented in hardware or software and can be set up to block specific IP addresses, ports or types of traffic.

If the server you are trying to connect to is located on a network that is behind a firewall, the connection may be blocked if the firewall is not configured to allow traffic on port 443.

It is recommended to check the firewall settings on your network or contact your network administrator to verify if the traffic to the server is being blocked.

If you are trying to connect to a server hosted by a third-party, you should contact their support team to check if the server is properly configured to accept your incoming connection.

Q: how many currencies we have for games?

we support any ISO currency + some popular crypto but then is up to providers if they support certain currency or not

Q: Is user can have 2 currencies?

No, you can only have one username in one currency. If you want to have the same username for multiple currencies, I suggest adding a prefix or something similar to the username

Q: Possible ways to get hashing wrong

We are sending jackpot_contribution_in_amount = 0 via the GET request. Check request if you see jackpot_contribution_in_amount = false. If yes then you need to handle parameter to 0.

Q: Find all jackpot games

To find out all the games that are jackpot, use the getGameList method. In the response you have parameter “has_jackpot”. This parameter have two values: true or false

Q: If you need jackpot type

if you need the jackpot type, add the show_additional: true parameter to the getGameList request. In the response you see a array of parameters.

Q: How to use ip for whitlising if you have dynamics IPs?

If you want develop locally and want to use dynamic IP, you can do, but you will have to update it by yourself in the backoffice. This is not possible on production

Q: Is it possible to set multiple callbacks for multiple domains?

If you want separate accesses for two separate website, you would have to request a new access so we can give you a new one that has a different endpoint set up, and you would use the new credential for game launches

Q: Evolution restriction

Evolution just implemented a currency restriction. This means that you can play with the currency that matchers the geo location from where you are launchink the game (e.g. TRY -turkey, INS-israel) or with any currency tthat stronger/more worth. Generic currencies like EUR, USD, EGP are excluded from this restrictions

Q: Mobile and desktop version of the games

We want to separate mobile and desktop games on out end to keep track on where the games was player

Q: What category is virtual-games?

Games are usually put into a separate category from live casinos and slots

Q: Why do you need to provide us with a callback URL when starting the integration?

You need to provide callback URL to which we will send waller requests when player start the game and play it. For example your callback url will be: https://test.com/api and we will be sending wallet requests on that url

Q: documentation it says our endpoint cannot be behind cloudflare

If you have no way of exposing URL from outside of Cloudflare infrastructure that is not a blocker, however we did have myriad of issues with clients who are having their API endpoint on Cloudflare.

• Potential errors that you may experience due to cloudflare?

1. We send 100 requests to you in a second, Cloudflare will mark us DDOS
2. If you are on Cloudflare, your ip will be changing and routes through which we are sending you requests will change too, which from experience bought bad experience to players, theirs spins taking long time or missing winning. Because CF decided some route is closer to us any point and debugging that issues in nearly impossible

Q: In documentation: jackpot_contribution_in_amount is defined as double(10,6). And you cant parse false as double.

Its actually sent as 0, but while long parsing logs they take a form Boolean value for some reason, its actually a 0

Q: We send credit request with parameters amount:0 if users doesn’t win anything. What does transaction_id represent them and if its possible to receive rollback with amount = 0?

Each bet/win is logged as separate transaction which has unique transaction_id. That transaction_id is also used when rollback request is sent, to know which transaction needs to be refunded

Q: Are sportsbook debit and credit requests the same as casino requests? Is there more data coming in?

the requests are the same yes, as for the payload, its the same, except we can add another parameter in the requests which includes additional bet and win data if you'd like. We more or less forward the whole request that the sportsbook provider sent us to you, so you get the whole data we get

Q: Is it mandatory to return balance field in every error response (status 404, 500, 400, ...)? What if you cant return balance in the moment of the error (for example query validation failed, internal server error happened)?

Status and balance are only mandatory in successful response cases, if the request fails for some reason you can respond with status and message, you can throw in the balance anyway and if its not possible to return it set it as null, doesnt really matter

Q: What should we do with a credit callbacks that have is_promo_win set to true? What are promo wins and when can we expect them?

Thats only signalling that the win is a promo win, generally promo wins come after the round has already completed, or even as a standalone round. Providers can have a promotion in one of their games, and if one of your players wins that promo, they can recieve a random "win" for some amount in that game. So for less confusion, its flagged

Q: Difference between session_id and gamesession_id as both of them are sent in response of getGame.  Which one shall we verify for validity when balance is debited?

"gamesession_id" is used to track game sessions that is unique per game launch. So when you close current game, and open another, you will receive new "gamesession_id". "sessionid" is used to track player login session. When for example player logins in your casino. You can use your own "sessionid" by sending "sessionid" parameter in getGame() request.

Q: How can we use our own sessionid and send it into getgame

You can use this parameter like others you send in getGame reuqest:

{

"api_login" : "testapi",

"api_password": "testapi",

"method": "getGame",

"lang" : "en",

"user_username":"player1",

"user_password":"player1", 

"gameid" : "114575",

"sessionid": "12345678910",

"homeurl" : "http://url.to.your.page.com",

"cashierurl" : "http://url.to.cashier.page.com",

"play_for_fun" : 0,

"currency": "EUR"

}

You can use it if you need it. It is not mandatory parameter to send it in request

Q: Is callerId always equal to api_username and callerPassword always equal api_password?

API username is the callerID, and API password is callerPassword. Its the same think just different naming. You need to use your API credentials.

Q: Do callerPassword and api_password have the same value?

yes, but callerPassword is sha1 encryption

Q: why we send game_id: null in balance request?

Some providers do not send us the game ID. Therefore we cannot forward it. Game_id is not mandatory in a balance request