Bonus engine integration guide

Before you begin

For a bonus engine integration to be possible, the following requirements must be met.

Authentication and API access — You must be able to make a secure, authenticated connection to the bonus engine and interact with it via API.

Core endpoint requirements — At a minimum, the bonus engine API must support one of the following patterns:

• Retrieve a list of active bonuses, and allocate Bonus ID X to Customer ID Y
• Retrieve a list of bonus types, and allocate a bonus of type X with value Y to Customer ID Z

Optional capabilities — Where supported, Xtremepush can also enable:

• Bonus de-allocation — Remove a bonus from a customer via the same assignment endpoint (de-allocate Bonus ID X from Customer ID Y). Note that allocation and de-allocation are handled through a single endpoint; separate endpoints for each operation are not supported.
• Post-campaign event capture — The bonus engine posts transactional events back to Xtremepush after a user has been added to a bonus audience. This is handled via the standard event stream integration path (for example, Bonus Claimed or Bonus Credited).

Technical integration

Standard configuration

Xtremepush provides a configuration-based setup that can be implemented within days (excluding lead time), provided the bonus engine meets the following requirements.

Supported authentication methods

The following are supported out of the box:

• Bearer token
• Header token
• Username and password
• OpenID
• OAuth

API requirements

• JSON format requests and responses with minimal levels of nesting
• An endpoint to retrieve a list of active promotions or bonuses
• A single endpoint to both allocate and remove bonuses for users

Standard functionality

As part of the standard integration, Xtremepush supports dynamic assignment — setting fixed values or values based on variables found in player attributes or triggering events. Where advanced per-bonus variable configuration is required, this is managed via the /sync endpoint, allowing clients to define variables on a per-bonus basis.

What we need from you

To get started, we require the following from your team, as an OpenAPI spec with examples where possible:

• API documentation for your bonus engine
• Confirmation of the authentication method in use
• The base URL for the API endpoints
• Full details of all fields required when assigning or removing a bonus — the exact field names, types, and any conditional requirements are important to confirm upfront to avoid delays during setup

Expected API format - simple

List bonuses

GET /bonus/fetch
Authorization: Bearer <token> or Basic <credentials>
Content-Type: application/json

Expected response:

[
  {
    "id": "183",
    "name": "Name of Promotion"
  },
  {
    "id": "184",
    "name": "Name of Promotion"
  }
]

Assign bonus - batched

POST /bonus/assign
Authorization: Bearer <token> or Basic <credentials>
Content-Type: application/json

Expected request body:

{
  "promotionId": "510948",
  "amount": 100.00,
  "userIds": ["1261853", "1261854"]
}

Bespoke integrations

Where a bonus engine has an unsupported authentication method, a different communication protocol (e.g., JSON-RPC or XML), or a complex request/response format, Xtremepush can build a bespoke integration where practical and feasible. This will carry additional lead time and may incur setup and maintenance costs.

Post-campaign events

Where possible, the bonus engine should post transactional events back to Xtremepush after a user has been added to a bonus audience. These can be sent to the event endpoint in the same way as any other transactional event (e.g., deposit, bet placed, bet outcome).

At a minimum, the following events should be included:

• Bonus Credited — Fired when a user has met any additional criteria and the bonus is added to their wallet
• Bonus Claimed — Fired when a user has successfully claimed the bonus

Existing third-party integrations

Xtremepush has pre-built integrations with the following bonus engine providers:

Frequently asked questions

How long does a standard bonus engine integration take?
Where the integration requirements are met, a standard configuration can typically be completed within a few days, excluding lead time. Bespoke integrations will take longer — timelines should be agreed with your Xtremepush account manager upfront.

What if our bonus engine uses a protocol other than REST/JSON?
Where a bonus engine uses an unsupported authentication method or communication protocol (e.g., JSON-RPC or XML), Xtremepush can build a bespoke integration where practical. This carries additional lead time and may incur setup and maintenance costs.

Can bonuses be removed as well as assigned?
Yes, where the bonus engine supports de-allocation, Xtremepush can remove a bonus from a customer. Allocation and de-allocation are handled through a single shared endpoint.

Do we need to send post-campaign events back to Xtremepush?
Where supported, yes. At a minimum, we recommend sending Bonus Credited and Bonus Claimed events via the standard event endpoint. These events enable accurate campaign reporting and allow you to trigger follow-up messaging based on bonus outcomes.

Our bonus engine is not in the existing integrations list. Can it still be integrated?
Yes. Xtremepush can integrate with any bonus engine that meets the API requirements outlined in this guide. Contact your account team to discuss your specific bonus engine and expected timeline.

Related pages

• Add promotion to campaign setup
• Promotions in a Multi Stage Journey
• Existing third-party integrations