User Bonus API

Base path: /api/v1/user-bonuses. Endpoints marked 🔐 require the X-Client-Id header (resolved server-side to a site_id); the others need no auth header.

1. List applicable bonus codes

Returns all active bonus codes available to a user on a given site, ordered by display_order ascending — used to render a bonus selection UI.

Codes flagged system_auto_apply are never returned here — those are applied automatically by the backend when a BONUS_RELEASE event fires and are not meant for manual selection.

GET /api/v1/user-bonuses/applicable-codes

Query parameter	Type	Required	Default	Description
user_id	string	Yes	—	Platform user identifier (max 50 chars)
chip_type	string	Yes	—	cash or in_app_purchase
display_on	string	No	DEPOSIT	Filter by display flow (e.g. DEPOSIT, REGISTRATION). A code matches if this value appears anywhere in its comma-separated display_on list

Response 200 OK

[
  {
    "promo_id": 12,
    "code": "WELCOME100",
    "max_amount": "500.00",
    "valid_from": "2025-01-01T00:00:00",
    "valid_to": "2025-12-31T23:59:59",
    "display_title": "Welcome Bonus",
    "display_description": "Get 100% on your first deposit up to ₹500",
    "terms_url": "https://example.com/terms/welcome",
    "banner_image_url": "https://cdn.example.com/banners/welcome.jpg",
    "badge_text": "Hot",
    "cta_text": "Claim Now",
    "auto_apply": false,
    "display_order": 1,
    "display_on": "DEPOSIT",
    "min_display_amount": "100.00",
    "wager_multiplier": "3.00",
    "no_of_chunks": 3,
    "applicability_frequency": "ONCE"
  }
]

Key response fields: promo_id (code record ID), presentation fields (display_title, display_description, terms_url, banner_image_url, badge_text, cta_text, display_order, display_on), auto_apply (if true, apply without user selection), min_display_amount (minimum transaction amount to show this bonus), plus the bonus mechanics the client can surface: wager_multiplier, no_of_chunks, applicability_frequency (e.g. ONCE, DAILY), max_amount, validity window (UTC).

2. Validate a bonus code

Validates whether a promo code is applicable for a user without consuming it. Use this to give the user confirmation before they commit to a code (e.g. on a deposit screen). No auth header required.

POST /api/v1/user-bonuses/validate-code

Request body application/json

{
  "user_id": "USER_001",
  "chip_type": "cash",
  "code": "WELCOME100"
}

Response 200 OK

{
  "valid": true,
  "code": "WELCOME100",
  "reason": null,
  "promo_id": 12,
  "display_title": "Welcome Bonus",
  "wager_multiplier": "3.00",
  "no_of_chunks": 3
}

Field	Type	Description
valid	boolean	true if the code is applicable for this user and chip type
code	string	Echo of the submitted promo code
reason	string | null	Human-readable reason when valid is false; null when valid
promo_id	integer | null	Bonus configure promo ID; null when invalid
display_title	string | null	Marketing title; null when invalid
wager_multiplier	decimal | null	Wagering requirement multiplier; null when invalid
no_of_chunks	integer | null	Number of release chunks; null when invalid

Validation never grants. There is no code-application endpoint — the grant itself is created internally when the configured release trigger event fires (deposit, registration, etc.). Show reason to the user when valid is false.

3. Consume a bonus chunk 🔐

Records that bonus was consumed against a wager event. Call this from the game server / PAM immediately after debiting the client wallet for a wager that draws from the user's bonus. The service auto-selects the user's next available released chunk — the client never picks chunks.

POST /api/v1/user-bonuses/consume

Request body application/json

{
  "user_id": "USER_001",
  "consume_txn_id": "TXN20250519001",
  "wager_amount": "300.00",
  "bonus_amount": "100.00",
  "chip_type": "cash",
  "wager_tnx_id": "WAGER_REF_001",
  "game_id": "GAME_ROULETTE_01",
  "round_id": "ROUND_999"
}

