MAL0147-1-Transparent Account Integration Manual

User Guide
TRANSPARENT ACCOUNT
INTEGRATION MANUAL
Play’n GO
Transparent Account Page 2 (36)
Integration Manual
Date Document id
2021-01-21 MAL0147
TRANSPARENT ACCOUNT INTEGRATION MANUAL
Table of Contents
1 Introduction ....................................................................................................... 4
2 Important Information ........................................................................................ 4
3 Integration overview .......................................................................................... 5
3.1 Conceptual Integration Overview .................................................................. 5
3.2 Integration Instructions ................................................................................. 5
3.3 Test Cases ................................................................................................... 6
3.4 Authentication ............................................................................................... 6
3.5 Session handling .......................................................................................... 7
3.6 Common Game Session ................................................................................... 8
3.7 Jurisdiction ..................................................................................................... 9

3.7.1 Transactional security ...........................................................................................11
3.7.2 Reconciliation ........................................................................................................11
3.7.3 Separation of Bonus and Real Money ..................................................................11
4 Services .......................................................................................................... 11
4.1 Authenticate ............................................................................................... 11
4.1.1 Authenticate Service Details .................................................................................12
4.2 Reserve ...................................................................................................... 14

4.2.1 Reserve Service Details ........................................................................................15
4.3 Release ...................................................................................................... 19

4.3.1 Release Service Details ........................................................................................19
4.4 Balance ...................................................................................................... 24

4.4.1 Balance Service Details ........................................................................................24
4.5 Cancel Reserve .......................................................................................... 25

4.6 GetUnfinishedGames ................................................................................. 29
www.playngo.com | info@playngo.com
Integration Manual
Date Document id
2021-01-21 MAL0147
4.6.1 GetUnfinishedGames Service Details ...................................................................31
5 Reload Functionality ........................................................................................ 32

5.1 Free Game Test Cases .............................................................................. 32
5.1.1 Definitions / Preconditions.....................................................................................33
5.1.2 Create Free Game via API ....................................................................................33
5.1.3 Free Game as Achievement Prize ........................................................................33
6 Supplement ..................................................................................................... 34
6.1 Status Codes .............................................................................................. 34
6.2 Status Message .......................................................................................... 35
6.3 Session States............................................................................................ 36
6.4 Transaction Types ...................................................................................... 36
Integration Manual
Date Document id
2021-01-21 MAL0147
1 Introduction
The objective of this manual is to provide the reader with the information necessary
to integrate with a Play'n GO Game system. The typical reader is a technical
manager and / or staff that will carry out the integration work.
Using the transparent account, the integration is done via POX/XML as transport
format.
2 Important Information
Below is stated important information that the reader must keep in mind during the
rest of the integration work. Please refer back to this section to avoid “simple” errors
in the integration.
- Play’n GO is responsible to keep the APIs backwards compatible as far as
possible. If backwards compatibility isn’t possible when creating a new
feature, consumers will be informed in appropriate time.
o The definition of backwards compatibility is that Play’n GO must be
able to do “passive changes” e.g. add non-mandatory parameters in
requests or null-able properties in the response and this should not
interrupt the service.
- Operator Account System must allow that a game session is initiated by a
Release call. Please see section 3.5 for more information.
- The DateTime is specified in UTC 24h and is handled as a String with the
format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
- Money is in general transferred using strings with two-decimal accuracy. The
monetary amounts are always truncated and not rounded. The exception is
for jackpotLoss in release call which can be configured to be transferred using
strings with four-decimal accuracy. Money must always be in the range
between -922,337,203,685,477.58 to 922,337,203,685,477.58.
- Any error messages that should be displayed for the player should be
returned in the language that the language parameter specify to give the user
the best possible experience.
- When settling monthly gaming between Operator and Play’n GO it must be
considered that Play’n GO Settlement report is based on finished rounds
while many back-office systems are based on finished sessions. To be able to
get an appropriate comparison, the ‘real’ parameter send in Reserve and
Release services must be stored by Operator Account System.
Integration Manual
Date Document id
2021-01-21 MAL0147
3 Integration overview
3.1 Conceptual Integration Overview
See the below overview of the calls being made between all parts throughout the
entire system.
3.2 Integration Instructions

• Please take notice of the appendences in the end of this document to
avoid errors in the implementation.
• Also note that all parameters are case sensitive so that any capital
characters must be as in the tables and examples.
Integration Manual
Date Document id
2021-01-21 MAL0147
• All parameters are mandatory if not stated as "Optional" in the

