> For the complete documentation index, see [llms.txt](https://docs.wynta.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wynta.com/bonus/api-reference/bonus-events.md). # 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) ```json { "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 | ```json { "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 | ```json { "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 | ```json { "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 | ```json { "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 | ```json { "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` | ```json { "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` | ```json { "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](/bonus/api-reference/player-and-s2s.md#8-get-user-referral-code)) | ```json { "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](broken://pages/K44hCnFoLjBc1OK0LM0t). ## 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.