Verwaltung von Promo und Boni auf Backend-Ebene

Vollständiger Artikel

💡 18+. Ingenieur- und Praxismaterial für Plattformen/Betreiber und Anbieter. Kein Aufruf zum Spiel. Unter „Geldbörse“ verstehen wir Ledger/Wallet mit ACID-Garantien, unter „Boni“ - Promoofer, die das Gleichgewicht und die Spielbedingungen beeinflussen.

1) Warum Promo in ein separates Backend nehmen

Geld-Invarianten. Bonus ≠ „balanciert“: Dies ist ein Vertrag mit Bedingungen (Lieferung, Einzahlung für Spiele, maximaler Einsatz/Gewinn).

Die Geschwindigkeit der Veränderung. Marketing-Teams veröffentlichen Kampagnen täglich - Sie brauchen eine deklarative Regel-Engine und einen Rollback.

Anti-Missbrauch/Compliance. KYC/RG/AML, Velocity, Segmentierung, Vier-Augen-Tasks für teure Offices.

Beobachtung und Berichterstattung. SLO, Werbekosten, Auswirkungen auf GGR/NGR/LTV.

Das Prinzip: Der Promo-Kern ist ein eigener Service mit eigenen Statusmaschinen, und das Geld bewegt sich nur über die Geldbörse, idempotent.

2) Bonustypologie und Invarianten

Deposit Match (100% bis X): Wird nach der Capture Deposit, Forward X × gutgeschrieben.

Cashback: Berechnet nach Zeitfenster/Spielen, kann sticky/non-sticky sein.

Free Spins/Free Bets: Coupons/Token mit einem Preis pro Spin/Wette, einem festen RTP-Pool.

Quests/Missionen: Aufgabe → Fortschritt → Belohnung.

Turniere/Flugevents: Veranstaltungsbeitrag, Rangliste, Preisgeld.

Invarianten:

Sticky: kann nicht ausgegeben werden, bevor die Bedingungen erfüllt sind.
Max bet/Max win: Einsatz-/Auszahlungslimits aus Bonusmitteln.
Beitrag: Beitrag pro Spiel (z.B. Slots = 100%, live = 10%).
Expiry: Gültigkeitsdauer des Bonus und des Vager-Fensters.

3) Bonus-Service-Architektur


Admin (Kampagnen/Regeln) ─Promo API ─Rules Engine/Eligibility
│
├─Bonus Ledger (Stand der Offices)
├─Wagering Engine (Fortschritt)
├─Anti -Abuse (Limits/Betrug/Velocity)
└─Outbox (events) ─Kafka/Pulsar ─BI/DWH/CRM

Wallet/Ledger── Idempotent Commands ───┘

Rules Engine - deklarative Bedingungen (Segmente, Geo/Lizenz, Kanäle, KYC/RG).

Wagering Engine - zählt den Beitrag von 'bet. settled`/`wallet. debit	credit`.
Bonus Ledger ist die Quelle der Wahrheit über Bonus-/Missionszustände.
Outbox/CDC - zuverlässige Veröffentlichung 'Bonus. issued	progress. updated

4) Datenmodell (vereinfacht)

`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“ (Prüfung)

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

5) Statusmaschinen und Sagas

5. 1 Ausgabe (Ausgabe) - Saga

1. eligibility. check (Segment, RG/KYC, Velocity)

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

3. wallet. credit [bonus] (idempotent; bei Sticky - im Bonusuntersaldo)

4. activate (status=`active`)

5. emit `bonus. issued`

Rollback: Bei einem Sturz in Schritt 3 → 'grant. cancel'+ event 'bonus. revoked`.

5. 2 Fortschritt der Weiger

Na 'bet. settled 'zählen Beitrag =' stake _ minor contribution_pct' (oder nach win/loss Regeln).

'wager _ progress' atomar aktualisieren; bei Erreichen von 100% „vollständig“.

5. 3 Fertigstellung (Consume)

complete → `wallet. convert_bonus_to_cash' (wenn nicht sticky) oder Aufhebung der Ausgabebeschränkungen.

emit `bonus. consumed`.

5. 4 Ablauf/Widerruf

Nach „expires _ at“ oder der Regel des Betrugs → „revoke“ (idempotent) ist eine Kompensation nach der Politik möglich.

6) Wallet-Verträge (nur über API, immer idempotent)

Bonus berechnen


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"}

Konvertierung in Cache nach Erfüllung der Bedingungen


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"}

Überprüfung max bet/max win - auf der RGS/Wallet Guard Seite:

Anfrage' bets. authorize "wird durch den Code" BONUS _ MAX _ BET _ EXCEEDED "abgelehnt.

7) Promo-Service-API (Benchmarks)

Erstellen eines Offers (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"}

Geben Sie einen Bonus (Laufzeit)


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"}

Weiger-Fortschritt (lesen)


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

Stornieren/widerrufen


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

Alle write-calls sind mit 'X-Idempotency-Key' und 'X-Trace-Id'.

8) Anti-Missbrauch und Compliance

Velocity die Limits: der Ausgaben/Konversionen/Versuche des Depositums (Redis counters + TTL + Lua).

Dedup-Trigger: eine Einzahlung → ein Zuschuss nach der Regel.

Segmentierung und RG: Self-Excluded/Limit ausschließen; per Marke/Region Lizenzen.

Konfliktblock von Offizieren: Nur ein Willkommensbonus ist gleichzeitig aktiv; Prioritäten.

Anomaliedetektor: mehrere Konten/Geräte/ASN, schnelle „Nullen“ des Verteilers.

„Vier Augen“ für große Zuschüsse und manuelle Anpassungen.

WORM-Audit aller Regeländerungen/Zuschüsse/Umbauten.

9) Beobachtbarkeit, Metriken und SLO

SLO (Benchmarks):

`grant. issue p95` (issue→credited) ≤ 300–500 мс.
Die Aktualisierung von 'wager _ progress p95' ≤ 200 ms seit 'bet. settled`.
Die Ereignisse „Bonus“ im Bus p95 ≤ 2 Minuten von dem, was passiert ist.
„Verlorene/doppelte Zuschüsse/Umwandlungen“ = 0.

