VisionLINK Operator Seamless API (1.73)

• The API communication is always using HTTP POST with json requests and json responses. Content-type on requests need to be set to application/json.

• Communication will always be over HTTPS.

• Http status 200 means operation was successful (only use 200 for success, never 201). If the request is unsuccessful the http status must be either 40x or 50x. The exact error is clarified by an errorcode variable. For a complete list of all error codes see below.

• All fields in all requests and responses are always in lower case.

• Language is defined by two char ISO 639 codes i.e. ja for Japanese. If other codes are required custom mappings can be configured upon request.

• Currency is defined by three char ISO 4217 codes i.e. JPY for Japanese Yen. If other codes are required custom mappings can be configured upon request.

• Country is defined by two char ISO 3166 alpha 2 codes i.e. JP for Japan.

• All amounts are presented in cents where for example 1.00 USD will be sent as 100. Meaning all amounts always has "two decimals". This also applies to currencies that do not have decimals like 1 JPY will also be sent as 100.

• The jackpot contribution in contributionamount is in ten-thousand of a cent, meaning contribution is with "six decimals", i.e. contribution of 1.00 USD will be sent as 1,000,000.

• JSON parser must be configured to ignore unknown fields. This to allow the API to grow with new features without breaking backwards compatibility.

• For requests, the JSON generator should be set to ignore null fields i.e. to not be included in the generated request data.

• Current outgoing IP from test/staging system is 158.180.12.240.

• The roundid value is used to uniquely identify the financial game round. The VisionLINK will make sure it's always unique, even if several players are playing on the same table.

• All debit, credit and reverse requests will always have the roundid included.

• All requests will always have the externalsessionid included.

• Each game round will always be notified as closed even if there's no win. In such cases there will be a zero credit call sent.

• The transid value is used to uniquely identify each individual transaction.

• The default platform behaviour is to send each FREEBET being played as individual game rounds, with regular debit and credit calls. This can be reconfigured on Vision Link side to only send a freebet summary. In such case there will not be any debit calls, just a single credit call in the end with reason=FREEBET_SUMMARY when all freebets are successfully consumed.

• The parameter jurisdiction, if used, must follow our internal definitions which are based on the country of the regulator for example 'MT' for MGA.

• The communication with wallet is expected to be idempotent processed. This means that if the same request is received again, the same result as before should be returned without changing the balance the second time.

• Any pending open game round will be automatically closed, normally after 48 hours but variations can exist for different games and products. This means that both method getbalance and credit must be allowed even if session is already closed.

• Please note for just integrating with Vision RGS the following are not used;

• • The api method debitandcredit is not used. The RGS will only send individual debit and credit calls.
• • The debit reasons BURST_TRANSFER and DEALER_TIP are not used. Please ignore these.
• • The credit reasons BURST_TRANSFER, FREEGAME_WIN and JACKPOT_WIN are not used. Please ignore these.

---

The Operator API is for server request from the operator to the Vision platform. This API is protected by Basic Auth mechanics, credentials will be given by the integration team. In production the API will be behind a firewall.

Method "gamelauncher/play"

To be used for creating a game session via API. This is called as a server to server call, where response will be a json response, not a 302 redirect response.

The game launch itself is a two step process as the launchurl responded will point to the public game launcher. This to allow injection of addition iframe's or other html based game loaders.

When calling the gamelauncher method the request will be considered already authenticated due to it's an authorised method, hence there is no additional callback for authenticate with the wallet.

Request:

class GameLauncherPlayRequestBean
{
    // Required
    String mode;
    String gamecode;
    String currency;
    String language;
    // Required if REAL mode
    String playerid;
    String externalsessionid;
    String ipaddress;
    String country;
    // Optional player flags
    String displayname;
    String brand;
    // Optional launch parameter
    String channel;
    String exiturl;
    String depositurl;
    // Optional settings, please ignore unless you know what these means
    String forcecountry;
    Integer rtpversion;
    Long defaultbet;
    Long minbet;
    Long maxbet;
    Long riskexposure;
}

Response:

class GameLauncherPlayResponseBean
{
    String launchurl;
    String sessionid;
}

Method "gamelauncher/replay"

To be used for getting replay data for a previously played game round.

Request:

class GameLauncherReplayRequestBean
{
    String roundid;
    String language;
    int timezone;
}

Response:

class GameLauncherReplayResponseBean
{
    String launchurl;
}

Possible error codes

If error is returned the json data will hold two fields;

• errorcode: in the context the error code is a numeric value, not a string, see list below
• errormessage: internal error message

Error codes with HTTP status in parentheses.

• 101 - Invalid request data / format (400)
• 102 - Incorrect request sequence (400)
• 201 - Incorrect access credentials (401)
• 205 - Player not found (404)
• 206 - Game not found (404)
• 209 - Currency not found (404)
• 211 - Player already exists (400)
• 309 - Transaction / request duplicated (403)
• 500 - Internal / unknown processing error (500)
• 501 - Network communication failure (500)
• 503 - Service temporarily disabled (503)

