MGT Interface Integration Manual

Last update: 02.February 2022

Changelog Author Notes

Manfred
04.01.2022 Power Comply Concept
Fröhlich

Adjusted value of comply property depending on type of event.

Manfred
02.02.2022 Extended Documentation for PEP&Sanction API and
Fröhloch
Identification API.

     

1 Basics
1.1 Introduction
This document describes the interfaces used for communication between the Torro Tec
Sportsbook System (short SBS) and the MGT interface (short MGT).

MGT will provides several endpoints for compliance purposes.

Staging Endpoints are hosted at: https://api-demo.mgt.eu

Production Endpoints are hosted at: https://api.mgt.eu

All requests are http POST requests using content-type application/json and expect params as
json object inside the request body.

1.2 Authentication
Each request requires authentication. For that purpose the /auth endpoint has to be used to
generate a valid token.

Request Example:

curl --location --request POST 'https://api-demo.mgt.eu/auth' \

--header 'Content-Type: application/json' \

--data-raw '{

"client": 1234,

"apiSecret": "abcd"

}'

The parameters "client" and "apiSecret" are provided by MGT.

In case of wrong credentials, the endpoint will return a json object containing an error code and
message property as shown below:
 Error Response Example:

{ "code": 1002, "message": "Client is not configured."}

As of now, the only known error code is 1002. The message property may contain additional
information about the reason the request failed.

A successful request will return a valid authentication token as shown below:

Success Response Example:

"token":

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IlA2R3hHWEhmcXBtRW0xeDEwR2EyIiwiaWF
0IjoxNjQwMDg1NjEwLCJleHAiOjE2NDAwODkyMTB9.6uMVui8M6HRngW5qymnx_7x_CL6xCC
wJi0QYPhD-x-k"

The token property contains a JWT token, which can be verified using the apiSecret used as
request parameter and can be decrypted to get the expire timestamp of the token. For more
details sie https://jwt.io.

2. Power Comply
2.1 Purpose
PowerComply is a compliance product provided by MGT. Compliance related events happening in
SBS will automatically forwarded to the MGT system using the PowerComply interface, allowing
them to create compliance related reports.

As of today, the following events have been concipated to be sent into PowerComply:
2.2 Common Request Handling
The comply request can be performed using the /registration endpoint. The authorization token
obtained from auth request needs to be passed inside the header as a bearer token. See example
below:

Request Example:

curl --location --request POST 'https://api-demo.mgt.eu/registration' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IlA2R3hHWEhmcXBtRW0xeDEwR2EyIiwiaWF0
IjoxNjQwMDg1NjEwLCJleHAiOjE2NDAwODkyMTB9.6uMVui8M6HRngW5qymnx_7x_CL6xCCw
Ji0QYPhD-x-k' \

--data-raw '{

"collection": "Account",

"onlineCustomerId": "xxxxx",

"sentAt": "2022-01-04T11:27:46.6603028Z",

"createdAt": "2022-01-04T11:26:24.827Z",

"account": {...}

"transaction": {...}

}'
The input parameters must contain the following mandadory properties:

collection: depends on the type of events. For account related events use "Account", for
payment transactions use "Payment". For Bet related transactions use "Transaction"
onlineCustomerId: the unique ID of the client from SBS (UTC)
createdAt: the timestamp of database transaction in SBS (UTC).
sentAt: the timestamp of the request to MGT ()

Additional details can be passed using variable child objects. For SBS we will define "account" and
"transaction".

account: will be used to pass account related changes and events. See chapter 2 for more
details about this object.
transaction: will be used to pass balance changing events like payments or betting
transactions. See chapter 3 for more details about this object.

Note that there can be a delay of several minutes between timestamps sentAt and createdAt. The
request are being carried out in an asynchron manner. A tool called PowerComply Handler will
look for database changes in an interval of one minute and will create requests for events
happened in the meantime. The timestamp createdAt therefore contains the actual event
timestamp of SBS, while sentAt contains the timestamp of when the event has been forwarded to
MGT.

Error Response Example:

