Node.js integration

Start with Node.js + PostgreSQL#

Import the SQL, set your connection details and sign in.

1. Download the Node.js + PostgreSQL demo below.
2. Import demo.sql into an empty PostgreSQL database.
3. Enter the API and database credentials in .env.
4. Open the application and log in with test / 123.

The demo covers login, currency selection, sportsbook, bet history, design controls and home page widgets. For a live integration, connect the player lookup to your existing member session.

Connection settings#

Use separate addresses for server requests and the player interface.

Send signed API requests from your server. Do not send a browser Origin header to the server API. The launch payload’s origin identifies the website that hosts the iframe. If an IP allowlist is enabled, your outbound server IP must be authorized.

Node.js setup#

Node.js 22.9+ · PostgreSQL 14+ · HTTPS

1. Create an empty PostgreSQL database. Import demo.sql using psql or pgAdmin.
2. Copy .env.example to .env and fill in your API, domain and PostgreSQL connection details.
3. Run npm ci, then npm start. Forward your HTTPS domain to 127.0.0.1:3000; nginx.conf includes a proxy example.

psql -h 127.0.0.1 -U YOUR_DATABASE_USER -d YOUR_DATABASE_NAME -f demo.sql
cp .env.example .env
# Fill in .env, then:
npm ci
npm start

SPORTS_SITE_KEY=YOUR_SITE_KEY
SPORTS_SITE_SECRET=YOUR_SITE_SECRET
CUSTOMER_ORIGIN=https://customer.example
DB_HOST=127.0.0.1
DB_PORT=5432
DB_NAME=YOUR_DATABASE_NAME
DB_USER=YOUR_DATABASE_USER
DB_PASSWORD=YOUR_DATABASE_PASSWORD

The SQL creates test / 123 and 16 wallets. Login sessions are stored in PostgreSQL. The HTTPS proxy must preserve the Host header.

Choose your wallet model#

Your site is configured for seamless or ledger mode.

Site betting credit and a player’s wallet balance are separate accounts.

Sign API requests#

Every server request carries an HMAC-SHA256 signature.

timestamp + "\n" +
nonce + "\n" +
METHOD + "\n" +
path_and_query + "\n" +
SHA256(raw_body)

Use the uppercase method and the exact path, including a query string when present. Sign and send the same UTF-8 body bytes. A GET request uses an empty body. Generate a fresh nonce when retrying, while keeping the financial idempotency key unchanged.

import { createHash, createHmac, randomBytes } from 'node:crypto';
const body = JSON.stringify(payload);
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(24).toString('hex');
const hash = createHash('sha256').update(body).digest('hex');
const message = [timestamp, nonce, 'POST', path, hash].join('\n');
const signature = createHmac('sha256', siteSecret).update(message).digest('hex');

Create a player session#

POST /api/integration/launch

Create a fresh launch when a player opens the sportsbook. The returned link lasts 60 seconds and can be used once. Member identity comes from your authenticated server session.

{
  "guest": false,
  "username": "player_example",
  "external_user_id": "42",
  "currency": "TRY",
  "language": "en",
  "origin": "https://customer.example",
  "callback_url": "https://customer.example/integration/callback"
}

{
  "ok": true,
  "data": {
    "url": "https://sports.sportsbookapi.work/?site_key=YOUR_SITE_KEY&lang=en#/home?launch=LAUNCH_TOKEN",
    "launch_token": "LAUNCH_TOKEN",
    "site_key": "YOUR_SITE_KEY",
    "expires_at": "2026-09-14T12:01:00.000Z"
  }
}

For a guest launch, set guest:true and omit the member fields. Keep one stable callback URL for the site. Never reuse a launch link for a second iframe.

Send an API request#

Use the included signing function or implement the HTTP contract yourself.

import { sportsbookClient } from './client.mjs';
const api = sportsbookClient({
  siteKey: process.env.SPORTS_SITE_KEY,
  siteSecret: process.env.SPORTS_SITE_SECRET,
});
const launch = await api.launch(payload);
const iframeUrl = launch.url;

Use your authenticated member identity to build the payload. The member password is never sent to the sportsbook API.

Display the sportsbook#

The demo renders the main iframe automatically.

To embed it in another page, load the SDK and obtain a fresh launch from your server:

<div id="sportsbook" style="height:85vh;min-height:640px"></div>
<script src="/assets/sportsbookapi.js"></script>

