Idempotency

All Seamless Wallet calls include a unique requestId. Network timeouts, gateway hiccups, or internal PlayStarters retries can cause the same request to arrive at your endpoint more than once. Your implementation must handle this without re-applying the financial movement.

The rule

If you receive a request with a requestId you have already processed, do not reapply the movement. Return HTTP 200 OK with the player’s current balance.

Recommended implementation

Store processed requestIds

On every successful BET, WIN, or VOID, persist the requestId together with the resulting balance in a transactions table or cache. Use a unique index/constraint on requestId to prevent duplicates at the database level.

Check before applying

Before applying a new transaction, look up the requestId. If it already exists, skip the movement and return the previously stored balance.

Wrap the read + write in a single transaction

The check, the movement, and the requestId write must be atomic to avoid race conditions when the same request arrives twice in parallel.

Example pseudocode

async function handleWalletCallback(req) {
  return db.transaction(async (tx) => {
    const existing = await tx.transactions.find(req.requestId);
    if (existing) {
      return { balance: existing.balanceAfter };
    }

    if (req.type === "BALANCE") {
      const balance = await tx.players.getBalance(req.playerId);
      return { balance };
    }

    // BET / WIN / VOID
    const balance = await tx.players.applyMovement(req);
    await tx.transactions.insert({
      requestId: req.requestId,
      playerId: req.playerId,
      type: req.type,
      amount: req.amount,
      balanceAfter: balance,
    });
    return { balance };
  });
}

Idempotency is mandatory. Without it, a single retried BET can debit the player twice, or a retried WIN can credit them twice — both create reconciliation issues that are painful to unwind.

Overview

Operator API

Seamless Wallet API

The rule

Recommended implementation

Example pseudocode

​The rule

​Recommended implementation

​Example pseudocode

The rule

Recommended implementation

Example pseudocode