LIVE AT ITS BEST

1

SUPPORT@VIVOGAMING.COM

V 1.5

VIVO GAMING SYSTEM (VGS)

COMMON WALLET – LIVE DEALER GAMES ACTIVATION

VIVOGAMING 2022

UPDATED:2023-06

VERSION

5.31

WWW.VIVOGAMING.COM

SUPPORT@VIVOGAMING.COM

LIVE AT ITS BEST
 
   
 

SUPPORT@VIVOGAMING.COM 
V 1.5 
CONTENTS 
 
 INTEGRATION BASICS ................................................................................................................... 3 
1 Terms ........................................................................................................................................ 3 
2 General Notes ....................................................................................................................... 3 
3 Client Activation – Front End ........................................................................................... 4 
4 API Summary ....................................................................................................................... 4 
5 Integration Workow ......................................................................................................... 6 
5 Fail-safety ............................................................................................................................... 7 
6 VGS game client error codes ........................................................................................... 7 
7 VGS-EC Servers Validated IP's ......................................................................................... 8 
 Integration API Calls ....................................................................................................................... 9 
1 Protocol format and description .................................................................................... 9 
1.1 Request format .............................................................................................................. 9 
1.2 Response format ........................................................................................................ 11 
1.3 Security .......................................................................................................................... 12 
2 Detailed API Format ........................................................................................................ 13 
2.1 Authenticate API......................................................................................................... 13 
2.2 ChangeBalance API .................................................................................................. 15 
2.3 Status API ..................................................................................................................... 22 
2.4 GetBalance API .......................................................................................................... 25 
 TransactionID and roundID matching. ............................................................................... 27 
 Live tables and limits information ......................................................................................... 29 
APPENDIX A - RESERVED ERROR CODES ................................................................................ 39 
APPENDIX B - API FLOW CHARTS ................................................................................................. 41 
APPENDIX C – Game Codes .............................................................................................................. 43 
APPENDIX D – Control Points .......................................................................................................... 44 
Hash Code Calculation ......................................................................................................................... 48 
 

LIVE AT ITS BEST

3

SUPPORT@VIVOGAMING.COM

V 1.5

1. INTEGRATION BASICS

1.1 Terms

The following terms and abbreviations are used in this document:

EC Client = External Client

VGS system = VGS server, VGS game software/system, developed and

supported by

VGS, provider.

EC Servers = External System Server

EC System = External System, Servers, Software and System

1.2 General Notes

VGS Games standard integration interface assumes:

A) VGS Systems-EC systems Integration is via B2B conguration, where

each side has its own system/back-end.

B) "One Wallet Integration" creates an environment where EC System, will

receive real time information, on any money transaction in VGS system

relates to EC Player, including Bets, Wins, Bonuses, and even Deposits. The

EC Players' Balance will become "One Updated Balance", and will create

transparent client to the player, which acts like any other game running in

EC System

C) In VGS-EC Common Wallet integration, EC system is the primary system,

and VGS is the secondary system. This means the EC system manages

primary user accounts database, balance, personal information, payment

operations etc. The VGS system manages only data necessary to perform

game operations. This data is either provided on game startup (login,

registration), or requested by VGS system from EC system. Similarly, VGS

system manages player balance in bounds of the turn, requesting

conrmation on bet from EC system and notifying it on win.

D) VGS-System keeps track of all gaming transaction and can offer

additional features such as Support, Bonuses, Cashiers, and additional

LIVE AT ITS BEST

4

SUPPORT@VIVOGAMING.COM

V 1.5

deposits methods, those can be used in addition as an optional feature by

VGS

E) Communication Protocol between VGS-EC systems is the Internet, using:

HTTP/HTTPS.

F) EC System must support TLS V 1.2 for supporting SSL (https) endpoints

1.3 Client Activation – Front End

VGS game clients are HTML5 applications loaded by a player’s browser.

Used method depends on EC front-end organization. For example, the

following general methods can be used:

a) Player loads EC container. EC container loads VGS application applet

inside.

b) Player loads VGS game lobby page from EC web site. The page loads

HTML5 Application inside.

c) EC website provides a link to VGS container, Player loads VGS container

via EC website.

In all cases, EC system must provide necessary startup parameters.

1.4 API Summary

There are 4 Methods in Seamless API:

• Authenticate: Used to validate an activation token and obtain the

player’s information (userID, Currency, Balance, etc.)

• Changebalance: Used to Add (WIN / CANCELEDBET) or substract

(BET) funds from a player balance.

• GetStatus: Used to obtain status information on a transcationID

• GetBalance: Used to obtain the latest balance from a userID

LIVE AT ITS BEST

5

SUPPORT@VIVOGAMING.COM

V 1.5

Example of Client Acvaon via URL

The player’s activation must be linked to a token, generated on ECS. This

token will be used for the Authentication request.

Lobby:

Example:

http://games.vivogaming.com/?token=5865885-

0141&operatorID=35&application=lobby

Parameters:

token= Id of the current session (generated by EC System)

operatorID= Id of the operator (xed value, provided by VGS Representative)

language= EN (2 Letters CODE; Client GUI Language)

application= Name of the application being opened

Important note: If the token can only be authenticated once, parameter

&lobbyactivation=true must be passed in the lobby activation.

Direct Game Activation (Roulette):

Example:

http://games.vivogaming.com/?token=5865885-

0141&operatorID=35&application=roulette&tableID=1

Parameters:

token= Id of the current session (generated by EC System)

operatorID= Id of the operator (xed value, provided by VGS Representative)

language= EN (2 Letters CODE; Client GUI Language)

tableID= Id of the table where the game will start

application= Name of the application being opened

LIVE AT ITS BEST

6

SUPPORT@VIVOGAMING.COM

V 1.5

1.5 Integration Workow

Refer to Annex B for Graphical Work Flows

1. First, EC system generates unique token associated with player. Token

must be provided as parameter to start a game. Recommendations for

token:

New token is preferred to be generated each time player starts a

game, In this case, token expires immediately after it was

authenticated via Authenticate API, by EC System

Token can also be generated as part of a lobby login, which will use

same token for multiple games activations, as long as it correlated to

a unique player on EC system.

In All cases token should automatically expire sometime after

