Ticket Placement Request
Client
→
MTS
The 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 core function 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 list of fields and descriptions, please refer to 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
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
See Content object description below
M
Object
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
Timestamp of ticket placement as submitted by the client (Unix time in milliseconds format), minimal: 1, maximum: 9223372036854776000
M
Integer
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
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:
Object
type
Declaration of content type, should be "ticket" in case of Ticket placement request
M
String
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
See bets array description, minimal number of bets per content (ticket) = 1, maximum number = 50
M
Array
context
Ticket context - additional information related to the ticket
M
Object
channel
Specifies the means of delivery of service to client's end customers (bettors), also called distribution channel
M
Object
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
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
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
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
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
— location
May be present only if "type": "retail" or "type": "terminal"
O
Object
--— type
Currently the only supported type: "geo"
M
String
--— latitude
min. value: -90.0, max. value: 90.0
M
Number
--— longitude
min. value: -180.0, max. value: 180.0
M
Number
(end of "channel" object)
payoutCap
Array of ticket maximum payouts, minimal number of payout caps per ticket =1, maximum number = 5
O
Array
type
Enumerator:
cash
withheld
M
String
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
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
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
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
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
End customer's suggested CCF Java regex: ^\\d{1,8}(\\.\\d{1,8})?$
O
String
(end of endCustomer object)
limitId
LimitId number provided to the client by Sportradar MTS CI team or OAM, minimal value =1, maximum value = 2147483647
M
Integer
ref
Reference to another ticket, must be present when placing a request with Alternative stake
M
(only in requests with Alternative stake)
ticketId
Id of the referenced ticket, for the field format, see description
M
String
ticketSignature
Signature from MTS's response to initial ticket placement
M
String
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
Array of bets, minimal number of bets per content (ticket) = 1, maximum number = 50
M
Array
betId
Unique bet id (in the client's system), minimal string length = 1, maximum length = 128
O
String
selections
Array of bet selections, see description, minimal number of selections per bet = 1, maximum number = 100
M
Array
stake
Array of bet stakes, minimal number of stake per bet =1, maximum number = 5
M
Array
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
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
See description
M
String
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
A string to help identify the source of operation/action/state
Minimal string length = 1, maximum length = 128,
O
String
context
Bet context - additional information related to the bet
O
Object
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
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
Array of selections, minimal number of selections per bet = 1, maximum number = 100
M
Array
type
Any of 7 specific selection types is allowed here, see descriptions below
M
String
1. Selections ("type": "uf") table:
This type of selection 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
Specifies a Selections type
M
String
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
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
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
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
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
M
Object
type
Supported odds formats:
"type": "decimal", "type": "fractional", "type": "moneyline", "type": "hong-kong", "type": "indonesian", "type": "malay"
M
String
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
Numerator of fractional odds, only present in "type": "fractional", Java regex: ^[1-9]\d{0,7}$
M
only if "type": "fractional"
String
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
Specifies a Selections type
M
String
event
Unique event identifier as defined by the client, see format rules, minimal string length = 1, maximum length = 100,
M
String
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
See odds description
M
Object
type
M
String
value
M
String
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
Specifies a Selections type
M
String
selections
Nesting of array of selections of "type":"uf", minimal number of selections = 2, maximum number = 10
M
Array
type
Only selections of "type":"uf" are allowed here
M
String
odds
See odds description above
M
Object
type
M
String
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
Specifies a Selections type
M
String
selections
Nesting of array of selections of any type, minimal number of selections = 2, maximum number = 30
M
Array
type
Nested selection type, currently only "uf" is supported.
M
String
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
Specifies a Selections type
M
String
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
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
Specifies the Selection type
M
String
selection
Selection to which the boosted odds apply
M
Object
type
Only selections of "type":"uf" or "type":"external" are allowed here (as only these two types are supported)
M
String
type
M
String
value
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
Specifies the Selection type
M
String
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
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 to which the promotion applies
M
Object
type
Only selections of "type":"uf" are allowed here
M
String
Last updated
Was this helpful?