Bonus Events

Events consumed by the bonus service to evaluate eligibility, trigger grants/releases, and update wager progress. Send events in the standard PAM batch envelope. All event_name values use lowercase snake_case (for example, deposit_success and bet_placed).

Envelope (common to all events)

{
  "events": [
    {
      "event_id": "uuid-v4",
      "event_name": "lowercase_snake_case_event_name",
      "schema_version": 1,
      "user_id": "user_001",
      "session_id": "sess_optional",
      "timestamp": "2026-08-03T10:00:00.000Z",
      "sdk": { "name": "client-name", "version": "1.0.0" },
      "device": { "platform": "web", "os": "operating-system", "ua": "user-agent" },
      "properties": {}
    }
  ]
}

event_id is the idempotency key for event ingestion.

User action events

login

Property	Type	Required	Notes
login_method	string	yes	email, phone, google, apple, etc.
ip	string	no	PII — hashed before storage

{
  "events": [
    {
      "event_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "event_name": "login",
      "schema_version": 1,
      "user_id": "user_001",
      "session_id": "sess_abc123",
      "timestamp": "2026-05-14T08:00:00.000Z",
      "sdk": { "name": "client-name", "version": "1.0.0" },
      "device": { "platform": "web", "os": "operating-system", "ua": "user-agent" },
      "properties": { "login_method": "phone" }
    }
  ]
}

registration

Property	Type	Required	Notes
registration_method	string	yes	email, phone, google, apple
currency	string	yes	ISO 4217 currency code
promo_code	string	no	Promotion code used at sign-up

{
  "events": [
    {
      "event_id": "3f2a9c1e-7b4d-4e6a-9f1c-2d8b5a7e4c60",
      "event_name": "registration",
      "schema_version": 1,
      "user_id": "user_12345",
      "session_id": "sess_1745750400000",
      "timestamp": "2026-08-03T10:00:00.000Z",
      "sdk": { "name": "bonus-client-test", "version": "1.0.0" },
      "device": { "platform": "web", "os": "simulator", "ua": "bonus-client-test/1.0" },
      "properties": {
        "registration_method": "google",
        "currency": "INR",
        "promo_code": "SIGNUP10"
      }
    }
  ]
}

app_visit

Property	Type	Required	Notes
visit_count	int	no	Cumulative visit count including this one

{
  "events": [
    {
      "event_id": "a1b2c3d4-0000-0000-0000-000000000003",
      "event_name": "app_visit",
      "schema_version": 1,
      "user_id": "user_001",
      "session_id": "sess_abc123",
      "timestamp": "2026-05-14T08:10:00.000Z",
      "sdk": { "name": "client-name", "version": "1.0.0" },
      "device": { "platform": "web", "os": "operating-system", "ua": "user-agent" },
      "properties": { "visit_count": 5 }
    }
  ]
}

Deposit events

deposit

Property	Type	Required	Notes
transaction_id	string	yes	Unique settled deposit transaction ID
amount	number	yes	Settled deposit amount
currency	string (ISO 4217)	yes	e.g. INR
payment_method	string	yes	upi, netbanking, card, wallet
promo_code	string	no	Promotion code applied to the deposit

{
  "events": [
    {
      "event_id": "3f2a9c1e-7b4d-4e6a-9f1c-2d8b5a7e4c60",
      "event_name": "deposit_success",
      "schema_version": 1,
      "user_id": "user_12345",
      "session_id": "sess_1745750400000",
      "timestamp": "2026-08-03T10:00:00.000Z",
      "sdk": { "name": "bonus-client-test", "version": "1.0.0" },
      "device": { "platform": "web", "os": "simulator", "ua": "bonus-client-test/1.0" },
      "properties": {
        "transaction_id": "txn_9f8a7b6c",
        "amount": 50.5,
        "currency": "USD",
        "payment_method": "card",
        "promo_code": "WELCOME50"
      }
    }
  ]
}

Gameplay & betting events

bet_placed

Emitted when a wager is accepted by the RGS. This event feeds the wagering progress that releases bonus chunks. It also resets the user's session timeout.

Property	Type	Required	Notes
transaction_amount	decimal string	yes	Wager amount; 4-decimal precision
bonus_amount	decimal string	yes	Bonus-funded portion; 4-decimal precision
chip_type	string	yes	Wallet source, such as CASH
wager_tnx_id	string	yes	Unique wager transaction ID
session_key	string	yes	Gaming-session identifier
platform_client_id	string	yes	Client platform identifier
product	string	yes	Product, such as RUMMY
game_type	string	yes	Game classification, such as TOURNEY
game_variant	string	no	Game variant
game_name	string	no	Display name for the game
game_action	string	yes	Action, such as REGISTER_TOURNEY
primary_transaction_id	integer	yes	Primary transaction identifier
secondary_transaction_id	integer	yes	Secondary transaction identifier
tertiary_transaction_id	integer	yes	Tertiary transaction identifier
base_request_id	integer	yes	Source request identifier