const response = await fetch("/integration/launch", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ action: "launch", csrf: csrfToken }),
});
const result = await response.json();
if (!response.ok || !result.ok) throw new Error("Launch failed");
const sportsbook = SportsbookAPI.mount("#sportsbook", {
  sportsOrigin: "https://sports.sportsbookapi.work",
  launchUrl: result.url,
  language: "en",
});

csrfToken comes from the authenticated host session. Without the SDK, set iframe src to the returned URL and implement the message contract below.

Home page widgets#

Place live matches, upcoming matches and popular leagues anywhere on your website.

const widget = SportsbookAPI.mountWidget("#live-matches", {
  section: "live",
  sportsPage: "/sports",
  launchEndpoint: "/integration/launch",
  csrfToken,
  language: "en",
});
// Remove the widget when its host component is removed.
// widget.destroy();

Match, odds and league clicks open the matching detail on your full sports page. The widget itself does not add a selection to a betslip. Height adjusts to content. Every widget needs its own guest launch.

The destination receives a validated sports_path query parameter. The provided SDK and host script open this route. For a custom router, use SportsbookAPI.routeFromLocation() and sportsbook.navigateTo(path).

Bet history and design controls#

Open either modal on a page without the main sportsbook iframe.

const options = {
  launchEndpoint: "/integration/launch",
  csrfToken,
  language: "en",
};
// Use each call in its own button handler.
SportsbookAPI.openBets(options);
SportsbookAPI.openDesign(options);

openBets requires member login and sends action=player-bets-launch. openDesign sends action=design-launch. Each opening obtains its own fresh launch.

Browser message contract#

For integrations using their own iframe and modal components.

Validate both event.origin and event.source. Host commands use source:"sportsbook-host"; iframe events use source:"sportsbook-iframe".

Standalone views use view=player-bets, view=design or view=home-widget in the launch URL query. Widgets also use section=live|upcoming|popular-leagues|all. Keep the launch token in the URL fragment.

Receive callbacks#

Server-to-server messages keep your wallet and bet records up to date.

1. Read the original body bytes and verify the signature and timestamp.
2. Validate site_key, username and currency.
3. For a wallet change, lock the wallet and check idempotency_key within one database transaction.
4. Apply amount once, store the response and commit; then return JSON.

const valid = verifyCallback({
  rawBody,
  timestamp: req.headers['x-callback-timestamp'],
  signature: req.headers['x-coupon-signature'],
  siteSecret,
});
if (!valid) return res.writeHead(401).end();

The callback handler receives the raw body before a JSON parser. Signature verification uses the sha256= prefix here; API request signing does not.

Event reference#

Only wallet events change a seamless wallet balance.

What does coupon.settled.1 mean?

coupon identifies a bet notification, settled means a settlement update, and 1 is the revision number. It does not mean won or lost. The same event name can describe a won, lost or refunded bet. A later correction may arrive as coupon.settled.2.

Settlement and cashout share the revision counter. The next settlement after a cashout may therefore end in .2 or a higher number. Do not infer a result from event suffixes, sequence or amount. Use raw_payload.status; apply money only from the signed wallet event.

10.00 stake at odds of 1.55

These are alternative outcomes for a single bet with no previous cashout or settlement. Wallet settlement amounts are payout differences; after a correction they may be negative.

N is the shared settlement/cashout revision number. Not every internal placement transition creates a callback. There is no separate coupon.rejected callback; a rejected reservation is acknowledged directly, and a definitive failure after reservation produces wallet.refund.

Bet and placement statuses#

Read raw_payload.status for the result; use status_label only for display.

An accepted bet waiting for results uses open; it does not use a separate pending status. Partial cashout also remains open.

Before acceptance

These are placement states, not won/lost results. Callback snapshots show the state at the time of that event. A result correction can reopen or change a settled bet; always process the revision and wallet delta.

Coupon payload fields#

One event envelope and one raw_payload snapshot.

