Contributing to Jackpots v2

The v2 Contribution API introduces a structured way to submit both source contributions and direct jackpot contributions within a single endpoint. It also enables advanced features such as linked jackpots and bet contexts.

More information on jackpot sources can be found here
More information on linked jackpot instances can be found here

Key Enhancements Over V1

Unified Contribution Model: Supports both source contributions and direct to instance contributions in the same request.
Linked Jackpot Support: Contributions automatically propagate to all directly linked instances.
Structured Data Format: Requests follow a more structured schema, ensuring consistency and extendability.
Expanded Response Structure:
- Synchronous contributions return an array of results for all contributions made.
- Asynchronous contributions trigger multiple webhook events, one per contribution.

Propagation Rules

A contribution applies to the target instance (or instance behind source) as well as all instances directly linked to it . Only the links defined for the target instance are honored.

Failure Handling

If the contribution to the main instance fails, contributions to linked instances will not be attempted.
If a linked instance contribution fails (e.g., due to missing opt-in or validation failure), other linked instances will still be processed normally.

Opt-in Requirement

Opt-ins do not propagate automatically. If a linked instance requires explicit opt-in and the user has not opted in, the contribution fails for that instance.

API Request structure

{
    // Contribution target
    "target": {
        // Contribution target type, can be either "source" or "instance"
        "type": "source",
        // Contribution target identifier
        // eg. "sitewide-casino" in case of source contribution
        // eg "bdfa6295-d5a5-4c54-98bf-046355ce0252" in case of direct contribution to jackpot
        "id": "sitewide-casino"
    },
    // Jackpot instance owner identifier (operator id)
    "owner_id": "thrilltech",
    // Details of the contributing player
    "player": {
        // Player identifier
        "id": "player_00001",
        // Player authentication token
        "token": "token_00001",
        // Player country
        "country": "UK",
        // Player brand identifier
        "brand_id": "brand1",
        // Any segments that the player might be part of
        "segments": ["vip-1", "regular"],
    },
    // Base game wager
    "base_wager": {
        // Base wager currency
        "currency": "EUR",
        // Base wager value
        "value": 1
    },
    // The contribution source that caused the contribution to happen.
    // For example, if a player made a bet on a game, this would be the game's gameround ID.
    // If a player made a successful deposit, this would be the deposit's identifier.
    // This field is stored by ThrillPots and is used a back-reference to the original user action
    // that caused the contribution to happen.
    "source": {
        // Type of the contribution source. Defaults to `gameround` but can be any value you choose
        "type": "gameround",
        // Identifier of the contribution source
        "id": "gameround_id_1"
    },
    // Opaque data object that contains pass-through data for the caller.
    // The content of this property will be sent back on the JackpotContributionResponse to this request.
    "metadata": {},
    // Opaque data object that contains pass-through data for the caller.
    // The content of this property will be attached to any resulting events. ( win events at that stage )
    "event_metadata": {},
    // Optional contribution request parameters. Each field in this field is optional as well.
    "options": {
        // Optional identifier of the vertical from which the contribution request originated
        "vertical_id": "slots",
        // Optional boolean specifying whether linked jackpots should be honored
        "allow_linked_contributions": true,
        // If you would like ThrillPots to not process duplicate contributions, then specify a unique
        // `idempotency_key` here
        "idempotency_key": "random_uuid_value",
        // Specify the webhook to call and which results you are interested in receiving
        "callback": {
            "web_hook": "https://your.host/webhook",
            "win_result_only": false
        }
    },
}

Synchronous Contribution

If you do not specify a callback in the options.callback field, your contribution request will be processed synchronously. In this case, the response will be an array of JackpotContributionResponse structures. Normally, the array will only contain 1 result, however when the initial jackpot is linked to other jackpots, the array will contain more than one element, one for each jackpot that was linked.

Returns results for the target jackpot instance and all of its linked instances.
Result structure remains the same with the only difference it being an array.

[
    {
        "instance_id": "bdfa6295-d5a5-4c54-98bf-046355ce0252",
        "timestamp": 1739972162307,
        "gameround_id": "bb2a5277-1f00-47cf-b62c-9f639ddff146",
        "win_amount": 0.0,
        "win_pot_id": null,
        "tickets_awarded": null,
        "win_withheld": false,
        "contribution_currency": "EUR",
        "contribution_amount": 0.0775,
        "metadata": null
    },
    {
        "instance_id": "3c90cb1e-a594-437e-a695-e76acb0e6809",
        "timestamp": 1739972162394,
        "gameround_id": "7eab0af4-1477-44d9-88f0-a9b7763a6d30",
        "win_amount": 0.0,
        "win_pot_id": null,
        "tickets_awarded": null,
        "win_withheld": false,
        "contribution_currency": "EUR",
        "contribution_amount": 0.1,
        "metadata": null
    }
]

If contribution to a linked instance fails (e.g., due to missing opt-in or regulatory restrictions), the response details which instances succeeded and which failed.

[
    {
        "instance_id": "bdfa6295-d5a5-4c54-98bf-046355ce0252",
        "timestamp": 1739972093142,
        "gameround_id": "0860e92b-6d75-45ab-a520-39ab511e18c1",
        "win_amount": 0.0,
        "win_pot_id": null,
        "tickets_awarded": null,
        "win_withheld": false,
        "contribution_currency": "EUR",
        "contribution_amount": 0.0775,
        "metadata": null
    },
    {
        "status_code": 400,
        "code": "CONTRIBUTION_REJECTED",
        "message": "PlayerNotOptedIn"
    }
]

Asynchronous Contributions & Webhooks

For asynchronous contributions, the API does not return immediate results. Instead, a webhook event is triggered for each contribution, providing its final outcome.

win_result_only Option
- If win_result_only is enabled, the webhook will only be triggered for contributions that result in a win.
- If disabled (default behavior), a webhook is sent for every contribution, regardless of the outcome.
- The webhook payload structure remains unchanged from v1 contributions.

{
    "type": "data",
    "instance_id": "bdfa6295-d5a5-4c54-98bf-046355ce0252",
    "timestamp": 1739972634263,
    "gameround_id": "0174c60b-f827-4e9c-8f66-8d5444732071",
    "win_amount": 0.0,
    "win_pot_id": null,
    "tickets_awarded": null,
    "win_withheld": false,
    "contribution_currency": "EUR",
    "contribution_amount": 0.0775,
    "metadata": null
}

OAS and Swagger documentation

For more details on using this functionality, refer to ThrillPots Service and ThrillPots Gateway API documentation

ThrillTech Technology & Integration Guide (SaaS)