argument table.
• Note that the format send is in XML and the order its recommended to
be as in the response tables inserted in this document.
• Play'n GO is responsible to keep the APIs backwards compatible as
far as possible. If backwards compatibility isn't possible when creating
a new feature, consumers will be informed in appropriate time.
o The definition of backwards compatibility is that Play'n GO
must be able to do "passive changes" e.g. add non-mandatory
parameters in requests or null-able properties in the response
and this should not interrupt the service.
3.3 Test Cases

During the integration development, the below URL to be used to initiate single calls
or full test cases from the Play’n GO services. This is used to verify calls between
systems and service can handle all necessary scenarios and of the solution. This can
only be done once the API is implemented. When ready inform your contact at Play’n
GO to setup environment to be able to sign off your solution. The Integration Helper
Site can be found here.
3.4 Authentication
The Authenticate call makes a request to the Operator Account System to validate
the user information upon start of a new game.
The Authenticate call validates the information sent in the ‘username’ or ‘ticket’
parameter, as it was received when starting the game. It can be a token, session or
reference depending on what the Operator Account System supports. For security
reasons, this random token created by the Operator Account System must not have
a “lifetime” of more than 5 minutes.
All calls between the Game, Game Server and the Operator Account System
contains a parameter called ‘AccessToken’. The AccessToken is static and
negotiated between Play’n GO and the Operator at integration setup.
The AccessToken should be a unique string validated in the Operator Account
System on each call from the Game or Game Server. The reason is to ensure that
the call comes from Play’n GO.
1. Player logs on to Operator portal.
2. Player starts a game. Operator Account System generates and stores an
Authentication token.
3. Operator portal redirect and launch a game, passing the token from the
Operator Account System as a parameter (“username” for desktop, “ticket” for
mobile).
4. Server Communication is initiated.
5. Game asks server to validate the token, the game server ask Operator
Account System to validate the token.
6. Game loads when the authentication is validated.
Integration Manual
Date Document id
2021-01-21 MAL0147
The Authentication service is described in detail in section 4.1.

Example below:
<authenticate>
<username>The ticket/user you provided to the launch
url</username>
<productId>1</productId>
<CID></CID>
<clientIP>1.2.3.4</clientIP>
<contextId>0</contextId>
<accessToken>secrettoken</accessToken>
<language>en_GB</language>
<gameId>53</gameId>
<channel>1</channel>
</authenticate>
If the ticket is valid Operator Account System returns a response similar as below.
<authenticate>
<externalId>554433</externalId>
<statusCode>0</statusCode>
<statusMessage>ok</statusMessage>
<userCurrency>EUR</userCurrency>
<nickname>testUser</nickname>
<country>SE</country>
<birthdate>1970-01-01</birthdate>
<registration>2010-05-05</registration>
<language>en</language>
<affiliateId></affiliateId>
<real>1234.56</real>
</authenticate>
Since the External ID is the common player identifier between the game, game
server and the Operator Account System it must be included in all calls between the
system. For instance, when a player launches a game and then another one the
same External ID must be sent
Player A starts a game using ticket ZXY
Operator Account System returns ExternalID 10
Player A starts a game using ticket YZA
Operator Account System return ExternalID
Important note: ExternalID is case sensitive and must be the same in all calls.
3.5 Session handling

When the game is started a game session is created. Normally a game round is
initiated with a bet/Reserve call and ended with a Release call. If a game supports
additional bets within the same game round, several Reserve calls can be included in
that game round.
Integration Manual
Date Document id
2021-01-21 MAL0147
Please note that for some games, a game round can be initiated by a release call
without a preceding reserve call. Operator Account System must support this
scenario. An example of this scenario is the game Tower Quest were the player
collects items in order to activate free spins. When the free spin is activated a release
call is sent to the Operator Account System with the result without a preceding
reserve call. This can also happen if a Free Game Offer is received by the Player but
not started, in this case a release call can be sent without a reserve when trying to
close the game session.
When game session is open the session will have state=0. And game session will be
active for more gameplay. Note that if a game session has Free Games, the session
will not be closed until all Free Games are used, this is to keep track of the progress
of the Free Games.
The game session is ended with a separate Release call that specify a status that the
session is closed (see section 4.3). Parameters real and roundId are always 0 for this
Release call which also includes summarized game session data in the parameters:
- totalGain
- totalLoss
- numRounds
- freegameGain
- freegameLoss
The Operator Account System can connect an own game session reference in the
externalGameSessionId parameter.
If no game rounds where played in the game session, the session is closed by a
Release call sending state=1 and numRounds =0.
The Operator Account System need to respond in up to 10 seconds to our requests
until the call will timeout.
As well, the Player idle is 5 minutes at default, during which, if no activity is taking
place in the game, Play'n GO will close the session.
Play’n GO will close game sessions once the correct parameters are sent by the
Operator to ensure correct session handling. However, when this is not possible due
to Operator system not resolving such requests, a 90-day counter will initiate from
the last time the session was active and once elapsed, sessions will be voided
automatically by the system.
3.6 Common Game Session

