Prize Drops

🎁 Description

Commands createPrizeDrop, listPrizeDrops, setPrizeDropStatus and prizeDropWinners – run Prize Drop promotions on eligible games directly through the API, without an admin panel.

A prize drop is a timed promotion on a game: while the promotion runs, every qualifying real-money round (bet at or above the promotion's minbet, player at or above min_viplvl, playing in the promotion's currency) can also win a cash prize from a limited pool. Prizes are defined in up to 3 tiers, each with a fixed amount, a count of prizes available, and odds (an integer N = a 1-in-N chance per qualifying round, while prizes remain in the tier).

A won prize is credited through your wallet with the transaction reference TPD{promo_id}.

Every promotion belongs to the operator whose credential signs the request: all reads and changes are scoped to your API account, and a promo_id that belongs to another operator answers ERROR Prize drop not found.

Eligible games: check command 24 (Get List Of Available Games) – a game that can carry a prize drop has "has_prize_drops": 1.

Wheel promotions: there is no wheel command and none is needed — on this engine a wheel promotion is a prize-drops campaign whose drop is revealed on a wheel; the wheel is the game's own presentation of the win. createPrizeDrop is the only call.

How the win is shown. The prize drop is shown by the game client when the win is credited to the player. Every game shows it as an in-game message; a wheel reveal is a presentation of the game client and will be announced per game when it ships. The API carries the same data for every game (the win amount, the tier, the promo id) through prizeDropWinners.

➕ createPrizeDrop

Creates one prize-drop promotion per game id you pass (all with the same name, window, tiers and conditions). The call is idempotent through uniqid: resending the same uniqid returns the original promo_ids (message "Prize drop already created (idempotent)") and never creates duplicates.

📜 Sample JSON Request (from your server to the RGS-CWS server)

{ "command": "createPrizeDrop", "name": "Weekend Rain", "currency": "EUR", "fdate": "2026-11-01", "tdate": "2026-11-30", "minbet": 1.00, "min_viplvl": 0, "max_prizes_per_player": 3, "tiers": [ { "amount": 500.00, "count": 2, "odds": 2000000 }, { "amount": 50.00, "count": 20, "odds": 200000 }, { "amount": 5.00, "count": 200, "odds": 20000 } ], "gameids": "6857,6858", "apiusername": "your_api_username", "apipass": "your_api_password", "uniqid": "pd_weekend_rain_2026_11" }

📥 Input Parameters (from your server to the RGS-CWS server)

Parameter	Mandatory	Description	Type
*command	✅	Must be "createPrizeDrop"	string
*name	✅	Promotion name (1–128 chars).	string
*currency	✅	The ISO / platform currency code of the drop (for example EUR, USD, GC, SC). The drop is fed only to players who play the game in that exact currency; prize amounts and minbet are in that currency, never converted. A missing or unknown code is refused with an ERROR.	string
fdate	❌	Promotion start. Format Y-m-d or Y-m-d H:i:s. Defaults to now. Times are GMT.	string
*tdate	✅	Promotion end. Must be in the future and after fdate. Times are GMT.	string
minbet	❌	Minimum total bet a round needs to qualify (0 = any bet; at most 3 decimals). Default 0.	float
min_viplvl	❌	Minimum VIP level of the player. Default 0.	integer
max_prizes_per_player	❌	How many prizes one player may win in this promotion. Default 999999.	integer
*tiers	✅	List of 1–3 { "amount", "count", "odds" }, top prize first. amount > 0 (max 3 decimals), count 1–1000000, odds = integer ≥ 1 (a 1-in-N chance per qualifying round; optional, default 10000). Tiers are numbered from the bottom: the last tier you send is always tier 3, the one above it 2, the one above that 1. EG: one tier is returned as "tier":3; two tiers as 2 and 3.	array
*gameids	✅	CSV of 1–50 game ids. Each game must be active and support prize drops ("has_prize_drops": 1 in command 24). One promotion is created per game.	string
*apiusername	✅	Your API username	string
*apipass	✅	Your API password	string
*uniqid	✅	A unique identifier generated by you, one per create (1–190 chars). Makes the call idempotent: resending the same uniqid returns the original promotion ids instead of creating duplicates. (Unique per operator.)	string