{
  "event": "coupon.accepted",
  "amount": "0.00",
  "bet_id": "cpn_example",
  "currency": "TRY",
  "event_id": "evt_example_coupon_accepted",
  "sequence": 10,
  "site_key": "YOUR_SITE_KEY",
  "username": "player_example",
  "occurred_at": "2026-09-14T08:38:51.276Z",
  "raw_payload": {
    "lines": [
      {
        "odds": "2",
        "stake": "10.00",
        "possible_win": "20.00",
        "selection_ids": [
          "301"
        ]
      }
    ],
    "payout": "0.00",
    "status": "open",
    "bet_type": "single",
    "revision": 0,
    "created_at": "2026-09-14T08:38:51.200Z",
    "error_code": null,
    "selections": [
      {
        "line": null,
        "scope": "sports",
        "esports": false,
        "is_live": false,
        "visible": true,
        "event_id": "101",
        "sport_id": "1",
        "start_at": "2026-09-15T08:38:50.000Z",
        "away_team": "Away 1",
        "home_team": "Home 1",
        "league_id": "3",
        "market_id": "201",
        "country_id": "2",
        "sport_name": "Football",
        "is_finished": false,
        "league_name": "Premier League",
        "market_name": "Match Result",
        "market_type": "P1XP2",
        "sport_alias": "Soccer",
        "country_name": "England",
        "placed_score": null,
        "selection_id": "301",
        "current_score": null,
        "displayed_odds": "2.00",
        "effective_odds": "2",
        "selection_name": "Home",
        "full_time_score": null,
        "score_updated_at": null,
        "current_game_time": null,
        "current_game_state": null
      }
    ],
    "settled_at": null,
    "settlement": null,
    "total_odds": "2.00",
    "updated_at": "2026-09-14T08:38:51.270Z",
    "odds_format": "decimal",
    "total_stake": "10.00",
    "possible_win": "20.00",
    "status_label": "Open",
    "wallet_state": "debited",
    "cashout_count": 0,
    "error_details": null,
    "error_message": null,
    "cashout_summary": {
      "history": [],
      "total_amount": "0.00",
      "remaining_stake": "10.00",
      "remaining_possible_win": "20.00"
    },
    "remaining_ratio": "1.000000000000",
    "selection_count": 1,
    "client_reference": "example-placement-reference",
    "odds_format_code": 0,
    "odds_format_label": "Decimal",
    "settlement_locked": false,
    "displayed_total_odds": "2.00"
  },
  "schema_version": 2,
  "idempotency_key": "cpn_example:coupon.accepted"
}

{
  "event": "coupon.settled.1",
  "amount": "0.00",
  "bet_id": "cpn_example",
  "currency": "TRY",
  "event_id": "evt_example_coupon_settled_1",
  "sequence": 103,
  "site_key": "YOUR_SITE_KEY",
  "username": "player_example",
  "occurred_at": "2026-09-14T08:38:51.292Z",
  "raw_payload": {
    "lines": [
      {
        "odds": "2",
        "stake": "10.00",
        "possible_win": "20.00",
        "selection_ids": [
          "301"
        ]
      }
    ],
    "payout": "20.00",
    "status": "won",
    "bet_type": "single",
    "revision": 1,
    "created_at": "2026-09-14T08:38:51.200Z",
    "error_code": null,
    "selections": [
      {
        "line": null,
        "scope": "sports",
        "esports": false,
        "is_live": false,
        "visible": true,
        "event_id": "101",
        "sport_id": "1",
        "start_at": "2026-09-15T08:38:50.000Z",
        "away_team": "Away 1",
        "home_team": "Home 1",
        "league_id": "3",
        "market_id": "201",
        "country_id": "2",
        "sport_name": "Football",
        "is_finished": false,
        "league_name": "Premier League",
        "market_name": "Match Result",
        "market_type": "P1XP2",
        "sport_alias": "Soccer",
        "country_name": "England",
        "placed_score": null,
        "selection_id": "301",
        "current_score": null,
        "displayed_odds": "2.00",
        "effective_odds": "2",
        "selection_name": "Home",
        "full_time_score": null,
        "score_updated_at": null,
        "current_game_time": null,
        "current_game_state": null
      }
    ],
    "settled_at": "2026-09-14T08:38:51.283Z",
    "settlement": {
      "note": "",
      "source": "provider",
      "results": {
        "301": 3
      },
      "revision": 1
    },
    "total_odds": "2.00",
    "updated_at": "2026-09-14T08:38:51.283Z",
    "odds_format": "decimal",
    "total_stake": "10.00",
    "possible_win": "20.00",
    "status_label": "Won",
    "wallet_state": "confirmed",
    "cashout_count": 0,
    "error_details": null,
    "error_message": null,
    "cashout_summary": {
      "history": [],
      "total_amount": "0.00",
      "remaining_stake": "10.00",
      "remaining_possible_win": "20.00"
    },
    "remaining_ratio": "1.000000000000",
    "selection_count": 1,
    "client_reference": "example-placement-reference",
    "odds_format_code": 0,
    "odds_format_label": "Decimal",
    "settlement_locked": false,
    "displayed_total_odds": "2.00"
  },
  "schema_version": 2,
  "idempotency_key": "cpn_example:coupon.settled.1"
}

