# RGS Wallet Integration

## Introduction

The document describes the integration process of the latest version of Sportradar’s Remote Game Server (RGS) version, which delivers all Sportradar’s Virtual Sports over a single integration. 

The integration involves a back-end (wallet) integration, which is described in this document, and a front-end (user interface) integration described in a separate document (RGS Frontend Integration Guide). 

## General

RGS is designed in a way that the platform sends requests to various endpoints on your wallet system and processes responses received from your wallet system:

<figure><img src="/files/iOngSyK4l1bD7Z8lExVI" alt=""><figcaption></figcaption></figure>

There are seven API endpoints that need to be implemented by your wallet system, which can be broken down into three categories:

* User related API endpoints: `/userInfo`, `/queryBalance`
* Betting related API endpoints: `/reserveFunds`, `/payment` and `/approve`
* Back office related API endpoints: `/cancel`, `/manualPayment`

Your wallet system is expected to implement all API endpoints which we will describe in more detail in this documentation.

## Interface Definition <a href="#toc104969926" id="toc104969926"></a>

In addition to this document, you will receive an OpenAPI document that conforms to the OpenAPI Specification.

Please study the OpenAPI document as well as it contains all technical details with regards to the wallet interface.

## Security

Wallet communication uses SSL (Secure Socket Layer). All messages are exchanged over non-persistent connection and contain HTTP Basic authentication for additional security.

Both our staging and production environments will reject unsecured (http) connections.

The following IP range needs to be whitelisted on your end to be able to get connection to our system:

`87.238.140.0/24`

## Batching Support

In general, requests from the RGS platform contain one element of a specific type. In the unlikely event we need to improve performance, we reserve the right to batch requests.

Batching means that each request can contain multiple elements allowing RGS to send multiple instructions per request. Nonetheless, each batch will contain only items of the same type.

Note that a batch does not represent a set of instructions, which must be executed in a single transaction; it is simply a “container” for sending multiple unrelated items between remote systems.

You need to ensure that your wallet system can accept and process batches as described above. Responses from your wallet system must contain an array with the same number of response instances of the same type (unless stated otherwise) and use the `correlationNumber` to match responses with their corresponding requests.

## Idempotence

Wallet endpoints must act idempotent, meaning that multiple calls of the same endpoints with same arguments have no side effects. This behavior prevents duplication in the case of failures or multiple retries.

## Response Parameters

Most of the requests received by your wallet system produce a response which contains an array of `GenericResponse` instances. This section describes the `GenericResponse` element.

When a request produces a specific response, the response is specified in the sections below describing that request.

### GenericResponse <a href="#ref103174461" id="ref103174461"></a>

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>balance</code></td><td valign="top"><code>number</code></td><td valign="top">Required</td><td valign="top">Funds available in the user’s account.</td></tr><tr><td valign="top"><code>correlationNumber</code></td><td valign="top"><code>integer</code></td><td valign="top">Required</td><td valign="top">A number used to match associated request and response elements.</td></tr><tr><td valign="top"><code>currencyCode</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A three-character ISO 4217 code specifying the currency used by the user.</td></tr><tr><td valign="top"><code>status</code></td><td valign="top"><code>Status</code></td><td valign="top">Required</td><td valign="top">An enumeration member describing potential errors encountered while processing associated request element. See section <a href="#status-codes">Status Codes</a> for further details.</td></tr></tbody></table>

## Status Codes

The table below lists all status codes that can be returned by your wallet system. As mentioned above, even though all response elements use the parameter status to indicate whether the associated request element was processed successfully, individual responses use only a subset of status codes defined in the enumeration:

<table><thead><tr><th valign="top">Status Code</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>OK</code></td><td valign="top">The associated request element was processed successfully.</td></tr><tr><td valign="top"><code>REQUEST_FORMAT</code></td><td valign="top">The format of the associated request element was not correct (missing required field…).</td></tr><tr><td valign="top"><code>INVALID_TOKEN</code></td><td valign="top">The specified user token is not valid or was revoked.</td></tr><tr><td valign="top"><code>INSUFFICIENT_FUNDS</code></td><td valign="top">The player does not have enough funds to complete the requested action.</td></tr><tr><td valign="top"><code>USER_NOT_FOUND</code></td><td valign="top">The player specified by the <code>userId</code> does not exist in your wallet system.</td></tr><tr><td valign="top"><code>INVALID_CREDENTIALS</code></td><td valign="top">The provided credentials are not valid.</td></tr><tr><td valign="top"><code>USER_FROZEN</code></td><td valign="top">The player specified with the <code>userId</code> is frozen.</td></tr><tr><td valign="top"><code>DUPLICATE_PAYMENT_ID</code></td><td valign="top">The specified <code>paymentId</code> is already in use.</td></tr><tr><td valign="top"><code>PAYMENT_ID_NOT_FOUND</code></td><td valign="top">The transaction with the specified <code>paymentId</code> was not found.</td></tr><tr><td valign="top"><code>RISK_VALIDATION</code></td><td valign="top">The payment request was denied due to failed risk validation.</td></tr><tr><td valign="top"><code>CANCEL_NOT_POSSIBLE</code></td><td valign="top">The transaction cannot be canceled because it has already been approved.</td></tr><tr><td valign="top"><code>USER_EXISTS</code></td><td valign="top">The player with the specified identifier already exists.</td></tr><tr><td valign="top"><code>ERROR</code></td><td valign="top">An unknown error occurred while processing the request element.</td></tr></tbody></table>

## User Messages

Messages in this section are the first that should be undertaken when implementing the RGS API. These messages are used to retrieve information about the logged in user.

All methods described in this section are mandatory and must be provided by your wallet system.

### Retrieving User Information – `/userInfo`

The `/userInfo` endpoint is called the moment the game launch URL containing a player’s token within the `id` parameter is accessed.

`/userInfo` is used primarily to authenticate the player in your wallet system.

