Zarządzanie promocjami i bonusami na poziomie backendu

Pełny artykuł

💡 18+. Materiały inżynieryjne i praktyczne dla platform/operatorów i dostawców. Ani telefonu do zabawy. Przez „portfel” rozumiemy Ledger/Portfel z gwarancjami ACID, przez „bonusy” - promotorów, które wpływają na równowagę i warunki gry.

1) Dlaczego wziąć promo do oddzielnego backendu

Monetarne niezmienne. Bonus „saldo dodane”: jest to umowa z warunkami (vager, wkład do gier, maksymalny zakład/wygrana).

Tempo zmian. Zespoły marketingowe codziennie wypuszczają kampanie - potrzebujesz deklaratywnych zasad silnika i rolki.

Przeciwdziałanie nadużyciom/zgodność. KYC/RG/AML, prędkość, segmentacja, zadania czterokołowe dla drogich ofert.

Obserwowalność i sprawozdawczość. SLO, koszty promocyjne, wpływ na GGR/NGR/LTV.

Zasada: rdzeń promocyjny jest osobną usługą z własnym statusem maszyn, a pieniądze przenoszą się tylko przez portfel, idempotently.

2) Typologia bonusowa i niezmienne

Mecz depozytowy (100% przed X): naliczony po złapaniu depozytu, vager X ×.

Cashback: obliczany przez okno/gry czasowe, może być lepki/nie lepki.

Darmowe spiny/darmowe zakłady: kupony/żetony z ceną za spin/zakład, stała pula RTP.

Zadania/misje: zadanie → postęp → nagroda.

Turnieje/imprezy lotnicze: wkład imprez, ocena, nagroda pieniężna.

Niezmienne:

Lepki: nie można wyjść do czasu spełnienia warunków.
Max bet/Max wygrywa: limity zakładu/wypłaty z funduszy bonusowych.
Wkład: wkład według gry (np. sloty = 100%, żywe = 10%).
Wygaśnięcie: Okres ważności bonusu i okno wahadłowe.

3) Architektura usług bonusowych


Administrator  Promo  Zasady Silnik API/Kwalifikowalność
│
 Bonus Ledger (status ofert)
  Silnik zakładów (postęp)
W przedmiocie przeciwdziałania nadużyciom (ograniczenia/oszustwa/prędkość)
 (zdarzenia)  Kafka/Pulsar, BI/DWH/CRM

Portfel/Księga ───┘

Zasady Silnik - warunki deklaracyjne (segmenty, geo/licencja, kanały, KYC/RG).

Silnik zakładów - liczy składki z portfela "bet. settled "/". debet	kredyt ".
Bonus Ledger jest źródłem prawdy o stanach bonusowych/misyjnych.
Outbox/CDC - niezawodny bonus publikacji. wydane	postęp. zaktualizowany

4) Model danych (uproszczony)

„bonus _ grant”

"grant _ id, player_id, offer_id, rodzaj, waluta, amount_minor, lepki, wager_x, max_bet_minor, max_win_minor, contribution_schema_id, status (wydany	aktywny	pauza	zakończone	wygasła	cofnięte), 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, zasady: [{gra _ type:” slot „, pct: 100}, {game _ type:” live „, pct: 10}]”

„bonus _ ledger _ entry” (audyt)

"entry _ id, grant_id, działanie (wydanie	spożywać	cofnij	wygasają	dostosować), amount_minor, powód, occurred_at, trace_id'

5) Maszyny stanu i sagi

5. 1 Wydanie - Saga

1. kwalifikowalność. sprawdzenie (segment, RG/KYC, prędkość)

2. dotacja. create (status = 'wydany')

3. portfel. kredyt [bonus] (idempotent; przy lepkim - do premii subbalansu)

4. aktywować (status = 'aktywny')

5. Wyemituj premię. wydane "

Rollback: podczas spadania na krok 3 → "grant. anulować bonus '+ event'. odwołane ".

5. 2 Vager postęp

Na 'bet. settled 'count contribution =' stake _ minor contribution_pct' (lub zgodnie z zasadami wygranej/straty).

Aktualizacja 'wager _ progress' pod względem atomowym; po osiągnięciu 100% - „kompletne”.