creation, or if player has left EC site (session expired)

2. EC system then starts game client with token generated.

3. VGS system receives the token from the VGS-Game Client and

immediately checks the token by making authenticate API call to EC

system passing token obtained as parameter. In case token exists and valid

– EC responds with information about user and his current balance. VGS

system registers user on VGS side on rst entering. VGS system logins user

on VGS side (generates unique internal session ID for player).

4. For Any Game Transaction that Require change in EC Player Balance:

a. For each bet player made during game session, VGS system sends

ChangeBalance request to EC system. The bet is sent before

processing of game logic on VGS side, the bet is sent as soon as it

occurs. In the case where a game can have more than 1 bet for a

single round – each bet will be sent separately.

b. Wins are sent to EC system as ChangeBalance request after

processing game logic on the VGS server. VGS can send each win as

it occurs at the end of each round with total round win.

LIVE AT ITS BEST

7

SUPPORT@VIVOGAMING.COM

V 1.5

c. For any other Situation that Balance has changed, VGS System will

also call ChangeBalance; those cases can be Canceled bet, Cashier

Deposit, Support System Credit etc...

Note: Change Balance is a generic procedure, it always requires EC System

to debit or credit funds to a specic EC-Player

1.5 Fail-safety

In some circumstances, such as network problems or application failure on

EC side, VGS system may not receive a proper response from the Bet/Result

request from EC system. As a result, VGS system does not have enough

information to nalize bet/win operation, as necessary. As such if

transaction was not received and/or not processed, the turn must be rolled

back.

As soon as the failure is detected, the operation is added to the VGS

Integration Engine and the game is locked for the player (player can’t enter

game and/or continue play) until operation is resolved.

In the case where the error occurred for the bet operation – VGS system

sends Status request to EC system to check status of transaction. If the

transaction was approved on EC side – VGS system (depending on what

model of sending wins is used) will make instant win request or will add win

to total win of current round to x the player's balance on EC system side.

Win operation can never fail. In the case that EC system returns any error

for win operation - VGS system will just re-send Bet/Result request to EC

system with the same parameters of win operation again and again until it

will be approved by the EC system.

1.6 VGS game client error codes

If errors are received in the VGS game client-server communication, the

corresponding error is displayed to player. By default, the following errors

are reserved and displayed:

a) INTERNAL ERROR - internal error of VGS system, VGS development team

must perform investigations.

LIVE AT ITS BEST

8

SUPPORT@VIVOGAMING.COM

V 1.5

b) SESSION ERROR - displayed in case of any problems reached through

VGS -EC communication

c) Insufcient funds - if user’s balance reaches zero during the session.

d) Late Bets Rejections, Due to Bets that have arrived too late,

communication delay between VGS-EC Systems is usually the cause for

this error, In such case Although EC system has approved the bet, VGS

system will send an API call to return the funds, as they are not usable for

the coming round. In Such case the next Transaction Type, will be Canceled

Bet

1.7 VGS-EC Servers Validated IP's

VGS Integrations specialist will provide EC Representative with a list of VGS

IP's that will access EC Server. EC Administrator should make sure only

those IP's are actually accessing the API and reject trafc from different IP

address, so EC server should receive requests from these IP only.

LIVE AT ITS BEST

9

SUPPORT@VIVOGAMING.COM

V 1.5

2. Integration API Calls

2.1 Protocol format and description

Communication protocol is XML over HTTP/HTTPS. In order to send a

request, EC side calls specied URL with parameters submitted using GET

method. Response is returned as XML document format.

Note: EC System API functions should accept parameters as Not Case Sensitive,

from VGS calls, for example 'amount' and 'Amount' should both be valid

2.1.1 Request format

Example of request:

http://ECsystem.com/authenticate.do?token=UniqueToken&hash=8cb54b1924db

bd626a3b079a47527d17

Table below describes the 4 available API requests calls.

Please note, all calls are always made from VGS system to EC System.

Call

API Call Name

From

To

Description

1

Authenticate

VGS

EC

Authenticate a user token.

2

ChangeBalance

VGS

EC

Tries to debit or credit funds from

player’s account on EC system,

Update EC system with Transaction

Type which caused the Debit or

Credit.

In case of Bet and Win from VGS

Client Games, This API will also

LIVE AT ITS BEST

10

SUPPORT@VIVOGAMING.COM

V 1.5

include information about the History

of the Bet, as well as Win, History, and

the Result that produced that

Outcome.

If EC system conrms the operation,

VGS system will approve the Bet, In

Case of Bets Debit Request.

In case of Credits and Wins, EC

system has to approve the credit.

3

Status

VGS

EC

Returns status of specic transaction

previously made to EC System. This

API is used to allow VGS System to

verify status of unclear API calls, due to

Internet problems, In order for VGS

system to understand if those calls

have been committed on EC system or

Not.

Base on the EC result, VGS system will

take a decision, Or Doing nothing, or

Executing another API call for Debit or

Credit.

4

GetBalance

VGS

EC

Return Current EC-Player balance in

EC system. Base on EC System Player

ID

Note: URLs below are only examples and cannot be used for testing.

Staging/production URLs are Unique for Each EC Client, and will be delivered from

VGS Integration Representative.

LIVE AT ITS BEST

11

SUPPORT@VIVOGAMING.COM

V 1.5

2.1.2 Response format

General format of response:

<(PARAM_NAME_1)>(Value 1)</(PARAM_NAME_1)>

<(PARAM_NAME_X)>(Value X)</(PARAM_NAME_X)>

</REQUEST>

<TIME>(System time)</TIME> <RESPONSE>

<(PARAM_NAME_1)>(Value 1)</(PARAM_NAME_1)>

<(PARAM_NAME_Y)>(Value Y)</(PARAM_NAME_Y)> </RESPONSE>

</VGSSYSTEM>

Where:

Header must start with <VGSSYSTEM>

<REQUEST> - marks the VGS System Request section. This section returns

the original parameters that were submitted by VGS System;

<PARAM_NAME_1>…< PARAM_NAME_X>...< PARAM_NAME_Y> - specic

parameters in Request/Response sections;

(Value 1)… (Value X)… (Value Y) - Values of corresponding parameters

