Wynta Bonus

Version: 1.0 | Date: 13 July 2026

This documentation describes the integration between Wynta Bonus (the bonus engine) and the External PAM (the Player Account Management platform), covering the full bonus lifecycle, the chunk-based wager-release model, the API reference, and the webhook contract.

Split of responsibility

System	Role	Owns
Wynta Bonus	Bonus engine (server)	Bonus configuration (Head → Subhead → Configure → Promo Codes), eligibility, grant triggers, wagering progress, chunk release, consumption ledger, expiry/forfeit, budget enforcement
External PAM (Client)	External client system	Player accounts, gameplay/wager events, bonus code validation UX, and the player Bonus Wallet (Pending + Available buckets per chip type)

The PAM is the external client system: it maintains the player Bonus Wallet and updates it based on the wallet-update webhooks pushed by Wynta. Every lifecycle transition in Wynta (grant, chunk release, consume confirmation, expiry, forfeit) is delivered through a single wallet-update webhook, with a periodic reconciliation job as the safety net. Wynta is the system of record for bonus lifecycle; the PAM's wallet is the webhook-driven projection the player sees.

Systems and actors

Component	Role
Wynta Bonus	Bonus engine: promo-code configuration, eligibility, release triggers, chunk release, consumption ledger, expiry/forfeit, budget enforcement
External PAM (Client)	External client: player accounts, gameplay/wager events, Bonus Wallet maintenance and spend, event emission
Bonus Wallet (in PAM)	Per-player, per-chip-type balance with two buckets: Pending (granted, not yet playable) and Available (released, spendable)
Player	Validates promo codes, deposits, wagers, and spends bonus funds via the PAM

Two directions of truth:

• Wynta → PAM (webhooks): grant, release, expiry, forfeit, consume confirmation — the PAM applies these to its wallet.

• PAM → Wynta (API): bonus code validation, qualifying events, wager events, and consume notifications — on wager spend, the PAM consumes from its client wallet first, then notifies Wynta via the consume API.

High-level flow

Player            PAM (Client) — external client        Wynta Bonus
  │  browse promos  │                                   │
  │────────────────▶│  GET applicable codes             │
  │                 │──────────────────────────────────▶│
  │                 │◀────── codes + eligibility ───────│
  │  enter code     │                                   │
  │────────────────▶│  POST /validate-code              │
  │                 │──────────────────────────────────▶│  read-only check —
  │                 │◀── valid=true / reason ───────────│  nothing created
  │                 │                                   │
  │  deposit (etc.) │  events: deposit, registration, … │
  │────────────────▶│──────────────────────────────────▶│  RELEASE TRIGGER fires →
  │                 │◀──── webhook: BONUS_GRANTED ──────│  grant created, chunks
  |                 |                                   |
  │                 │  wallet: Pending += amount        │  PENDING (not spendable)
  │  wagers…        │  events: bet_placed, …            │
  │────────────────▶│──────────────────────────────────▶│  triggers + wager progress
  │                 │◀──── webhook: BONUS_RELEASED ─────│  chunk: PENDING → RELEASE
  │                 │  wallet: Pending → Available      │
  |                 |                                   |
  │  spend bonus    │                                   │
  │────────────────▶│  1. consume from client wallet    │
  │                 │     (Available -= amount)         │
  │                 │  2. notify consume (S2S)          │
  │                 │──────────────────────────────────▶│  ledger: consumed per chunk
  │                 │◀──── webhook: BONUS_CONSUMED ─────│  confirmation
  │                 │  reconcile vs resulting_balance   │
  |                 │        nightly reconciliation     │
  |                 │◀─────────────────────────────────▶│

Key concepts

• Client wallet, webhook-driven — the PAM maintains the Bonus Wallet; all credit-side changes (grant, release, expiry, forfeit) come exclusively from Wynta webhooks. The only PAM-initiated wallet change is the consume debit, which is immediately notified to Wynta and confirmed by webhook.

• Validation ≠ grant — POST /validate-code is a read-only eligibility check; there is no code-application endpoint. The grant is created by the release trigger event (deposit, registration, …) and the spendable value is delivered as triggers and wagering progress release chunks — see Bonus Events.

• Chip type — every balance and operation is scoped to a chip type: cash or in_app_purchase. The Bonus Wallet holds one Pending/Available bucket pair per chip type.

• Chunks — a granted bonus is split into no_of_chunks equal chunks; each chunk releases independently as the player's cumulative eligible wagering crosses its threshold. See Bonus Lifecycle & Chunk Model.

• Grant triggers — event-based rules (Wynta API name: release triggers) that award a bonus when a qualifying player event occurs (deposit, registration, bet_placed, …; event names are lowercase snake_case), resolved via promo code. Trigger types in configuration remain uppercase enums.

• Budgets — spend caps cascade from Head → Subhead → Configure with DAILY / WEEKLY / MONTHLY periods; a grant is never emitted if it would breach a cap.

Source note

Endpoints, request/response schemas, authentication, and event definitions are taken from the published Bonus Engine API documentation (docs.wynta.com/bonus-engine-api), supplemented by the admin configuration API surface. The PAM-facing wallet-update webhook contract remains a proposal pending sign-off and is marked as such.