System Integration for Bet and Coupon Calculation

How Does the Odds and Outcomes Calculation System Work?

Integration with our bet and coupon calculation system consists of three key stages:

Step 1: Authorization

In the first stage, you need to authorize in the system. This is done by performing a POST request with user credentials (login and password). Successful authorization returns a session represented as a cookie, which must be saved. These cookies are required for all subsequent requests as they are used to identify the user's session in the system.

Step 2: Sending a Bet

At this stage, a bet code is sent to our system containing:

• Match ID, corresponding to the event.
• Bet code, describing the selected outcome (e.g., team win, handicap, or total).
• Bet odds, valid at the time of submission.

When submitting data, the cookies obtained during authorization must be included. This ensures proper user identification and bet processing.

Step 3: Receiving Results

After the outcomes or coupons are calculated, our system sends POST requests to the specified remote_host. This request includes:

• Coupon status (win, loss, or refund).
• Statuses of all outcomes included in the coupon.

Results are sent as soon as the outcome is determined. For example:

• If the bet was placed on an intermediate outcome (e.g., handicap 2.5, and the third goal is scored), the calculation may be performed during the match.
• If the bet is on the final result (e.g., team win), the status information will be sent immediately after the match ends.

Now review each step individually. We have described the requests, parameters, and API responses in detail.

Login, password, and the host for sending requests can be obtained from the manager.

Request URL:

{APIHOST}/WebServices/BCService.asmx/LogIn/

Data Submission Type: POST

Submitted Data:

Parameter	Description
login	User login
password	User password

Important!

• During authorization, the response includes cookies. These cookies must be saved and sent with subsequent requests.

Recommendations for easier integration:

• Ensure the login field is passed as a string.
• Verify the correct saving and sending of cookies, as this affects the execution of subsequent requests.
• In case of an error, the request will return an empty object. Make sure to handle this scenario appropriately.

Cookies are valid for 3 months. However, they may be reset if the server is restarted. Therefore, you need to reauthorize if you encounter an error while saving a coupon.

"errorCode":1,
"fullErrorCode":99,
"errorMessage":"Invalid access level"

Example Response:

Successful:

{"d":{"UserId":"36557"}}

Unsuccessful:

{"d":{}}

Response Fields Description:

Field	Description
UserId	Unique user identifier
d	Root object of the response

General Recommendations:

• Before the first request, ensure the user has entered the correct credentials.
• Set up error handling to display the reasons for failed authorization to the user (e.g., incorrect login or password).
• Log both successful and unsuccessful attempts for analysis and monitoring.

Cookies must be saved and sent with subsequent requests.

import requests
import json

url = "https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/"

payload = json.dumps({
  "login": "demo-login@demosportapi.net",
  "password": "demo-password"
})
headers = {
  'Content-Type': 'application/json'
}

print(response.text)

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
    "login":"demo-login@demosportapi.net",
    "password":"demo-password"
}',
    CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
    ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
    "login": "demo-login@demosportapi.net",
    "password": "demo-password"
});

const requestOptions = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow"
};

fetch("https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/", requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.error(error));

OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"login\":\"demo-login@demosportapi.net\",\r\n    \"password\":\"demo-password\"\r\n}");
Request request = new Request.Builder()
.url("https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();

To submit a bet, you must use the cookies obtained during the authorization stage. These data are required to identify your session and process requests.

Request URL:

{HOST_API}/bet/place/

{
    "data":{
        "list_bets":[
            "line#586464528|17|954|2.5#4.27",  "live#586464528|87|4|0#1.12"
        ],
        "realAmount":"2",
        "currency":"USD",
        "lang":"en",
        "remote_host":"https://mysites.com",
        "rate_mode":"reject"
    }
}

Field Descriptions

Parameter	Description
list_bets	Bet code and odds. Format: "event_type#match_ID|bet_code#odds". Example: "live#579216393|1|1|0#2.1"
realAmount	Bet amount. Must be passed as a string, e.g., "150".
currency	Coupon currency.
lang	The language in which the bet and coupon are saved. For example: "en", "ru", or "tr".
remote_host	The URL to send the coupon calculation results to. Do not include a trailing slash.
rate_mode	Option for handling coupon acceptance when odds change: "reject" (reject on changes) or "accept" (accept regardless of changes). Default: "accept".

Note: Ensure that parameters are passed in the correct format. For example, list_bets must be an array, even if there is only one bet.

We do not validate the bet amount. You can submit either the actual bet amount or any arbitrary value. This is to ensure the confidentiality of your financial data. Our task is to provide calculation results. You are responsible for crediting winnings to your players.

Required Parameters for Submitting a Bet:

• list_bets — contains information about the bet and the corresponding match.
• remote_host — the URL to which we will send the calculation results for the coupon or outcome.
• rate_mode — determines how the system handles odds changes.

Other parameters should also be sent, but they are optional and can be used for your convenience.

Description of the remote_host Parameter

remote_host is the address of your server where we send requests with the results of bet calculations. This host must be configured to accept requests from our server. Below are examples of possible values and specific details about working with this parameter.

You can specify various options for remote_host:

• Simple host: https://mysites.com
• Host with port: https://mysites.com:78665
• Host with additional paths: https://mysites.com/request/sportapi/sender
• Host with parameters: https://mysites.com/request.php?action=webhook

Important: When sending a request, our system automatically appends the string /api/bet/result to the specified remote_host. Thus, the final address for receiving requests is formed as remote_host + "/api/bet/result". Ensure that your server is configured to receive data at this path.

Examples:

• You specify remote_host = https://mysites.com. We send requests to: https://mysites.com/api/bet/result.
• You specify remote_host = https://mysites.com/request.php?action=webhook. We send requests to: https://mysites.com/request.php?action=webhook/api/bet/result.

Technical Details:

• Requests are sent using the POST method.
• Your server must be ready to accept JSON data that we send.
• Your server must return a 200 status code upon successful data receipt.

Ensure that your server correctly processes the specified path and requests. The next section provides an example of the data structure sent by our server.

Description of the rate_mode Parameter

The rate_mode parameter defines the system's behavior when odds change. It can take two values:

• accept: In this mode, the coupon will be accepted with the current odds, even if they have changed. For example, a player adds a bet "Manchester Wins" with odds of 2.02. While they press the "Place Bet" button, the odds change to 1.37 or 2.78. In the accept mode, the system saves the coupon with the new odds without notifying your system.
• reject: In this mode, the system rejects the coupon if the odds have changed. The response will include an error notifying that the odds have changed.

Choose the mode that best suits your business processes and provides convenience for your users.

Important Recommendations

1. JSON Formatting: Ensure that the data is properly serialized into JSON format before sending.
2. Cookies: Include the cookies obtained during authorization to successfully identify the user's session.
3. Error Handling: Handle server responses, especially cases where errorCode = 1 is returned.
4. Testing: Conduct tests at all stages of integration, including sending single and multiple bets.

Response Fields

Parameter	Description
betCode	Unique bet number in our system
errorCode	Main status of the request result
fullErrorCode	Error details
errorMessage	System error text messages
AmountOut	Potential win amount
CountEvents	Number of bets in the coupon
Coef	Outcome coefficients
IsLive	Bet type: live or pre-match (true/false)
LinesId	Match ID
EventDate	Match date

Error Description for Bet Submission

Various errors may occur when submitting a bet. The server response contains three key fields:

• errorCode: Main request status.
• fullErrorCode: Error details.
• errorMessage: Text description of the error.

If the bet is successfully accepted, the server returns a success response (see above). The coupon has been accepted, and there are no errors.

If an error occurs, the server returns a general error response (see above). One of the possible errors occurred. Below are the error codes and messages.

Possible Error Codes and Descriptions

Error Code (fullErrorCode)	Error Message (errorMessage)	Description
1	error_wrong_bet_data	Incorrect bet data. Check the list_bets parameter and other required fields.
1	error_block_bet_data	The bet is temporarily blocked and cannot be accepted.
1	error_repeat_bet_data	Duplicate bets on the same outcome from one match are not allowed.
2	label_change_rate	The odds have changed. The coupon was rejected due to a mismatch between the specified and current odds.
3	error_exist_bet	The specified bet outcome no longer exists. Check the data for accuracy.
99	Invalid access level	The user does not have the rights to perform this operation. Most likely, reauthorization is required, cookies are missing, or the account is blocked.
99	Error exist remote host!	The remote_host parameter is incorrect or missing. Check your server settings.

Recommendations for Error Handling

• Input Data Validation: Ensure that all required parameters are provided correctly. Check the format of list_bets and the presence of all mandatory fields.
• Working with Odds: If rate_mode = reject is used, handle errors related to odds changes (label_change_rate).
• Server Configuration: Ensure that your server is correctly specified in the remote_host parameter.
• Error Logging: Log all errors (errorCode, fullErrorCode, errorMessage) to simplify debugging and interaction with support.
• Actions for Critical Errors: In case of level 99 errors, check access rights and API configurations on your side.

{
  "errorCode": 1,
  "fullErrorCode": [ERROR_CODE],
  "errorMessage": "[ERROR_DESCRIPTION]"
}

When a bet is added to our system and calculated, we send the coupon results to your server. These can include:

• Coupon results (full calculation).
• Coupon statuses (win, loss, refund).

Requests are sent to the address you specified in the remote_host parameter. The string /api/bet/result is automatically appended to this address. Ensure that your server is configured to receive data at this path.

Example of the Final Address:

If you specified: remote_host = https://mysite.com, we will send data to: https://mysite.com/api/bet/result.

{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "344143",
            "BarCode": "x9c52i8411"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 11130,
        "DateReceive": "1597075782"
    }]
}

Field Descriptions

Field	Description
remote_host	The address of your server where data is sent.
Id	Unique identifier of the bet in our system. Ignored in most cases.
BarCode	Unique coupon number.
Status	Current status of the coupon. Possible values: 2 — win, 4 — loss.
ExtStatus	Additional status in case of a refund: 0 — no changes, 1 — one or more outcomes were calculated with a changed coefficient.
AmountOut	Win amount (if the coupon won).
DateReceive	The time and date when the coupon was calculated.

How to Interpret Status and ExtStatus

• Status = 2 and ExtStatus = 0: The coupon won.
• Status = 4 and ExtStatus = 0: The coupon lost.
• Status = 2 and ExtStatus = 1: Refund. The coupon was calculated with a coefficient of 1.

Important Points for Integration

• Handling ExtStatus = 1: This may occur if a match was canceled or ended prematurely. In such cases, all bets are calculated with a coefficient of 1.
• Technical Requirements: Requests are sent using the POST method. Your server must be ready to accept JSON data at the path remote_host + /api/bet/result.

{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "313",
            "BarCode": "75vz48t935"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 19.85,
        "DateReceive": "1592937968"
    }, {
        "KeyHead": {
            "Id": "312",
            "BarCode": "77i0r6e15t"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 12.51,
        "DateReceive": "1592937280"
    }]
}