<TIME> - marks time of execution;

<RESPONSE> - marks Response section of EC System. This section contains

result of operation as

Set of parameters/values.

Example of response for a Change Balance API from VGS to EC system:

LIVE AT ITS BEST

12

SUPPORT@VIVOGAMING.COM

V 1.5

<TRNDESCRIPTION> GameRound:TableID=2 </TRNDESCRIPTION>

<ISROUNDFINISHED>false</ISROUNDFINISHED>

</REQUEST>

<ECSYSTEMTRANSACTIONID>5432154321</ECSYSTEMTRANSACTIO

NID>

</RESPONSE>

</VGSSYSTEM>

Note: In the XML Request Section, EC System returns the same parameters EC

system has received from VGS system on the original URL Request. The Response

XML Tag, Represent the Information Returned from EC System to VGS System

2.1.3 Security

Each API request has a "hash" parameter that contains MD5 hash (base64)

of string build basing on request parameters and secret PASS_KEY.

EC Receiving side can optionally validate request using hash passed (build

hash from parameters and PASS_KEY and compare it to passed one).

String for hash is built by concatenating parameters in specied order and

adding PASS_KEY at the end. Values of parameters must be the same as

passed in request (values should not be reformatted). If optional parameter

has not been passed or has no value - nothing should be inserted to string

at its place (do not insert "null" or "nil" or something like this).

LIVE AT ITS BEST

13

SUPPORT@VIVOGAMING.COM

V 1.5

For security reasons we strongly suggest implementing at least 2 out of the

3 security methods below:

1. HASH MD5 check on all requests.

2. Passing the session ID parameter in AUTH response that will be further

sent in Change Balance Calls.

3. IP whitelisting to Vivo authorized IPs (please request the updated list to

the support team)

2.2 Detailed API Format

2.2.1 Authenticate API

Uses: Request to authenticate a user token.

Request parameters:

• token: token provided by EC, must be a String up to 50 Chars in

length

• hash: order to generate hash: token

Example of request:

http://ECsystem.com/authenticate.do?token=SomeUniqueToken&hash=h4

732hfkjd7843hre013jh4j2l35l23

Response parameters: (Note, Optional parameters, should contain XML Tag,

but can be empty)

• USERID: Unique ID of user within EC system

• USERNAME: optional. Username. (Displayed name).

• FIRSTNAME: optional. First name.

• LASTNAME: optional. Last name

• EMAIL: optional. Email

• CURRENCY: ISO code of player’s currency.( Please note that the

currency code passed on the rst activation will be the currency for

the player in our system and cannot be changed players can only

have one associate currency )

• BALANCE: (2 Digit Precision Long Number), current balance of

player on

EC system side.

LIVE AT ITS BEST

14

SUPPORT@VIVOGAMING.COM

V 1.5

Note: parameters username, rstname, lastname and email are optional; VGS

system can store them if necessary for EC convenience. However it is highly

recommended to transfer the username since it will serve as the user displayed

game across all game applications and lobbies. Those Parameters are more

important in the case of integrators that require additional VGS Modules; Such as

"VGS Support Module". (In that case, it can help the support guy getting as more

information on the Player as possible), On the basic integration, those parameters

can also benet those who use VGS System for Additional Backend as well. (In those

cases, identifying the users can be helpful)In any other situation, those optional

parameters are irrelevant.

Note: EC System Response parameters should always be Upper Case Letters

Example of response from Authenticate API in case of successful operation:

<TOKEN>sometoken</TOKEN>

</REQUEST>

<USERNAME>optional_someplayernamek</USERNAME>

<FIRSTNAME>optional_playerrstname</FIRSTNAME>

<LASTNAME>optional_lastname</LASTNAME>

<EMAIL>optional_email@mail.com</EMAIL>

LIVE AT ITS BEST

15

SUPPORT@VIVOGAMING.COM

V 1.5

</RESPONSE>

</VGSSYSTEM>

• GAMESESSIONID Is optional parameter in response format, In case

provided by EC system this parameter will be forward to each one

of the ChangeBalance future request.

This is security feature that allows EC system validate

GAMESESSIONID parameter.

IMPORTANT NOTE: GAMESESSIONID tag value should not exceed

the 50 characters in the response.

Example of response in case of failed Authenticate API operation:

<TOKEN>someuniquetoken</TOKEN>

</REQUEST>

<RESULT>FAILED</RESULT>

</RESPONSE>

</VGSSYSTEM>

2.2.2 ChangeBalance API

Uses: Request to Debit or Credit funds to Balance of EC Player.

Request parameters:

• userId: ID of user in EC system

• Amount: Transaction Amount

• TransactionID: Unique ID of the transaction at VGS side (Long Integer,

or string of 32 hexadecimal, depending on the game)

Important Note: In case that EC system approves the money

transaction, EC System must store VGS Transaction ID in the EC

System Database, and uniquely Index the id in its own

LIVE AT ITS BEST

16

SUPPORT@VIVOGAMING.COM

V 1.5

Database. EC System Must Not process same VGS Transaction

ID twice, therefor EC System need to make sure the query for

the VGS Transaction ID will be fast on its side. This issue will also

apply to optimize the Status API call.

TransactionID validation should be per user ID + RoundID basis,

meaning the same transaction ID can be repeated for two

different userIDs for example but not for the same

transactionID+RoundID+UserID combination.

• TrnType: Transaction Type: Text represents one of several transaction

types: look bellow

1. BET (Debit - Game Bet Transaction)

2. WIN (Credit - Game Win Transaction)

3. CANCELED_BET (Credit - refund a previous bet transaction,

that was rejected due to late arrival to VGS server)

• TrnDescription : Base on TrnType, will contain Optional additional

data

1. BET,WIN, CANCELED_BET: Description: The Live Table ID,

which uniquely represent the Table in the casino oor.

2. In case of a TIP, the TrnDescription will include:

<TRNDESCRIPTION>PlayerTip:TableID=X</TRNDESCRIPTIO

N>

• roundId: unique ID of game round at VGS side. Game round can have

several Bet/Result requests., This ID will be unique number among all

different games and tables, Same game round for bet and win will

contain same rounded (this can help matching pairs of rounds

belongs to the same round)