In the latest update to the Transparent Account Integration, Play’n GO added the
Common Game Session feature. This feature gets rid of the old way of separating
sessions between different devices and introduces the ability for a session to be
started in one device and continued in another (i.e desktop to mobile etc.). The new
Channel parameter is used to differentiate between different devices.
Integration Manual
Date Document id
2021-01-21 MAL0147
Also, in introducing this feature, additional fields to the integration was added to the
Reserve, Release and Cancel Reserve calls. These are marked in the tables below
in yellow.
If your integration hasn’t been updated yet to have Common Game Session activated
these fields will not be sent. Please refer to your Play’n GO representative for any
questions.
3.7 Jurisdiction
A player’s Jurisdiction is based on the Country field that the Operator sends in the
Authentication response. This decides which Jurisdiction the player will be in and
also which configurations in that particular Jurisdiction will apply.
It is also important to note that any Open Game Sessions are locked to the
Jurisdiction that they started with initially.
Integration Manual
Date Document id
2021-01-21 MAL0147
Example– Normal flow
Integration Manual
Date Document id
2021-01-21 MAL0147
3.7.1 Transactional security

All transactional calls need to be idempotent, meaning that any call with a
transactional id that is done multiple times have to generate the same response from
the Operator Account System.
3.7.2 Reconciliation
If any transaction fails to receive a response in a number of retries it is held open to
be reconciled at a later time. Each call is performed with a unique state to provide full
security in case of an extended failure in communication or hardware.
Transaction Reconciliation
Reserve CancelReserve issued

Release Retry until successful
CancelReserve Retry until cancel successful
3.7.3 Separation of Bonus and Real Money

Play’n GO offers a solution for UK Competitions and Marketing Agency (CMA)
regarding separation of bonus and real money. A description of the integration details
needed is described in MAL1108-1-UK Solution for Separation of Bonus and Real
Money.
4 Services
Below are the integration services described in detail.
4.1 Authenticate
When a player logs in to a product the username should be a session token
generated by the receiving party since the information is only tunneled. If such a
session token is used it should be generated to be completely random, valid only
once and for no more than 5 minutes.
Any error messages should be returned in the language that the language parameter
specify to give the user the best possible experience. Please find language codes in
Currency, Country & Language Appendix.
Integration Manual
Date Document id
2021-01-21 MAL0147
4.1.1 Authenticate Service Details

Request
The following table describes the parameters when performing the service request.
Parameter Type Description
username string (64) Session token provided by Operator

Account System.
productId string (32) Assigned identifier to product.
clientIP string (32) Optional

Client IP in the form xxx.xxx.xxx.xxx
contextId string (50) Optional

As specified to the game.
accessToken string (64) A secret access token that should be

verified with each call.
language string (5) Optional

As specified to the game. Please find
references in Currency, Country &
Language Appendix.
gameId string (16) Game identifier. Please find references
in Currency, Country & Language
Appendix.
channel enum Which channel the game is launched in.
1 = Desktop
2 = Mobile
3 = Mini Game
5 = Embedded in Native app
Example
<authenticate>
<username>CAA13F18-713C-443C-AEFD-0AE52D29A3CF</username>
<clientIP>100.101.102.103</clientIP>
<contextId>VIP</contextId>
<language>en_GB</language>
<gameId>53</gameId>
</authenticate>
Integration Manual
Date Document id
2021-01-21 MAL0147
Response
The following table describes the parameters returned when responding to the
Authenticate service request.
externalId string (64) Unique customer id. This must always

be the same for the same user. Case
sensitive.
statusCode enum Status of request. See Status Codes

in section 6.1.
statusMessage string (256) The error string to be shown in the

client in case status is not ok.
userCurrency string (3) Player Currency. Please find
Language Appendix.
nickname string (32) Optional
2-12 letters. a-z A-Z 0-9 - . _ & space
(only one space in a row allowed).
country string (2) Player Country Code. Please see