---

The Wallet API is for server request from the Vision platform to the wallet. This API is using Basic Auth mechanics that must be verified on wallet side. The credentials will be given by the integration team. In production the API will be behind a firewall.

Method "getbalance"

The getbalance method will be called to retrieve initial balance, as well as pulling new balance. Some external provider might call get balance to force a keep alive of the gaming session.

Request:

class WalletVisionBalanceRequestBean
{
    String playerid;
    String sessionid;
    String externalsessionid;
    String gamecode;
}

Response:

class WalletVisionGenericSuccessResponseBean
{
    String currency;
    Long cashbalance;
    Long bonusbalance;
    String externaltransid;
}

Method "debit"

The debit method, used for bet request. Please note it is possible to get dual debits on the same game round (occurs on game like Blackjack). It is also possible to receive a debit call with roundended flag set to true meaning there will not be any further transactions in this game round.

The debitamount is always the exact amount to debit the player account. The contributionamount is information of how much of bet that will go into jackpot pooling.

Possible game play reason are as below. For these reasons the 'gamecode' field is always included.

• REGULAR - regular game play
• BUY_FEATURE - if player choose to use BUY feature in the game (not supported on all content)
• FREEBET - when playing on freebets (free rounds)
• BURST_TRANSFER - for game that uses the BURST dynamic transfer
• GAMBLE - if player choose to gamble the winnings

Possible expense reason are as below. For these reasons the 'gamecode' field is not included.

• DEALER_TIP - player gave away funds to the dealer / streamer
• MEGAJACKPOT_BUYIN - player choose to buy into a site wide jackpot
• TOURNAMENT_BUYIN - player choose to buy into a tournament

Please note that due to lack in API logic on most external providers the tags BUY_FEATURE and GAMBLE cannot be mapped correctly. For such game rounds the reason will still be REGULAR.

The platform might send reason=FREEBET with debitamount=0. This to notify free game round starts. In such cases the extra value for freebetamount=nn will be included. This behaviour is though not consistent over all game providers, some will only send credits, and some will only send a final credit.

The BURST_TRANSFER is used for transaction intense games where server need to hold a balance temporarily before returning back actual winnings.

For reason DEALER_TIP, MEGAJACKPOT_BUYIN and TOURNAMENT_BUYIN the VisionLINK platform will only send a debit with both roundstarted and roundended set to true.

Request:

class WalletVisionDebitRequestBean
{
    String playerid;
    String sessionid;
    String externalsessionid;
    String gamecode;
    String reason;
    String roundid;
    String transid;
    String currency;
    String externalfreebetid;
    Long freebetamount;
    Boolean freebetended;
    Long debitamount;
    Long contributionamount;
    boolean roundstarted;
    boolean roundended;
}

Response:

class WalletVisionGenericSuccessResponseBean
{
    String currency;
    Long cashbalance;
    Long bonusbalance;
    String externaltransid;
}

Method "credit"

The credit method, used for win request. Please note it is possible to get dual credits on the same game round. Actual end of game round is notified by roundended flag.

The creditamount is always the exact amount to credit the player account. The jackpotamount is information of how much of the win that came from jackpot pool.

The reason type will not change between debit and credit.

Possible game play reason are as below. For these reasons the 'gamecode' field is always included.

• REGULAR - regular game play
• BUY_FEATURE - if player choose to use BUY feature in the game (not supported on all content)
• FREEBET - when playing on freebets (free rounds)
• FREEBET_SUMMARY - a summary for all freebets being played
• BURST_TRANSFER - for game that uses the BURST dynamic transfer
• GAMBLE - if player choose to gamble the winnings

Possible payout reason are as below. For these reasons the 'gamecode' field might be included.

