Gestione promo e bonus a livello di backend

Testo completo dell'articolo

💡 18+. Materiale di ingegneria e pratica per piattaforme/operatori e provider. Non una chiamata al gioco. Per «portafoglio» si intende Ledger/Wallet con garanzie ACID, per «bonus» sono promozioni che influenzano l'equilibrio e le condizioni di gioco.

1) Perché portare il promo in un backend separato

Invarianti in denaro. Il bonus ≠ «accoppiato l'equilibrio» è un contratto con termini (vager, contributi giochi, massima scommessa/vincita).

Velocità di cambiamento. I team di marketing producono campagne quotidiane - serve un motore di dichiarazione delle regole e un ritorno.

Anti - abuse/compilation. KYC/RG/AML, velocity, segmentazione, taschi dei quattro occhi per offerenti costosi.

Osservazione e rendicontazione. SLO, costo promo, impatto GGR/NGR/LTV.

Il principio è che il nucleo promozionale è un servizio separato con le proprie macchine statuarie, e il denaro si muove solo attraverso il portafoglio, idipotenzialmente.

2) Tipologia di bonus e invarianti

Deposit match (100% prima di X) - Viene addebitato dopo la capture deposito, vager X x.

Cashback (perso-back) - Calcolato in base alla finestra del tempo/gioco, può essere sticky/no-sticky.

Free Spins/Free Bets: coupon/token con price per spin/tasso, pool RTP fisso.

Missioni/missioni, lavoro, progresso, premio.

Tornei/voli-iventi: contributo eventi, classifica, premi.

Invarianti:

Sticky - Non può essere visualizzato prima che vengano soddisfatte le condizioni.
Max bet/Max win: limiti di puntata/pagamento con bonus.
Contribuisci ai giochi (ad esempio, slots = 100%, live = 10%).
Expiry: la scadenza del bonus e della finestra del vager.

3) Architettura del servizio bonus


Applin (campagne/regole) ─Promo API ─Rules Engine/Elisibility
│
├─Bonus Ledger (stato offshore)
├─Wagering Engine (progresso)
├─Anti -Abuse (limiti/frod/velocity)
└─Outbox (events) ─Kafka/Pulsar ─BI/DWH/CRM

Wallet/Ledger── Idempotent Commands ───┘

Rule Engine - Condizioni dichiarative (segmenti, geo/licenza, canali, KYC/RG).

Wagering Engine - conta il contributo dì bet. settled`/`wallet. debit	credit`.
Bonus Ledger è una fonte di verità per gli stati di bonus/missioni.
Outbox/CDC è una pubblicazione affidabile del bonus. issued	progress. updated

4) Modello di dati (semplificato)

`bonus_grant`

`grant_id, player_id, offer_id, type, currency, amount_minor, sticky, wager_x, max_bet_minor, max_win_minor, contribution_schema_id, status (issued	active	paused	completed	expired	revoked), issued_at, expires_at, brand_id, region, idempotency_key`

`wager_progress`

`grant_id, required_minor, contributed_minor, remaining_minor, last_update_at`

`contribution_schema`

`schema_id, rules: [{game_type:"slot", pct:100},{game_type:"live", pct:10}]`

«bonus _ ledger _ entry» (controllo)

`entry_id, grant_id, action (issue	consume	revoke	expire	adjust), amount_minor, reason, occurred_at, trace_id`

5) Macchine statuarie e saghe

5. 1 Estrazione (issue) - saga

1. eligibility. check (segmento, RG/KYC, velocity)

2. grant. create (status=`issued`)

3. wallet. credit [bonus] (idipotente; sticky - in bilanci secondari bonus)

4. activate (status=`active`)

5. emit `bonus. issued`

Rollback, in caso di caduta al 3 passo →. cancel' + evento 'bonus. revoked`.

5. 2 Progresso del wager

Su 'bet. settled'conta il contributo = 'stake _ minor content _ pct' (o secondo le regole win/loss).

Aggiorna «wager _ progress» nell'atomaro; al 100% - «complete».

5. 3 Completamento (consume)

