Promo Code Sync, Validation & Bonus Grant

There is no code-application endpoint, and validation never grants. POST /validate-code is a read-only eligibility check. The bonus grant is created internally by Wynta when the configured release trigger event fires (deposit, registration, bet_placed, …) — see Bonus Events. The PAM learns of the grant via the BONUS_GRANTED webhook and updates its client wallet from it.

Flow 1 — Promo code sync (PAM → Wynta, pull)

Trigger: the PAM (external client) needs to display available offers — deposit screen, registration, lobby promotions page.

Endpoint: GET /api/v1/user-bonuses/applicable-codes?user_id=&chip_type=&display_on= (no auth header)

Returns active codes ordered by display_order, filtered to the requested display flow (display_on, default DEPOSIT, matched against each code's comma-separated display_on list), with presentation fields (display_title, banner_image_url, badge_text, cta_text, terms_url, …) plus mechanics the PAM can surface (wager_multiplier, no_of_chunks, applicability_frequency, max_amount, validity window). See the full endpoint reference.

Rules:

• Synchronous request/response. Do not cache beyond the current session — budgets, validity windows, and eligibility change server-side.

• Codes are filtered by validity window, active flag, min_display_amount, and the configure's eligibility criteria.

• Codes flagged system_auto_apply are never returned — the backend applies them automatically when a BONUS_RELEASE event fires; they are not for manual selection.

Flow 2 — Validate bonus code (PAM → Wynta)

Trigger: the player enters a bonus code in the PAM UI.

Endpoint: POST /api/v1/user-bonuses/validate-code with { "user_id", "chip_type", "code" } (no auth header)

1. The PAM validates before accepting the code.

2. Wynta returns valid with either the bonus preview (promo_id, display_title, wager_multiplier, no_of_chunks) or a human-readable reason when valid is false.

3. On success the PAM attaches the code to the player's flow (e.g., the deposit in progress) and can show the wagering terms up front; on failure it surfaces reason directly.

Validation is read-only — no grant, no wallet change, no webhook. A code that validates now can still fail at grant time (budget exhausted in the interim, frequency consumed on another device) — the grant-time evaluation is authoritative.

Flow 3 — Release trigger event → bonus grant (events → Wynta → PAM)

The grant is created by the event trigger, not by any API call from the code flow. When a qualifying PAM event arrives — deposit (with is_ftd for first-deposit rules), registration, tournament_won, friend_signup, … — Wynta evaluates it against the configured release triggers, resolved via the promo code:

1. Trigger match — event type, occurrence (e.g., 1 = first deposit only), min/max_trigger_amount, payment_method, product, trigger_config_json conditions

2. Eligibility criteria — all AND-ed rows must pass

3. Applicability frequency — EVERYTIME / ONCE / WEEKLY / MONTHLY per player

4. Budget caps — atomically checked at Configure → Subhead → Head levels

On approval, Wynta computes the grant amount (bonus_amount_fixed, or bonus_amount_percent of the event amount capped by bonus_amount_max), splits it into no_of_chunks chunks — all PENDING — writes the grant ledger entry, and emits the BONUS_GRANTED webhook. The PAM updates its client wallet from the webhook, incrementing Pending.

system_auto_apply codes are granted the same way without any player code entry.

Failure handling: if the trigger conditions, eligibility, frequency, or budget checks fail, no grant is created — no ledger entry, no webhook, no wallet change.

Flow 4 — Release delivers the spendable bonus

Chunks then move PENDING → RELEASE through further trigger events and wagering progress, each emitting BONUS_RELEASED and moving value Pending → Available in the client wallet — see Wager-Based Chunk Release.

Budget checks and the grant ledger write are atomic in Wynta — a cap breach can never leak a grant. The PAM's wallet is updated only by webhooks: BONUS_GRANTED for pending value, BONUS_RELEASED for spendable value.