Seamless Wallet Overview

The Seamless Wallet API lets PlayStarters use your existing player balances as the source of truth during gameplay. You expose a single POST endpoint that handles all operation types, identified by the type field in the request body.

Endpoint contract

Property	Value
URL	Provided by you (e.g. `https://api.yoursite.com/wallet-callback`).
HTTP method	Always `POST`.
Authentication	`Authorization: Bearer <your_api_key>` (your same API key, sent as a Bearer token).
Request body	JSON, with `type` indicating the operation.
Successful response	HTTP `200 OK` with the updated balance: `{ "balance": 100.50 }`.

Supported operation types

`type`	Description	Reference
`BALANCE`	Read the current balance for a player.	Balance Read
`BET`	Deduct the bet amount from the player’s balance.	Transactions
`WIN`	Credit the win amount to the player’s balance.	Transactions
`VOID`	Refund a previously placed bet (round cancelled).	Transactions

Common request fields

Every call from PlayStarters to your endpoint includes the following fields:

string

Your unique identifier for the player (the same value you passed as playerId to POST /operator/launch).

string

Operation type. One of BALANCE, BET, WIN, VOID.

number

Transaction amount in the player’s currency. 0 for BALANCE operations.

string

ISO 4217 currency code (e.g. EUR).

string

Unique identifier for this request. Use it for idempotency.

string

UUID of the game the transaction belongs to. Not sent for BALANCE operations.

string

Identifier for the game round. Groups related BET/WIN/VOID transactions together. Not sent for BALANCE operations.

string

Present only on WIN and VOID. Correlates the transaction with the original BET’s requestId.

Successful response

Always return HTTP 200 OK with the player’s updated balance:

{ "balance": 100.50 }

Error response

The only error response PlayStarters expects is insufficient funds on a BET. See Transactions for the exact format.

Always verify the Authorization header on every incoming request. Never trust the body fields without authenticating the caller first.

​Endpoint contract

​Supported operation types

​Common request fields

​Successful response

​Error response

Endpoint contract

Supported operation types

Common request fields

Successful response

Error response