Field	Type	Required	Description
user_id	string	Yes	Platform user identifier (max 50 chars)
consume_txn_id	string	Yes	Idempotency key — unique per consumption event (max 50 chars)
wager_amount	decimal string	Yes	Total wager amount placed (≥ 0)
bonus_amount	decimal string	Yes	Bonus amount being consumed (≥ 0)
chip_type	string	Yes	cash or in_app_purchase
wager_tnx_id	string	Yes	Reference ID of the wager transaction (max 50 chars)
game_id	string | null	No	Game identifier (max 50 chars)
round_id	string | null	No	Game round identifier (max 50 chars)

Response 201 Created

{
  "txn_id": 88,
  "consume_txn_id": "TXN20250519001",
  "bonus_amount": "100.00",
  "consumed_amount": "100.00",
  "chip_type": "cash"
}

Idempotency: a retry with the same consume_txn_id returns 409 Conflict. Store consume_txn_id values on your side before calling so you can safely detect duplicates — treat a 409 for a known ID as "already recorded", not as an error to surface. 409 is also returned when no released chunk is available for the user — in that case the client wallet has drifted and the local debit must be reversed.

4. Revert a bonus consumption

Cancels a previously recorded consumption — e.g., when a wager is voided or rolled back. Decrements the user's consumed balance by the original amount. No auth header required — the consume_txn_id path parameter scopes the operation.

POST /api/v1/user-bonuses/consume/{consume_txn_id}/revert

Response 200 OK

{
  "txn_id": 88,
  "consume_txn_id": "TXN20250519001",
  "amount": "100.00",
  "chip_type": "cash"
}

Reverting an already-reverted consumption returns 409 Conflict.

5. Get user bonus summary 🔐

Bonus figures per chip type — Wynta's authoritative view, used for wallet drift checks and to power the wagering progress bar.

GET /api/v1/user-bonuses/{user_id}/summary

Response 200 OK

[
  {
    "chip_type": "cash",
    "bonus_balance": "600.00",
    "pending_bonus": "400.00",
    "wagering_required": "1200.00"
  },
  {
    "chip_type": "in_app_purchase",
    "bonus_balance": "200.00",
    "pending_bonus": "100.00",
    "wagering_required": "300.00"
  }
]

Field	Description
bonus_balance	Available bonus (total released minus total consumed)
pending_bonus	Total bonus amount in chunks not yet released
wagering_required	Remaining wager amount needed to release all pending chunks

6. List user transactions 🔐

Paginated flat ledger of bonus events, most recent first. Every event — grant, chunk release, consumption, expiry, or forfeit — is its own entry.

GET /api/v1/user-bonuses/{user_id}/transactions?chip_type=cash&limit=50&offset=0

Query parameter	Type	Required	Default	Description
chip_type	string	Yes	—	cash or in_app_purchase
limit	integer	No	50	Results per page (1–200)
offset	integer	No	0	Pagination offset (≥ 0)

Response 200 OK

[
  { "txn_id": 15, "bonus_code": "WELCOME100", "amount": "500.00", "type": "grant",     "created_at": "2025-05-19T08:00:00" },
  { "txn_id": 20, "bonus_code": null,         "amount": "166.67", "type": "released",  "created_at": "2025-05-19T09:00:00" },
  { "txn_id": 21, "bonus_code": null,         "amount": "166.67", "type": "consumed",  "created_at": "2025-05-19T10:15:00" },
  { "txn_id": 22, "bonus_code": null,         "amount": "166.67", "type": "expiry",    "created_at": "2025-05-20T08:00:00" },
  { "txn_id": 23, "bonus_code": null,         "amount": "166.67", "type": "forfeited", "created_at": "2025-05-21T11:00:00" }
]