Currency, Country & Language
Appendix. Requirement for specific
jurisdictions
birthdate Date (8) Date of birth of the user
registration Date (8) Date when user was originally

registered in the original system.
language string (2) Optional

Player language code. Please see
Appendix.
affiliateId string (32) Optional

Operator affiliate id.
real Money Amount of the players’ real money

balance.
gender string (1) Optional

Gender of user (’m’ or ’f’).
Integration Manual
Date Document id
2021-01-21 MAL0147
externalGameSessionId string (64) Optional

Operator Account System game
session reference.
region string (32) Optional

Player region, only applicable in
certain jurisdictions.
gameMode enum Optional

Used to separate bonus and real
money. Please see MAL1108-1-UK
Solution for Separation of Bonus and
Real Money
0 = Real or Bonus (default)
1 = Real money
2 = Bonus money
bonusBalance money Optional

Amount of player’s bonus money.
Real Money
Example
<authenticate>
<externalId>554433</externalId >
<userCurrency>EUR</userCurrency>
<nickname>MaxPower</nickname>
<country>SE</country>
<birthdate>1970-01-01</birthdate>
<registration>2010-05-05</registration>
<language>EN</language>
<affiliateId></affiliateId>
<externalGameSessionId></externalGameSessionId>
<region>3</region>
</authenticate>
4.2 Reserve
Transfer money from provider to be used in game sessions. Please see section 2 for
more information. If a game supports additional bets within the same game round,
additional Reserve calls can be included in game round. All additional bets are added
as a new transaction. Example, where additional bets occur is in Black Jack and
Video Bingo games.
Integration Manual
Date Document id
2021-01-21 MAL0147
Example – Reserve
4.2.1 Reserve Service Details

Request
externalId string (64) Unique customer id. This

must always be the same
for the same user.
productId string (16) Assigned identifier to

product.
transactionId string (32) Unique transaction id.
real money Amount of “real” money

used in the bet. If Free
game round, this is 0.
currency string (3) Currency code. Please

find references in
Currency, Country &
Language Appendix.
Integration Manual
Date Document id
2021-01-21 MAL0147
gameId string (16) Game identifier. Please

find references in Game
Details Matrix.
gameSessionId string (16) Game session identifier

generated by Play’n GO.

As specified in
Authentication request.
accessToken string (64) A secret access token that
should always be verified.
roundId long Id of the played round.

As specified by Operator
Account System in
authentication response.

Used to separate bonus
and real money. Please
see MAL1108-1-UK
Solution for Separation of
Bonus and Real Money
0 = Real or Bonus
(default)
1 = Real money
2 = Bonus money
channel enum Which channel the game

is launched in.
1 = Desktop
2 = Mobile
3 = Mini Game
5 = Embedded in Native
app
freegameExternalId string (32) Freegame reference id.

Unique per user and
freegame offer
actualValue money The actual value of the
bet. Both for normal bet
and for freegame. For
freegame it will be bet
Integration Manual
Date Document id
2021-01-21 MAL0147
configured for the free

game. For normal bet this
will be same as in “real”.
jackpots Optional
Tag contains one or more
jackpot tags.
jackpots/jackpot Optional
Tag contains information
about the jackpot.
jackpots/jackpot/id int (32) Optional

Id of jackpot
jackpots/jackpot/loss money Optional

Jackpot contribution
amount
Example
<reserve>
<transactionId>43210</transactionId>
<real>15.00</real>
<currency>EUR</currency>
<gameId>53</gameId>
<gameSessionId>237842347</gameSessionId>
<roundId>87654321</roundId>
<freegameExternalId>123</freegameExternalId>
<actualValue>0.10</actualValue>
<jackpots>
<jackpot>
<id>1</id>
<loss>0.10</loss>
</jackpot>
<jackpot>
<id>2</id>
<loss>0.20</loss>
</jackpot>
</jackpots>
Integration Manual
Date Document id
2021-01-21 MAL0147
</reserve>
Response
externalTransactionId string (64) Optional

Operator Account System unique id
for this transaction.
real money Customer balance of real money

after transaction.

in section 6.1
statusMessage string (256) Optional
Message indicating failure.

Real Money
1 = Real money
2 = Bonus money
Customer balance of bonus money
after transaction. Used to separate
bonus and real money. Please see
MAL1108-1-UK Solution for
Separation for Bonus and Real
Money
Example
<reserve>
<externalTransactionId>56789</externalTransactionId>
</reserve>
Integration Manual
Date Document id
2021-01-21 MAL0147
4.3 Release
This is the way the Gaming System transfer back money to the Operator Account
System together with the associated game session data.
Note that at game session close, a separate Release call is made that sends a
summary of the additional parameters totalGain, totalLoss, numRounds,
freegameGain and freegameLoss. This Release call will always get state=1.
Example Release
4.3.1 Release Service Details