• gameId: game ID at VGS side. Please refer to Annex C.

• sessionId=785df376123dfg - In case provided in INIT response

(GAMESESSIONID)

• History: On Roulette, Craps and Baccarat: on bets Transactions

represent a set of chip position and chip value per position, on wins:

the result number or cards plus the set of winning chips positions

and a wins values per position, on BJ Only: Split, Double, Bet,

Insurance,

LIVE AT ITS BEST

17

SUPPORT@VIVOGAMING.COM

V 1.5

The Exact Mapping point and each point description is described at

Annex D (Mapping Points)

In case of a tip, the history tag will include: History=DEALER TIP<

• isRoundFinished: “true” or “1” values represent that this game round

has been completed, “false” or “0” values means this game is in

progress, and other updates can apply, in BJ this parameter, is false

as long as the BJ Round was not completed yet, On Roulette, Craps

and Baccarat, False is sent during the Bet, and True is send during

the Win API call.

• hash: order: userId, Amount, TrnType, TrnDescription, roundId,

gameId, history

Note: if we send a transactionID already processed, you should not affect

balance again or fail the request. Please reply with the same

ECSYSTEMTRANSACTIONID you provided when it was processed, and

current balance, without affecting balance again.

Example of "ChangeBalance" API request:

(URL Request from VGS System to EC System)

http://ECsystem.com/ChangeBalance.aspx?userId=12345&Amount=75.00&

TransactionID=12344546&TrnType=BET&TrnDescription=GameRound:Tabl

eID=2&roundId=12345&gameId=5&History=127,15;129,50&isRoundFinished=f

alse&hash=4b3j2n4n533k234j5k4jnn3h4k3k23&sessionId=785df376123dfg

Response Parameters (XML Format)

• RESULT: Result of operation on EC side, either OK or FAILED

• ECSYSTEMTRANSACTIONID: Long Integer (Max

9223372036854775807), EC System Transaction ID ( ID of debit/credit

Transaction ID in EC System) (only if result is OK)

• BALANCE: New Balance of user in EC system after the operation

(only if result is OK)

• CODE: Error code in EC system (only if operation has FAILED)

Important Note: In case that the TransactionID sent was already processed

in the past by EC System, EC System should response with Result="OK" and

LIVE AT ITS BEST

18

SUPPORT@VIVOGAMING.COM

V 1.5

the proper ECSYSTEMTRANSACTIONID that was processed in the past, DO

Not response with Error code 302 for that case.

Example of a response from EC System in case of successful

ChangeBalance operation:

<TRNDESCRIPTION> GameRound:TableID=2 </TRNDESCRIPTION>

<ISROUNDFINISHED>false</ISROUNDFINISHED>

</REQUEST>

<ECSYSTEMTRANSACTIONID>5432154321</ECSYSTEMTRANSACTIO

NID>

</RESPONSE>

</VGSSYSTEM>

Example of ChangeBalance response in case of failed operation:

Note: EC system must replay with error code 300, in case Bet command is bigger

than the player balance, in such case, EC system should not affect the player

balance

LIVE AT ITS BEST

19

SUPPORT@VIVOGAMING.COM

V 1.5

<TRNDESCRIPTION> GameRound:TableID=2 </TRNDESCRIPTION>

<ISROUNDFINISHED>false</ISROUNDFINISHED>

</REQUEST>

<RESULT> FAILED </RESULT>

</RESPONSE>

</VGSSYSTEM>

IMPORTANT NOTES:

Note 1: In any case of calls to ChangeBalance due to Game Rounds, Bet and Win

operation are processed as Separate Multiple API Calls to EC System

Note 2: "ChangeBalance" API call must replay to VGS System in less than Maximum

of 3 seconds, Due to the fact that VGS System is a Live Betting System, Bets Needs

to get conrmation in a short time frame, Please note that higher response times

are risking the bet to be rejected, and funds will be returned to ES system in a

different API call Immediately

LIVE AT ITS BEST

20

SUPPORT@VIVOGAMING.COM

V 1.5

Note3: History Description is not required as a return parameter in the Response

XML

Note4: VG server will always report win transaction with value 0, this is meant to

always have a correlation between the Bet and the Win, if VG provide

TransactionType=WIN with Amount 0, please return OK as standard Win reported.

There will be one Sidebet Win to close all Side bets Bets per seat

Note5: On Blackjack there may be more than one bet per round, for example when

a player doubles, takes insurance or splits his hand. Moreover, the player’s may take

up to 2 seats on the table, so there may be different bets for the same round for one

player. In order to be able to make a match of these BETS and WINS you may use

the content of the History tag in the changebalance request which has the

following format: BLACKJACK:{type};{seatID}\{handID}:CARDS-{Cards} where {type}

is one of the INITBET/DOUBLE/SPLIT/INSURANCE/WINS. So a player can have a bet

with seatID=1, and one with seatID=2.

When a hand is split, the request will have this format:

"history=BLACKJACK:SPLIT;X\Y" in these cases there will be more than one WIN for

this seat, player and round, so there will be a win with

"history=BLACKJACK:WINS;X\'Y' and one with "history=BLACKJACK:WINS;X\'Y+1' "

Example:

BLACKJACK: WIN;3\1:CARDS-10$3-114$2>23\6$1-7$4-13$1

Note6: On Blackjack, Integrators have a maximum of 3 seconds to approve

continued bets (split / double / insurance / even money / side bets).

Otherwise if VG gets the response too late, we will issue canceled_bet for that

specic Bet request.

LIVE AT ITS BEST

21

SUPPORT@VIVOGAMING.COM

V 1.5

Note7: On Blackjack, CANCELED_BET will include the indication about the type of

CANCELED_BET for each Seat / Hand ID, in addition we will include the cards

details.

Note that on Blackjack CANCELED_BET it is possible that INITBET will be successful

but DOUBLE or SIDEBET bet will be Canceled as they are continues, in that case

only the additional BET will be canceled and the Round will continue with the Valid

Bets, in all cases the Round ID will be shared between Bet / Win and Bet /

Canceled_Bet with indication about the type of Bet which was canceled in that

round.

Note8: EC System should NOT approve Wins / Canceled_bet requests for userID in