Metriken:

Rate/latency по `issue/convert/revoke`, error-rate (business/4xx/5xx), `IDEMPOTENCY_MISMATCH`.
Vager-Konvertierung, Durchschnitt 'Zeit-zu-vervollständigen', Anteil überfällig.
Promo-Kosten: 'promo _ cost' (minor) und 'promo _ roi' auf Kohorten.
Anti-Missbrauch: Velocity-Trigger, abgelehnt von max bet/win.

Tracing: OpenTelemetry entlang der Kette' trigger → grant → wallet. credit → progress. update → convert`.

10) Integration mit RGS/Spiele

Free Spins/Free Bets Coupons - durch 'entitlements' API: Ausgabe von Token, Abschreibung in Rantayme, Telemetrie durch Nutzung.

Max bet/win - Regeln in 'bets. authorize` и `bets. settle`; die Codes' BONUS _ RULE _ VIOLATION 'zurückgeben.

Beitrag - Schema auf der Ebene' bet. settled'(von 'game _ type/provider _ id'), eine Version der Schemas.

11) DWH/BI und Berichte

Outbox Veranstaltungen → Lake (Bronze) → Silber (Dedup, SCD2) → Gold Vitrinen:

`fact_bonus_grants`, `fact_wager_progress`, `fact_bonus_cost`, `fact_promo_roi`.
SLA Frische: Silber ≤ 15 min, Gold ≤ 30-60 min.
Panels: Konvertierung nach Anbietern/Segmenten, Time-to-complete, Beiträge nach Spielen, Missbrauchsfälle.

12) Sicherheit und Wohnsitz

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

Schlüssel/Token - pro Marke/Region, kurz lebend; Geheimnisse in Vault/HSM.

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

Preisobergrenzen und Emissionsquoten; Schutz vor Sturm-Retrays.

13) Checklisten

Plattform/Betreiber

Alle Geldtransaktionen laufen über Wallet mit 'Idempotency-Key'.
Rules/Eligibility werden versioniert; „Doppeltes Schreiben“ von Ereignissen auf Wanderungen.
Beitragsdiagramme werden zentralisiert, durch Tests abgedeckt.
Velocity und Anti-Betrug enthalten; „Vier Augen“ für große Summen.
Outbox/CDC, DLQ und Managed Replay für „Bonus“.
SLO-Dashboards, OpenTelemetry, WORM-Audit.
DWH-Vitrinen für ROI und Compliance (RG/AML).

Integrationen (RGS/Wallet/CRM)

Ich überprüfe max bet/win; Ich gebe den Geschäftsfehlercode zurück.
Ich schieße' trace _ id 'und' idempotency _ key'.
Dedup-Trigger und Liefergarantien (Webhooks signiert).

14) Rote Fahnen (Anti-Muster)

Sammeln Sie den Bonus „manuell“ direkt in Ihr Guthaben und umgehen Sie Wallet.

Keine Idempotenz → doppelte Zuschüsse/Konversionen.

Vager zählt nach 'bet. placed', nicht nach den Ergebnissen von 'bet. settled`.

Es gibt keine Beitragsschemata oder sie sind im Code der Anbieter „verkabelt“.

Kollidierende Offs werden gleichzeitig aktiviert.

Kein Velocity/Anti-Fraud und WORM Audit.

„Bonus“ -Ereignisse werden unter Umgehung der Outbox/CDC veröffentlicht.

Die Promo-Zahlen stimmen nicht mit Ledger/BI überein (keine ROI-Schaufenster).

15) Das Ergebnis

Ein zuverlässiges Backend-Promo sind Verträge und Invarianten, nicht „Balance hinzufügen“. Sie trennt Regeln vom Geld, zählt Fortschritte zu tatsächlichen Ergebnissen, garantiert Idempotenz und Beobachtbarkeit, schützt vor Missbrauch und sorgt für Compliance. Mit einem solchen Kern bewegt sich das Marketing schnell, der Spieler sieht faire Bedingungen und die Finanzen und Aufsichtsbehörden erhalten ein genaues Bild von den Kosten und Auswirkungen jedes Offers.