Casino games API: integration guide with code examples

Integrating a casino games API is mostly a wallet problem wearing a content costume. The catalog and launch calls are straightforward REST; the part that decides whether the integration is calm or painful is how carefully you handle money moving through callbacks you do not control. This guide walks the concepts in the order you will meet them, with illustrative Node.js examples against deliberately generic endpoints. For the specifics of our own implementation, see the iGaming API developer hub.

Core concepts

Almost every casino games API — aggregated or direct — exposes the same five surfaces. Names differ, shapes rarely do.

Two directions of traffic matter here. You call the provider for catalog and session work; the provider calls you for wallet work. Those are different security models, different failure modes and, usually, different services in your architecture. Keeping them mentally separate from day one avoids a lot of confusion later.

Authentication

Outbound calls are typically authenticated with an API key or token sent as a bearer header, scoped per environment. Keep sandbox and production credentials in separate secret stores, never ship a key to the browser, and rotate on a schedule rather than after an incident.

Inbound callbacks need the opposite treatment: you are the one verifying. Most providers sign the request body with a shared secret, and some also publish a source IP range. Verify the signature before you parse anything meaningful, use a constant-time comparison, and reject unsigned requests outright rather than logging and continuing.

// Illustrative example — verify that a callback really came from the provider.
import { createHmac, timingSafeEqual } from 'node:crypto';

function verifySignature(req, res, next) {
  const received = req.get('x-signature') ?? '';
  const expected = createHmac('sha256', process.env.WALLET_CALLBACK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return res.status(401).json({ status: 'INVALID_SIGNATURE' });
  }
  next();
}

A typical integration flow

The order below is the one that gets teams to a working lobby fastest, because each step is independently testable and each one de-risks the next.

Fetching the game list

The catalog is a read-mostly resource. Fetch it on a schedule, persist a normalised copy alongside your own merchandising fields, and serve your lobby from that. This keeps page loads fast, keeps the lobby up if the provider has a blip, and gives you a stable place to apply jurisdiction filtering before anything reaches a player.

// Illustrative example — endpoints are generic placeholders.
const res = await fetch('https://api.example-aggregator.com/v1/games?' +
  new URLSearchParams({ category: 'slots', limit: '50' }), {
  headers: {
    Authorization: `Bearer ${process.env.GAMES_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!res.ok) throw new Error(`Game list failed: ${res.status}`);

const { items } = await res.json();
// items[0] => { id, name, studio, category, thumbnail, jurisdictions: [...] }

Store the provider's game identifier as an opaque string and never derive meaning from its format. Track jurisdiction availability per game and enforce it server-side at launch time as well as when rendering the lobby — a hidden tile is a UI decision, not a compliance control.

Launching a game session

Session creation is always a server-side call. Your back end knows the authenticated player, chooses the currency and language, and asks the provider for a short-lived launch URL. The browser only ever sees that URL.

// Illustrative example — create the session server-side only.
async function launchGame({ gameId, playerId, currency, language }) {
  const res = await fetch('https://api.example-aggregator.com/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.GAMES_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      gameId,
      playerId,          // your internal, stable player identifier
      currency,          // ISO 4217, e.g. 'EUR'
      language,          // ISO 639-1, e.g. 'en'
      mode: 'real',      // or 'demo'
      returnUrl: 'https://your-casino.example/lobby',
    }),
  });

  const session = await res.json();
  return session.launchUrl; // render in an iframe or redirect
}

A few details save time. Pass a stable internal player identifier, not an email or anything you may want to change. Treat launch URLs as single-use and short-lived. Support demo mode from the same code path so your QA can exercise the lobby without touching the wallet. And always supply a return URL, so a player leaving a game lands back in your lobby rather than on a blank page.

Handling wallet callbacks

This is the part worth over-engineering. The provider will call your endpoints while the player spins, and those calls represent real money. Three properties matter more than anything else: idempotency, atomicity and speed.

// Illustrative example — seamless wallet endpoint on YOUR server.
import express from 'express';
const app = express();
app.use(express.json());

app.post('/wallet/debit', verifySignature, async (req, res) => {
  const { transactionId, playerId, amount, currency, roundId } = req.body;

  // 1. Idempotency: the same transactionId must never debit twice.
  const existing = await db.transactions.findByExternalId(transactionId);
  if (existing) {
    return res.json({ status: 'OK', balance: existing.balanceAfter });
  }

  // 2. Apply atomically: check funds and write the ledger row together.
  try {
    const { balanceAfter } = await db.tx(async (t) => {
      const player = await t.players.lockById(playerId);
      if (player.currency !== currency) throw new CurrencyMismatch();
      if (player.balance < amount) throw new InsufficientFunds();

      const balance = player.balance - amount;
      await t.players.setBalance(playerId, balance);
      await t.transactions.insert({
        externalId: transactionId, playerId, roundId,
        type: 'debit', amount, balanceAfter: balance,
      });
      return { balanceAfter: balance };
    });

    return res.json({ status: 'OK', balance: balanceAfter });
  } catch (err) {
    if (err instanceof InsufficientFunds) {
      return res.status(200).json({ status: 'INSUFFICIENT_FUNDS' });
    }
    return res.status(500).json({ status: 'INTERNAL_ERROR' });
  }
});

Idempotency means a repeated transaction ID returns the original outcome instead of applying a second debit. Enforce it with a unique constraint in the database, not with an application-level check that can race. Atomicity means the balance update and the ledger row are written in one transaction — never one then the other. Speed means responding in milliseconds: queue anything slow, such as bonus evaluation or analytics, and let the callback return.

Model business outcomes as successful HTTP responses carrying a status, and reserve 5xx for genuine faults you want the provider to retry. Insufficient funds is not a server error. Rollback deserves particular care: it can arrive for a round you never saw, so record it as a no-op rather than failing, and keep it idempotent too.

Errors, retries and reconciliation

Assume every callback can arrive twice and every outbound call can time out having actually succeeded. That assumption drives the design: idempotency keys on writes, bounded retries with backoff on reads, and a reconciliation job that compares your ledger with provider reporting on a fixed schedule. Discrepancies found by a daily job are an operational task; the same discrepancies found by a player are a support incident.

Log with correlation. Every wallet write should be searchable by transaction ID, round ID and player ID, and every outbound call should carry a request ID you can quote to the provider's support team. Alert on the shape of traffic, not just on errors — a sudden drop in credits relative to debits usually means something is wrong long before anyone files a ticket.

Frequently asked questions

The examples above are deliberately generic so they apply to any provider. For our exact endpoints, SDKs and wallet contract, see the iGaming API developer hub, or talk to our team about your platform and markets.