a Round ID in which they don’t have a valid BET.

In such cases please return Code 299.

Note9: In case of Promo / Tournament WIN, the transaction will include the

following information:

This API request will be a ChangeBalance WIN request, and will include the amount

to be credited.

Example of a win call for Promo / Tournament WIN

TrnType=WIN&userId=USER1&Amount=50.00&TransactionID=124990182896&roundI

d=29&gameId=777&TrnDescription=GameRound:TableID=77777&History=Promo:C

ASH:&isRoundFinished=0&sessionId=&hash=

GameRound:TableID=77777"

history will only say this: "Promo:CASH:

LIVE AT ITS BEST

22

SUPPORT@VIVOGAMING.COM

V 1.5

Canceledbet

TRNTYPE Canceledbet is a request to credit the player with funds. It will

have a unique transactionID, and will include the amount to credit the

player.

It will also include the RoundID (same as the original bet) and information

on the History tag, for you to know which round and transaction is being

refunded (example INIT / DOUBLE / SPLIT / SIDEBET / ETC in blackjack).

In terms of how the ow should be in the API, cancelebed works the same

as WIN, adding funds to the player, there is no need to match the amounts

when approving the request

Basic ow of this request:

1. We send you a BET request;

2. You affect balance, and then send us back the response

3. This response never gets to us for any reason, or gets too late

4. We will issue a getstatus request for the transactionID of the bet

5. if your response is OK (meaning you deducted balance from the

player), we will issue a Canceledbet. (if you respond with 302 to the

status, we will not issue a canceledebet)

6. Inside the history eld of the canceledbet request you will nd

description to match the Bet which was canceled (history tag)

2.2.3 Status API

Uses: Query EC System, for a specic transaction status

Request parameters:

• userId: ID of user in EC system

• casinoTransactionId: VGS transaction ID

• hash: order: userId, casinoTransactionId

Example of request:

http://ECsystem.com/requeststatus.do?userId=12345&casinoTransactionId=

12344546&hash=8cb54b1924dbbd626a3b079a47527d17

Response parameters:

LIVE AT ITS BEST

23

SUPPORT@VIVOGAMING.COM

V 1.5

• result: Result of operation on EC side, either OK or FAILED

Note: Result of OK, means the transaction ID was processed at

EC System, and at the time of the process the bets or wins were

approved!

In case bets or wins for this transaction ID where not approved

result should return FAIL

In Case of FAILED, only Error Code 302 indicates the transaction

ID was not processed.

Any other error messages codes will cause VGS system to check

the same status over and over again.

• ECSystemTransactionID: ID of bet/win transaction in EC SYSTEM

(only if result is OK)

• code: Error code in EC system (only if result is FAILED)

Example of response in case of successful operation:

</REQUEST>

<ECSYSTEMTRANSACTIONID>154456456</ECSYSTEMTRANSACTIO

NID>

</RESPONSE>

</VGSSYSTEM>

Example of Status response in case of failed operation:

</REQUEST>

LIVE AT ITS BEST

24

SUPPORT@VIVOGAMING.COM

V 1.5

<RESULT>FAILED</RESULT>

</RESPONSE>

</VGSSYSTEM>

LIVE AT ITS BEST

25

SUPPORT@VIVOGAMING.COM

V 1.5

Important Notice for GetStatus API

Note: Error 302, Informs VGS that the transaction ID in the query URL was not

processed on EC System in the Past.

Error 302 is the proper response from EC system in case the queried transaction ID

was not processed by the EC system in the Past.

2.2.4 GetBalance API

Uses: Query EC System, for Player current Balance

Request parameters:

• userId: ID of user in EC system

• hash: order: userId

Example of request:

http://ECsystem.com/getbalance.do?userId=12345&hash=8cb54b1924dbbd

626a3b079a47527d17

Response parameters:

• result: Result of operation on EC side, either OK or FAILED

• balance: Current balance of player in EC System (only if result is OK)

• code: Error code in EC system (only if result is FAILED)

Example of response in case of successful operation:

LIVE AT ITS BEST

26

SUPPORT@VIVOGAMING.COM

V 1.5

</REQUEST>

</RESPONSE>

</VGSSYSTEM>

Example of response in case of failed operation:

</REQUEST>

<RESULT>FAILED</RESULT>

</RESPONSE>

</VGSSYSTEM>

LIVE AT ITS BEST

27

SUPPORT@VIVOGAMING.COM

V 1.5

3. TransactionID and roundID

matching.

The BET and WIN transactions can be related using the Round ID, this

is a failsafe mechanism so that no WIN is approved if there is no BET on

the same RoundID.

The Round ID will be the same for bet/win of same round. And each

transaction will have unique Transaction ID. Transaction IDs are always

unique values per transaction.

There will always be a WIN transaction posted, even if the amount of

the WIN is 0.

Live Games

Live Roulette – There will always be only 1 bet transaction and 1 win

transaction per RoundID (each has unique transaction ID and same

round ID)

Live Baccarat - There will always be only 1 bet transaction and 1 win

transaction per RoundID (each has unique transaction ID and same

round ID)

Live Blackjack - user can have multiple bets per round (initial bet, split,

double) and only one Win (each has unique transaction ID and same

round ID) - also note that in live blackjack player may take more than

one seat, in that case the user can have second hand with multiple

transactions in the same round ID (one WIN per seat). The Seat value

can be seen in the History Tags.

Note: The roundIDs/TransactionIDs are unique for each tableID,

however they can be used again for other tableIDs.

Live Casino Holdem- user can have multiple bets per round (Ante,

Bonus, Call) and only one Win (each has unique transaction ID and

same round ID).

RNG

On RNG games there will always be at least 1 BET and 1 WIN per

RoundID (each has unique transaction ID and same round ID), however

LIVE AT ITS BEST

28

SUPPORT@VIVOGAMING.COM

V 1.5

there might also be multiple WIN transactions for same round ID, in

case a bonus or free spins are triggered.

LIVE AT ITS BEST

29

SUPPORT@VIVOGAMING.COM

V 1.5

4. Live tables and limits information

For Operators who wish to design the games lobby independently, this request can allow to display

dynamic games menu inside the website in real me, the response for this request will provide the

