> 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.md).

# 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](/bonus/api-reference/bonus-events.md).
* **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](/bonus/architecture/lifecycle-and-chunks.md).
* **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

{% hint style="info" %}
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.
{% endhint %}