Single wallet vs transfer wallet

At a glance

Single wallet (seamless)

In the single wallet (seamless) model your system is the wallet. When a player places a bet the SSG API calls your callback endpoint, you change the balance in your own ledger, and you answer with the new balance. No funds ever leave your database.

Call flow

1. Launch: your backend asks SSG for a game URL with a player ID and session token.
2. Bet: for each round SSG calls debit with a unique txId. You check funds, write the ledger row and return the new balance.
3. Win: SSG calls credit with the payout (which can be zero) for the same round.
4. Failure: if a call times out SSG retries with the same txId, and after the retry limit it sends rollback.

Callback methods (illustrative)

{
  "method": "debit",
  "playerId": "p_839201",
  "txId": "tx_20261007_000184",
  "roundId": "r_77f3a1",
  "gameId": "slots_fruit_01",
  "currency": "MYR",
  "amount": "2.50",
  "ts": 1791338577,
  "sign": "hex(HMAC-SHA256(secret, canonical))"
}

{
  "status": "OK",
  "txId": "tx_20261007_000184",
  "balance": "97.50",
  "currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
//         DUPLICATE_TX (return original result), INTERNAL_ERROR

Rules your wallet service must follow

Idempotency

A repeated debit or credit with the same txId must return the original result and must not move money again. Enforce it with a unique index on txId.

Atomic ledger write

Check balance, insert the ledger row and update the balance in one database transaction, so two concurrent bets can never overdraw.

Rollback before debit

A rollback can arrive for a txId you never saw because the original debit timed out. Store a tombstone so a late debit with that txId is rejected.

Latency budget

Aim for a p99 below 500 ms including network. Keep the callback path to one indexed read and one write, and keep reporting queries off it.

Money format

Treat amounts as decimal strings or integer minor units. Never use floating point, and validate currency against the player account.

Bonuses and free spins

A free spin is a debit of 0 followed by a credit of the win. Keep promotional balances separate from cash balance in your ledger.

Security

Verify an HMAC-SHA256 signature over the canonical request, reject stale timestamps, allowlist SSG source IPs, and require TLS 1.2 or higher.

Reconciliation

Compare daily round reports from SSG with your ledger by roundId. Differences point to missed callbacks or rollbacks.

Transfer wallet

In the transfer wallet model the provider keeps a game balance for each player. Your backend moves funds in before play and out afterwards. During play there are no callbacks to your system, so you only need outbound REST calls.

Call flow

1. Transfer in: your backend calls transferIn with a unique txId and the amount. The result is PENDING or SUCCESS.
2. Play: launch the game. All bets and wins change the provider-side balance with no callbacks to you.
3. Transfer out: when the player leaves, call transferOut for the full balance and credit it back to your own ledger on SUCCESS.
4. Unknown outcome: if a transfer call times out, query getTransferStatus with the same txId before doing anything else.

API methods (illustrative)

Rules your backend must follow

One txId per intent

Generate the txId before the first call and reuse it for every retry. Never create a new txId until the status of the previous one is known.

Debit your ledger first

For transfer in, reserve the amount in your ledger before calling SSG, then confirm or release it when the status is final.

Sweep stranded balances

Run a job that finds players with a game balance and no active session, then transfers it out. This covers players who close the browser mid-session.

Wagering and reports

Because you see no bets live, calculate turnover, bonus wagering and risk limits from round reports pulled from SSG, not from callbacks.

Reconciliation

Match every transfer in and out against SSG records by txId, and alert on any PENDING older than your timeout.

Security

Sign requests with HMAC-SHA256, call only over TLS 1.2 or higher, keep API keys in a secret store, and restrict which of your servers may call SSG.

Failure scenarios

Which one should you choose

Many operators start on transfer wallet to go live, then move to single wallet once their own wallet service is ready. Ask us how the switch is staged.

Integration checklist

• Unique index on txId and idempotent handlers for every money-moving call
• HMAC signature check, timestamp tolerance and IP allowlist
• Decimal-safe amounts and currency validation
• Timeout, retry and rollback tests in the sandbox, including a late retry
• Daily reconciliation job by roundId (single) or txId (transfer)
• Monitoring and alerts: callback latency, error rate, pending transfers, stranded balances