5. 3 Wykończenie (spożywać)

kompletny → 'portfel. convert_bonus_to_cash' (jeśli nie jest lepki) lub usunąć ograniczenia wyjściowe.

Wyemituj premię. spożywane ".

5. 4 Wygaśnięcie/wycofanie

Przez 'expires _ at' lub zasada oszustwa → 'cofnij' (idempotent), odszkodowanie według polityki jest możliwe.

6) Umowy torebkowe (tylko za pośrednictwem API, zawsze idempotent)

Bonus akcyzy


POST/v1/portfel/kredyt
Nagłówki: X-Idempotency-Key: bonus_grant_123
{
„player_id":"p_001,” „kwota”: {„minor _ units”: 100000, „currency”: „EUR”}, „balance_type":"bonus,” „reference”: {„grant _ id':” gr _ 123 „,” offer _ id': „of _ 777”}
}
→ 200 {"status": "credited", "entry _ id':" e _ 9001 "}

Konwersja do pamięci podręcznej po spełnieniu warunków


POST/v1/portfel/convert
Nagłówki: X-Idempotency-Key: bonus_convert_gr_123
{
„player_id":"p_001,” „from_balance":"bonus,” „to_balance":"cash,” „amount_minor":100000”, odniesienie „: {” grant _ id': „gr _ 123”}
}
→ 200 {"status": "konwersja", "entry _ id':" e _ 9010 "}

Sprawdź maksymalny zakład/maksymalną wygraną - po stronie RGS/Wallet Guard:

zakłady na żądanie. autoryzacja "jest odrzucona kodem 'BONUS _ MAX _ BET _ EXCEEDED'.

7) API usługi promocyjnej (szablony)

Utwórz ofertę (admin)


POST/v1/oferty
{
„nazwa”: „Welcome 100% up to 100 €”, „type”: „deposit _ match”, „params': {” match _ pct „: 100,” cap _ minor „: 10000,” wager _ x „: 20,” lepki „: true,” max_bet_minor":200,"max_win_minor":50000,"contribution_schema_id":"c_slot100_live10"} „, eligibility”: {„marki”: [„A”], „regiony”: [„EU”], „segment”: „new _ depositors”}, „schedule”: {„start”: „2025-10-20T00: 00: 00Z”, „end”: „2025-11-30T23: 59: 59Z”}
}
→ 201 {"offer _ id':" of _ 777 "}

Wystawić bonus (czas trwania)


POST/v1/premia/dotacje
Nagłówki: 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 ":" aktywny "}

Postęp zakładów (czytaj)


GET/ v1/bonus/grants/gr_123/progress
→ 200 {„required _ minor „: 200000, „contributed _ minor”: 45000,” remaining _ minor”: 155000,” pct”: 0. 225}

Nieważność/cofnięcie


POST/ v1/bonus/grants/gr_123/revoke
Nagłówki: X-Idempotency-Key: revoke_gr_123
{„powód „: „oszustwo _ prędkość”}
→ 200 {„status „:” odwołany”}

Wszystkie połączenia pisane są z 'X-Idempotence-Key' i 'X-Trace-Id'.

8) Przeciwdziałanie nadużyciom i zgodność

Limity prędkości: emisje/konwersje/próby wpłat (liczniki Redis + TTL + Lua).

Trigger dedup: jeden depozyt → jedna dotacja według reguły.

segmentacja i RG: wykluczyć samodzielne wyłączenie/limit; na licencję marki/regionu.

Blok konfliktu ofert: tylko jeden bonus powitalny jest aktywny na raz; priorytety.

Wykrywacz anomalii: wiele kont/urządzeń/ASN, szybkie „zerowanie” pochwy.

„Cztery oczy” na duże dotacje i ręczne korekty.

Audyt WORM wszystkich zmian reguł/dotacji/konwersji.

9) Obserwowalność, mierniki i SLO

SLO (punkty orientacyjne):

"uczciwy. emisja p95 '(emisja → przypisana) ≤ 300-500 М.
Aktualizacja 'wager _ progress p95' ≤ 200ms od 'bet. settled'.
Premia za wydarzenia. 'W autobusie p95 ≤ 2 minuty od tego, co się stało.
„Stracone/powielone dotacje/konwersje” = 0.