complete → `wallet. convert _ bonus _ to _ cash '(se non-sticky) o l'eliminazione dei vincoli di output.

emit `bonus. consumed`.

5. 4 Decadenza/recensione

Per «expires _ at» o regola del frodo «revoke» (idepotente), è possibile compensare secondo la politica.

6) Contratti con portafogli (solo tramite API, sempre Idempotico)

Accantonare il bonus


POST /v1/wallet/credit
Headers: X-Idempotency-Key: bonus_grant_123
{
"player_id":"p_001",  "amount":{"minor_units":100000,"currency":"EUR"},  "balance_type":"bonus",  "reference":{"grant_id":"gr_123","offer_id":"of_777"}
}
→ 200 {"status":"credited","entry_id":"e_9001"}

Conversione in cache una volta soddisfatte le condizioni


POST /v1/wallet/convert
Headers: X-Idempotency-Key: bonus_convert_gr_123
{
"player_id":"p_001",  "from_balance":"bonus",  "to_balance":"cash",  "amount_minor":100000,  "reference":{"grant_id":"gr_123"}
}
→ 200 {"status":"converted","entry_id":"e_9010"}

Controllo max bet/max win - Lato RGS/Wallet Guard:

richiesta dì bets. authorize'rifiutato dal code'BONUS _ MAX _ BET _ EXCEEDED '.

7) API del servizio promo (riferimento)

Crea offshore (Admin)


POST /v1/offers
{
"name":"Welcome 100% up to 100€",  "type":"deposit_match",  "params":{"match_pct":100,"cap_minor":10000,"wager_x":20,"sticky":true,       "max_bet_minor":200,"max_win_minor":50000,"contribution_schema_id":"c_slot100_live10"},  "eligibility":{"brands":["A"],"regions":["EU"],"segment":"new_depositors"},  "schedule":{"start":"2025-10-20T00:00:00Z","end":"2025-11-30T23:59:59Z"}
}
→ 201 {"offer_id":"of_777"}

Rilascia bonus (runtime)


POST /v1/bonus/grants
Headers: X-Idempotency-Key: grant_p001_of777
{
"player_id":"p_001","offer_id":"of_777","trigger":"deposit_captured","amount_minor":10000
}
→ 200 {"grant_id":"gr_123","status":"active"}

Progresso del wager (read)


GET /v1/bonus/grants/gr_123/progress
→ 200 {"required_minor":200000,"contributed_minor":45000,"remaining_minor":155000,"pct":0. 225}

Annulla/revoca


POST /v1/bonus/grants/gr_123/revoke
Headers: X-Idempotency-Key: revoke_gr_123
{ "reason":"fraud_velocity" }
→ 200 {"status":"revoked"}

Tutte le chiamate write sono con X-Idempotency-Key e X-Trace-Id.

8) Anti-abuse e compilazione

Limiti Velocity: erogazioni/conversioni/tentativi di deposito (Redis counters + TTL + Lua).

Un deposito per un grant per regola.

Segmentazione e RG: escludi self-ecluded/limited; per brand/region licenza.

Blocco di conflitto offshore: un solo premio welcome è attivo contemporaneamente; Priorità.

Rilevatore di anomalie: account/dispositivi/ASN multipli, veloci «azzeramenti» del vager.

Quattro occhi per grandi borse di studio e aggiustamenti manuali.

Controllo WORM di tutte le modifiche a regole/borse di studio/conversioni.

9) Osservabilità, metriche e SLO

SLO (punti di riferimento):

`grant. issue p95` (issue→credited) ≤ 300–500 мс.
Aggiornamento dì wager _ progress p95 "da 200 ms dì bet. settled`.
Gli eventi del bonus sono nel p95.
«Borse di studio/conversioni perdute/duplicate» = 0.

Metriche:

Rate/latency по `issue/convert/revoke`, error-rate (business/4xx/5xx), `IDEMPOTENCY_MISMATCH`.
Conversione vager, media time-to-complete, percentuale scaduta.
Costo promo: «promo _ cost» (minore) e «promo _ roi» sulle coorti.
Anti-Abuse: attivazioni velocity rifiutate da max bet/win.

Tracising, la catena dì trigger «grant» wallet. credit → progress. update → convert`.

10) Integrazione con RGS/giochi

Coupon Free Spins/Free Bets - Tramite «entitlements» API: rilascio di token, riscossione, telemetria di utilizzo.

Max bet/win - regole in'bets. authorize` и `bets. settle`; restituire i codici'BONUS _ RULE _ VIE '.

Content - schema a "bet. settled '(in «game _ type/provider _ id»), versione degli schemi.

11) DWH/BI e rapporti

Outbox eventi Lake (bronze) Silver ( , SCD2) vetrina Gold:

`fact_bonus_grants`, `fact_wager_progress`, `fact_bonus_cost`, `fact_promo_roi`.
SLA freschezza: Silver 15 min, Gold 30-60 min.
Pannelli: conversione per off/segmenti, time-to-complete, contributo giochi, abuse-incidenti.

12) Sicurezza e residenza

mTLS + OAuth2 CC; scope’ы `promo:issue`, `promo:convert`, `promo:revoke`.

Chiavi/token - per brand/region, di breve durata; segreti in Vault/HSM.

Isolamento PII: 'player _ id' - Alias; RLS по `brand/region`.

Rate limits e quote di emissione; Protezione contro le tempeste retraiche.

13) Assegno fogli

Piattaforma/operatore

Tutte le transazioni sono via Wallet con'Idempotency-Key '.
Rule/Elegibilità sono versionati; «doppia lettera» di eventi sulle migrazioni.
Gli schemi di Content sono centralizzati, coperti da test.
Velocity e anti-frod inclusi; Quattro occhi su grandi somme.
Outbox/CDC, DLQ e replay gestito per «bonus.».
SLO-dashboard, , WORM.
Vetrine DWH per il RE e la compilazione (RG/AML).

Integrazioni (RGS/portafoglio/CRM)

Controllo max bet/win; restituisce il codice di errore aziendale.
Sgancio «trace _ id» e «idempotency _ key».
Deduplicazione dei trigger e garanzia di consegna (webhooks firmati).

14) Bandiere rosse (anti-pattern)

Incassi il bonus manualmente in bilico, passando da Wallet.

La mancanza di idampotenza ha → doppie sovvenzioni/conversioni.

Vager è considerato «bet». piazzed ', non a seguito dì bet. settled`.

Nessun schema di contribute o «cucito» nel codice dei provider.

Gli offer in conflitto vengono attivati contemporaneamente.

Nessuna velocity/anti-frod o controllo WORM.

Gli eventi bonus sono pubblicati oltre l'outbox/CDC.

Gli indicatori promo non corrispondono a Ledger/BI (nessuna vetrina REI).

15) Totale

I buoni backend promozionali sono contratti e invarianti, non «aumentare il saldo». Separa le regole dal denaro, considera il progresso degli esiti effettivi, garantisce idipotenza e osservabilità, protegge dall'abete e fornisce la compliance. Con questo core il marketing si muove rapidamente, il giocatore vede le condizioni oneste e la finanza e i regolatori ottengono un quadro preciso del costo e dell'effetto di ogni offer.