Request
externalId string (64) Unique customer id. Case sensitive.
productId string (16) Assigned identifier to

provider/product.
transactionId string (32) Unique transaction id.
retry Boolean Optional

“1” if it is a retry, “0” if otherwise. Only
Integration Manual
Date Document id
2021-01-21 MAL0147
sent if
integration.corexternal.sendretryflag
config is set.
real money Amount of money to transfer.
currency string (3) 3-character currency code. See

Appendix.
gameSessionId string (32) Game session identifier generated by

Play’n GO.

As specified in Authentication
request.
state enum 0 = Game session is still open.

1 = Game session is closed.
See Session States in section 6.2.
totalLoss money Optional

Amount of bets made in the game
session excluding any amount from
free games.
totalGain money Optional

Amount of winnings received in the
game session including any amount
from free games.
numRounds int Optional

Total rounds played in the game
session.
type enum See Transaction Types in section 6.4.

gameId string (16) Game identifier. Please find
references in Game Details Matrix.
accessToken string (64) A secret access token that should

always be verified.

Note: The roundID is set to 0 if the
release is sent when closing a
session.
jackpotGain money Amount of money won from jackpot.
Integration Manual
Date Document id
2021-01-21 MAL0147
jackpotLoss money Amount of money contributed to

jackpot(s).
jackpotGainSeed money Amount of money seeded after

jackpot win.
jackpotGainId int ID of jackpot that was won and

seeded.
freegameExternalId string (32) Optional

Free game reference id (sent if this is
a Free game payout, i.e. type =
Promotional).
turnover int Optional

Turnover times from Free game setup
(Only on last Free game payout, i.e.
finished = 1).
freegameFinished bool (0 or 1) Optional

Indicates if the Release is the last one
in the Free game (finished = 1
indicates the last Free game round).
freegameGain money Optional

The total amount won in free games.
This amount is also included in the
totalGain attribute.
freegameLoss money Optional

The total amount lost in free games.
This amount is not included in the
totalLoss attribute.

As specified by Operator Account
System in authentication response.

Solution for Separation for Bonus and
Real Money.
1 = Real money
2 = Bonus money
channel enum Which channel the game is launched
in.
Integration Manual
Date Document id
2021-01-21 MAL0147
1 = Desktop
2 = Mobile
3 = Mini Game
freegameTotalGain decimal Total gain during the freegame if

freegame round.
jackpots Optional
Tag contains one or more jackpot
tags.
Tag contains information about the
jackpot.
jackpots/jackpot/id Int (32) Optional

Id of jackpot won
jackpots/jackpot/win money Optional

Jackpot win amount
jackpots/jackpot/seed money Optional

Jackpot seed amount
Example
<release>
<real>200.00</real>
<gameSessionId>237842347</gameSessionId>
<state>1</state>
<totalLoss>150.00</totalLoss>
<totalGain>246.90</totalGain>
<numRounds>10</numRounds>
<type>0</type>
<gameId>53</gameId>
<jackpotGain>200.00</jackpotGain>
<jackpotLoss>12.34</jackpotLoss>
<jackpotGainSeed>25.00</jackpotGainSeed>
<jackpotGainId>5623</jackpotGainId>
Integration Manual
Date Document id
2021-01-21 MAL0147
<freegameExternalId>abc123</freegameExternalId>
<turnover>1</turnover>
<freegameFinished>1</freegameFinisihed>
<freegameGain>2.34</freegameGain>
<freegameLoss>0.00</freegameLoss>
<freegameTotalGain>1.50</freegameTotalGain>
<jackpots>
<jackpot>
<id>1</id>
<win>1000.00</win>
<seed>0.50</seed>
</jackpot>
<jackpot>
<id>2</id>
<win>500.00</win>
<seed>0.50</seed>
</jackpot>
</jackpots>
</release>
Response

Operator Account System
unique id for this transaction.
real money Customer balance of real

money after transaction.
statusCode enum Status of request. See Status
Codes in section 6.1.

Used to separate bonus and
real money. Please see
Separation of Bonus and
Real Money
1 = Real money
2 = Bonus money

Customer balance of bonus
money after transaction.
Used to separate bonus and
Integration Manual
Date Document id
2021-01-21 MAL0147
real money. Please see