Metryka:

Szybkość/latencja „issue/convert/revoke”, wskaźnik błędów (business/4xx/5xx), „IDEMPOTENCY _ MISMATCH”.
Konwersja wahadłowa, średni „czas do końca”, odsetek zaległy.
Koszt promo: 'promo _ cost' (minor) i 'promo _ roi' na kohortach.
Anty-nadużycie: wyzwalacze prędkości odrzucone przez maksymalny zakład/wygraną.

Śledzenie: OpenTelemetry na łańcuchu 'trigger → grant → portfel. kredyt → postęp. aktualizacja → konwersja '.

10) Integracja z RGS/gry

Darmowe spiny/darmowe kupony na zakłady - poprzez 'entitlements' API: wydawanie żetonów, złomowanie w czasie trwania, telemetria przy użyciu.

Max bet/win - zasady w zakładach. autoryzować zakłady typu „а”. rozliczenie "; kody zwrotne „BONUS _ RULE _ VIOLATION”.

Wkład - system na poziomie zakładu. settled '(przez' game _ type/provider _ id'), schemat version.

11) DWH/BI i sprawozdania

Wydarzenia na wystawie → Jezioro (brąz) → Srebro (dedup, SCD2) → Prezentacje złota:

'fact _ bonus _ grants', 'fact _ wager _ progress', 'fact _ bonus _ cost', 'fact _ promo _ roi'.
Świeżość SLA: srebro ≤ 15 min, złoto ≤ 30-60 min.
Panele: konwersja według ofert/segmentów, czas do końca, wkład gier, przypadki nadużyć.

12) Bezpieczeństwo i pobyt

mTLS + OAuth2 CC; zakres '' promo: issue ',' promo: convert', 'promo: cofnij'.

Klucze/żetony - dla każdej marki/regionu, krótkotrwały; sekrety w skarbcu/HSM.

Izolacja PII: 'player _ id' - alias; RLS - „marka/region”.

limity stóp procentowych i kwoty emisji; ochrona przed burzami retreacyjnymi.

13) Listy kontrolne

Platforma/Operator

Wszystkie transakcje pieniężne przechodzą przez portfel z 'Idempotency-Key'.
Zasady/Kwalifikacje są zmieniane; „podwójna litera” wydarzeń dotyczących migracji.
Programy składek są scentralizowane, objęte testami.
Umożliwiła szybkość i zwalczanie nadużyć finansowych; „cztery oczy” na dużych sumach.
Outbox/CDC, DLQ i managed replay for 'bonus. '.
Deski rozdzielcze SLO, OpenTelemetry, audyt WORM.
Sklepy DWH dla ROI i zgodności (RG/AML).

Integracje (RGS/portfel/CRM)

Sprawdzanie maksymalnego zakładu/wygranej; zwrócenie kodu błędu firmy.
Rzucam 'trace _ id' i' idempotence _ key '.
Triggery deadup i gwarancje dostawy (podpisane haki internetowe).

14) Czerwone flagi (anty-wzory)

Ładowanie bonusu „ręcznie” bezpośrednio do salda, omijając portfel.

Brak idempotencji → podwójne dotacje/konwersje.

Zakład jest rozpatrywany przez „bet. placed”, a nie zgodnie z wynikami „bet. settled”.

W kodeksie dostawców nie istnieją systemy składek lub są one „chronione”.

Sprzeczne oferty są aktywowane jednocześnie.

Nie ma szybkości/zwalczania oszustw i audytu WORM.

'bonus. "wydarzenia są umieszczane omijając zewnętrzne/CDC.

Mierniki promo nie dodają się do Ledger/BI (brak prezentacji ROI).

15) Najważniejsze

Niezawodne promocje backend są kontrakty i niezmienne, a nie "dodać równowagę. "Oddziela przepisy od pieniędzy, uwzględnia postępy w zależności od rzeczywistych wyników, gwarantuje wrażliwość i obserwowalność, chroni przed nadużyciami i zapewnia zgodność. Dzięki takiemu rdzeniu marketing szybko się porusza, gracz widzi uczciwe warunki, a finanse i regulatorzy otrzymują dokładny obraz kosztów i efektów każdej oferty.