Core concepts

Seamless wallet

Player balances live only in your system. Star Game never holds player money: when a player stakes, the platform asks your wallet to debit the stake; when a round pays out, it asks you to credit the winnings; when a debit’s outcome is uncertain, it asks you to roll it back. Amounts are integer minor units sent as decimal strings ("1500"), paired with the currency code and number of decimal places (Currency and Decimals) you configure in Console → Integration. Floats are never used.

Launch code

Each time a player opens a game, your App asks your backend for a launch code and hands it to the game page through the Host Bridge (getConfig → code). The platform exchanges it exactly once via POST /players/authenticate and never stores it.

• Make it opaque, random and single-use.
• Keep its lifetime short: ≤ 5 minutes.
• Bind it to one player on your side; do not put your App’s own access token in the URL or in getConfig.

A reusable code (for example one that survives a page reload) still works, but the self-test reports single-use as an advisory warning.

session_id

authenticate returns a session_id that you define. The platform echoes it on every debit, so you can refuse new stakes after logout, a ban or a limit breach (session_invalid, player_blocked, limit_exceeded).

Rules:

• Credits and rollbacks never check the session. Rounds that were already played must always settle, even if the player logged out or was banned in the meantime.
• Extend the session whenever a debit or a balance call carries it. The platform calls balance at least every 20 minutes for players who are still in a game, so a watching-but-not-betting player keeps a live session.

Idempotency by transaction_id

Every transaction carries a globally unique transaction_id (≤ 128 characters).

• A repeated transaction_id must return the result of the first processing — including failures such as insufficient_funds — and must never book twice.
• The same transaction_id with a different type, player_id, amount, currency or reference_transaction_id returns duplicate_mismatch and books nothing.
• Keep transactions for at least 180 days for reconciliation.

Rollbacks and tombstones

A rollback reverses the debit named in reference_transaction_id:

Situation on your side	What you do	Answer
Debit booked, not yet reversed	Refund it	ok
Debit already reversed, or booked as failed	Nothing	ok
Debit never received	Record a tombstone for that transaction id	ok
The tombstoned debit arrives later	Do not book it	rolled_back

The platform sends a rollback for every debit whose outcome it could not learn (timeout, connection reset, 5xx) and keeps retrying until it gets ok. With tombstones this always converges: both sides agree without scanning reconciliation reports.

A credit whose referenced debit was never booked or was rolled back returns reference_not_found.

Staged debits (several debits per player per round)

During a betting window the platform debits newly placed stakes every few seconds, so one player can have several debits in the same round:

lantern:59666:p_123:bet      first stake batch
lantern:59666:p_123:bet:1    stakes placed a few seconds later
lantern:59666:p_123:bet:2    ...

• Do not deduplicate or reject debits by round or by player-per-round.
• Each debit stands on its own: one can be refused (insufficient_funds) or rolled back while the others stay booked.
• The payout credit references the player’s first booked debit of the round and pays the total for all booked stakes of that round.
• round_id groups every transaction of one round; use it in your support tools.

Batches

POST /transactions carries 1–500 transactions (never more than the max batch size you configure).

• Items are independent, not atomic. You may process them in parallel.
• Items of the same player must be applied in array order.
• Answer HTTP 200 only when every item has a result; one failed item never fails the batch.
• Results come back in request order, one per item.

Retries

• The platform retries HTTP 408, 429, 5xx and timeouts with the same transaction ids, honouring Retry-After.
• An item with status retry (transient failure, nothing booked) is resent with the same id.
• Every HTTP attempt carries a new webhook-id and a fresh signature; your idempotency key is transaction_id, not webhook-id.
• The platform never sends more parallel requests than your max concurrent requests setting.