Separation for Bonus and
Real Money
Example
<release>
</release>
4.4 Balance
Get current account balances available to transfer to specified provider. This is made
by game and occurs at no specific time. This call is events made by game, example
when the game is loaded or the balance is running low.
4.4.1 Balance Service Details

Request
externalId string (64) Unique customer id. This must

always be the same for the same
user. Case sensitive.
currency string (3) Currency code that the returned

balance must be in. Please find
Language Appendix.


always be verified.

Example
<balance>
Integration Manual
Date Document id
2021-01-21 MAL0147
<gameId>54</gameId>
</balance>
Response
real money Amount of “real” money

in section 6.1.

Real Money
1 = Real money
2 = Bonus money

Amount of Bonus money. Used to
separate bonus and real money.
Please see MAL1108-1-UK Solution
for Separation of Bonus and Real
Money
Example
<balance>
</balance>
4.5 Cancel Reserve

If a Reserve call fails, a CancelReserve is sent with the transactionId of the Reserve
call. When received, that transactionId needs to be reversed by the Operator
Account System. If no such transactionId has been received by the Operator
Account System, a positive response needs to be sent together with an empty
externalTransactionId. The CancelReserve will be resent until status ok (0) is
returned from the Operator Account System.
Integration Manual
Date Document id
2021-01-21 MAL0147
When a call fails or times out, we keep retrying during 10 seconds (usually two
retries). If this is reserve failing, then SessionMaintenance will call the
CancelReserve. If then the CancelReserve fails, it will also retry during 10 seconds.
After that SessionMaintenance might call the CancelReserve again, while the
session is active.
When the session is inactive and the user tries to resume (log in), CancelReserve
will be called again. This is because the User cannot resume the game session until
CancelReserve is resolved.
Example – CancelReserve
Cancel Reserve Service Details

Request
externalId string (64) Unique customer id. This must

always be the same for the same
user. Case sensitive.
Integration Manual
Date Document id
2021-01-21 MAL0147
transactionId string (32) Casino System transaction id as

sent during the Reserve call. I.e.
the transaction that needs to be
cancelled.
retry Boolean Optional

“1” if it is a retry, “0” if otherwise.
Only sent if
integration.corexternal.sendretryflag
config is set.
real money Amount of “real” money. If Free

game round, this is 0.
currency string (3) Currency code. Please find
Language Appendix.
gameSessionId string (16) Game session identifier generated
by Play’n GO.

always be verified.


channel enum Which channel the game is

launched in.
1 = Desktop
2 = Mobile
3 = Mini Game
freegameExternalId string (32) Optional
Freegame reference id. Unique per
user and freegame offer
actualValue money The actual value of the bet. Both for

normal bet and for freegame. For
freegame it will be bet configured
for the free game. For normal bet
this will be same as in “real”.
Integration Manual
Date Document id
2021-01-21 MAL0147
jackpots Optional
Tag contains one or more jackpot
tags.
Tag contains information about the
jackpot.
jackpots/jackpot/id Int (32) Optional

Id of jackpot won
jackpots/jackpot/loss money Optional

Jackpot contribution amount
Example
<cancelReserve>
<real>123.45</real>
<gameId>54</gameId>
<freegameExternalId>123</freegameExternalId>
<actualValue>0.10</actualValue>
<jackpots>
<jackpot>
<id>1</id>
<loss>0.10</loss>
</jackpot>
<jackpot>
<id>2</id>
<loss>0.50</loss>
</jackpot>
</jackpots>
</cancelReserve>
Response
Integration Manual
Date Document id
2021-01-21 MAL0147

Operator Account System
unique id for this
transaction
statusCode enum Status of request. See

Status Codes in section
6.1.
Example
<cancelReserve>
</cancelReserve>
4.6 GetUnfinishedGames
If there is a need for information about a players’ unfinished games i.e. game rounds
that are not finished by the player, this call can be used. Note that player can
reconnect to an unfinished game and continue play the round.
There exists a built-in method that closes unfinished games. When this happens, the
bet is ‘voided’ and send from the gaming system to the Operator Account System.
This is configured in the gaming system and executed after the configured amount of
days.
Example –Unfinished game play continue
Integration Manual
Date Document id
2021-01-21 MAL0147
Example –Unfinished game round is voided
Integration Manual
Date Document id
2021-01-21 MAL0147
4.6.1 GetUnfinishedGames Service Details

Arguments
Name Type Description
ExternalId string Unique customer id. This