"message": "Internal Server Error"

Success Response Example:

"code": 200,

"data": {

"onlineCustomerId": "xxxxx",

"client": "1234",

"requestId": "862581ef-2c54-4514-b613-e18bf2fc2347",

"createdAt": "2021-12-21T11:36:02.285Z",

"id": "Ht7y13jCmC5X7xdOAare"

In addition, the request may also contain all of the original request params.
2.1.1 Account Related Events
Account events are used for each event changing the account data or affect the account status,
such as login, verification steps, and so on. For this purpose the following base object will be used:

"account": {

"eventType": "login",

Based on "eventType" additional event related properties will be added to the object.

2.1.2 Balance Related Events

For each event changing the current balance of a client, a transaction is being created. The SBS
uses many types of transactions, but for simplicity we will summarize them in two major types:
payment and bet transactions. The base object will contain common properties used for each
transaction type:

"transaction": {

"transactionType": "deposit",

"transactionId": 1234,

"currency": "EUR",

"currencyRate": 1.000,

"wallet": "online",

"amount": 1.00

"newBalance": 1.00,

transactionType: Depending on the transaction type, the object may contain additional
information
transactionId: unique transaction ID in SBS
currency: ISO 4217 currency code
currencyRate: currency exchange rate to EUR. (for example an amount of 1,00 and a rate of
2,000 would be 0,500 EUR)
wallet: an SBS account can have multible balances at the same time. Each being considered
its own wallet and can be used for specific purposes only. As of know the following wallets
are possible: shop, online, casino, sportbonus, casinobonus
amount: the monetary transaction value (if positive, balance gets increased, if negative
balance gets decreased)
newBalance: resulting balance of the wallet after transaction has been performed

Wallet Definition:

sport: balance available for sportbets only

casino: balance available for casino games only
sportbonus: bonus balance, can be used only for sportbets
casinobonus: bonus balance, can be used only for casino games
shop: balance available for customer cards to be used only inside shops and only for
sportbets

2.1 Signup Event

For new signups the eventType "signup" will be used.
 eventType: "signup"

The object may contain the following additional properties:

birthdate: "1070-01-10"
country: ISO 3166 alpha-2 country code (e.g. "DE")
street
houseNr
city
postcode
firstName
lastName
gender: possible values are "Male" or "Female"
email: current email adress of the user

example:

{"collection":"Account","onlineCustomerId":"6605","sentAt":"2022-01-
04T12:16:48.7353717+01:00","createdAt":"2022-01-04T12:15:27.413","account":
{"eventType":"signup","birthdate":"1985-03-
09T00:00:00","city":"Osnabrück","country":"DE","email":"","firstName":"Manfred","gender":"Male","
houseNr":"1","lastName":"Fröhlic","postcode":"12345","street":"Testß1"}}

2.2 Login Events

For login the eventType "login" and for logout the eventType "logout" will be used.

eventType: "login"
eventType: "logout"

Currently no additional properties will be used.

Example:

{"collection":"Account","onlineCustomerId":"6605","sentAt":"2022-01-
04T12:07:16.0049876+01:00","createdAt":"2022-01-04T12:05:07.0019","account":
{"eventType":"login"}}

2.3 Limit Change Events

For limit changes the eventType "limit" will be used.

eventType: "limit"

The object may contain the following additional properties:

maxDepositMonth: maximum sum of deposit amount per month (calculation starting from
1. of the month)
maxDepositWeek: maximum sum of deposit amount per week (calculation from monday to
sunday)
maxDepositDay: maximum sum of deposit per day (calculation from 00:00 to 23:59:59)
maxStakeMonth: max sum of stake per month
maxStakeWeek: max sum of stake per week
maxStakeDay: max sum of stake per day
maxStakeHour: max sum of stake within one hour
maxStakeSession: max sum of stake per session
maxLossMonth: max loss sum per month
maxLossWeek: max loss sum per week
 maxLossDay: max loss per day
maxLossHour: max loss within one hour

The limits above are used for sportbets, for casino own limit properties may be used:

maxCasinoDepositMonth: maximum sum of deposit amount per month (calculation starting

from 1. of the month)
maxCasinoDepositWeek: maximum sum of deposit amount per week (calculation from
monday to sunday)
maxCasinoDepositDay: maximum sum of deposit per day (calculation from 00:00 to
23:59:59)
maxCasinoStakeMonth: max sum of stake per month
maxCasinoStakeWeek: max sum of stake per week
maxCasinoStakeDay: max sum of stake per day
maxCasinoStakeHour: max sum of stake within one hour
maxCasinoStakeSession: max sum of stake per session
maxCasinoLossMonth: max loss sum per month
maxCasinoLossWeek: max loss sum per week
maxCasinoLossDay: max loss per day
maxCasinoLossHour: max loss within one hour

Some specicial limits may be used for LUGAS:

maxDepositLugasCurrent: the current global max deposit limit known to LUGAS

maxDepositLugasNew: in case of LUGAS limit change this value will state the new limit

Example:

{"collection":"Account","onlineCustomerId":"6605","sentAt":"2022-01-
04T11:27:46.6603028Z","createdAt":"2022-01-04T11:26:24.827Z","account":
{"eventType":"limit","maxDepositMonth":999.0}}

2.4 Status Change Events

For status changes dynamic eventTypes will be used. As of now, the following event types have
been defined:

eventType: "active" (will be used when account becomes active)

eventType: "suspended" (will be used when account becomes inactive)
eventType: "verification" (will be used when a verification has been performed)
eventType: "pepcheck" (will be used when a pep and sanctions check has been performed)
eventType: "selfexcluded" (will be used when user performed a selfexclusion)
eventType: "paused" (will be used when casino games have been paused due to max time
limit)

The object may contain the following additional properties:

verificationExpiry: may be used on verification and contain the date of the identification
document expiry date
pepRating: may be used on pepcheck and contains the pep rating returned from MGT pep
check api
excludedUntil: may be used to pass the timestamp of the exclusion end for selfexcluded if
user didn't excluded indefinately
 pausedUntil: may be used to pass the timestamp of the pause end

Example:

{"collection":"Account","onlineCustomerId":"6605","sentAt":"2022-01-
04T12:16:45.5478825+01:00","createdAt":"2022-01-04T12:14:48.942","account":
{"eventType":"suspended"}}

2.5 Data Change Event

For account data changes the eventType "data" will be used.

eventType: "data"

The object may contain the following additional properties:

firstname, lastname,... basically same as signup but for existing client who changed personal
details.

Example:

{"collection":"Account","onlineCustomerId":"6605","sentAt":"2022-01-
04T12:16:48.7353717+01:00","createdAt":"2022-01-04T12:15:27.413","account":
{"eventType":"data","birthdate":"1985-03-
09T00:00:00","city":"Osnabrück","country":"DE","email":"","firstName":"Manfred","gender":"Male","
houseNr":"1","lastName":"Fröhlic","postcode":"12345","street":"Testß1"}}

2.6 Payment Transaction

For payment transactions the transactionType "deposit" or "widthdrawl" may be used.

transactionType: "deposit" will be used for deposits

transactionType: "withdrawal" will be used for withdrawals
transactionType: "withdrawalCanceled" will be used for canceled withdrawals
transactionType: "depositCanceled" will be used for canceled deposits

The object may contain the following additional properties:

paymentProvider: for example paypal.

paymentComment: may be used in case of payments where no payment provider exists or
for additional information. for example in case of manual correction from admin panel, it
may contain the comment provided by the admin user.
depositAmount: absolute transaction amount used for deposit (always positive value)
withdrawalAmount: absolute transaction amount
depsoitCanceledAmount: absolute transaction amount
withdrawalCanceledAmount: absolute transaction amount

Example:

{"collection":"Payment","onlineCustomerId":"6605","sentAt":"2022-01-
04T12:10:17.3216032+01:00","createdAt":"2022-01-04T12:08:56.2222","transaction":
{"transactionId":511,"transactionType":"deposit","currency":"EUR","currencyRate":1.0,"wallet":"sho
p","newBalance":112.05,"paymentComment":"test","amount":10.0,"depositAmount":10.0}}

 
2.7 Bet Transaction
For each event changing the current balance of a client, a transaction is being created. The SBS
uses many types of transactions, but for simplicity we will summarize them in two major types:
payment and bet transactions. The base object will contain common properties used for each
transaction type:

"transaction": {

"transactionType": "deposit",

"transactionId": 1234,

"currency": "EUR",

"currencyRate": 1.000,

"wallet": "online",

"amount": 1.00

"newBalance": 1.00,

transactionType: Depending on the transaction type, the object may contain additional
information
transactionId: unique transaction ID in SBS
currency: ISO 4217 currency code
currencyRate: currency exchange rate to EUR. (for example an amount of 1,00 and a rate of
2,000 would be 0,500 EUR)
wallet: an SBS account can have multible balances at the same time. Each being considered
its own wallet and can be used for specific purposes only. As of know the following wallets
are possible: shop, online, casino, sportbonus, casinobonus
amount: the monetary transaction value (if positive, balance gets increased, if negative
balance gets decreased)
newBalance: resulting balance of the wallet after transaction has been performed

Wallet Definition:

sport: balance available for sportbets only

casino: balance available for casino games only
sportbonus: bonus balance, can be used only for sportbets
casinobonus: bonus balance, can be used only for casino games
shop: balance available for customer cards to be used only inside shops and only for
sportbets

For bet transactions transactionType depends on the status of the bet.

transactionType: "stake" will be used when a bet has been placed

transactionType: "stakeCanceled" will be used when bet has been canceled
transactionType: "fee" will be used if bet has been placed and a fee has been charged
transactionType: "feeCanceled" will be used if bet has been canceled and fee has been
returned
transactionType: "win" will be used if a bet has won
transactionType: "winCanceled" will be used if a won bet has been canceled
transactionType: "cashout" will be used if a cashout has been performed
transactionType: "cashoutCanceled" will be used if a cashout has been canceled

The object may contain the following additional properties:

betId: unique ID of the coupon

 betNumber: for example "123/123456" where the first part contains the shop ID and the
second part the number of the coupon unique within one shop
betType: type of the bet (single, combi or system bet).
maxOdd: the maximum accumulated odd. meaning the maximum win can not be higher
than stake * maxOdd.
stakeAmount: absolute transaction amount
stakeCanceledAmount: absolute transaction amount
feeAmount: absolute transaction amount
feeCanceledAmount: absolute transaction amount
winAmount: absolute transaction amount
winCanceledAmount: absolute transaction amount
cashoutAmount: absolute transaction amount
cashoutCanceledAmount: absolute transaction amount

The betType can contain specific values. here are some examples and their meanings:

"E": single bet

"2o2": combi bet where 2o2 means the coupon contains two odds and both need to win
"1o2": system bet where 1o2 means one odd has to win to win a fraction of the max possible
win
"1o2/2o2": a coupon can contain multiple types of combinations seperated by a slash.
"1o2+1B": a system bet containing one bank. meaning: the bet contains three odds. one has
to win in any case or the whole coupon is lost and from the remaining two odds, at least one
needs to win.

Example:

{"collection":"Transaction","onlineCustomerId":"6605","sentAt":"2022-01-
04T12:07:16.6456103+01:00","createdAt":"2022-01-04T12:05:30.3576","transaction":
{"transactionId":510,"transactionType":"stake","currency":"EUR","currencyRate":1.0,"wallet":"sport
","newBalance":86.27,"betId":256,"betNumber":"6/221","betType":"E","maxOdd":1.27,"amount":-1.
0,"stakeAmount":1.0}}

4 PEP and Sanction Checks

4.1 Purpose
MGT provides an endpoint for passing client details for the purpose of checking against their PEP
and Sanction database. If one or more hits were found, the response is expected to contain a
rating property, which SBS uses for onboaring automation and ongoing client assesments.

4.2 Request
The request can be performed using the /registration endpoint. The authorization token
obtained from auth request needs to be passed inside the header as a bearer token. See example
below:

Request Example:

curl --location --request POST 'https://api-demo.mgt.eu/registration' \

--header 'Content-Type: application/json' \

 --header 'Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IlA2R3hHWEhmcXBtRW0xeDEwR2EyIiwiaWF0
IjoxNjQwMDg1NjEwLCJleHAiOjE2NDAwODkyMTB9.6uMVui8M6HRngW5qymnx_7x_CL6xCCw
Ji0QYPhD-x-k' \

--data-raw '{

"collection": "Identify",

"services": ["PEP", "Sanction"],

"birthdate": "2021-01-31",

"city": "München",

"country":"Deutschland",

"email":"test@test.com",

"firstName":"Vorname",

"gender":"Mann",

"houseNr":"1a",

"lastName":"Nachname",

"postcode":"12345",

"street":"Straße"

}'

The input parameters must contain the following mandadory properties:

collection: pass "Identify".

services: Array of comands. PEP and Sanction needs to be included for receiving expected
results
birthdate: the client's birthdate (Format yyyy-MM-dd)
country, city, postcode, street, houseNr: the client's current residence
email: the client's email adress
gender: the client's gender. expected values are "Frau" (Female) and "Mann" (Male)
firstName, lastName: the client's first and last name

Note: SBS issues a request automatically on client signup. In addition, manual requests can be
triggered from the SBS admin panel for ongoing assessments.

Error Response Example:

"message": "Internal Server Error"

Success Response Example:

{

"tolerantPEP": {

"service": "PEP",

"returnCode": 0,

"errorMsg": "OK",

"reqId": "ef35b9fb-186b-4ab6-b0e5-f69b2181d5d4",

"resultOverflow": false,

"resultCount": 0,

"ruleHits": [

"A_NO_HITS"

],

"hits": [

"rating": "A",

"color": "Green",

"description": "No Hit"

}

},

"tolerantSanction": {

"service": "Sanction",

"returnCode": 0,

"errorMsg": "OK",

"reqId": "ef35b9fb-186b-4ab6-b0e5-f69b2181d5d4",

"resultOverflow": false,

"resultCount": 13,

"ruleHits": [

"BB_UNSURE_SL_01"

],

"hits": [

"rating": "B",

"color": "Yellow",

"description": "Similar Sanction List Hit"

],

"results": [

"key": "90019128001",

"score": 95,

"ruleId": "8",

"ruleName": "R8",

"singleScores": {

"FullNameORF": "0",

"relativeId": 0,

"recordType": 0,

"title": 0,

"gender": 0,

"firstName": 0,

"lastName": 0,
"fullName": 95,

"otherNames": 0,

 "alternativeScript": 0,

"function": 0,

"specificfunction": 0,

"category": 0,

"exPEPs": 0,

"dateNotInChargeSince": 0,

"dob": 0,

"pob": 0,

"country": 0,

"additionalInformation": 0,

"countryOfOrigin": 0,

"countryOfActivity": 0,

"pid": 100

},
"internalData": {

"FullNameORF": "ngaikosset eugene barret",

"relativeId": "90019128",

"fullName": "ngaikosset eugene barret",

"dob": "08 10 1967",

"country": "caf",

"additionalInformation": "bangui",

"pid": "us"

},
"originalData": {

"FullNameORF": "NGAIKOSSET, Eugene Barret",

"relativeId": "90019128",

"fullName": "NGAIKOSSET, Eugene Barret",

"function": "Geburtsdaten: DOB 08 Oct 1967; alt. DOB 10 Aug 1967; POB
Bossangoa, Central African Republic Geburtsort: Bossangoa Geburtsland: CF
Staatsangehörigkeit",

"specificfunction": "SDN",

"category": "USSDN - CAR",

"dob": "08.10.1967",

"country": "CF",

"additionalInformation": "Bangui",

"pid": "US"

The response contains two main properties named "tolerantPEP" and "tolerantSanction". The first
one may contain PEP related hits, while the second one may contain sanction related hits. Both of
them contain the following properties:

service: type of results (for example PEP or Sanction)

returnCode: 0 = request was successfull, other codes may be used for any error occcured
during the request.
errorMsg: in case of unsuccessfull request, this property may contain additional information
about the error
 reqId: unique request id
resultOverflow: true/false (may be used to indicate too many results for returning all of
them)
resultCount: count for results matching the input params
ruleHits: array contains hints about hit rules, leading to the result
hits: contains the summary of the request result
results: list of hits (detail records about the hits)

The "hits" property contains the following sub properties:

rating: in case of positive hits, this property contains a rating for the purpose of risk
validation. The values to be expected are "A", "B", "C", where A means no relevant matches
were found, B means similar matches were found and C means exact matches were found.
color: contains a signal color which may be used to highlight a rating
description: description of the rating

SBS uses the "returnCode" property to check the overall success of the request and "hits.rating"
for internal reporting. All other properties are being logged for manual review if needed.

Note: SBS considers a response without results to be the same as an "A" rating. For automatic PEP
and Sanction Check on client onboarding, only "A" rating will used to skip detailed review by an
employee.

5 Verification
5.1 Purpose
MGT provides an endpoint for automated verification on client onboarding. The endpoint will
return an url, the client will be redirected to and provides an UI for the client to upload his
identification documents. The verification itself will be handled by one of the configurated third
party identification provider. The result of the verification will then be pushed to a callback
endpoint to SBS, for completing the automated verification process.

5.2 Request
The request can be performed using the /registration endpoint. The authorization token
obtained from auth request needs to be passed inside the header as a bearer token. See example
below:

Request Example:

curl --location --request POST 'https://api-demo.mgt.eu/registration' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IlA2R3hHWEhmcXBtRW0xeDEwR2EyIiwiaWF0
IjoxNjQwMDg1NjEwLCJleHAiOjE2NDAwODkyMTB9.6uMVui8M6HRngW5qymnx_7x_CL6xCCw
Ji0QYPhD-x-k' \

--data-raw '{
 "collection": "Identify",

"birthdate": "2021-01-31",

"city": "München",

"country":"Deutschland",

"email":"test@test.com",

"firstName":"Vorname",

"gender":"Mann",

"houseNr":"1a",

"lastName":"Nachname",

"postcode":"12345",

"street":"Straße"

"callbackUrl":

"returnUrl":

}'

The input parameters must contain the following mandadory properties:

collection: pass "Identify".

birthdate: the client's birthdate (Format yyyy-MM-dd)
country, city, postcode, street, houseNr: the client's current residence
email: the client's email adress
gender: the client's gender. expected values are "Frau" (Female) and "Mann" (Male)
firstName, lastName: the client's first and last name
callbackUrl: the URL used for pushing the result of the verification to SBS
returnUrl: the URL the client will be redirected to, after compleding the verification (for
example https://sportsbook.de/callbackendpoint)

Note: compared to PEP and Sanctions, no services param should be used.

Note: SBS issues a request automatically on client signup, if internal verification processes fail.

Error Response Example:

"message": "Internal Server Error"

Success Response Example:

"id": "qJugjZbg5s4rvFMM5X5M"

"identUrl": "https://fastident-demo.mgt.eu/ident/sid/2003/1fa5eb52-442f-431e-8bab-a8737
08d3f9b"

}
The response contains two main properties named "id" and "identUrl".

id: the unique verification id, which will be used on callback to identify the client in SBS
identUrl: the url the client should be redirect to for the verification process

5.3 Callback
Once the verification process finished, a HTTP GET request will be performed from MGT to the
callbackUrl passed on initial verification request. The callback request will contain a HTTP param
named "transactionId", containing the verification id received on initial verification request. For
example:

https://sportsbook.de/callbackendpoint?transactionId=qJugjZbg5s4rvFMM5X5M

The callback endpoint is expected to return a json object as shown below:

Response Example:

"success": true

The success value may be true or false depending on whether or not the input validation was
successful.