operator with informaon about the acve and open live tables in the system, together with their

set of available limits in JSON format.

URL for requests:

hp://1vivo.com/ash/getacvetablesex.aspx?

Request parameters:

• Gamename: The Live game you wish to retrieve its status. Can be: Roulee, Baccarat,

Craps or Blackjack

• OperatorID: Unique parameter provided by VGS representave and set globally for all the

website

• Playercurrency: Player Currency should be passed in the request; Currency parameter is

provided in user login response or it may be provided by External system (the currency

eld is relevant when working with mulcurrency limits).

Requests examples per game:

hp://1vivo.com/ash/getacvetablesex.aspx?GameName=baccarat&OperatorID=41&PlayerCurre

ncy=USD

hp://1vivo.com/ash/getacvetablesex.aspx?GameName=roulee&OperatorID=41&PlayerCurre

ncy=USD

hp://1vivo.com/ash/getacvetablesex.aspx?GameName=blackjack&OperatorID=41&PlayerCurr

ency=USD

hp://1vivo.com/ash/getacvetablesex.aspx?GameName=poker&OperatorID=41&PlayerCurrenc

y=USD

LIVE AT ITS BEST

30

SUPPORT@VIVOGAMING.COM

V 1.5

Baccarat response example:

{

"gameData":{

"tables":{

"3":{

"tableId":"3",

"dealerName":"BULGARY1",

"videoUrls":null,

"limits":[

{

"limitName":"Standard",

"limitMin":"1.0000",

"limitMax":"200.0000",

"Chips":[

"0.1",

"1",

"5",

"10",

"50",

"100",

"250"

],

"limitid":"LMT7E1C2F-F381-43BD-BB99-04775BBE",

"player":{

"min":"1",

"max":"200"

},

"tie":{

"min":"1",

"max":"25"

},

"banker":{

"min":"1",

"max":"200"

},

"big":{

"min":"1",

"max":"25"

},

"eitherPair":{

"min":"1",

"max":"25"

},

"small":{

LIVE AT ITS BEST

31

SUPPORT@VIVOGAMING.COM

V 1.5

"min":"1",

"max":"25"

},

"playerPair":{

"min":"1",

"max":"25"

},

"perfectPair":{

"min":"1",

"max":"25"

},

"bankerPair":{

"min":"1",

"max":"25"

},

"playerBonus":{

"min":null,

"max":null

},

"bankerBonus":{

"min":null,

"max":null

}

},

{

"limitName":"VIP",

"limitMin":"10.0000",

"limitMax":"1500.0000",

"Chips":[

"1",

"5",

"10",

"50",

"100",

"500",

"1000"

],

"limitid":"LMT7C8903-6B5B-4E72-83FB-943FEDA2",

"player":{

"min":"10",

"max":"1500"

},

"tie":{

"min":"10",

"max":"200"

LIVE AT ITS BEST

32

SUPPORT@VIVOGAMING.COM

V 1.5

},

"banker":{

"min":"10",

"max":"1500"

},

"big":{

"min":"10",

"max":"200"

},

"eitherPair":{

"min":"10",

"max":"200"

},

"small":{

"min":"10",

"max":"200"

},

"playerPair":{

"min":"10",

"max":"200"

},

"perfectPair":{

"min":"10",

"max":"200"

},

"bankerPair":{

"min":"10",

"max":"200"

},

"playerBonus":{

"min":null,

"max":null

},

"bankerBonus":{

"min":null,

"max":null

}

],

"stats":null,

"roundId":"127076007",

"open":"True",

"state":"placingBets"

},

LIVE AT ITS BEST

33

SUPPORT@VIVOGAMING.COM

V 1.5

Roulee response example:

{

"gameData":{

"tables":{

"1":{

"tableId":"1",

"dealerName":"BULGARY1",

"videoUrls":null,

"limits":[

{

"limitName":"Standard",

"limitMin":"0.1000",

"limitMax":"1500.0000",

"Chips":[

"0.1",

"1",

"5",

"10",

"25",

"100",

"250"

],

"limitid":"LMT8C2ECD-9945-432A-AA74-C48F50B7",

"player":{

"min":"0.1",

"max":"20"

},

"tie":{

"min":"0.1",

"max":"50"

},

"banker":{

"min":"0.1",

"max":"30"

},

"big":{

"min":null,

"max":null

},

"eitherPair":{

"min":"0",

"max":"1500"

LIVE AT ITS BEST

34

SUPPORT@VIVOGAMING.COM

V 1.5

},

"small":{

"min":null,

"max":null

},

"playerPair":{

"min":"5",

"max":"1500"

},

"perfectPair":{

"min":"0",

"max":"1000"

},

"bankerPair":{

"min":"5",

"max":"1000"

},

"playerBonus":{

"min":null,

"max":null

},

"bankerBonus":{

"min":null,

"max":null

}

},

{

"limitName":"VIP",

"limitMin":"1.0000",

"limitMax":"3000.0000",

"Chips":[

"1",

"5",

"10",

"50",

"100",

"500",

"1000"

],

"limitid":"LMTA32425-84F4-40D9-BC27-168E3688",

"player":{

"min":"1",

"max":"100"

},

"tie":{

LIVE AT ITS BEST

35

SUPPORT@VIVOGAMING.COM

V 1.5

"min":"1",

"max":"200"

},

"banker":{

"min":"1",

"max":"150"

},

"big":{

"min":null,

"max":null

},

"eitherPair":{

"min":"0",

"max":"3000"

},

"small":{

"min":null,

"max":null

},

"playerPair":{

"min":"10",

"max":"3000"

},

"perfectPair":{

"min":"0",

"max":"2000"

},

"bankerPair":{

"min":"10",

"max":"2000"

},

"playerBonus":{

"min":null,

"max":null

},

"bankerBonus":{

"min":null,

"max":null

}

],

"stats":null,

"roundId":"127075993",

"open":"True",

LIVE AT ITS BEST

36

SUPPORT@VIVOGAMING.COM

V 1.5

"state":"placingBets"

},

Blackjack response example:

{

"gameData":{

"tables":{

"16":{

"seats":"",

"tableId":"16",

"dealerName":null,

"videoUrls":null,

"limits":[

{

"limitName":"Standard",

"limitMin":"5.0000",

"limitMax":"250.0000",

"Chips":[

"16}"

],

"limitid":"LMT902EBD-B2C4-4B09-805E-788C7D95"

},

{

"limitName":"VIP",

"limitMin":"25.0000",

"limitMax":"2000.0000",

"Chips":[

"16}"

],

"limitid":"LMT213EA5-9A00-48EE-BF0B-8186DAA6"

}

],

"stats":null,

"roundId":null,

"open":"True",

"state":null

},

"18":{

"seats":"",

"tableId":"18",

"dealerName":null,

"videoUrls":null,

"limits":[

{

LIVE AT ITS BEST

37

SUPPORT@VIVOGAMING.COM

V 1.5

"limitName":"Standard",

"limitMin":"5.0000",

"limitMax":"250.0000",

"Chips":[

"18}"

],

"limitid":"LMTBFA1A7-2ED9-4080-A2C7-BC0EA785"

},

{

"limitName":"VIP",

"limitMin":"25.0000",

"limitMax":"2000.0000",

"Chips":[

"18}"

],

"limitid":"LMT2D19E7-FF7C-4FA0-951C-A3DF570A"

}

],

"stats":null,

"roundId":null,

"open":"True",

"state":null

},

"211":{

"seats":"",

"tableId":"211",

"dealerName":null,

"videoUrls":null,

"limits":[

],

"stats":null,

"roundId":null,

"open":"True",

"state":null

},

"212":{

"seats":"",

"tableId":"212",

"dealerName":null,

"videoUrls":null,

"limits":[

],

LIVE AT ITS BEST

38

SUPPORT@VIVOGAMING.COM

V 1.5

"stats":null,

"roundId":null,

"open":"True",

"state":null

}

Response parameters:

In the response each block of informaon is separate by “[NEW_LINE]” each block contains

informaon of one operator limit per table.

TableID: Indicates on a unique physical table in the casino oor, the parameter should be taken

from the response and be used in the game acvaon URL.

Limit Name: Should be taken from the response and displayed as limit descripon in the website

menu.

Limit ID: Should be taken from the response and later be passed in the URL to acvate the game.

Limit Min: Should be taken from the response and displayed as limit descripon in the website

menu.

Limit Max: should be taken from the response and displayed as limit descripon in the website

menu.

Dealer Name: Should be taken from the response and be displayed in the website menu.

Open: Operators should display only tables with status “Open”:“True” in the website game menu

Stats: Oponal parameter, operators can show last results in his website. (In Baccarat shows latest

result history with winning hand value, for example T;6 = latest winning hand was a TIE of 6) In

roulee simply shows latest winning number.

In Blackjack, Baccarat, Caribbean poker and Dragon Tiger will show latest dealer hand values and

cards.

The proper way to display dynamic menus in the website is by displaying game tles according to

the available game names such as: Roulee / Blackjack / Baccarat Under each one of those tles

should be displayed the buons to launch the live tables under this game. Each buon should be

for a specic limit per table and contain the following informaon.

TableID, Limit Name, Limit Min – LimitMax, Dealer Name, Table Status

LIVE AT ITS BEST

39

SUPPORT@VIVOGAMING.COM

V 1.5

APPENDIX A - RESERVED ERROR

CODES

VGS Client Errors Codes:

Note: VGS Errors generated due to an EC System fault are Bolded

Code Description

2 token was not found

3 parameters mismatch

5 integrator URL error

29 database error

55 integrator url does not have mapping

56 Integrator server error

101 Invalid Token

102 Session Expired

103 Invalid Status Table Reading

104 Table Status Does Not Exist

105 Late Bets Rejection

106 Table is in closing procedure

107 Table is closed

108 No Proper Bets Reported

109 Insufcient Funds at STP System, newbalance=[XXXXX]

110 Player Record is Locked for too long

111 Player Balance Update Error

137 Integrator Player Operator Has Been Changed

138 Integration error, unable to build integrator player in host system

141 Internal DB Error, Could not locate built player id

142 Internal DB Error, Fail to insert Integrator to Mapping Table

155 Invalid Table ID

175 Player Record is Locked for too long

200 Integration Bet Error, Integrator Description=[Description]

212 Insufcient Funds at Integrator System,newbalance=XXXX

LIVE AT ITS BEST

40

SUPPORT@VIVOGAMING.COM

V 1.5

222 Permission denied

555 Integrator Has Past Fault that needs attention; please contact your

supplier – (Fail Safety System)

EC system to VGS system API Error Calls

Code Description

300 Insufcient funds

301 Operation failed

302 Unknown transaction id for Status API

310 Unknown user ID

399 Internal Error

400 Invalid token

500 Invalid hash

812 Betting limit reached

299 Win of unrecognized bet

LIVE AT ITS BEST

41

SUPPORT@VIVOGAMING.COM

V 1.5

APPENDIX B - API FLOW CHARTS

Example of ow, Authenticate and Bets/Wins

LIVE AT ITS BEST

42

SUPPORT@VIVOGAMING.COM

V 1.5

Example of ow, Fault in Bet, Triggers Status Request

LIVE AT ITS BEST

43

SUPPORT@VIVOGAMING.COM

V 1.5

APPENDIX C – Game Codes

European Live Roulette = 1

Live Baccarat=2

Live Blackjack=8

American Live Roulette=5

Dragon Tiger = 18

Casino Holdem=202

SicBo = 21

TeenPatti = 218

Xoc Dia = 220

RNG game codes will depend on the each RNG game (Example:

gameId=SlotMachine_DemiGods4)

LIVE AT ITS BEST

44

SUPPORT@VIVOGAMING.COM

V 1.5

APPENDIX D – Control Points

Note: This Annex is intended for specic integrators who wish to manage full history

on their own back end system. In case your VGS Integration specialist will nd this

relevant, you will receive this annex in addition.

European Roulette Control Points

LIVE AT ITS BEST

45

SUPPORT@VIVOGAMING.COM

V 1.5

Baccarat Result Description:

Bets / wins and result history description inside ChangeBalance Call.

when the TRNTYPE=BET you will nd detailed information about all player

betting points inside the history eld:

1: player

2: banker

3: tie

4: player pair

5: banker pair

6: player bonus

7: banker bonus

8: perfect pair

9: either pair

10: big

11: small

when the TRNTYPE=WIN you will get information about the winnings per

each betting point, in addition to description of the cards in that round.

LastResaultCards=P:5$1,B:5$2,P:3$3,B:14$3

card values are from 2-10 (same value) 11=J, 12=Q, 13=K, 14=A

suit values are 1-4 where 1=clubs, 2=heart, 3=diamond, 4=spades

LIVE AT ITS BEST

46

SUPPORT@VIVOGAMING.COM

V 1.5

Blackjack Result Description:

Blackjack BET transacon Type the descripons in History:

• INITBET

• DOUBLE

• SPLIT

• InsuranceEvenMoney

• sideBetPpair

• sideBet21p3

Example:

&History=BLACKJACK:INITBET;2\1

&History=BLACKJACK:SPLIT;2\1

&History=BLACKJACK:InsuranceEvenMoney;2\1

&History=BLACKJACK:DOUBLE;2\1

&History=BLACKJACK:sideBetPpair;2\1

&History=BLACKJACK:sideBet21p3;2\1

Note: BET will include the indication about the type of BET type and the Seat / Hand

ID

Blackjack WIN transacon Type the descripons in History:

• SIDE_BET__WIN

• WIN

Example:

&History=BLACKJACK:SIDE_BET__WIN;4\1:CARDS=14$3-8$3>20\10$1-13$1

&History=BLACKJACK:WIN;4\1:CARDS=14$3-8$3>20\10$1-13$1

LIVE AT ITS BEST

47

SUPPORT@VIVOGAMING.COM

V 1.5

Note: WIN will include the indication about the type of Win (Side Bet / Main bet) for

each Seat / Hand ID, in addition we will include the cards details.

Blackjack CANCELED_BET transacon Type the descripons in History:

• CANCELED_INITBET

• CANCELED_DOUBLE

• CANCELED_SPLIT

• CANCELED_InsuranceEvenMoney

• CANCELED_SIDE_BET

&History=BLACKJACK:CANCELED_INITBET;2\1

&History=BLACKJACK:CANCELED_DOUBLE;2\1

&History=BLACKJACK:CANCELED_SPLIT;2\1

&History=BLACKJACK:CANCELED_InsuranceEvenMoney;2\1

&History=BLACKJACK:CANCELED_sideBetPpair;2\1

&History=BLACKJACK:CANCELED_sideBet21p3;2\1

LIVE AT ITS BEST

48

SUPPORT@VIVOGAMING.COM

V 1.5

Hash Code Calculation

Hash code is calculated as an MD5 Standard hash

Note 1: The code will hash only the parameters values, and not the titles involved

Note 2: In case of multiple parameters, they should be concatenated in the exact

order described for each of the 4 calls

Online calculator can be found here: http://www.md5.cz/

Authenticate Hash:

Parameters to Hash:

1. Token

2. PassKey

Format: MD5(Token+PassKey)=HASH

ChangeBalance Hash:

Parameters to hash: (Hash calculation is performed only on the following

parameters)

1. userId

2. Amount

3. TrnType

4. TrnDescription

5. RoundId

6. GameId

7. History

LIVE AT ITS BEST

49

SUPPORT@VIVOGAMING.COM

V 1.5

Format:

MD5(userid+Amount+TrnType+TrnDescription+roundid+GameId+History+PassKe

y)=HASH

ChangeBalance Example

Example URL Sent to your server: using Pass Key 123456

http://127.0.0.1/ECServer/ChangeBalance.php?TrnType=BET&userId=y1234&

Amount=0.6&TransactionID=2466430041&roundId=1465989301&TrnDescri

ption=GameRound:TableID=33&gameId=193&History=Slot:Once Upon a

Time&isRoundFinished=false&hash=7f52d5615511e2862968f9589704c118

Here are the parameters:

TrnType=BET

userId=y1234

Amount=0.6

TransactionID=2466430041

roundId=1465989301

TrnDescription=GameRound:TableID=33

gameId=193

History=Slot:Once Upon a Time

isRoundFinished=false

hash= 7f52d5615511e2862968f9589704c118

Now will build the string for the hash according to this order: userId +

Amount + TrnType TrnDescription + roundId + gameId + History

This is how it looks: (With Spaces and +)

y1234 + 0.6 + BET + GameRound:TableID=33 + 1465989301 + 193 + Slot:Once

Upon a Time

This is how it should look

y12340.6BETGameRound:TableID=331465989301193Slot:Once Upon a Time

After adding the passkey:

y12340.6BETGameRound:TableID=331465989301193Slot:Once Upon a

Time123456

LIVE AT ITS BEST

50

SUPPORT@VIVOGAMING.COM

V 1.5

Now Run MD5: (http://www.md5.cz/)

MD5 ("y12340.6BETGameRound:TableID=331465989301193Slot:Once Upon

a Time7f1c5d") = 7f52d5615511e2862968f9589704c118

Hash=76b4d532a44efda2d46ae300d9a88148

GetStatus Hash:

Parameters to Hash:

1. userId

2. casinoTransactionId

Format: MD5(userId+CasinoTransactionId+PassKey)= Hash

GetBalance Hash:

Parameters to Hash:

1. userId

Format: MD5(userId+PassKey)=Hash

LIVE AT ITS BEST

51

SUPPORT@VIVOGAMING.COM

V 1.5

A summary table is below

Method type

Hash Parameters

Authencate

1. Token

2. PassKey for tesng: 7f1c5d

Format: MD5(Token+PassKey)= Hash

ChangeBalance

1. userId

2. amount

3. Trntype

4. TrnDescripon

5. RoundId

6. Gameid

7. History

Format:

MD5(userid+amount+trntype+TrnDescripon+roundid+gameID+History+

PassKey)=HASH

GetStatus

1. userId

2. casinoTrsnaconId

Format: MD5(userId+CasinoTransaconID+PassKey)= Hash

Getbalance

1. userId

Format: MD5(userId+PassKey)=Hash

Note: Your passkey will be delivered by VG integration manager

LIVE AT ITS BEST

52

SUPPORT@VIVOGAMING.COM

V 1.5