📃 Sample JSON Response (returned by RGS-CWS)

{ "status": "OK", "message": "Prize drop created", "promo_ids": [311, 312], "pool": "3000.000", "pool_cap": "unlimited" }

promo_ids lists one promo_id per game, in the order of gameids. pool is the total prize money of one game's tier set (amount × count, summed); pool_cap names the configured maximum pool, or unlimited.

Resending the same uniqid returns { "status": "OK", "message": "Prize drop already created (idempotent)", "promo_ids": [...] } (no pool fields). Other errors: Unknown currency XXX (the code is not a currency we support) · A prize drop for this uniqid is already being processed (a concurrent call with the same uniqid; retry it) · Game N does not support Prize Drops (has_prize_drops=0) · currency is required (2-12 letters/digits).

Behaviour note: A second ACTIVE promotion with the same gameid, currency, minbet and min_viplvl is refused and the response names the existing promo_id (... already exists (promo_id N) - close it first or change the shape). Closed promotions never block a new one. Two prize drops of the same shape may be active on the same game at the same time when their currencies differ.

📋 listPrizeDrops

Lists the caller's prize-drop promotions. Every row belongs to the operator whose credential signs the request.

• status (optional): active | paused | closed.

• scope (optional): active (default) = the live promotions table · closed = the promotions already moved to the archive · all = both. A status=closed filter with no scope reads all. Every row carries archived (false live, true archived) and archived_at (null while live).

NOTE: this read also performs the housekeeping move: the caller's promotions that are closed, past their tdate, or have every tier exhausted are moved to the archive before the list is built (at most 50 per call; a promotion that still holds an unpaid prize is kept live until it is paid). Nothing a player can trigger depends on this move — a dead promotion never rolls either way.

Paging: limit (optional, 1-500, default 500) and before_id (optional, a promo_id) return the next page of older promotions; the reply carries limit and next_before_id (null on the last page). Errors: limit must be a whole number from 1 to 500 / before_id must be a promo_id (a whole number above 0) / Unknown currency <code>. A wrong filter answers ERROR status must be active, paused or closed / ERROR scope must be active, closed or all.

📜 Sample JSON Request (from your server to the RGS-CWS server)

{ "command": "listPrizeDrops", "status": "active", "scope": "active", "apiusername": "your_api_username", "apipass": "your_api_password" }

📥 Input Parameters (from your server to the RGS-CWS server)

Parameter	Mandatory	Description	Type
*command	✅	Must be "listPrizeDrops"	string
status	❌	(optional) active | paused | closed	string
scope	❌	(optional) active (default) | closed | all	string
currency	❌	(optional) A currency code; only drops in that currency are listed. Omit it to list every currency.	string
limit	❌	(optional) Page size, 1–500. Default 500.	integer
before_id	❌	(optional) A promo_id; returns the next page of older promotions.	integer
*apiusername	✅	Your API username	string
*apipass	✅	Your API password	string

📃 Sample JSON Response (returned by RGS-CWS)

{ "status": "OK", "message": "OK", "scope": "active", "limit": 500, "next_before_id": null, "prizedrops": [ { "promo_id": 311, "name": "Weekend Rain", "gameid": 6857, "currency": "EUR", "minbet": "1.000", "min_viplvl": 0, "max_prizes_per_player": 3, "fdate": "2026-11-01 00:00:00", "tdate": "2026-11-30 00:00:00", "status": "active", "archived": false, "archived_at": null, "tiers": [ { "tier": 1, "amount": "500.000", "count": 2, "given": 0, "odds": 2000000 }, { "tier": 2, "amount": "50.000", "count": 20, "given": 3, "odds": 200000 }, { "tier": 3, "amount": "5.000", "count": 200, "given": 41, "odds": 20000 } ] } ] }