• CAMPAIGN_WIN - player won from some kind of additional campaign on the provider side
• FREEGAME_WIN - player won from additional free games (instant freebets)
• JACKPOT_WIN - player won a jackpot win (where payout isn't pegged to a specific game round)
• MEGAJACKPOT_WIN - player won from one of the internal MegaJackpot pools
• TOURNAMENT_WIN - player won from a tournament

Please note that due to lack in API logic on most external providers the tags BUY_FEATURE and GAMBLE cannot be mapped correctly. For such game rounds the reason will still be REGULAR.

The BURST_TRANSFER is used for transaction intense games where server need to hold a balance temporarily before returning back actual winnings. When winnings are credited back the extra optional fields for totalbetcount, totalbetamount, totaljackpotcontribution, totalwinamount and totaljackpotamount will also be provided. These will help the wallet to calculate correct turnover for kickback / wagering requirements.

For reason CAMPAIGN_WIN, FREEGAME_WIN, JACKPOT_WIN and TOURNAMENT_WIN the VisionLINK platform will only send a credit with both roundstarted and roundended set to true.

Request:

class WalletVisionCreditRequestBean
{
    String playerid;
    String sessionid;
    String externalsessionid;
    String gamecode;
    String reason;
    String roundid;
    String transid;
    String currency;
    String externalfreebetid;
    Long freebetamount;              // Only FREEBET_SUMMARY
    Long creditamount;
    Long jackpotamount;              // Only REGULAR and BUY_FEATURE
    Integer totalbetcount;           // Only BURST_TRANSFER
    Long totalbetamount;             // Only BURST_TRANSFER
    Long totaljackpotcontribution;   // Only BURST_TRANSFER
    Long totalwinamount;             // Only BURST_TRANSFER
    Long totaljackpotamount;         // Only BURST_TRANSFER
    boolean roundstarted;
    boolean roundended;
}

Response:

class WalletVisionGenericSuccessResponseBean
{
    String currency;
    Long cashbalance;
    Long bonusbalance;
    String externaltransid;
}

Method "debitandcredit" (only Vision LINK)

The unified debitandcredit method is used for processing both bet and win as one transaction where end of round is notified with the roundended flag. Please note the debitamount must be validated and processed before the creditamount. I.e. if player have 100 on the account, a request with debitamount of 200 plus creditamount of 300 must be rejected with error NOT_SUFFICIENT_FUNDS. It cannot result in net +100 for the player.

Please note this method is not used by the Vision RGS. It is only required by a few 3rd party game providers through the optional Vision LINK aggregation logic.

Possible debit and credit reasons are as below. For these reasons the 'gamecode' field is always included.

• REGULAR - regular game play
• FREEBET - when playing on freebets
• GAMBLE - if player choose to gamble the winnings

Request:

class WalletVisionDebitCreditRequestBean
{
    String playerid;
    String sessionid;
    String externalsessionid;
    String gamecode;
    String reason;
    String roundid;
    String transid;
    String currency;
    String externalfreebetid;
    Long freebetamount;
    Boolean freebetended;
    Long debitamount;
    Long contributionamount;
    Long creditamount;
    Long jackpotamount;
    boolean roundstarted;
    boolean roundended;
}

Response:

class WalletVisionGenericSuccessResponseBean
{
    String currency;
    Long cashbalance;
    Long bonusbalance;
    String externaltransid;
}

Method "reverse"

The reverse method is used to reverse (rollback) a previous debit. Only debit amounts can be reversed. You either reply http status 200 + currency + balance (as in request was received and processed successfully, though nothing where needed to be done) or return http status 404 with errorcode=ROUND_NOT_FOUND + currency + balance.

Request:

class WalletVisionReverseRequestBean
{
    String playerid;
    String sessionid;
    String externalsessionid;
    String gamecode;
    String roundid;
    String transid;
    String originaltransid;
    Boolean roundended;
}

Response:

class WalletVisionGenericSuccessResponseBean
{
    String currency;
    Long cashbalance;
    Long bonusbalance;
    String externaltransid;
}

Method "endsession"

The endsession method will be called when Vision platform identifies that the gaming session has ended. If you don't process this request the server must still return success:true.

Request:

class WalletVisionEndSessionRequestBean
{
    String playerid;
    String sessionid;
    String externalsessionid;
    String gamecode;
    Integer numrounds;
    Long totalbetamount;
    Long totalwinamount;
}

Response:

class WalletVisionGenericSuccessResponseBean
{
    boolean success = true;
}

Error response

In case a validation or processing error occur, the server should send an error response instead of a success response. The response parser is dependent on correct errorcode being used, where the http status is used for monitoring. The http status can not be 200 as that means "success". Exact list see below.

For errorcode=NOT_SUFFICIENT_FUNDS it's mandatory to include currency, cashbalance and bonusbalance. This to avoid an extra server call for getbalance. For all other errors it can be omitted (fields should not be included in the json).

Response:

class WalletVisionGenericErrorResponseBean
{
    // Mandatory
    String errorcode;
    String errormessage;
    // Optional except for NOT_SUFFICIENT_FUNDS
    String currency;
    Long cashbalance;
    Long bonusbalance;
}

The errorcode need to be any of the following codes. In this context the error code is a text string, not a numeric value. The expected http status is put in parentheses.

• AUTHENTICATION_FAILED (401)
• BAD_REQUEST (400)
• BONUS_LIMIT_REACHED (403)
• COMMUNICATION_FAILURE (500)
• GAME_NOT_FOUND (404)
• GAMING_LIMIT_REACHED (403)
• INTERNAL_ERROR (500)
• INVALID_CURRENCY (404)
• INVALID_TOKEN (403)
• NOT_SUFFICIENT_FUNDS (402)
• PLAYER_BLOCKED (403)
• PLAYER_NOT_FOUND (404)
• PREVIOUS_ROUND_NOT_ENDED (403)
• RACE_CONDITION (503)
• ROUND_ENDED (403)
• ROUND_NOT_FOUND (403)
• SERVICE_DISABLED (503)
• SESSION_EXPIRED (403)
• SESSION_LIMIT_REACHED (403)
• SESSION_NOT_FOUND (404)
• TRANS_DUPLICATED (403)
• TRANS_NOT_ALLOWED (403)
• TRANS_NOT_FOUND (404)