# Cash-out Requests

<table><thead><tr><th width="115.0677490234375" align="center">Source</th><th width="55.919189453125" align="center"></th><th width="114.782958984375" align="center">Destination</th></tr></thead><tbody><tr><td align="center"><strong>Client</strong></td><td align="center"><strong>→</strong></td><td align="center"><strong>MTS</strong></td></tr></tbody></table>

### **Cash-out request types**

* Cash-out Inform (operation: "cashout-inform") - This request is sent to MTS when the client wants to inform MTS that a particular cash-out event has occurred. The client does not expect a validation of this cash-out event. However, MTS does perform a basic check of the values received, such as whether the current potential win has been exceeded.
* Cash-out Build (operation: "cashout-build") - This request is optional and may be sent over by the client once or several times whenever the client wants 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 provide a full validation of a cash-out event, including a validation result (accepted/rejected).

{% hint style="warning" %}
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.
{% endhint %}

<figure><img src="https://754701251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk9SMFSuFGUx0b4iEHZ2f%2Fuploads%2FPu0iOPxYsLLvZGW9QgDY%2FCashout%20operations%20and%20content%20types_MTS%20space.drawio.svg?alt=media&#x26;token=cab4752d-7b0b-45b6-90b3-f8a033db402d" alt=""><figcaption></figcaption></figure>

### **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

<table data-full-width="true"><thead><tr><th width="360.1171875">Example</th><th width="146.2960205078125">Field Name</th><th>Field Description</th><th width="100">Mandatory/Optional</th><th width="100">Data Type</th></tr></thead><tbody><tr><td><pre><code>{
</code></pre></td><td><br></td><td><br></td><td><br></td><td><br></td></tr><tr><td><pre data-overflow="wrap"><code>  "operatorId": 9985,
</code></pre></td><td>operatorId</td><td>ID to uniquely identify the client from which the ticket originated,<br>ID is provided to the client by Sportradar,<br>The client is obliged to include it in every ticket</td><td>M</td><td>Integer</td></tr><tr><td><pre><code>  "content": {
    .......
    .......
      },
</code></pre></td><td>content</td><td>See <a href="#mtscashoutrequests-v3.0-contentobject">Content object</a> description below</td><td>M</td><td>Object</td></tr><tr><td><pre data-overflow="wrap"><code>  "correlationId": "ds7w32ndsJg2",
</code></pre></td><td>correlationId</td><td>Client defined string to facilitate the request-response pairing,<br>Sportradar is obliged to return the same string in every response</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>  "timestampUtc": 1678273428000,
</code></pre></td><td>timestampUtc</td><td>Timestamp of ticket placement as submitted by the client (Unix time in milliseconds format),<br>minimal: 1,<br>maximum: 9223372036854776000</td><td>M</td><td>Integer</td></tr><tr><td><pre data-overflow="wrap"><code>  "operation": "cashout-inform",
</code></pre></td><td>operation</td><td><p>Declaration of ticket content type, can be "cashout-inform" or<br>"cashout-build" <br>or<br>"cashout-placement"</p><p><br></p></td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>  "version": "3.0"
</code></pre></td><td>version</td><td>Indicates the ticket format version</td><td>M</td><td>String</td></tr><tr><td>}</td><td><br></td><td><br></td><td><br></td><td><br></td></tr></tbody></table>

### Content object <a href="#mtscashoutrequests-v3.0-contentobject" id="mtscashoutrequests-v3.0-contentobject"></a>

The fields for each type of cash-out request are described in the following tables.

**Cashout Inform** content object table

