Cash-out Requests
Client
→
MTS
Cash-out request types
Cash-out Inform (operation: "cashout-inform") - This request is sent to MTS to inform it that a specific cash-out event has occurred. The client does not expect a validation of this cash-out event. However, MTS does perform a basic check on the received values, such as whether the current potential win has been exceeded.
Cash-out Build (operation: "cashout-build") - This request is optional and may be sent by the client once or multiple times to obtain information about a potential cash-out event (for example, when the client is preparing a cash-out offer to its bettor).
Cash-out Placement (operation: "cashout-placement") is sent to MTS when the client expects MTS to fully validate a cash-out event, including a validation result (accepted/rejected).
Auto Cash-out (operation: "auto-cashout") is sent to MTS along with the expected cash-out amount (threshold) for a particular transaction. When the threshold is reached, the client is notified via a separate Transaction Stream WebSocket connection. The client can then perform the actual cash-out and send either a Cash-out Inform or a Cash-out Placement to MTS.
Auto Cash-out Cancellation (operation: "auto-cashout-cancel") cancels a previously activated Auto Cash-out check when the threshold is reached, along with the subsequent notification.
Cash-out Build Subscription (operation: "cashout-build-subscription") is sent to MTS to subscribe to cash-out build updates for a specific ticket or bet. Unlike the standard Cash-out Build request, the payout array can be empty, allowing the client to receive cash-out suggestions without specifying an initial payout value.
The "ticket-cashout" operation and "cashout" content type will be deprecated. Do not use them in new projects, use "cashout-inform" instead. Currently, the old types are still accepted to maintain compatibility.
Description of cash-out request handling
MTS supports cash-out requests regarding cash-outs of live and pre-match bets and for singles, multiples and system bets. A Cash-out request will be accepted by MTS if the following conditions are met:
MTS must manage events from a risk management perspective
Ticket cash-out value is equal to or less than the maximum ticket value (Ticket Total Stake * Ticket Total Odds)
Ticket Total Stake – Stake amount in the original ticket
Ticket Total Odds – Product of all selection odds in the original ticket
A ticket can be cashed out in its entire or partial value. In the case of partial cash-out, a portion of the ticket’s current value is paid out to the end customer (bettor), while the remaining part still depends on the event's outcome. In this case, apart from the cash-out amount, the Cash-out request must also include the ratio of the ticket the end customer has cashed out (field "percentage"). MTS will validate if the provided cash-out value is equal to or lower than the same ratio of the maximum possible payout of the ticket.
Clients can send as many partial cash-out requests as they wish, provided that the cash-out amount and ratio of each cash-out request include the values of all previous cash-out requests. MTS does not aggregate cash-out amount and ratio values of individual requests and treats the last request as if there were no previous requests.
Using different types of the Cash-out details object makes it possible to cash out – fully or partially – a single bet or a subset of bets within a multi-bet ticket, with custom cash-out ratios for each bet.
Envelope and Content table:
The Envelope provides the content's (cash-out 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
correlationId
Client defined string to facilitate the request-response pairing, Sportradar is obliged to return the same string in every 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
Declaration of ticket content type, can be "cashout-inform" or "cashout-build" or "cashout-placement" or "auto-cashout" or "auto-cashout-cancel" or "cashout-build-subscription"
M
String
version
Indicates the ticket format version
M
String
1. cashout-inform Content object
The Content object includes the following fields:
type
cashout
validation
suggestionSignature
Content object table:
Object
type
Declaration of content type
M
String
validation
Cash-out validation information as provided by the client
M
Object
code
Cash-out validation code as provided by the client, minimum = -1000000, maximum = 100000
M
Integer
message
Readable cash-out validation message as provided by the client, minimal string length = 1, maximum string length = 128
M
String
rejected
Clients' indication that the cash-out has been rejected on their end. (A missing field means it has not been rejected.)
O
Boolean
suggestionSignature
Signature of the transaction (e.g., an auto-cashout trans.) that suggested this cash-out transaction, minimal string length = 1, maximum string length = 512, Java Regex: ^[A-Za-z0-9+/=]{1,512}$
O
String
2. cashout-build Content object
The Content object includes the following fields:
type
cashout
Content object table:
3. cashout-placement Content object
The Content object includes the following fields:
type
cashout
Content object table:
4. auto-cashout Content object and notification on threshold reached
A client sends an Auto Cash-out request to MTS for a specific transaction, including the expected cash-out amount. MTS continuously checks for the threshold to be reached, and once reached, notifies the client with a cashout-inform Content object. The client can then perform the actual cash-out and send to MTS either a Cash-out Inform or a Cash-out Placement. The notification is sent over a separate Transaction Stream WebSocket connection. Visit the Connectivity page to read how to establish this connection.
4.1 auto-cashout Content object
The Content object includes the following fields:
type
autoCashoutId
details
Content object table
Object
type
Declaration of content type
M
String
autoCashoutId
Unique ID of this particular auto cash-out request in the client's system,
minimal string length = 1, maximum length = 128,
O
String
details
Auto cash-out details
M
Object
type
Enumerator:
ticket
bet
M
String
ticketId
ID of the original ticket that is to be affected by this auto cash-out request
M
String
ticketSignature
Signature from MTS's response to initial ticket placement
M
String
betId
Field not present if "type": "ticket", ID of the initial bet (defined by client) that is to be affected by this cash-out request
M if "type": "bet"
String
threshold
Max array length = 2, Min array length = 1
M
Array
type
Enumerator:
take-win
stop-loss
M
String
percentage
Proportion of the bet that is to be cashed-out, format: up to 8 decimal places after a zero and decimal point, has to be passed as a decimal (i.e. 0.6 and not 60), Java regex: ^0(\\.\\d{1,8})?$
M
String
4.2 Notification on threshold reached (cashout-inform Content object)
The notification takes the form of a Cashout Inform request. It contains the standard transaction envelope and the cashout-inform Content object.
5. auto-cashout-cancel Content object
Content object includes the following fields:
type
cancellationId
details
Content object table
Object
type
Declaration of content type
M
String
cancellationId
Unique ID of this particular auto cash-out cancellation request in the client's system,
minimal string length = 1, maximum length = 128,
O
String
details
Auto cash-out details
M
Object
type
Enumerator:
ticket
bet
M
String
ticketId
ID of the original ticket that is to be affected by this auto cash-out cancellation request
M
String
ticketSignature
Signature from MTS's response to initial ticket placement
M
String
betId
Field not present if "type": "ticket", ID of the initial bet (defined by client) that is to be affected by this cash-out cancellation request
M if "type": "bet"
String
6. cashout-build-subscription Content object
The Cash-out Build Subscription request is used to subscribe to cash-out value updates for a specific ticket or bet. Unlike the standard Cash-out Build request, the payout array in the details object can be empty (minItems: 0), allowing the client to receive cash-out suggestions without specifying an initial payout value. The subscription stays active for up to 5 minutes. For details of returned cash-out values, see cashout-build-subscription-reply.
The Content object includes the following fields:
type
cashoutId
details
Content object table:
Object
type
Declaration of content type
M
String
cashoutId
Unique ID of this particular cash-out subscription request in the client's system,
minimal string length = 1, maximum length = 128
M
String
details
Cash-out subscription details - the same structure as standard cash-out details, but the payout array can be empty (minItems: 0).
See Details object for field descriptions.
Enum for type:
ticket
ticket-partial
bet
bet-partial
M
Object
Cashout object
The Cashout object contains the following fields:
type
cashoutId
details
context (cashout-context)
Cashout object table:
Object
type
Declaration of type
M
String
cashoutId
Unique ID of this particular cash-out request in client's system, referenced in eventual ack message, minimal string length = 1, maximum string length = 128
O
String
type
M
String
context
Cash-out context - additional information for the cash-out process
O
Object
autoAcceptChange
Enumerator:
not-set - Use current validation without changing accepted cashout.
any - Accept any cashout value change that will be calculated, including lower.
higher - Accept calculated cashout value change if it is equal to or higher (with rounding tolerance).
none - Accept only if calculated cashout value matches requested value (with rounding tolerance).
O
String
Details object
1. Details ("type": "ticket") table
This type is used to cash out an entire ticket.
Fields:
type
ticketId
ticketSignature
code
payout
Object
type
Defines the type of Cash-out details
M
String
ticketId
ID of the original ticket that is to be affected by this cash-out request
M
String
ticketSignature
Signature from MTS's response to initial ticket placement
M
String
payout
Session payout array, minimal number of payouts per session =1, maximum number = 5
M
Array
type
Enumerator:
cash
withheld
M
String
currency
2 to 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
stakeOrigin
Enumerator:
cash
bonus
free
free-cash
free-rollover
O
String
2. Details ("type": "ticket-partial") table
This type is used to cash out only a portion of the ticket.
Fields:
type
ticketId
ticketSignature
code
percentage
payout
Object
type
Defines the type of cash-out details
M
String
ticketId
ID of the original ticket that is to be affected by this cash-out request
M
String
ticketSignature
Signature from MTS's response to initial ticket placement
M
String
percentage
Proportion of the bet that is to be cashed-out, format: up to 8 decimal places after a zero and decimal point, has to be passed as a decimal (i.e. 0.6 and not 60), Java regex: ^0(\\.\\d{1,8})?$
M
String
3. Details ("type": "bet") table
This type is used to cash out an entire bet.
Fields:
type
ticketId
ticketSignature
betId
code
payout
Object
type
Defines the type of cash-out details
M
String
ticketId
ID of the original ticket that is to be affected by this cash-out request
M
String
ticketSignature
Signature from MTS's response to initial ticket placement
M
String
betId
ID of the initial bet (defined by client) that is to be affected by this cash-out request
M
String
4. Details ("type": "bet-partial") table
This type is used to cash out a portion of a bet.
Fields:
type
ticketId
ticketSignature
betId
code
percentage
payout
Object
type
Defines the type of cash-out details
M
String
ticketId
ID of the original ticket that is to be affected by this cash-out request
M
String
ticketSignature
Signature from MTS's response to initial ticket placement
M
String
betId
ID of the initial bet (defined by client) which is to be affected with this cash-out
M
String
percentage
Proportion of the bet that is to be cashed-out, format: up to 8 decimal places after a zero and decimal point, has to be passed as a decimal (i.e. 0.8 and not 80), Java regex: ^0(\\.\\d{1,8})?$
M
String
Request sequencing and correlation
The following sequence is recommended for a managed, full-risk-delegation cash-out:
The client may send multiple cashout-build requests while the bettor is viewing the ticket. A build request only calculates the current cash-out information; it does not change the ticket state and does not reserve the returned amount.
The client should use the ticketId and ticketSignature from the original accepted ticket-placement response in both the build and placement requests.
A placement request does not need to reuse:
the
cashoutIdfrom a previous build request;the signature from a
cashout-build-reply;a quote token or build-expiration token.
There is no protocol requirement to link a particular build response to a later placement request. The client should create unique cashoutId and correlationId values and retain them for client-side tracking and troubleshooting.
For operational consistency, clients should stop unnecessary build requests after sending placement and should prevent another cash-out action for the same ticket or bet until placement has returned a response.
An accepted cashout-placement completes the managed cash-out. The client must not send a subsequent cashout-inform for the same accepted placement.
Request target restrictions
Each cash-out request supports one target:
one ticket; or
one complete bet.
Unrelated tickets or bets cannot be batched into one request.
For a ticket target, a maximum of 50 bets and 100 selections per bet is supported.
A request may target a complete independent bet within a multi-bet ticket while the other bets remain open. A request must not target an individual selection or leg inside an accumulator.
MTS validates the Sportradar-managed content represented in the request. If the local ticket contains omitted, unsupported, or external content, the local full-ticket target may not be eligible for managed cash-out.
Partial cash-out values
Partial cash-out requests must contain cumulative values.
The percentage and payout values in each request must represent the total portion and total payout cashed out up to that request. MTS does not add the values from previous requests to the values in the latest request.
For example:
The second request represents 90% of the original stake and a cumulative payout of 30.00.
When the remaining portion is cashed out completely, use the complete ticket or complete bet details structure rather than a partial structure, as applicable.
Currency, precision, and stake origin
The payout currency in a cash-out request must be present on the original ticket. EUR is the MTS calculation base currency, and ticket-acceptance exchange rates are used for supported ticket currencies.
Cash-out values support up to 8 decimal places. If submitting fewer decimal places, round down. For example, 8.89514137 may be submitted as 8.89.
stakeOrigin is optional and defaults to cash. It can be used to distinguish cash-out values by stake type on a multi-stake ticket. Only the cash stake is managed by MTS.
traceId is optional and may be used by the client to identify the origin of a payout.
Last updated
Was this helpful?