Skip to content
Star GameStar Game Docs

Overview

Operator Wallet API 1.0.0

Section titled “Operator Wallet API 1.0.0”

Endpoints an operator (the platform that owns player balances, e.g. a voice-room app) implements so that the game platform can authenticate players and move money in a seamless-wallet model.

  • Direction: game platform → operator. The operator hosts these endpoints under a base URL of its choice.
  • Transport: HTTPS, JSON (UTF-8), snake_case fields. Readers must ignore unknown fields.
  • Authentication: Standard Webhooks signatures — webhook-id, webhook-timestamp, webhook-signature (v1,<base64 HMAC-SHA256(secret, id.timestamp.body)>). Official verification libraries exist for Go, Python, JavaScript/TypeScript, Java/Kotlin, C#, PHP, Ruby, Rust and Elixir. Reject timestamps more than 300 s away from your clock; a webhook-id is unique per HTTP attempt and may be rejected if seen again. During key rotation the header carries several space-separated signatures; accept if any matches.
  • Money: amount / balance are decimal strings of integer minor units (e.g. "1500"), paired with currency (ISO 4217 or an operator-defined code such as GOLD; decimal places are agreed at onboarding). Never floats.
  • Identifiers are strings. Times are RFC 3339 UTC.
  • Whole-request errors use HTTP status codes with application/problem+json (RFC 9457). The platform retries 408 / 429 / 5xx / timeouts with the same transaction ids, honouring Retry-After.

Transaction semantics

  1. Idempotency. transaction_id is globally unique. A repeated transaction returns the result of the first processing (including failures) and never books twice. The same id with a different type, player_id, amount, currency or reference_transaction_id returns duplicate_mismatch.
  2. Sessions. debit may be refused with session_invalid / player_blocked. credit and rollback MUST NOT check the session, logout or ban state: rounds already played must always settle.
  3. Rollback. Reverses the referenced debit. If it was booked and not yet reversed → refund and ok. Already reversed or never booked → ok with no money movement. Never received → record the rollback and answer ok; if that debit arrives later, answer rolled_back and do not book it. The platform sends a rollback for every debit whose outcome it could not learn, until it gets ok.
  4. Items in one batch are independent (not atomic) and may be processed in parallel; items of the same player are applied in array order. HTTP 200 means every item has a result.
  5. Keep transactions for at least 180 days for reconciliation.
  6. Session lifetime. Operators SHOULD extend a session whenever a debit or a balance call carries its session_id. The platform calls balance at least every 20 minutes for players who are still active, so a session never expires under a player who is watching but not betting.
  7. Several debits per round. A player may be debited several times in one round (the platform debits new stakes every few seconds during the betting window): …:bet, …:bet:1, …:bet:2. Do not deduplicate or reject by round. A payout’s reference_transaction_id is the player’s first booked debit of the round.

Information

  • License: Proprietary
  • OpenAPI version: 3.0.3

Operations

Section titled “Operations”
POST
/players/authenticate
POST
/players/balance
POST
/transactions
GET
/transactions/{transaction_id}

Authentication

Section titled “Authentication”

standardWebhooks

Section titled “standardWebhooks”

Standard Webhooks HMAC-SHA256 signature; also requires webhook-id and webhook-timestamp headers.

Security scheme type: apiKey

Header parameter name: webhook-signature