Ticket Placement Request
Client
→
MTS
Ticket placement request is the main element in the client-to-MTS communication. It contains the actual bets the client has received from the end customer. The request is sent to MTS, which will respond with a Ticket placement response. The essential part of the response is MTS's suggestion of whether this concrete bet (or ticket) should be accepted or rejected. In other words, this is the corefunction of the risk management system. MTS determines the mentioned suggestion in a process called ticket validation. In this process, MTS considers multiple factors, including comparing the actual bet (ticket) against the client's configuration parameters and the client's accumulated liability (incurred by previously accepted tickets).
Ticket structure
From the top-level perspective, a ticket consists of two parts:
envelope
content
The envelope includes additional information about the content. Envelope fields are described in the below Envelope and Content table.
The content part represents the Ticket placement request itself and constitutes the Content object.
The most complex part of the Content object is the Bets array (described in a separate table below).
Further on, the Bets array includes several fields, with the Selections array being the most complex one (also described in a separate table below).
The following diagram depicts the ticket structure by using a simple ticket example. Please note that this diagram does not include all possible fields. For a complete field list and description, please see the tables below.
Ticket structure diagram:
Envelope and Content table:
The Envelope provides the Content's (Ticket placement request) context and contains the following fields (besides Content):
operatorId
correlationId
timestampUtc
operation
version
{
"operatorId": 9985,operatorId
ID to uniquely identify the client from which the ticket originated ID is provided to the client by Sportradar The client is obliged to include it in every ticket
M
Integer
"content": {content
See Content object description below
M
Object
...........
...........
},
"correlationId": "Uw59kwUL",correlationId
Client defined string to facilitate the request-response pairing, Sportradar is obliged to return the same string in the corresponding response
M
String
"timestampUtc": 1678202888000,
timestampUtc
Timestamp of ticket placement as submitted by the client (Unix time in milliseconds format), minimal: 1, maximum: 9223372036854776000
M
Integer
"operation": "ticket-placement",operation
Should be "ticket-placement" in the case of Ticket Placement Request,
in the case of Cancellation, Cash-out, External Settlement and Pre-validated Ticket Placement requests / responses - enumerator:
"ticket-cancel"
"ticket-cashout"
"ticket-ext-settlement"
"ticket-placement-inform",
in the case of Acknowledgement messages and Acknowledgement reply messages - enumerator:
"ticket-placement-ack"
"ticket-cancel-ack"
"ticket-cashout-ack"
"ticket-ext-settlement-ack"
M
String
"version": "3.0"version
Indicates the ticket format version
M
String
}
Content object (Ticket placement request)
This object constitutes the ticket itself. Its main part is the bets array (which represents one or more actual bets) and additional information related to the ticket.
The Content object includes the following fields:
type
ticketId
bets (array)
context (ticket context)
location
Content object table:
"content": {
Object
"type": "ticket",type
Declaration of content type, should be "ticket" in case of Ticket placement request
M
String
"ticketId": "Ticket_3690",ticketId
Client defined string to identify the ticket (unique in the client's system), minimal string length = 1, maximum string length = 128
M
String
"bets": [bets
See bets description, minimal number of bets per content (ticket) = 1, maximum number = 50
M
Array
........... ],
"context": {context
Ticket context - additional information related to the ticket
M
Object
"channel": {channel
Specifies the means of delivery of service to client's end customers (bettors), also called distribution channel
M
Object
"type": "mobile",type
Declaration of channel type, enumerator:
agent
call-centre
internet
mobile
mobile-app
phone (used for USSD betting - USSD is a communication protocol in mobile networks)
retail
sms
terminal
tv-app
M
String
"ip": "109.74.24.155",ip
IP address of the end customer's device
May be present only if "type": "internet" or "type": "mobile" or "type": "mobile-app" or "type":" tv-app"
O
String
"deviceId": "device_133123",deviceId
ID of the end customer's device
May be present only if "type": "mobile" or "type": "tv-app" or "type": "internet" or "type": "retail" or "type": "sms" or "type": "mobile-app"
Minimal string length = 1, maximum length = 36, allowed characters : uppercase and lowercase letters, numerals, #, :, -, _, \ Java regex: ^[0-9A-Za-z#:\\-_]{1,36}$
O
String
"shopId": "shop_789135",shopId
ID of the shop
May be present only if "type": "retail" or "type": "terminal"
Minimal string length = 1, maximum length = 36, allowed characters : uppercase and lowercase letters, numerals, #, :, -, _, \
M if "type": "retail" or "type": "terminal"
String
"terminalId": "term_2313",terminalId
May be present only if "type": "terminal"
Minimal string length = 1, maximum length = 36, allowed characters : uppercase and lowercase letters, numerals, #, :, -, _, \
M if "type": "terminal"
String
"lang": "ES",lang
End customer's user interface language code according to ISO 639-1 (string length = 2)
M
String
"location": {— location
May be present only if "type": "retail" or "type": "terminal"
O
Object
"type": "geo", --— type
Currently the only supported type: "geo"
M
String
"latitude": 46.1,--— latitude
min. value: -90.0, max. value: 90.0
M
Number
"longitude": 14.5 }--— longitude
min. value: -180.0, max. value: 180.0
M
Number
},
(end of "channel" object)
"payoutCap": [payoutCap
Array of ticket maximum payouts, minimal number of payout caps per ticket =1, maximum number = 5
O
Array
{
"type": "cash",type
Enumerator:
cash
withheld
M
String
"currency": "EUR",currency
3 or 4 letter currency code, BTC and mBTC are also supported (4 letters only apply to mBTC). For more details please check https://www.iso.org/iso-4217-currency-codes.html
M
String
"amount": "100",amount
String pattern: 1 up to 8 digits, optionally followed by a decimal point and 1 up to 8 digits, Java regex: ^\\d{1,8}(\\.\\d{1,8})?$
M
String
"traceId": "Source2099"traceId
A string to help identify the source of operation/action/state
Minimal string length = 1, maximum length = 128,
O
String
}
],
(end oy payoutCap array)
"endCustomer": {endCustomer
Data about client's end customer (bettor), it can only be omitted if the bet is placed by an unregistered bettor in retail or on a terminal
O
Object
"id": "endCustomer_e34t45",id
End customer's unique ID (in client's system). It should be an anonymous value which cannot be used to identify a physical person. minimal string length = 1, maximum length = 36, allowed characters are : uppercase and lowercase letters, numerals, #, :, -, _, \ Java regex: ^[0-9A-Za-z#:\\-_]{1,36}$
M
String
"confidence": "1.15"confidence
End customer's suggested CCF Java regex: ^\\d{1,8}(\\.\\d{1,8})?$
O
String
},
(end of endCustomer object)
"limitId": 1409,limitId
LimitId number provided to the client by Sportradar MTS CI team or OAM, minimal value =1, maximum value = 2147483647
M
Integer
"ref": {ref
Reference to another ticket, must be present when placing a request with Alternative stake
M
(only in requests with Alternative stake)
"ticketId": "Ticket_1005",ticketId
Id of the referenced ticket, for the field format, see description
M
String
"ticketSignature": "AAbzv7XIEl+SmjWB3x
DB0AIB6fUZVFOvmGKm6Rcvxm0=",ticketSignature
Signature from MTS's response to initial ticket placement
M
String
"type": "alt-stake"type
Indicates the MTS functionality which was used when offering a suggested acceptable stake, Enumerator:
alt-stake
reoffer
M
String
}
(end of ref object)
}
(end of context object)
},
(end of content object)
Relations between distribution channel parameters
Distribution channel
"channel type"
End-customer is
"channel"
"ip"
"deviceId"
"shopId"
"terminalId"
"lang"
"endCustomer"
"id"
agent
registered
mandatory
omitted
omitted
omitted
omitted
mandatory
mandatory
call-centre
registered
mandatory
omitted
omitted
omitted
omitted
mandatory
mandatory
internet
registered
mandatory
optional
optional
omitted
omitted
mandatory
mandatory
mobile
registered
mandatory
optional
optional
omitted
omitted
mandatory
mandatory
mobile-app
registered
mandatory
optional
optional
omitted
omitted
mandatory
mandatory
phone
registered
mandatory
omitted
omitted
omitted
omitted
mandatory
mandatory
retail
unregistered
mandatory
omitted
optional
mandatory
omitted
mandatory
omitted
retail
registered
mandatory
omitted
optional
mandatory
omitted
mandatory
mandatory
sms
registered
mandatory
omitted
optional
omitted
omitted
mandatory
mandatory
terminal
unregistered
mandatory
omitted
omitted
mandatory
mandatory
mandatory
omitted
terminal
registered
mandatory
omitted
omitted
mandatory
mandatory
mandatory
mandatory
tv-app
registered
mandatory
optional
optional
omitted
omitted
mandatory
mandatory
Bets array
The actual bets are specified in the Bets array. Ticket format v3.0 allows for multiple bets to be included in one ticket. Each Bets array element consists of the following fields:
betId
selections
stake
context (bet context)
Bets array table:
"bets": [bets
Array of bets, minimal number of bets per content (ticket) = 1, maximum number = 50
M
Array
{
"betId": "Ticket_3690_bet0",betId
Unique bet id (in the client's system), minimal string length = 1, maximum length = 128
O
String
"selections":
[ {
......
......
} ], selections
Array of bet selections, see description, minimal number of selections per bet = 1, maximum number = 100
M
Array
"stake": [stake
Array of bet stakes, minimal number of stake per bet =1, maximum number = 5
M
Array
{
"type": "cash",type
Stake type, enumerator:
cash (used for stake and payout)
bonus (amount added on top of end customer's winnings in case a bet is won )
M
String
"currency": "DKK",currency
The client must always submit stakes in punter's local currency,
Currently MTS does not support multiple bets with stakes in different currencies,
See description
M
String
"amount": "12",amount
See description
M
String
"mode": "total",mode
Stake mode enumerator (default = total):
unit - stake amount relates to each sub-bet (a sub-bet is one combination (in case of system bets))
total - stake amount relates to all sub-bets (each sub-bet receives a portion of the amount)
O
String
"traceId": "Source_2099"
}
],traceId
A string to help identify the source of operation/action/state
Minimal string length = 1, maximum length = 128,
O
String
"context": { context
Bet context - additional information related to the bet
O
Object
"oddsChange": "higher", oddsChange
Specifies MTS behaviour in the event when the actual odds from the client's UOF at the moment of validation differ from those submitted in the ticket, enumerator:
none: do not accept odds change, ticket rejected - default behaviour
any: accept tickets with any odds change, consider feed's odds
lower: (Currently not supported) accept tickets when feed's odds are equal or lower, consider feed's odds
higher: accept tickets when feed's odds are equal or higher, consider feed's odds
O
String
"payoutCap": [
{
.......
.......
}] payoutCap
Array of bet maximum payouts, minimal number of payout caps per bet =1, maximum number = 5
See description of payoutCap array above
O
Array
}
}
],
Selections array
The actual selections (one or more) that constitute a bet are included here. A selection represents a specific outcome (the one that a bettor places a bet on) of a specific market of an event. (Basic example: home win in 1x2 market of a soccer match.)
There are 5 types of selections foreseen in the ticket format v3.0 as well as several ways of selection nesting.
Selections array table:
"selections": [selections
Array of selections, minimal number of selections per bet = 1, maximum number = 100
M
Array
{
"type": .....,
........
........
}
], type
Any of 7 specific selection types are allowed here, see description below
M
String
1. Selections ("type":"uf") table:
This type of selections is used in cases when outcomes, markets, events and specifiers (additional info) originate from UOF (from one of the UOF producers). The IDs of the elements mentioned also correspond to values obtained from UOF. Market settlements are also obtained from UOF.
Fields:
type
productId
eventId
marketId
outcomeId
specifiers
odds
{
"type": "uf",type
Specifies a Selections type
M
String
"productId": "3",productId
Specifies the UOF producer, i.e. 1 for LiveOdds, 5 for Premium Cricket, value is retrieved from the UOF feed, Minimal string length = 1, maximum length = 5
M
String
"eventId": "sr:match:16470657",eventId
Specifies a betting event as defined by UOF, Value is retrieved from the UOF feed, Minimal string length = 1, maximum length = 100
M
String
"marketId": "534",marketId
Specifies a betting market as defined by UOF, Value is retrieved from the UOF feed, Minimal string length = 1, maximum length = 100
M
String
"outcomeId": "pre:outcometext:9919",outcomeId
Specifies a market outcome as defined by UOF, Value is retrieved from the UOF feed, Minimal string length = 1, maximum length = 1000,
M
String
"specifiers": "setnr=1|total=45.5",specifiers
Specifies an additional market data as defined by UOF, Value is retrieved from the UOF feed, Minimal string length = 1, maximum length = 1000
O*
*Although optional in the schema, when the UOF market is additionally defined by a specifier (market line: Total 1.5, Total 2.5), the specifier must be provided in the bet.
String
"odds": {odds
M
Object
"type":"decimal",type
Supported odds formats:
"type": "decimal", "type": "fractional", "type": "moneyline", "type": "hong-kong", "type": "indonesian", "type": "malay"
M
String
"value": "7.1", value
Odds value submitted by the client, String pattern: 1 up to 8 digits (the first digit should not be 0), optionally followed by a decimal point and 1 up to 8 digits, Java regex: ^[1-9]\\d{0,7}(\\.\\d{1,8})?$
M
String
"numerator": "10",numerator
Numerator of fractional odds, only present in "type": "fractional", Java regex: ^[1-9]\d{0,7}$
M
only if "type": "fractional"
String
"denominator": "3"
}
}denominator
Denominator of fractional odds, only present in "type": "fractional", Java regex: ^[1-9]\d{0,7}$
M
only if "type": "fractional"
String
2. Selections ("type":"external") table: Used in cases when outcomes, events, odds and market settlements are not related to UOF or Sportradar but are managed by the client instead. Clients should provide unique identification of events and outcomes. Clients should provide ticket settlements on time (utilising External settlement requests).
Fields:
type
event
expSettleTime
odds
outcome
{
"type": "external",type
Specifies a Selections type
M
String
"event": "ext:match:736977",event
Unique event identifier as defined by the client, see format rules, minimal string length = 1, maximum length = 100,
M
String
"expSettleTime": 1691581504000,expSettleTime
To inform MTS about the expected time of settlement, MTS may start certain actions based on this time (e.g. automatic settlement of unsettled tickets), (Unix time milliseconds format), see format rules, minimal: 1, maximum: 9223372036854776000
M
Integer
"odds": {odds
See odds description
M
Object
"type": "decimal",type
M
String
"value": "7.1"value
M
String
},
"outcome": "ext-pre:9985:s77"
}outcome
Unique outcome identifier as defined by the client, should include unique designation of betting market and selection, see format rules, minimal string length = 1, maximum length = 1000,
M
String
3. Selections ("type":"uf-custom-bet") table: Used in cases when selections constitute a custom bet (a bet including selections which would normally be rejected due to contingency rules). For more information, please see Custom Bet description.
Fields:
type
selections (array)
odds
{
"type": "uf-custom-bet",type
Specifies a Selections type
M
String
"selections": [selections
Nesting of array of selections of "type":"uf", minimal number of selections = 2, maximum number = 10
M
Array
{
"type": "uf",type
Only selections of "type":"uf" are allowed here
M
String
.......
.......
}
],
"odds": {odds
See odds description above
M
Object
"type": "decimal",type
M
String
"value": "7.1"value
M
String
}
}
4. Selections ("type": "system") table: This type of selection contains multiple selections that form a system bet.
Fields:
type
selections (array)
size (array)
{
"type": "system",type
Specifies a Selections type
M
String
"selections": [selections
Nesting of array of selections of any type, minimal number of selections = 2, maximum number = 30
M
Array
{
"type": "uf",type
Nested selection type, currently only "uf" is supported.
M
String
.......
.......
}
],
"size": [2,3 size
Array of size items (each item must be unique), each item represents a system bet (in this example 2/4 and 3/4, given that there are four selections to make systems from), minimal number of items = 1, maximum number of items = 30
M
Array of integers
],
}
5. Selections ("type":"ways") table:
This type of selection contains one or more selections related to an event (or even the same market on an event) that are already included in another selection of the same bet.
Fields:
type
selections (array)
{
"type": "ways",type
Specifies a Selections type
M
String
"selections": [selections
Nesting of array of selections of "type":"uf" or "type":"external" or "type":"odds-boost", minimal number of selections = 2, maximum number = 30
M
Array
{
"type": "uf",type
Only selections of "type":"uf" or "type":"external" or "type":"odds-boost" are allowed here (as only these types include "eventId" (or "event") field)
M
String
.......
.......
}
],
}
6. Selection ("type":"odds-boost") table:
This type of selection contains boosted odds and a selection type = "uf" or "external" (as only these are currently supported).
Fields:
type
selection
odds (boosted odds)
{
"type": "odds-boost",type
Specifies the Selection type
M
String
"selection": {selection
Selection to which the boosted odds apply
M
Object
"type": "uf",type
Only selections of "type":"uf" or "type":"external" are allowed here (as only these two types are supported)
M
String
........
........
},
"type": "decimal",type
M
String
"value": "7.1value
M
String
}
}
7. Selection ("type":"payout-modifier") table:
This type of selection contains a selection that is eligible for the payout modification.
Fields:
type
selection
description
reference
{
"type": "payout-modifier",type
Specifies the Selection type
M
String
"reference": "24uAF4GHCmL3pYOmQujyjRsLTfrRIRDn",reference
Specifies the unique identifier of the promotion that will be used in the settlement message to identify outcomes that need to be settled (across all eligible tickets), client defined string.
M
String
"description": "2 Up",description
Specifies the type of promotion to which the selection is linked, client defined string, max. string length = 512, min. string length =1.
Examples: "2 Up", "2 Goal Early Payout", "Early Payout", "Lose To Win", "Supersub"
O
String
"selection": {selection
Selection to which the promotion applies
M
Object
"type": "uf",
.......
.......
}
}type
Only selections of "type":"uf" are allowed here
M
String
Last updated
Was this helpful?