If the `/userInfo` call is successful, your wallet system should respond with a `UserInfoResponse` of status `OK` along with the required fields containing the player information to the RGS server.

Otherwise, your wallet system should send a `UserInfoResponse` with the most appropriate error enumeration in the status field.

It is also important to note that the parameter `currencyCode` is used by the frontend to determine which currency should be displayed in the player’s bet slip.

#### **`UserInfoRequest`**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>correlationNumber</code></td><td valign="top"><code>integer</code></td><td valign="top">Required</td><td valign="top">A number used to match request and response elements.</td></tr><tr><td valign="top"><code>token</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A token passed to the platform when authenticating the user.</td></tr></tbody></table>

#### **`UserInfoResponse`**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>balance</code></td><td valign="top"><code>number</code></td><td valign="top">Required</td><td valign="top">Player’s funds available on their account.</td></tr><tr><td valign="top"><code>correlationNumber</code></td><td valign="top"><code>integer</code></td><td valign="top">Required</td><td valign="top">A number used to match associated request and response elements.</td></tr><tr><td valign="top"><code>currencyCode</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top"><p>A three-character ISO 4217 code specifying the currency used by the user. Currency codes must be provided in lower case.</p><p></p><p>If no currency is added, it will fall back to default <code>eur</code>.</p></td></tr><tr><td valign="top"><code>languageCode</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top"><p>An ISO 639-1 code specifying the language of the user. Language codes must be provided in lower case.</p><p></p><p>If no language will be added it will fall back to default <code>en</code>.</p></td></tr><tr><td valign="top"><code>status</code></td><td valign="top"><code>Status</code></td><td valign="top">Required</td><td valign="top">An enumeration member describing potential errors encountered while processing an associated request element. See section <a href="#status-codes">Status Codes</a> for further details.</td></tr><tr><td valign="top"><code>timeToLive</code></td><td valign="top"><code>integer</code></td><td valign="top">Optional (deprecated)</td><td valign="top">A value specifying the time interval after which the token will expire.</td></tr><tr><td valign="top"><code>userId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top"><p>A pseudo anonymous string uniquely identifying the user in your wallet system.</p><p> </p><p>Values for <code>userId</code> are restricted to the following:</p><p> </p><p>· Allowed characters are [0-9A-Za-z_-]</p><p>· Max. length is 36</p></td></tr><tr><td valign="top"><code>username</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A username of the user in your wallet system.</td></tr><tr><td valign="top"><code>vipLevel</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A VIP level of the user in your wallet system.</td></tr></tbody></table>

#### **`UserInfo` Status Codes**

| Status Code      |
| ---------------- |
| `OK`             |
| `REQUEST_FORMAT` |
| `INVALID_TOKEN`  |
| `USER_NOT_FOUND` |
| `USER_FROZEN`    |
| `ERROR`          |

### Retrieving Player’s Balance – `/queryBalance`

RGS retrieves a player’s current balance by calling the `/queryBalance` endpoint.