Up to 500 promotions are returned, newest first. In each tier, given counts the prizes already won. fdate is the promotion start, tdate the end, both echoed in GMT. In each row, currency is the code, or null for a drop created before currency codes were required.

🔁 setPrizeDropStatus

Pauses, re-activates or closes a promotion. promo_id and status (pause | active | closed) are required.

📜 Sample JSON Request (from your server to the RGS-CWS server)

{ "command": "setPrizeDropStatus", "promo_id": 311, "status": "closed", "apiusername": "your_api_username", "apipass": "your_api_password" }

📥 Input Parameters (from your server to the RGS-CWS server)

Parameter	Mandatory	Description	Type
*command	✅	Must be "setPrizeDropStatus"	string
*promo_id	✅	The promotion id (from createPrizeDrop / listPrizeDrops)	integer
*status	✅	pause (or paused) | active | closed	string
*apiusername	✅	Your API username	string
*apipass	✅	Your API password	string

📃 Sample JSON Response (returned by RGS-CWS)

{ "status": "OK", "message": "Status set", "promo_id": 311, "new_status": "closed", "archived": true }

• status=closed MOVES the promotion to the archive in the same request; the response carries archived: true and the promotion is then readable through listPrizeDrops scope=closed|all and prizeDropWinners. A promotion that still holds an unpaid prize stays in the live list (archived: false, the message says so) and is archived on your next listPrizeDrops call once the prize is paid.

• Closing an already-archived promotion answers OK with message: Already closed (idempotent). Reopening one answers ERROR A closed prize drop cannot be reopened. A promo_id that belongs to another operator answers ERROR Prize drop not found.

• A promotion whose tdate has passed cannot be set back to active (ERROR The prize drop has ended (tdate passed)).

• A promotion being changed by two requests at the same time answers ERROR The prize drop is being changed by another request - retry.

🏆 prizeDropWinners

Lists the prizes won in one promotion. Works for an archived (closed) promo_id exactly as for a live one; the optional from / to date filters apply the same way. A promo_id of another operator answers ERROR Prize drop not found.

📜 Sample JSON Request (from your server to the RGS-CWS server)

{ "command": "prizeDropWinners", "promo_id": 311, "from": "2026-11-01", "to": "2026-11-30", "apiusername": "your_api_username", "apipass": "your_api_password" }

📥 Input Parameters (from your server to the RGS-CWS server)

Parameter	Mandatory	Description	Type
*command	✅	Must be "prizeDropWinners"	string
*promo_id	✅	The promotion id whose winners to list	integer
from	❌	(optional) Y-m-d or Y-m-d H:i:s	string
to	❌	(optional) Y-m-d or Y-m-d H:i:s	string
since_id	❌	(optional) Return only wins with win_id greater than this — pass the next_since_id of the previous page	integer
limit	❌	(optional) Page size, 1–1000 (default 1000)	integer
*apiusername	✅	Your API username	string
*apipass	✅	Your API password	string

📃 Sample JSON Response (returned by RGS-CWS)

{ "status": "OK", "message": "OK", "promo_id": 311, "winners": [ { "win_id": 88, "wallet_ref": "TPD311", "date": "2026-11-07 19:24:11", "username": "player01", "login": "u44_player01", "gameid": 6857, "amount": "50.000", "currency": "EUR", "wallet_state": "paid", "granted": true } ], "truncated": false }

Up to limit winners (default 1000) are returned, oldest first. truncated is true when more winners exist than fit the page; the reply then also carries next_since_id — send it as since_id to read the next page. truncated: false means the list is complete.

wallet_ref is the transaction reference your wallet received for the prize credit (TPD{promo_id}); wallet_state shows the state of that credit (a prize still owed shows pending). username is the player's name as your platform knows it; from / to take Y-m-d or Y-m-d H:i:s.