<table data-full-width="true"><thead><tr><th width="360.26824951171875">Example</th><th width="161.7421875">Field Name</th><th>Field Description</th><th width="100">Mandatory/Optional</th><th width="100">Data Type</th></tr></thead><tbody><tr><td><pre><code>"content": {
</code></pre></td><td><br></td><td><br></td><td><br></td><td>Object</td></tr><tr><td><pre data-overflow="wrap"><code>    "type": "cashout-inform",
</code></pre></td><td>type</td><td>Declaration of content type</td><td>M</td><td>String</td></tr><tr><td><pre><code>    "cashout": {
      ........
      ........
       },
</code></pre></td><td>cashout</td><td>See description of <a href="#mtscashoutrequests-v3.0-cashoutcashoutobject">Cashout object</a></td><td>M</td><td>Object</td></tr><tr><td><pre><code>    "validation": {
</code></pre></td><td>validation</td><td>Cash-out validation information as provided by the client</td><td>M</td><td>Object</td></tr><tr><td><pre><code>        "code": 1100,
</code></pre></td><td><ul><li>code</li></ul></td><td>Cash-out validation code as provided by the client,<br>minimum = -1000000,<br>maximum = 100000</td><td>M</td><td>Integer</td></tr><tr><td><pre data-overflow="wrap"><code>        "message": "Validated, OK",
</code></pre></td><td><ul><li>message</li></ul></td><td>Readable cash-out validation message as provided by the client,<br>minimal string length = 1,<br>maximum string length = 128</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "rejected": false
</code></pre></td><td><ul><li>rejected</li></ul></td><td>Clients' indication if the cash-out has been rejected on the client side<br>(missing field means not rejected)</td><td>O</td><td>Boolean</td></tr><tr><td>}</td><td><br></td><td><br></td><td><br></td><td><br></td></tr><tr><td>},</td><td><br></td><td><br></td><td><br></td><td><br></td></tr></tbody></table>

**Cashout Build** content object table

<table data-full-width="true"><thead><tr><th width="360.470458984375">Example</th><th width="162.017333984375">Field Name</th><th>Field Description</th><th width="100">Mandatory/ Optional</th><th width="100">Data Type</th></tr></thead><tbody><tr><td><pre><code>"content": {
</code></pre></td><td><br></td><td><br></td><td><br></td><td>Object</td></tr><tr><td><pre data-overflow="wrap"><code>    "type": "cashout-build",
</code></pre></td><td>type</td><td>Declaration of content type</td><td>M</td><td>String</td></tr><tr><td><pre><code>    "cashout": {
         .......
         }
</code></pre></td><td>cashout</td><td>See description of <a href="#mtscashoutrequests-v3.0-cashoutcashoutobject">Cashout object</a></td><td>M</td><td>Object</td></tr><tr><td>},</td><td><br></td><td><br></td><td><br></td><td><br></td></tr></tbody></table>

**Cashout Placement** content object table

<table data-full-width="true"><thead><tr><th width="361.3819580078125">Example</th><th width="161">Field Name</th><th>Field Description</th><th width="100">Mandatory/ Optional</th><th width="100">Data Type</th></tr></thead><tbody><tr><td><p></p><pre><code>"content": {
</code></pre></td><td></td><td></td><td></td><td>Object</td></tr><tr><td><pre data-overflow="wrap"><code>    "type": "cashout-placement",
</code></pre></td><td>type</td><td>Declaration of content type</td><td>M</td><td>String</td></tr><tr><td><pre><code>    "cashout": {
         .......
         }
</code></pre></td><td>cashout</td><td>See description of <a href="#mtscashoutrequests-v3.0-cashoutcashoutobject">Cashout object</a></td><td>M</td><td>Object</td></tr><tr><td>},</td><td></td><td></td><td></td><td></td></tr></tbody></table>

### Cashout object <a href="#mtscashoutrequests-v3.0-cashoutcashoutobject" id="mtscashoutrequests-v3.0-cashoutcashoutobject"></a>

The Cashout object contains the following fields:

* type
* cashoutId
* details

**Cashout object table:**

<table data-full-width="true"><thead><tr><th width="359.923583984375">Example</th><th width="116.49652099609375">Field Name</th><th>Field Description</th><th width="100">Mandatory/ Optional</th><th width="100">Data Type</th></tr></thead><tbody><tr><td><pre><code>"cashout": {
</code></pre></td><td><br></td><td><br></td><td><br></td><td>Object</td></tr><tr><td><pre><code>   "type": "cashout",
</code></pre></td><td>type</td><td>Declaration of type</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>   "cashoutId": "COUT92328", 
</code></pre></td><td>cashoutId</td><td>Unique ID of this particular cash-out request in client's system, referenced in eventual ack message, minimal string length = 1,<br>maximum string length = 128</td><td>O</td><td>String</td></tr><tr><td><pre><code>   "details": {
</code></pre></td><td>details</td><td><p>Cash-out details - additional information related to the transaction,</p><p>see description</p></td><td>M</td><td>Object</td></tr><tr><td><pre><code>      "type": .......
      .........
      .........
 },     
</code></pre></td><td><ul><li>type</li></ul></td><td><p>See description of the 4 specific <a href="#mtscashoutrequests-v3.0-detailsdetailsobject">"details" types below</a></p><p>Enum:</p><ul><li>ticket</li><li>ticket-partial</li><li>bet</li><li>bet-partial</li></ul></td><td>M</td><td>String</td></tr></tbody></table>

### Details object <a href="#mtscashoutrequests-v3.0-detailsdetailsobject" id="mtscashoutrequests-v3.0-detailsdetailsobject"></a>

**1. Details ("type": "ticket") table**

This type is used to cash out an entire ticket.

Fields:

* type
* ticketId
* ticketSignature
* code
* payout

<table data-full-width="true"><thead><tr><th width="349.38800048828125">Example</th><th width="163.0008544921875">Field Name</th><th>Field Description</th><th width="100">Mandatory/ Optional</th><th width="100">Data Type</th></tr></thead><tbody><tr><td><pre><code>"details": {
</code></pre></td><td><br></td><td><br></td><td><br></td><td>Object</td></tr><tr><td><pre data-overflow="wrap"><code>        "type": "ticket",
</code></pre></td><td>type</td><td>Defines the type of Cash-out details</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "ticketId": "Ticket_3690",
</code></pre></td><td>ticketId</td><td>ID of the original ticket that is to be affected by this cash-out request</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "ticketSignature": "HHDut7XIEl+SmjWB3x
DB0AIB6fUZVFOvmGKm6Rcvxm0=",
</code></pre></td><td>ticketSignature</td><td>Signature from MTS's response to initial ticket placement</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "code": 101,     
</code></pre></td><td>code</td><td>Cash-out reason code,<br>see <a href="..#mtscashoutdescriptionandflow-v3.0-cash-outreasoncodes">list of codes</a></td><td>M</td><td>Integer</td></tr><tr><td><pre data-overflow="wrap"><code>        "payout": [ {      
</code></pre></td><td>payout</td><td>Session payout array,<br>minimal number of payouts per session =1,<br>maximum number = 5</td><td>M</td><td>Array</td></tr><tr><td><pre data-overflow="wrap"><code>            "type": "cash",
</code></pre></td><td><ul><li>type</li></ul></td><td><p>Enumerator:</p><ul><li>cash</li><li>withheld</li></ul></td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>            "currency": "EUR",
</code></pre></td><td><ul><li>currency</li></ul></td><td>3 or 4 letter currency code, BTC and mBTC are also supported (4 letters only apply to mBTC).<br>For more details please check<br><a href="https://www.iso.org/iso-4217-currency-codes.html">https://www.iso.org/iso-4217-currency-codes.html</a></td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>            "amount": "100",
</code></pre></td><td><ul><li>amount</li></ul></td><td>String pattern: 1 up to 8 digits, optionally followed by a decimal point and 1 up to 8 digits,<br>Java regex: ^\\d{1,8}(\\.\\d{1,8})?$</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>            "traceId": "Source_2099",
</code></pre></td><td><ul><li>traceId</li></ul></td><td><p>A string to help identify the source of operation/action/state</p><p>Minimal string length = 1,<br>maximum length = 128,</p></td><td>O</td><td>String</td></tr><tr><td><pre><code>            "stakeOrigin": "cash"
</code></pre></td><td><ul><li>stakeOrigin</li></ul></td><td><p></p><p>Enumerator:</p><ul><li>cash</li><li>bonus</li><li>free</li><li>free-cash</li><li>free-rollover</li></ul></td><td>O</td><td>String</td></tr><tr><td><pre><code> }  ]  }, 
</code></pre></td><td></td><td></td><td></td><td></td></tr></tbody></table>

**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

<table data-full-width="true"><thead><tr><th width="360.70745849609375">Example</th><th width="149.96612548828125">Field Name</th><th>Field Description</th><th width="100">Mandatory/ Optional</th><th width="100">Data Type</th></tr></thead><tbody><tr><td><pre><code>"details": {
</code></pre></td><td><br></td><td><br></td><td><br></td><td>Object</td></tr><tr><td><pre data-overflow="wrap"><code>        "type": "ticket-partial",
</code></pre></td><td>type</td><td>Defines the type of cash-out details</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "ticketId": "Ticket_3690",
</code></pre></td><td>ticketId</td><td>ID of the original ticket that is to be affected by this cash-out request</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "ticketSignature": "HHDut7XIEl+SmjWB3x
DB0AIB6fUZVFOvmGKm6Rcvxm0=",
</code></pre></td><td>ticketSignature</td><td>Signature from MTS's response to initial ticket placement</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "code": 101,     
</code></pre></td><td>code</td><td>Cash-out reason code,<br>see <a href="..#mtscashoutdescriptionandflow-v3.0-cash-outreasoncodes">list of codes</a></td><td>M</td><td>Integer</td></tr><tr><td><pre data-overflow="wrap"><code>        "percentage": "0.6",
</code></pre></td><td>percentage</td><td>Proportion of the bet that is to be cashed-out,<br>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),<br>Java regex:<br>^0(\\.\\d{1,8})?$</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "payout": [
        ..........
        ..........
 ] },              
</code></pre></td><td>payout</td><td>See the payout array description in the <a href="#mtscashoutrequests-v3.0-detailsdetailsobject">Details ("type": "ticket")</a> table above</td><td>M</td><td>Array</td></tr></tbody></table>

**3. Details ("type": "bet") table**

This type is used to cash out an entire bet.

Fields:

* type
* ticketId
* ticketSignature
* betId
* code
* payout

<table data-full-width="true"><thead><tr><th width="360.9296875">Example</th><th width="158.72393798828125">Field Name</th><th>Field Description</th><th width="100">Mandatory/ Optional</th><th width="100">Data Type</th></tr></thead><tbody><tr><td><pre><code>"details": {
</code></pre></td><td><br></td><td><br></td><td><br></td><td>Object</td></tr><tr><td><pre data-overflow="wrap"><code>        "type": "bet",
</code></pre></td><td>type</td><td>Defines the type of cash-out details</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "ticketId": "Ticket_3690",
</code></pre></td><td>ticketId</td><td>ID of the original ticket that is to be affected by this cash-out request</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "ticketSignature": "HHDut7XIEl+SmjWB3x
DB0AIB6fUZVFOvmGKm6Rcvxm0=",
</code></pre></td><td>ticketSignature</td><td>Signature from MTS's response to initial ticket placement</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "betId": "bjda6GH",
</code></pre></td><td>bettId</td><td>ID of the initial bet (defined by client) which is to be affected with this cash-out</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "code": 101,     
</code></pre></td><td>code</td><td>Cash-out reason code,<br>see <a href="..#mtscashoutdescriptionandflow-v3.0-cash-outreasoncodes">list of codes</a></td><td>M</td><td>Integer</td></tr><tr><td><pre data-overflow="wrap"><code>        "payout": [
        ..........
        ..........
] },               
</code></pre></td><td>payout</td><td>See the payout array description in the <a href="#mtscashoutrequests-v3.0-detailsdetailsobject">Details ("type": "ticket")</a> table above</td><td>M</td><td>Array</td></tr></tbody></table>

\
**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

<table data-full-width="true"><thead><tr><th width="361.1640625">Example</th><th width="148.9696044921875">Field Name</th><th>Field Description</th><th width="100">Mandatory/ Optional</th><th width="100">Data Type</th></tr></thead><tbody><tr><td><pre><code>"details": {
</code></pre></td><td><br></td><td><br></td><td><br></td><td>Object</td></tr><tr><td><pre data-overflow="wrap"><code>        "type": "bet-partial",
</code></pre></td><td>type</td><td>Defines the type of cash-out details</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "ticketId": "Ticket_3690",
</code></pre></td><td>ticketId</td><td>ID of the original ticket that is to be affected by this cash-out request</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "ticketSignature": "HHDut7XIEl+SmjWB3x
DB0AIB6fUZVFOvmGKm6Rcvxm0=",
</code></pre></td><td>ticketSignature</td><td>Signature from MTS's response to initial ticket placement</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "betId": "bjda6GH",
</code></pre></td><td>betId</td><td>ID of the initial bet (defined by client) which is to be affected with this cash-out</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "code": 101,    
</code></pre></td><td>code</td><td>Cash-out reason code,<br>see <a href="..#mtscashoutdescriptionandflow-v3.0-cash-outreasoncodes">list of codes</a></td><td>M</td><td>Integer</td></tr><tr><td><pre data-overflow="wrap"><code>        "percentage": "0.8",
</code></pre></td><td>percentage</td><td>Proportion of the bet that is to be cashed-out,<br>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),<br>Java regex: ^0(\\.\\d{1,8})?$</td><td>M</td><td>String</td></tr><tr><td><pre data-overflow="wrap"><code>        "payout": [
        ...........
        ...........
] },              
</code></pre></td><td>payout</td><td>See the payout array description in the <a href="#mtscashoutrequests-v3.0-detailsdetailsobject">Details ("type": "ticket")</a> table above</td><td>M</td><td>Array</td></tr></tbody></table>