{
  "events": [
    {
      "event_id": "3f2a9c1e-7b4d-4e6a-9f1c-2d8b5a7e4c60",
      "event_name": "bet_placed",
      "schema_version": 1,
      "user_id": "user_12345",
      "session_id": "sess_1745750400000",
      "timestamp": "2026-08-03T10:00:00.000Z",
      "sdk": { "name": "bonus-client-test", "version": "1.0.0" },
      "device": { "platform": "web", "os": "simulator", "ua": "bonus-client-test/1.0" },
      "properties": {
        "transaction_amount": "25.0000",
        "bonus_amount": "0.0000",
        "chip_type": "CASH",
        "wager_tnx_id": "wager_5566",
        "session_key": "sess_1745750400000",
        "platform_client_id": "bonus-client-test",
        "product": "RUMMY",
        "game_type": "TOURNEY",
        "game_variant": "holdem",
        "game_name": "Friday Holdem",
        "game_action": "REGISTER_TOURNEY",
        "primary_transaction_id": 1,
        "secondary_transaction_id": 2,
        "tertiary_transaction_id": 3,
        "base_request_id": 3
      }
    }
  ]
}

Game events

leaderboard_won

Property	Type	Required	Notes
leaderboard_id	string	yes	ID of the leaderboard
rank	int	yes	User's final rank
prize_amount	decimal string	yes	In currency units; 4-decimal precision
currency	string (ISO 4217)	yes	e.g. INR
period	string	yes	DAILY, WEEKLY, MONTHLY

{
  "events": [
    {
      "event_id": "a1b2c3d4-0000-0000-0000-000000000031",
      "event_name": "leaderboard_won",
      "schema_version": 1,
      "user_id": "user_001",
      "session_id": "sess_abc123",
      "timestamp": "2026-05-14T23:59:00.000Z",
      "sdk": { "name": "client-name", "version": "1.0.0" },
      "device": { "platform": "web", "os": "operating-system", "ua": "user-agent" },
      "properties": {
        "leaderboard_id": "lb_weekly_001",
        "rank": 2,
        "prize_amount": "5000.0000",
        "currency": "INR",
        "period": "WEEKLY"
      }
    }
  ]
}

tournament_won

Property	Type	Required	Notes
tournament_id	string	yes	ID of the tournament
rank	int	yes	User's final rank
prize_amount	decimal string	yes	In currency units; 4-decimal precision
currency	string (ISO 4217)	yes	e.g. INR

{
  "events": [
    {
      "event_id": "a1b2c3d4-0000-0000-0000-000000000032",
      "event_name": "tournament_won",
      "schema_version": 1,
      "user_id": "user_001",
      "session_id": "sess_abc123",
      "timestamp": "2026-05-14T23:59:00.000Z",
      "sdk": { "name": "client-name", "version": "1.0.0" },
      "device": { "platform": "web", "os": "operating-system", "ua": "user-agent" },
      "properties": {
        "tournament_id": "trn_may_championship",
        "rank": 1,
        "prize_amount": "10000.0000",
        "currency": "INR"
      }
    }
  ]
}

Referral events

friend_signup

A friend referred by this user completes registration.

Property	Type	Required	Notes
friend_user_id	string	yes	User ID of the friend who signed up
referral_code	string	yes	Code used by the friend at sign-up (see referral-code endpoint)

{
  "events": [
    {
      "event_id": "a1b2c3d4-0000-0000-0000-000000000010",
      "event_name": "friend_signup",
      "schema_version": 1,
      "user_id": "user_001",
      "session_id": "sess_abc123",
      "timestamp": "2026-05-14T12:00:00.000Z",
      "sdk": { "name": "client-name", "version": "1.0.0" },
      "device": { "platform": "web", "os": "operating-system", "ua": "user-agent" },
      "properties": { "friend_user_id": "user_002", "referral_code": "REF_XYZ99" }
    }
  ]
}

Event → trigger mapping

Each event maps 1:1 to a bonus_release_trigger.trigger_type (trigger types remain uppercase configuration enums):

event_name	trigger_type
login	LOGIN
registration	REGISTRATION
app_visit	APP_VISIT
deposit_success	DEPOSIT
bet_placed	BET_PLACED
leaderboard_won	LEADERBOARD_WON
tournament_won	TOURNAMENT_WON
friend_signup	FRIEND_SIGNUP

Trigger rules additionally filter by occurrence (0 = every event, 1 = first only, N = Nth), min/max_trigger_amount, payment_method, product, and trigger_config_json conditions — see Configuration APIs.

PII fields

The following properties are PII and must be hashed (SHA-256 with project salt) before persistence: email, phone, ip. Raw values may transit over TLS but must never be logged or written to storage unhashed.