must always be the same for
the same user.
Example
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:v1="http://playngo.com/v1">
<soapenv:Header/>
<soapenv:Body>
<v1:GetUnfinishedGames>
<v1:ExternalId>TestUser</v1:ExternalId>
</v1:GetUnfinishedGames>
</soapenv:Body>
</soapenv:Envelope>
Response
Name Type Description
GameId int Game identifier. Please find

references in Game Details
Matrix.
Gid string(64) Game identifier. Please find

references in Game Details
Matrix.
Serialized bool True or false, if the game

data has been stored in the
database.
MobileGame bool True or false, if the game is

a mobile game.
Bet money The amount of the bet.

Currency string (3) Currency code. Please find
references in Currency,
Country & Language
Appendix.
GameName string (64) Game name.
Integration Manual
Date Document id
2021-01-21 MAL0147
GameType string (32) Type of the game.
Example
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetUnfinishedGamesResponse xmlns="http://playngo.com/v1">
<OpenGameIds xmlns:i="http://www.w3.org/2001/XMLSchema-
instance">
<OpenGameId>
<GameId>307</GameId>
<Gid>firejoker</Gid>
<Serialized>true</Serialized>
<MobileGame>false</MobileGame>
<Bet>
<Value>1425.0000</Value>
<Currency>EUR</Currency>
</Bet>
<GameName>Fire Joker</GameName>
<GameType>casino</GameType>
</OpenGameId>
</OpenGameIds>
</GetUnfinishedGamesResponse>
</s:Body>
</s:Envelope>
5 Reload Functionality
There are two scenarios where a game needs to be reloaded. When a player
receives multiple free games in the same game or if a player receives a free game
during an ongoing session in the same game e.g. as an Achievement prize. A
reloadgame function is available for Desktop games while a reloadgame URL
parameter can be used for mobile games. The reloadgame function and the
reloadgame URL destination is responsible for getting new login tokens needed to
reload the same game.
In both multiple free games and ongoing session scenarios the player will be
prompted with an option in the game to activate the free game or not. In the case of
multiple free games this option will appear when the first free game has ended. If the
player chooses to activate the free game offer the game will be reloaded using the
reloadgame function / URL.
IMPORTANT: Make sure to contact your Play’n GO representative in order to
activate the reload functionality in Play’n GO internal system.
5.1 Free Game Test Cases

Please use the below test cases to ensure the Play’n GO Free Game functionality.
Integration Manual
Date Document id
2021-01-21 MAL0147
5.1.1 Definitions / Preconditions

- Free Games are promotional games given to players.
- Free Spins is a feature in certain games where the player receive additional
spins as part of the game.
- PID is the same as a Product Id, a unique identifier of the Operator.
- This document presume knowledge about Free Game offer parameters.
- Contact your assigned Play’n GO contact to order the
‘showingamefreegamemessage’ to be enabled for your PID.
5.1.2 Create Free Game via API

1. Start SOAP UI (or your integrating system) and create a
AddFreeGameOffers for a player. Use the parameters:
- Coins=1
- Lines=15
- Denomination=0.1
2. Use the same player to load the game. The game launch URL must include
&reloadgame=<game-path>
3. Go thru the following steps:
a. Game: Spin
b. Soap: Create another < AddFreeGameOffers >
c. Game: Wait approx. 30 seconds or Spin
d. Game: "You have 1 freegame is presented", Click <OK> but don’t
press Spin.
e. Soap: Create yet another < AddFreeGameOffers >
f. Game: Wait approx. 30 seconds and play the first Free Game Offer.
g. Game: When the first Free Game offer has been played, a message is
shown: "You have another free game….” is presented, Click <OK>
h. Close session
5.1.3 Free Game as Achievement Prize

1. Create a Free Game Offer for Achievement in GMT.
2. Setup an Achievement Campaign for the same game, using the Free Game
as a prize.
3. Verify that &reloadgame=<game-path> is added to URL when open the
game.
4. Play the game and pay attention to when the Achievement is triggered.
Expected:
A popup message shall present the Free Games to the player a couple of
seconds or spins after the Achievement has been triggered.
Integration Manual
Date Document id
2021-01-21 MAL0147
6 Supplement
6.1 Status Codes
Status codes are used to indicate success or additional information for unsuccessful
requests. In the Response, the Status Code is sent as an enum.
Example:
<balance>
</balance>
In this example, it is an OK response so 0 should be sent.
Status Status Message Description

