Contributing to Jackpots

Now that you are processing events from your platform, you want to be able to make Contributions on behalf of players to the jackpot. The process of contributing is quite straight forward and does not require your service to be aware of player opt-in status. You will however need to decide which jackpot to contribute to and this can be done in one of two ways:

• Contribute by source
• Contribute direct to jackpot

Sources

A Source can be thought of as an operator-defined identifier for a user journey, a group of games, or even a single game. You can read more about Sources here,

Example: Sitewide Jackpot

If you wanted to create a site-wide jackpot for your casino vertical, you could create a Source named casino-sitewide, map a jackpot to the source and then send all contributions to that specific Source.

{
    "token": "token_00001",
    "brand_id": "thrilltech:brand1",
    "player_id": "player_00001",
    "player_country": "UK",
    "source_id": "casino-sitewide",
    "gameround_id": "1",
    "currency": "EUR",
    "base_wager": 1
}

Example: Deposit Jackpot

If you wanted to create a deposit jackpot, you can create a source called deposit, map the relevant jackpot to the source and then send all deposit-based contributions ot that source

{
    "token": "token_00001",
    "brand_id": "thrilltech:brand1",
    "player_id": "player_00001",
    "player_country": "UK",
    "source_id": "deposit",
    "gameround_id": "DEPOSIT_TX_ID",
    "currency": "EUR",
    "base_wager": 1
}

Example: Game Group Jackpot

If you wanted to create a jackpot for a specific set of games, for example, a jackpot for all egyptian themed games, you can create a source called egyptian-games and use that for contributions each time a player bets into a game that is egyption themed. This would naturally require your integration service to know which games are matched to which Game Group source.

{
    "token": "token_00001",
    "brand_id": "thrilltech:brand1",
    "player_id": "player_00001",
    "player_country": "UK",
    "source_id": "egyptian-games",
    "gameround_id": "1",
    "currency": "EUR",
    "base_wager": 1
}

Example: Game Specific Jackpots

If you want to split your liquidity by game title, you can create sources that correspond to the game codes of games in your system. Each source would need a jackpot mapped to it, but once that is done, you are able to make contributions to the source based on the game code of the base game bet.

{
    "token": "token_00001",
    "brand_id": "thrilltech:brand1",
    "player_id": "player_00001",
    "player_country": "UK",
    "source_id": "provider-game-code",
    "gameround_id": "1",
    "currency": "EUR",
    "base_wager": 1
}

Direct to Jackpot Contribution

An alternative to using sources is to make contributions directly to Jackpot Instances by their ID. For example, if you have created a Jackpot instance, you will have its ID available to you. This ID will not change over the lifetime of the jackpot. Making contributions directly to a Jackpot ID incurs less processing cost, but may also reduce the flexibility you may have in changing which jackpot players contribute to based on the content or user flows.

The only difference in the contribution payload is that the source_id is replaced with an instance_id field as seen below:

{
    "instance_id": "0a1cfeea-5b07-4f2b-b2f1-2e4cd2aa991d",
    "token": "token_00001",
    "brand_id": "thrilltech:brand1",
    "player_id": "player_00001",
    "player_country": "MT",
    "gameround_id": "1000",
    "base_wager": 2,
    "currency": "EUR"
}

Synchronous vs Asynchronous contribution

The default contribution mechanism is synchronous. However, depending on your system architecture (and system load), you may prefer to make use of asynchronous contribution mechanics. In order to make asynchronous contributions, you need to provide a webhook that the ThrillPots system can call once the result of a contribution has been determined.

In order to make a contribution asynchronously, you simple need to add a callback property to either of the contribution payloads above to specify the webhook to call and which results you are interested in receiving.

The structure of the callback property is as follows:

{
    "web_hook": "https://your.host/webhook",
    "win_result_only": false
}

The web_hook field indicates the fully qualified HTTP path to your webhook and the win_result_only property indicates whether the webhook should only receive win results or all contribution results.

Therefore, an asynchronous contribution for a sitewide casino jackpot would look like this:

{
    "token": "token_00001",
    "brand_id": "thrilltech:brand1",
    "player_id": "player_00001",
    "player_country": "UK",
    "source_id": "casino-sitewide",
    "gameround_id": "1",
    "currency": "EUR",
    "base_wager": 1,
    "callback": {
        "web_hook": "https://your.host/webhook",
        "win_result_only": false
    }
}

When making an asynchronous contribution, the ThrillPots system will either return 200 OK with a JSON payload that contains a trace_id for the request when it has successfully accepted the contribution request for processing, or you will receive an error due to the request being malformed.

Any contribution request errors will be send to the webhook. The structure of the webhook payload is defined as follows:

Successful contribution result

{
    "type": "data",
    "contribution_amount": Number,
    "contribution_currency": String,
    "gameround_id": String,
    "instance_id": String,
    "metadata": null | Object,
    "tickets_awarded": null | Number,
    "timestamp": Number,
    "win_amount": Number,
    "win_pot_id": null | String,
    "win_withheld": Boolean
}

Error result

{
    "type": "error",
    "status_code": Number,
    "code": String,
    "message": String,
}

The data portion will either be a ContributionResult structure or an Error structure. You can find more information on these structures in the API documentation.

Examples of payloads sent to the web hook

Contribution Result

{
    "type": "data",
    "contribution_amount": 0.1,
    "contribution_currency": "EUR",
    "gameround_id": "cc83c1cc-6260-44fc-822b-d3c03acf2d89",
    "instance_id": "a49ff35f-6ecd-491f-b373-85e6caabacf1",
    "metadata": null,
    "tickets_awarded": null,
    "timestamp": 1715714218408,
    "win_amount": 0,
    "win_pot_id": null,
    "win_withheld": false
}

Error Result

{
    "type": "error",
    "status_code": 404,
    "code": "GAME_NOT_FOUND",
    "message": "sitewide-casino2",
}

Contribution Request Errors

A contribution request may result in a direct or a downstream error. A direct error is an error that is the result of the ThrillPots system return an error to the contribution request itself. A downstream error is an error that is propogated to the contribution request caller from a downstream system, such as ThrillGate or the operator wallet itself.

List of Direct Errors

For Direct Errors, you can expect:

Passing Metadata

If you need to pass contextual metadata from your event processor to your wallet, you can do so by adding a metadata field to the Contribution Request. This data will be passed through the system and attached to transaction requests to your wallet.

The metadata field can be any valid JSON value, for example:

Metadata containing an Object:

{
    "token": "token_00001",
    "brand_id": "thrilltech:brand1",
    "player_id": "player_00001",
    "player_country": "UK",
    "source_id": "casino-sitewide",
    "gameround_id": "1",
    "currency": "EUR",
    "base_wager": 1,
    "metadata": {
        "value1": "some value",
        "value2": 1234
    }
}

Metadata containing a String:

{
    "token": "token_00001",
    "brand_id": "thrilltech:brand1",
    "player_id": "player_00001",
    "player_country": "UK",
    "source_id": "casino-sitewide",
    "gameround_id": "1",
    "currency": "EUR",
    "base_wager": 1,
    "metadata": "This is an arbitrary string value"
}