type	Meaning
grant	Bonus was granted to the user (bonus_code populated for grants only)
released	A bonus chunk moved from pending to released
consumed	A released chunk was consumed against a wager
expiry	A chunk or bonus expired before being consumed
forfeited	The bonus was forfeited before full consumption

7. Get transaction detail 🔐

Full detail of a single bonus grant including all chunks, forfeit record (if any), and expiry events — the ground truth for disputes and reconciliation.

GET /api/v1/user-bonuses/{user_id}/transactions/{txn_id}

Response 200 OK

{
  "txn_id": 15,
  "user_id": "USER_001",
  "bonus_code": "WELCOME100",
  "wager_multiplier": "3.00",
  "no_of_chunks": 3,
  "chunk_expiry_days": 7,
  "bonus_expiry_days": 30,
  "wager_chip_type": "BONUS",
  "credit_chip_type": "CASH",
  "grant_amount": "500.00",
  "release_amount": "300.00",
  "bonus_consumed": "200.00",
  "status": "PARTIALLY_RELEASED",
  "created_at": "2025-05-01T08:00:00",
  "chunks": [
    {
      "id": 101,
      "chunk_ref": "CHUNK_001",
      "chunk_amount": "166.67",
      "wager_multiplier": "3.00",
      "status": "CONSUMED",
      "wager_amount": "500.00",
      "created_at": "2025-05-01T08:00:00",
      "updated_at": "2025-05-03T14:22:00"
    }
  ],
  "forfeit": null,
  "expiry_events": []
}

Grant-level fields: grant_amount (total granted), release_amount (total released), bonus_consumed (total consumed), derived lifecycle status (e.g. PARTIALLY_RELEASED), configuration snapshot (wager_multiplier, no_of_chunks, chunk_expiry_days, bonus_expiry_days, wager_chip_type, credit_chip_type).

Chunk object:

Field	Description
id / chunk_ref	Chunk record ID / human-readable reference
chunk_amount	Bonus amount in this chunk
wager_multiplier	Wagering multiplier for this chunk
status	PENDING, RELEASE, CONSUMED, or EXPIRED
wager_amount	Wagering progress toward release (per chunk)
created_at / updated_at	Creation / last status change timestamps

Forfeit object: id, amount, type (e.g. MANUAL, RULE_VIOLATION), operator (nullable), forfeited_at.

Expiry event object: id, chunk_id, amount, type (CHUNK_EXPIRY or BONUS_EXPIRY), operator (nullable, if manual), expired_at.

8. Get user referral code

GET /api/v1/user-bonuses/{user_id}/referral-code

Response 200 OK

{
  "user_id": "USER_001",
  "referral_code": "REF_XYZ99",
  "created_at": "2025-05-01T08:00:00"
}

created_at is when the referral code was generated (UTC). Returns 404 if no referral code exists for the user. No auth header required. The code is shared with friends and drives FRIEND_SIGNUP trigger eligibility.

Integration flow

1. User initiates a deposit / game round
       │
       ▼
2. GET /applicable-codes?user_id=&chip_type=
   → Display eligible bonus offers
       │
       ▼
3. User enters a code
   → POST /validate-code  { user_id, chip_type, code }
   → Check valid=true before proceeding; show reason to user if false
       │
       ▼
4. Release triggers fire (event-driven, internal)
   → Grant created; chunks move PENDING → RELEASE as the user meets
     trigger conditions and wagering progress accrues
       │
       ▼
5. User wagers using released bonus
   → PAM debits client wallet, then:
     POST /consume  { user_id, consume_txn_id, bonus_amount, wager_amount, wager_tnx_id, … }   🔐
       │
       ▼
6. If wager is voided:
   → POST /consume/{consume_txn_id}/revert
       │
       ▼
7. Display wallet / history:                                                                    🔐
     GET /{user_id}/summary
     GET /{user_id}/transactions?chip_type=cash
     GET /{user_id}/transactions/{txn_id}