`/queryBalance` endpoint parameters contain an array with one or more `QueryBalanceRequest` instances. Your wallet system’s response must contain an array with the same number of [`GenericResponse`](#ref103174461) instances.

#### **`QueryBalanceRequest`**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>correlationNumber</code></td><td valign="top"><code>integer</code></td><td valign="top">Required</td><td valign="top">A number used to match request and response elements.</td></tr><tr><td valign="top"><code>token</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A token passed to the platform when authenticating the user.</td></tr><tr><td valign="top"><code>userId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top"><p>A pseudo anonymous string uniquely identifying the user in your wallet system.</p><p>Values for <code>userId</code> are restricted to the following:</p><p> </p><p>· Allowed characters are [0-9A-Za-z_-]</p><p>· Max. length is 36</p></td></tr></tbody></table>

#### **Status Codes**

<table><thead><tr><th valign="top">Status Code</th></tr></thead><tbody><tr><td valign="top"><code>OK</code></td></tr><tr><td valign="top"><code>REQUEST_FORMAT</code></td></tr><tr><td valign="top"><code>INVALID_TOKEN</code></td></tr><tr><td valign="top"><code>USER_NOT_FOUND</code></td></tr><tr><td valign="top"><code>ERROR</code></td></tr></tbody></table>

## Betting Messages

There are three core API endpoints that must be implemented in your wallet system to handle betting related requests:

* `/reserveFunds`
* `/payment`
* `/approve`

Details about each endpoint will be provided in the following sub-sections.

Prior to entering this phase of the integration, Sportradar will have provided you with access to the RGS Backoffice system in Betradar’s staging environment. The RGS Backoffice will give visibility to audit logs, helping with any troubleshooting of error messages.

### Placing a Bet – `/reserveFunds`

The `/reserveFunds` endpoint is called by RGS during bet placement to take money from a player’s account.

/reserveFunds endpoint parameters contain an array with one or more `ReserveFundsRequest` instances. Your wallet system’s response must contain an array with the same number of [`GenericResponse`](#ref103174461) instances.

Your wallet system should verify that the token present in each request is still valid and return an error response if the token has expired.

Also note, that whilst RGS will reject bets that were placed in a currency other than the one specified in the `UserInfoResponse` it is good practice to either reject the transaction or perform a currency conversion if the `currencyCode` sent with this request does not match the currency in the player’s wallet.

If the `ReserveFundsRequest` is successful, your wallet system should deduct the stake amount from the player’s account.

#### **Timeouts during Bet Placement**

Should a response on a `ReserveFundsRequest` take longer than 8 seconds, the player will be presented with a message informing them that the bet was not placed.

If the response arrives after this message was delivered to the player, RGS will try to roll-back the transaction on your wallet system by calling the /cancel endpoint sending a CancelRequest (see section 2.10.1 for further details).

RGS will wait up to 1 minute for the response from the wallet (The player will be notified in 8 seconds). If there is no response or if the response is not parsable, RGS will try to cancel (rollback) the transaction. We will attempt the cancellation up to 10 times, using an exponential delay up to a maximum delay of 32 minutes between retries.

After the retry limit is exceeded, the ticket will be put into the BACKOFFICE\_SETTLEMENT state and will require manual intervention via the backoffice.

#### **ReserveFundsRequest**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>correlationNumber</code></td><td valign="top"><code>integer</code></td><td valign="top">Required</td><td valign="top">A number used to match request and response elements.</td></tr><tr><td valign="top"><code>currencyCode</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A three-character ISO 4217 code specifying the currency used by the user. Currency codes must be provided in lower case.</td></tr><tr><td valign="top"><code>gameCategoryCode</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A value specifying the category of the game associated with the request.</td></tr><tr><td valign="top"><code>gameCode</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A value specifying the game associated with the request. See section <a href="#product-game-codes">Product Game Codes</a> for further details.</td></tr><tr><td valign="top"><code>gameFormatCode</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A value specifying the channel (web, mobile…) used by the user when placing the bet.</td></tr><tr><td valign="top"><code>maxPayout</code></td><td valign="top"><code>number</code></td><td valign="top">Required</td><td valign="top"><p>A value specifying the maximum payout for the ticket associated with the request.</p><p>Risk control is handled on during bet acceptance, before any wallet requests are made. Min and max bet amounts and max payouts can be set in back office. This is only some additional info to inform you about the maximum possible winnings for this reservation, should you wish to implement additional risk control.</p></td></tr><tr><td valign="top"><code>paymentId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top">A value used to uniquely identify the transaction. The value must be unique through the application’s lifetime.</td></tr><tr><td valign="top"><code>stake</code></td><td valign="top"><code>PaymentElement</code></td><td valign="top">Required</td><td valign="top">A value specifying the amount to be reserved (withdrawn) from the user’s account.</td></tr><tr><td valign="top"><code>ticketInfo</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A JSON representation of the ticket associated with the current element.</td></tr><tr><td valign="top"><code>token</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A token that was passed to the RGS when the user was registered</td></tr><tr><td valign="top"><code>userId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top"><p>A pseudo anonymous string uniquely identifying the user within the wallet system.</p><p> </p><p>Values for userId are restricted to the following:</p><p> </p><p>·         Allowed characters are [0-9A-Za-z_-]</p><p>·         Max. length is 36</p></td></tr></tbody></table>

#### **Product Game Codes**

<table><thead><tr><th valign="top">Product Game Code</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><p> </p><p><code>VFB</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football Bundesliga</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFEL</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football English League</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFSL</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football Spanish League</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFIL</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football Italian League</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFFL</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football French League</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFGL</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football German League</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VWMF1</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual World Match Football 1</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VWMF2</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual World Match Football 2</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VWMF3</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual World Match Football 3</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFF1</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Fast Football 1</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFF2</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Fast Football 2</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFF3</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Fast Football 3</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFLM</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football League Mode</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFWC</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football World Cup</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFEC</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football Euro Cup</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFAS</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football Asian Cup</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFNC</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football Nations Cup</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VFCC</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Football Champions Cup</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VCI</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Cricket In-Play</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VBI</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Baseball In-Play</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VTI</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Tennis In-Play</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VTIATP1</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Tennis In-Play ATP 1 (1990s)</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VTIATP2</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Tennis In-Play ATP 2 (2000s)</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VTIATP3</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Tennis In-Play ATP 3 (2010s)</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VTIATP4</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Tennis In-Play ATP 4 (2020s)</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VBL</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Basketball League</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VDR</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Dogs Kiron</p><p> </p></td></tr><tr><td valign="top"><p> </p><p><code>VHC</code></p><p> </p></td><td valign="top"><p> </p><p>Virtual Horses Kiron</p><p> </p></td></tr></tbody></table>

#### **PaymentElement**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>amount</code></td><td valign="top"><code>number</code></td><td valign="top">Required</td><td valign="top">Specifies the value to be withdrawn or deposited to the user’s account.</td></tr><tr><td valign="top"><code>timestamp</code></td><td valign="top"><code>integer</code> (int64)</td><td valign="top">Required</td><td valign="top">Specifies the time of the event in UTC time.</td></tr></tbody></table>

#### **Status Codes**

<table><thead><tr><th valign="top">Status Code</th></tr></thead><tbody><tr><td valign="top"><code>OK</code></td></tr><tr><td valign="top"><code>REQUEST_FORMAT</code></td></tr><tr><td valign="top"><code>INVALID_TOKEN</code></td></tr><tr><td valign="top"><code>INSUFFICIENT_FUNDS</code></td></tr><tr><td valign="top"><code>USER_NOT_FOUND</code></td></tr><tr><td valign="top"><code>USER_FROZEN</code></td></tr><tr><td valign="top"><code>DUPLICATE_PAYMENT_ID</code></td></tr><tr><td valign="top"><code>RISK_VALIDATION</code></td></tr><tr><td valign="top"><code>ERROR</code></td></tr></tbody></table>

### Crediting an Account – `/payment`

The `/payment` endpoint is used by RGS to credit money to a player’s account.

`/payment` endpoint parameters contain an array with one or more `PaymentRequest` instances. Your wallet system’s response must contain an array with the same number of [`GenericResponse`](#ref103174461) instances.

The `approvePayment` property is almost always set to false, as such the payment will be approved later by calling the `/approve` endpoint.

If the `PaymentRequest` is successful, the wallet should credit the payment amount to the player’s account.

Also note, that whilst RGS will reject bets that were placed in a currency other than the one specified in the [`UserInfoResponse`](#userinforesponse) it is good practice to either reject the transaction or perform a currency conversion if the `currencyCode` sent with this request does not match the currency in the player’s wallet.

Should the payment fail due to an error or a timeout, RGS will automatically retry the payment, up to 30 times (10 on staging), using an exponential delay between the retries, up to a maximum delay of 32 minutes between retries. After the retry limit has been exceeded, RGS will no longer try to automatically pay out the ticket and the ticket will be set into the `BACKOFFICE_SETTLEMENT` state, and require manual action via back office to resolve.

#### **Bet Cancellation**

If market information received by RGS indicates that one of the markets associated with the bet was cancelled, RGS will call the `/payment` endpoint to refund the affected bet(s).

In case a ticket contains several bets on different markets and some bets are unaffected by the market cancellation, potential winnings from the unaffected bets will also be credited in the same [`PaymentRequest`](#paymentrequest).

Information on whether a bet has been refunded due to market cancellation can be obtained by inspecting the JSON representation of the ticket associated with the request, which is passed in the `ticketInfo` `string` parameter to the [`PaymentRequest`](#paymentrequest). Such refunded lines will have the result attribute set to `#`.

#### **PaymentRequest**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>approvePayment</code></td><td valign="top"><code>boolean</code></td><td valign="top">Required</td><td valign="top">A value specifying whether the transaction should be approved. If value is false, the transaction will be approved by a separate message</td></tr><tr><td valign="top"><code>correlationNumber</code></td><td valign="top"><code>integer</code></td><td valign="top">Required</td><td valign="top">A number used to match request and response elements.</td></tr><tr><td valign="top"><code>currencyCode</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A three-character ISO 4217 code specifying the currency used by the user. Value should be provided in lower case.</td></tr><tr><td valign="top"><code>payment</code></td><td valign="top"><code>PaymentElement</code></td><td valign="top">Required</td><td valign="top">A value specifying the amount won by the user (see section <a href="#paymentelement"><code>PaymentElement</code></a> for further details).</td></tr><tr><td valign="top"><code>paymentId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top">A value used to uniquely identify the transaction. Value must be unique through the application’s lifetime.</td></tr><tr><td valign="top"><code>ticketInfo</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A JSON representation of the ticket associated with current element.</td></tr><tr><td valign="top"><code>userId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top"><p>A pseudo anonymous string uniquely identifying the user within the wallet system.</p><p> </p><p>Values for <code>userId</code> are restricted to the following:</p><p> </p><p>· Allowed characters are [0-9A-Za-z_-]</p><p>· Max. length is 36</p></td></tr></tbody></table>

#### **Status Codes**

<table><thead><tr><th valign="top">Status Code</th></tr></thead><tbody><tr><td valign="top"><code>OK</code></td></tr><tr><td valign="top"><code>REQUEST_FORMAT</code></td></tr><tr><td valign="top"><code>USER_NOT_FOUND</code></td></tr><tr><td valign="top"><code>DUPLICATE_PAYMENT_ID</code></td></tr><tr><td valign="top"><code>PAYMENT_ID_NOT_FOUND</code></td></tr><tr><td valign="top"><code>ERROR</code></td></tr></tbody></table>

### Ending the Round – `/approve` <a href="#ref103174092" id="ref103174092"></a>

Each transaction initiated by RGS must be either approved or cancelled. When a transaction is approved all withdrawals and deposits associated with its `paymentId` are approved.

The `/approved` endpoint is used by RGS to initiate the approval of a transaction.

`/approve` endpoint parameters contain an array with one or more [`ApproveRequest`](#approverequest) instances. Your wallet system’s response must contain an array with the same number of [`GenericResponse`](#ref103174461) instances.

Should the approval fail due to an error or a timeout, RGS will automatically retry the approval, up to 30 times (10 on staging), using an exponential delay between the retries, up to a maximum delay of 32 minutes between retries. After the retry limit has been exceeded, RGS will no longer try to automatically approve the ticket and the ticket will be set into the `BACKOFFICE_SETTLEMENT` state, and require manual action via back office to resolve.

#### **ApproveRequest**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>correlationNumber</code></td><td valign="top"><code>integer</code></td><td valign="top">Required</td><td valign="top">A number used to match request and response elements.</td></tr><tr><td valign="top"><code>paymentId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top">A value used to uniquely identify the transaction. Value must be unique through the application’s lifetime.</td></tr><tr><td valign="top"><code>ticketInfo</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A JSON representation of the ticket associated with current element.</td></tr></tbody></table>

#### **Status Codes**

<table><thead><tr><th valign="top">Status Code</th></tr></thead><tbody><tr><td valign="top"><code>OK</code></td></tr><tr><td valign="top"><code>REQUEST_FORMAT</code></td></tr><tr><td valign="top"><code>USER_FROZEN</code></td></tr><tr><td valign="top"><code>PAYMENT_ID_NOT_FOUND</code></td></tr><tr><td valign="top"><code>ERROR</code></td></tr></tbody></table>

### Betting Flow Examples

#### **Player places a Bet and loses**

The sequence diagram below describes the interaction steps when the player places the bet, and the bet is lost.

RGS calls the `/reserveFunds` endpoint in order to debit the funds required for the bet.

When the markets associated with the bet are settled, RGS determines that the bet was lost. Since there are no winnings (the user lost the bet) the `/payment` endpoint will not be called.

However, RGS will call the `/approve` endpoint in order to specify the bet is settled and the transaction is completed.

<figure><img src="/files/dMFWPqqn0PwE4zFzkkqf" alt=""><figcaption></figcaption></figure>

#### **Player places a Bet and wins**

When a player places a bet and wins, the flow of messages is like the example above. However, this time when the markets associated with the bet are settled, RGS determines that the bet is won and will call the `/payment` endpoint.

Once RGS receives the confirmation that the request was successfully processed, it will call the `/approve` endpoint to notify your wallet system that the bet is settled, and the transaction is completed.

<figure><img src="/files/AcgmG1kaTqd68Ozy4REB" alt=""><figcaption></figcaption></figure>

## Backoffice Messages

Endpoints described in this section support the RGS Backoffice functionality.

A user guide for the Backoffice is available as a standalone document, and should be made available to your operation staff, so they can support management of bets in RGS.

There are two API calls that need to be implemented in your wallet system to handle Backoffice requests:

* /cancel
* /manualPayment

### Ticket Cancellation – `/cancel` <a href="#ref106287397" id="ref106287397"></a>

The `/cancel` endpoint is called by RGS when a bookmaker’s support staff want to cancel a ticket through the Backoffice, if the market has been voided, or if an error occurred during ticket placement.

When the transaction is cancelled, all withdrawals and deposits associated with its `paymentId` are cancelled.

`/cancel` endpoint parameters contain an array with one or more [`CancelRequest`](#cancelrequest) instances. Your wallet system’s response must contain an array with the same number of [`GenericResponse`](#ref103174461) instances.

Should the automated cancellation fail due to an error or a timeout, RGS will automatically retry the cancellation, up to 10 times, using an exponential delay between the retries, up to a maximum delay of 32 minutes between retries.

If the transaction has already been approved, then the `force` parameter will be set to true.

#### **CancelRequest**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>correlationNumber</code></td><td valign="top"><code>integer</code></td><td valign="top">Required</td><td valign="top">A number used to match request and response elements.</td></tr><tr><td valign="top"><code>force</code></td><td valign="top"><code>boolean</code></td><td valign="top">Optional</td><td valign="top"><p>A value specified whether to attempt to cancel an approved transaction.</p><p> </p><p>force will be set to true when <code>/cancel</code> is called by triggering the action through the back office.</p></td></tr><tr><td valign="top"><code>paymentId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top">A value used to uniquely identify the transaction. The value must be unique through the application’s lifetime.</td></tr><tr><td valign="top"><code>ticketInfo</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A JSON representation of the ticket associated with current element.</td></tr></tbody></table>

#### **Status Codes**

<table><thead><tr><th valign="top">Status Code</th></tr></thead><tbody><tr><td valign="top"><code>OK</code></td></tr><tr><td valign="top"><code>REQUEST_FORMAT</code></td></tr><tr><td valign="top"><code>USER_FROZEN</code></td></tr><tr><td valign="top"><code>PAYMENT_ID_NOT_FOUND</code></td></tr><tr><td valign="top"><code>CANCEL_NOT_POSSIBLE</code></td></tr><tr><td valign="top"><code>ERROR</code></td></tr></tbody></table>

#### **Cancellation of a winning Bet**

In case that a winning bet needs to be cancelled, the winnings and the stake should be rolled back, and the stake reapplied.

The flow below describes the scenario of cancelling a winning bet:

* Starting balance: 100.00
* Place 1.00 bet @ 1.50 odds
* Balance: 99.00
* Bet wins, returning 1.50 (1.00 for stake, and 0.50 winnings)
* Balance: 100.50
* `/cancel` called
* Winnings and stake are rolled back
* Balance: 99.00
* Original stake is applied
* Final Balance 100.00

### Manual Ticket Re-settlement – `/manualPayment`

The `/manualPayment` endpoint is called by RGS when a bookmaker’s support staff want to manually re-settle a ticket through the Backoffice.

Situations where this may be needed include but are not limited to:

* Timeout during `/payment`
  * RGS called /payment, but your response takes longer than 8 seconds.
  * RGS then will retry to send the request.
  * While retrying, RGS receives the initial response, but an error is returned for the consecutive requests.
  * Now we have a situation where RGS does not know which state the ticket is in as it has conflicting statuses.
  * To reconcile the status, a manual payment needs to be initiated from the Backoffice.
* Missing Settlement Information
  * When results fail to come through, the bet needs to be manually settled via the Backoffice.

`/manualPayment` endpoint parameters contain an array with one or more [`ManualPaymentRequest`](#manualpaymentrequest) instances. Your wallet system’s response must contain an array with the same number of [`GenericResponse`](#ref103174461) instances.

Also note, that whilst RGS will reject bets that were placed in another currency other than the one specified in the [`UserInfoResponse`](#userinforesponse), it is good practice to either reject the transaction, or perform a currency conversion if the `currencyCode` sent with this request does not match the currency in the user’s wallet.

#### **ManualPaymentRequest**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Required</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>comment</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">An optional comment entered by the operator when re-settling a bet.</td></tr><tr><td valign="top"><code>correlationNumber</code></td><td valign="top"><code>integer</code></td><td valign="top">Required</td><td valign="top">A number used to match request and response elements.</td></tr><tr><td valign="top"><code>currencyCode</code></td><td valign="top"><code>string</code></td><td valign="top">Optional</td><td valign="top">A three-character ISO 4217 code specifying the currency used by the user. Currency codes must be provided in lower case.</td></tr><tr><td valign="top"><code>payment</code></td><td valign="top"><code>PaymentElement</code></td><td valign="top">Required</td><td valign="top">A value specifying the amount won by the user (see <a href="#paymentelement"><code>PaymentElement</code></a> for further details).</td></tr><tr><td valign="top"><code>paymentId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top">A value used to uniquely identify the transaction. Value must be unique through the application’s lifetime.</td></tr><tr><td valign="top"><code>userId</code></td><td valign="top"><code>string</code></td><td valign="top">Required</td><td valign="top"><p>A pseudo anonymous string uniquely identifying the user within the wallet system.</p><p> </p><p>Values for <code>userId</code> are restricted to the following:</p><p> </p><p>· Allowed characters are [0-9A-Za-z_-]</p><p>· Max. length is 36</p></td></tr></tbody></table>

#### **Status Codes**

<table><thead><tr><th valign="top">Status Codes</th></tr></thead><tbody><tr><td valign="top"><code>OK</code></td></tr><tr><td valign="top"><code>REQUEST_FORMAT</code></td></tr><tr><td valign="top"><code>USER_FROZEN</code></td></tr><tr><td valign="top"><code>ERROR</code></td></tr></tbody></table>

#### **Re-settlement of a winning Bet**

In case that a winning bet needs to be manually re-settled, the winnings and the stake should be rolled back, and the new win amount value applied.

The flow below describes the scenario of re-settling a winning bet:

* Starting balance: 100.00
* Place 1.00 bet @ 1.50 odds
* Balance: 99.00
* Bet wins, returning 1.50 (1.00 for stake, and 0.50 winnings)
* Balance: 100.50
* `/manualPayment` with `PaymentElement.amount` of 1.00 called
* Winnings and stake are rolled back
* Balance: 99.00
* `PaymentElement.amount` is applied
* Final Balance 100.00

## TicketInfo Object <a href="#toc104969945" id="toc104969945"></a>

This section contains a sample JSON ticket object, which can be optionally passed in certain API calls.

The `TicketInfo` Object contains a snapshot of a ticket’s state.

In general, you should not need to process the `TicketInfo` Object as a ticket’s life cycle is managed on our end and details of a ticket can be looked up in the RGS Back Office.

In addition, the frontend of RGS provides a betting history of a player’s bets, so players can check their bets on Sportradar’s Virtual Sports at any time.

{% hint style="danger" %}
The `TicketInfo` object is intended to be used for debugging purposes only and we recommend to process the `TicketInfo` object only in case you have strong reasons. This will keep the integration as simple as possible.

Please also note, that the `TicketInfo` Object may be subject to changes which may impact your integration even though we aim to implement any changes in a backwards-compatible manner.

Lastly, be aware that data may be missing in the `TicketInfo` Object depending on the ticket’s state which can make processing the `TicketInfo` Object more complicated than anticipated.
{% endhint %}

### Example <a href="#toc104969946" id="toc104969946"></a>

Below you will find an example of a TicketInfo Object that will be sent during the approve operation:

```json
{
    "ticketId": "618cdf5ffe69e601d116b723",
    "status": "PLACED",
    "bkId": 12345,
    "transactionId": "74226243394769538",
    "product": "VFB",
    "placedTs": "1636622164932",
    "receivedTs": "1636622164046",
    "updatedTs": "1636622401792",
    "ticketExpiryTs": "1636632964054",
    "estimatedSettlementTs": "",
    "settledTs": "",
    "stake": "50000",
    "possibleWinnings": "135000",
    "totalReturn": "0.00",
    "productType": "VFB",
    "selections": [
        {
            "eventId": "vf:match:177637419",
            "id": "uof:6/sr:sport:1/1/1",
            "result": "*",
            "odds": 13500,
            "metaData": {
                "lang": "EN-EN",
                "marketName": "Fulltime",
                "outcomeName": "Borussia M'gladbach",
                "productType": "VFB",
                "tournament": {
                    "name": "Season 1422",
                    "sequence": "",
                    "event": {
                        "competitors": [
                            {
                                "id": "sr:competitor:798914",
                                "name": "Borussia M'gladbach",
                                "abbr": "BMG"
                            },
                            {
                                "id": "sr:competitor:798930",
                                "name": "VfB Stuttgart",
                                "abbr": "VFB"
                            }
                        ],
                        "eventStart": "1636622251000",
                        "name": "Matchday 20",
                        "sequence": ""
                    }
                }
            }
        },
        {
            "eventId": "vf:match:177637421",
            "id": "uof:6/sr:sport:1/1/1",
            "result": "-",
            "odds": 20000,
            "metaData": {
                "lang": "EN-EN",
                "marketName": "Fulltime",
                "outcomeName": "Bayer 04 Leverkusen",
                "productType": "VFB",
                "tournament": {
                    "name": "Season 1422",
                    "sequence": "",
                    "event": {
                        "competitors": [
                            {
                                "id": "sr:competitor:798912",
                                "name": "Bayer 04 Leverkusen",
                                "abbr": "B04"
                            },
                            {
                                "id": "sr:competitor:798916",
                                "name": "Eintracht Frankfurt",
                                "abbr": "SGE"
                            }
                        ],
                        "eventStart": "1636622251000",
                        "name": "Matchday 20",
                        "sequence": ""
                    }
                }
            }
        }
    ],
    "bets": [
        {
            "selectionRefs": [],
            "selectedSystems": [
                2
            ],
            "sumOfWins": "135000"
        }
    ],
    "exchangeRate": "1.0"
}
```

### Data Structure

Below you will find a list of all possible data that can be sent inside the TicketInfo Object. All fields are optional and only if the information is available, the field will be sent as part of the object.

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>ticketId</code></td><td valign="top"><code>string</code></td><td valign="top">The ticket’s unique id.</td></tr><tr><td valign="top"><code>status</code></td><td valign="top"><code>string</code></td><td valign="top">The ticket’s status. See section 3.2.1 for further details.</td></tr><tr><td valign="top"><code>bkId</code></td><td valign="top"><code>integer</code></td><td valign="top">Identifies you as a bookmaker in our system. The bkId will be provided to you by your technical account manager.</td></tr><tr><td valign="top"><code>transactionId</code></td><td valign="top"><code>string</code></td><td valign="top">A value used to uniquely identify the transaction. Value must be unique through the application’s lifetime.</td></tr><tr><td valign="top"><code>product</code></td><td valign="top"><code>string</code></td><td valign="top">A value specifying the game associated with the ticket.</td></tr><tr><td valign="top"><code>placedTs</code></td><td valign="top"><code>string</code></td><td valign="top">13-digit epoch timestamp representing the time of ticket placement.</td></tr><tr><td valign="top"><code>receivedTs</code></td><td valign="top"><code>string</code></td><td valign="top">13-digit epoch timestamp specifying the time when the ticket was received by RGS.</td></tr><tr><td valign="top"><code>updatedTs</code></td><td valign="top"><code>string</code></td><td valign="top">13-digit epoch timestamp specifying the time when the ticket was last updated.</td></tr><tr><td valign="top"><code>ticketExpiryTs</code></td><td valign="top"><code>string</code></td><td valign="top">13-digit epoch timestamp specifying the time when the ticket is going to expire.</td></tr><tr><td valign="top"><code>estimatedSettlementTs</code></td><td valign="top"><code>string</code></td><td valign="top">13-digit epoch timestamp specifying the estimated time when the ticket will be settled.</td></tr><tr><td valign="top"><code>settledTs</code></td><td valign="top"><code>string</code></td><td valign="top">13-digit epoch timestamp representing the time of ticket settlement.</td></tr><tr><td valign="top"><code>stake</code></td><td valign="top"><code>string</code></td><td valign="top">The stake multiplied by 10000.</td></tr><tr><td valign="top"><code>possibleWinnings</code></td><td valign="top"><code>string</code></td><td valign="top">The maximum possible winnings multiplied by 10000.</td></tr><tr><td valign="top"><code>totalReturn</code></td><td valign="top"><code>string</code></td><td valign="top">The actual won amount.</td></tr><tr><td valign="top"><code>productType</code></td><td valign="top"><code>string</code></td><td valign="top">Abbreviation of the product which the ticket was placed under.  See section 2.9.1.3 for further details.</td></tr><tr><td valign="top"><code>selections</code></td><td valign="top"><code>Selection[]</code></td><td valign="top">An array containing the selections of a ticket. See section 3.2.2 for further details.</td></tr><tr><td valign="top"><code>bets</code></td><td valign="top"><code>Bet[]</code></td><td valign="top">An array containing all bet combinations of a ticket. See section 3.2.3 for further details.</td></tr><tr><td valign="top"><code>exchangeRate</code></td><td valign="top"><code>string</code></td><td valign="top">Exchange rate between the ticket’s currency and Euro.</td></tr></tbody></table>

#### TicketInfo Status Codes

<table><thead><tr><th valign="top">Status</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>UNDEFINED</code></td><td valign="top">The ticket has not yet been processed by RGS.</td></tr><tr><td valign="top"><code>PLACING</code></td><td valign="top">The ticket is currently being processed.</td></tr><tr><td valign="top"><code>REJECTED_INTERNAL_ERROR</code></td><td valign="top">The ticket was rejected because of an internal RGS error (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_EXTERNAL_ERROR</code></td><td valign="top">The ticket was rejected because of an external error, e.g., unexpected wallet issues (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_BASIC_VALIDATION</code></td><td valign="top">The ticket was rejected because basic validation failed, e.g., invalid ticket structure (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_SESSION_VALIDATION</code></td><td valign="top">The ticket was rejected because it was placed with an invalid authentication token (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_RISK_VALIDATION</code></td><td valign="top">The ticket was rejected because risk validation failed, e.g., stake too high or too low, possible winnings are too high or too low (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_BOOKMAKER_SETTINGS_VALIDATION</code></td><td valign="top">The ticket was rejected because bookmaker settings were not respected, e.g., betting restrictions.</td></tr><tr><td valign="top"><code>REJECTED_BY_BROKER</code></td><td valign="top">The ticket was rejected by the RGS broker. This state is not likely to happen as a more specific rejection status will be associated with the ticket (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_WG_INTERNAL_ERROR</code></td><td valign="top">The ticket was rejected because of internal RGS wallet adapter error (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_WG_EXTERNAL_ERROR</code></td><td valign="top">The ticket was rejected because of an external RGS wallet adapter error, e.g., a bookmaker wallet integration issue (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_WG_INSUFFICIENT_FUNDS</code></td><td valign="top">The ticket was rejected because a punter does not have enough funds available (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_WG_SESSION_EXPIRED</code></td><td valign="top">The ticket was rejected because the authentication token used with the session expired on bookmaker side (terminal state).</td></tr><tr><td valign="top"><code>REJECTED_ADAPTER_INTERNAL_ERROR</code></td><td valign="top">The ticket was rejected because of an internal RGS settlement / ticket engine error. The ticket will eventually be cancelled.</td></tr><tr><td valign="top"><code>REJECTED_ADAPTER_EXTERNAL_ERROR</code></td><td valign="top">The ticket was rejected because of an external RGS settlement / ticket engine error. The ticket will be eventually be cancelled.</td></tr><tr><td valign="top"><code>REJECTED_ADAPTER_MARKET_DOES_NOT_EXIST</code></td><td valign="top">The ticket was rejected because RGS settlement / ticket engine did not recognize one or more markets. The ticket will eventually be cancelled.</td></tr><tr><td valign="top"><code>REJECTED_ADAPTER_NOT_ACKED</code></td><td valign="top">The ticket was rejected because RGS settlement / ticket engine did not acknowledge the ticket. This status is not likely to happen as more a specific status will be associated with the ticket. The ticket will eventually be cancelled.</td></tr><tr><td valign="top"><code>REJECTED_ADAPTER_MARKET_EXPIRED</code></td><td valign="top">Ticket was rejected because the market had expired on RGS settlement / ticket engine. Ticket will eventually be cancelled.</td></tr><tr><td valign="top"><code>REJECTED_ADAPTER_TICKET_NOT_VALID</code></td><td valign="top">Ticket was rejected because RGS settlement / ticket engine rejected the ticket. Ticket will eventually be cancelled.</td></tr><tr><td valign="top"><code>REJECTED_ADAPTER_MARKET_NOT_ACTIVE</code></td><td valign="top">Ticket was rejected because market is not active on RGS settlement / ticket engine. Ticket will eventually be cancelled.</td></tr><tr><td valign="top"><code>CANCELLATION_PENDING</code></td><td valign="top">The ticket is waiting to be cancelled.</td></tr><tr><td valign="top"><code>TIMEOUTED</code></td><td valign="top">Ticket placement exceeded the timeout threshold. A cancellation attempt will be made.</td></tr><tr><td valign="top"><code>PLACED</code></td><td valign="top">The ticket was successfully placed.</td></tr><tr><td valign="top"><code>CLEARED</code></td><td valign="top">The ticket result is known.</td></tr><tr><td valign="top"><code>CANCELED_WG</code></td><td valign="top">The payment associated with the ticket was cancelled on bookmaker’s wallet. The ticket will be eventually cancelled.</td></tr><tr><td valign="top"><code>BACK_OFFICE_SETTLEMENT</code></td><td valign="top">The ticket requires manual intervention.</td></tr><tr><td valign="top"><code>CANCELED</code></td><td valign="top">The ticket was cancelled.</td></tr><tr><td valign="top"><code>SETTLED</code></td><td valign="top">The ticket was settled and monetized (final state; can be refunded and manually settled afterwards).</td></tr><tr><td valign="top"><p><code>MANUALLY_SETTLED</code></p><p> </p></td><td valign="top">The ticket was manually settled by a back-office user (final state; can be refunded and manually settled afterwards).</td></tr><tr><td valign="top"><p><code>REFUNDED</code></p><p> </p></td><td valign="top">The ticket was refunded by a back-office user (final state; can be refunded and manually settled afterwards).</td></tr><tr><td valign="top"><p><code>REFUNDED_WG</code></p><p> </p></td><td valign="top">The payment associated with the ticket was refunded on bookmaker wallet, but the ticket has not been refunded on RGS settlement / ticket engine yet.</td></tr><tr><td valign="top"><code>EXPIRED</code></td><td valign="top">The ticket’s result was not recorded and requires manual intervention.</td></tr></tbody></table>

#### Selections <a href="#ref105578322" id="ref105578322"></a>

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>eventId</code></td><td valign="top"><code>string</code></td><td valign="top">Betradar’s internal match identifier.</td></tr><tr><td valign="top"><code>id</code></td><td valign="top"><code>string</code></td><td valign="top">Betradar’s internal market type identifier.</td></tr><tr><td valign="top"><code>result</code></td><td valign="top"><code>string</code></td><td valign="top">Represents the result of a selection. Possible values are “+” (won), “-“ (lost), “#” (void) and “*” (open)</td></tr><tr><td valign="top"><code>odds</code></td><td valign="top"><code>integer</code></td><td valign="top">Odds of the selection multiplied by 10000.</td></tr><tr><td valign="top"><code>metaData</code></td><td valign="top"><code>MetaData</code></td><td valign="top">Additional information for the selection. MetaData is not unified and my vary from product to product. See section 3.2.2.1 for further details.</td></tr></tbody></table>

**MetaData**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>lang</code></td><td valign="top"><code>string</code></td><td valign="top">The language code.</td></tr><tr><td valign="top"><code>marketName</code></td><td valign="top"><code>string</code></td><td valign="top">The human-readable market name.</td></tr><tr><td valign="top"><code>outcomeName</code></td><td valign="top"><code>string</code></td><td valign="top">The human-readable name of the selected outcome.</td></tr><tr><td valign="top"><code>productType</code></td><td valign="top"><code>string</code></td><td valign="top">A value specifying the game associated with the ticket. See section 2.9.1.3 for further details.</td></tr><tr><td valign="top"><code>tournament</code></td><td valign="top"><code>Tournament</code></td><td valign="top">Provides details about the tournament. See section 3.2.2.2 for further details.</td></tr></tbody></table>

**Tournament**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>name</code></td><td valign="top"><code>string</code></td><td valign="top">The tournament’s name.</td></tr><tr><td valign="top"><code>sequence</code></td><td valign="top"><code>string</code></td><td valign="top">Additional information about the tournament. Varies from product to product.</td></tr><tr><td valign="top"><code>event</code></td><td valign="top"><code>Event</code></td><td valign="top">Provides details about the event. See section 3.2.2.3 for further details.</td></tr></tbody></table>

**Event**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>competitors</code></td><td valign="top"><code>Competitors[]</code></td><td valign="top">Provides information about the competitors of a fixture. See section 3.2.2.4 for further details.</td></tr><tr><td valign="top"><code>eventStart</code></td><td valign="top"><code>string</code></td><td valign="top">13-digit epoch timestamp representing the time a match started.</td></tr><tr><td valign="top"><code>name</code></td><td valign="top"><code>string</code></td><td valign="top">A name specifying the round within a season.</td></tr><tr><td valign="top"><code>sequence</code></td><td valign="top"><code>string</code></td><td valign="top">Additional information about the event. Varies from product to product.</td></tr></tbody></table>

**Competitor**

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>id</code></td><td valign="top"><code>string</code></td><td valign="top">Betradar’s internal competitor identifier.</td></tr><tr><td valign="top"><code>name</code></td><td valign="top"><code>string</code></td><td valign="top">The competitor’s name.</td></tr><tr><td valign="top"><code>abbr</code></td><td valign="top"><code>string</code></td><td valign="top">The abbreviation of the competitor’s name.</td></tr></tbody></table>

#### Bets <a href="#ref106288482" id="ref106288482"></a>

<table><thead><tr><th valign="top">Parameter</th><th valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>selectionRefs</code></td><td valign="top"><code>integer[]</code></td><td valign="top">References the selections a bet is built of.</td></tr><tr><td valign="top"><code>selectedSystems</code></td><td valign="top"><code>integer[]</code></td><td valign="top"><p>We identify systems using an array of the length of combinations to include in each bet:</p><p> </p><p>·         Singles: [1] - All combinations with length = 1.</p><p>·         Multi: [n] - The only combination where length = n.</p><p>·         System x/n: [x] - All combinations with length 2..n-1, i.e., for a ticket with 4 lines we have 2/4 and 3/4. Each refers to all combinations of x length, respectively [2] and [3].</p><p>·         Full Cover: [2..n] - All the above excluding singles, i.e., a full cover of 4 lines is identified by [2, 3, 4].</p><p>·         Full Cover with Singles: [1..n] - All possible combinations including singles: [1, 2, 3, 4].</p></td></tr><tr><td valign="top"><code>sumOfWins</code></td><td valign="top"><code>string</code></td><td valign="top">The sum of winnings from won combinations.</td></tr></tbody></table>

&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportradar.com/games/virtual-sports/remote-game-server-rgs/rgs-wallet-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.