Code
0 OK Request successful.
1 NOUSER User was not logged in.
2 INTERNAL Internal server error.
3 INVALIDCURRENCY An unsupported currency

was specified.
4 WRONGUSERNAMEPASSWORD Wrong username or

password.
5 ACCOUNTLOCKED Account is locked.
6 ACCOUNTDISABLED Account is disabled.
7 NOTENOUGHMONEY The requested amount is

too high or too low.
8 MAXCONCURRENTCALLS The system is unavailable

for this request. Try again
later.
9 SPENDINGBUDGETEXCEEDED Responsible gaming limit
(money) exceeded.
10 SESSIONEXPIRED The player session has

expired.
11 TIMEBUDGETEXCEEDED Responsible gaming limit

(time) exceeded.
Integration Manual
Date Document id
2021-01-21 MAL0147
12 SERVICEUNAVAILABLE Service is unavailable for

any reason but able to
respond, similar to
MAXCONCURRENTCALLS
which is a specialized
condition of
SERVICEUNAVAILABLE.
6.2 Status Message

For Authenticate and Reserve call response, it is possible to also send a Status
Message (for OK response it has no function as nothing is shown to Player):
<reserve>
</reserve>
This can be used to show a custom message to player in case the response is not
“OK”, for example it could be like this:
<reserve>
<real>12.56</real>
<statusMessage>Responsible Gaming Limit
exceeded</statusMessage>
</reserve>
Then “Responsible Gaming Limit exceeded” will be shown to the player instead of
the standard text.
Note that this can be used for all Status Code / Messages except for Status Code 7
(NOTENOUGHMONEY).
Integration Manual
Date Document id
2021-01-21 MAL0147
6.3 Session States

Session states indicate the current state of the game session.
State Value Description
OPEN 0 Game session is still open.
CLOSED 1 Game session has been closed.
6.4 Transaction Types

The type of money the Release is for.
Status Code Value Description
REAL 0 Real money.

PROMOTIONAL 1 Promotional money. For example, the
result of Free game spins.

MAL0147-1-Transparent Account Integration Manual

Uploaded by

Copyright:

Available Formats

MAL0147-1-Transparent Account Integration Manual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

MAL0147-1-Transparent Account Integration Manual

Uploaded by

Copyright:

Available Formats

User Guide

TRANSPARENT ACCOUNT INTEGRATION MANUAL

3.7 Jurisdiction ..................................................................................................... 9

3.7.2 Reconciliation ........................................................................................................11

3.7.3 Separation of Bonus and Real Money ..................................................................11

4.2 Reserve ...................................................................................................... 14

4.3 Release ...................................................................................................... 19

4.4 Balance ...................................................................................................... 24

4.5 Cancel Reserve .......................................................................................... 25

4.6.1 GetUnfinishedGames Service Details ...................................................................31

5 Reload Functionality ........................................................................................ 32

5.1.2 Create Free Game via API ....................................................................................33

5.1.3 Free Game as Achievement Prize ........................................................................33

3.2 Integration Instructions

• All parameters are mandatory if not stated as "Optional" in the

3.3 Test Cases

The Authentication service is described in detail in section 4.1.

3.5 Session handling

3.6 Common Game Session

Example– Normal flow

3.7.1 Transactional security

Reserve CancelReserve issued

CancelReserve Retry until cancel successful

3.7.3 Separation of Bonus and Real Money

4.1.1 Authenticate Service Details

Parameter Type Description

username string (64) Session token provided by Operator

productId string (32) Assigned identifier to product.

clientIP string (32) Optional

contextId string (50) Optional

accessToken string (64) A secret access token that should be

language string (5) Optional

Parameter Type Description

externalId string (64) Unique customer id. This must always

statusCode enum Status of request. See Status Codes

statusMessage string (256) The error string to be shown in the

country string (2) Player Country Code. Please see

registration Date (8) Date when user was originally

language string (2) Optional

affiliateId string (32) Optional

real Money Amount of the players’ real money

gender string (1) Optional

externalGameSessionId string (64) Optional

region string (32) Optional

gameMode enum Optional

bonusBalance money Optional

4.2.1 Reserve Service Details

externalId string (64) Unique customer id. This

productId string (16) Assigned identifier to

transactionId string (32) Unique transaction id.

real money Amount of “real” money

currency string (3) Currency code. Please

gameId string (16) Game identifier. Please

gameSessionId string (16) Game session identifier

contextId string (50) Optional

roundId long Id of the played round.

externalGameSessionId string (64) Optional

gameMode enum Optional

channel enum Which channel the game