Match and selection details#

Each raw_payload.selections entry describes one selected outcome.

Scores describe the match, not the settlement of an individual market. Use the settlement results and coupon status for betting outcomes.

The current settlement engine requires a supported result for every selection in the line. Do not derive a win/loss from an absent result.

Callback responses#

Acknowledge the recorded outcome of each request.

wallet.balance

{"ok":true,"balance":"100.00","currency":"TRY"}

Committed wallet or notification event

{"ok":true,"idempotency_key":"cpn_example:coupon.accepted","balance":"90.00","currency":"TRY"}

Insufficient funds for wallet.reserve

{"ok":false,"code":"INSUFFICIENT_BALANCE","idempotency_key":"cpn_example:wallet.reserve"}

Return HTTP 200 for a balance response. For durable events, return a successful 2xx response with ok:true and the matching key after commit. A definitive reserve rejection also includes the matching key. Network errors are not insufficient-balance decisions.

Retries and ordering#

An event can be delivered more than once.

Store a unique (site_key,idempotency_key) record with the wallet update and response in one transaction. An identical repeated body returns the stored response. If the same key has a different body, return HTTP 409 without another balance change. Verify the signature for every delivery.

Events are sent in sequence within the same bet. Different bets may arrive concurrently. The callback timeout is 10 seconds. Failed durable deliveries are retried with increasing delays, up to 20 attempts; unresolved deliveries require reconciliation. These retries are separate from a synchronous wallet.balance request.

Results and corrections#

Apply the wallet delta, then update the result record.

For a loss without prior payout, settlement amount is 0.00. For a full refund without prior cashout, the stake is returned. Corrections can increase or decrease a previous payout, or reopen the bet. Use the amount actually delivered rather than calculating from the status alone.

Full and partial cashout#

Cashout payments and remaining exposure are reported separately.

Apply wallet.cashout.N.amount once. Full cashout changes status to cashout and remaining_ratio to zero. Partial cashout leaves status open; remaining_ratio, remaining_stake and remaining_possible_win decrease. Later settlement concerns the remaining portion.

payout includes cashout already paid. The following coupon.cashout.N event has amount 0.00 and updates the bet record.

Currencies and amounts#

Money is a decimal string in both requests and responses.

These are precision limits, not a requirement to type that many digits. 10.50 TRX, 2.25 TRY and 3.00 KWD are valid amount formats. Site stake and payout limits also apply.

Coupon events remove unnecessary trailing zeros and keep at least two decimal places. Preserve meaningful fractions such as 1.001 and 0.00000001. Use decimal arithmetic for balances and compare status codes rather than display labels.

Ledger transfers#

POST /api/integration/wallet

{
  "username": "player_example",
  "currency": "TRY",
  "operation": "credit",
  "amount": "100.00",
  "idempotency_key": "transfer-example-0001"
}

credit adds funds to the sportsbook wallet; debit removes them. This endpoint is for ledger sites. The member wallet must exist after iframe bootstrap. Amount must be positive and match currency precision.

{"ok":true,"data":{"transaction_id":"txn_example","idempotency_key":"transfer-example-0001","balance":"100.00","currency":"TRY"}}

When a transfer times out, retry the same operation and financial key with a fresh signing nonce. Do not create a second transfer to compensate for an unknown result.

Site betting credit#

GET /api/integration/credit

{"ok":true,"data":{"site_key":"YOUR_SITE_KEY","credit":"1000.00","currency":"USD"}}

This returns your site’s betting credit, not a player balance. Sign the request with an empty body. The currency comes from your site configuration.

Error handling#

Use code for handling and request_id for support.

{"ok":false,"code":"SIGNATURE_INVALID","message":"Request signature is invalid.","request_id":"request_example"}

A 503 or connection timeout does not prove that a financial operation failed. Preserve its reference and reconcile the result before retrying a different operation. Error message language may vary; code remains the integration key.

Downloads#

Node.js + PostgreSQL · application and API reference