Sportsbook iframe integration

Iframe API Integration Guide

Technical reference for opening the sportsbook iframe, selecting the active currency wallet, validating signed callbacks and processing balance movements safely.

Start integration Download iframe.php Download server.js

Active guide PHP iframe.php Node.js PostgreSQL

Default integration works through a single iframe.php file.

Node.js integration works through one server file: src/server.js.

Standard field currency

Used for wallet selection and every balance callback.

Supported currencies TRY, USD, GBP, EUR, TND, KWD, BRL, CAD, AUD

Requests with unsupported currency values are rejected.

Security HMAC SHA-256

The currency value is included in the signature base string.

Setup

Fill the configuration block at the top of iframe.php.

Fill the .env file, install dependencies and start the Node.js service.

iframe.php configuration

$dbHost = 'YOUR_DB_HOST';
$dbName = 'YOUR_DB_NAME';
$dbUser = 'YOUR_DB_USER';
$dbPass = 'YOUR_DB_PASSWORD';

$siteKey  = 'YOUR_SITE_KEY';
$apiToken = 'API_TOKEN_PROVIDED_BY_ALVARON';

Setting	Type	Description
`$dbHost`	string	Database host.
`$dbName`	string	Database name used by the integration.
`$dbUser`	string	Database username.
`$dbPass`	string	Database password.
`$siteKey`	string	Site key assigned for the integration.
`$apiToken`	string	Secret token used for signatures and API requests.

.env

PORT=3058
PUBLIC_BASE_URL=https://your-domain.com
ALVARON_SITE_KEY=YOUR_SITE_KEY
ALVARON_API_TOKEN=API_TOKEN_PROVIDED_BY_ALVARON
ALVARON_CENTRAL_BASE=https://alvarontech.work
DEFAULT_PAGE=sports/pre-match/
DEFAULT_CURRENCY=TRY

PGHOST=127.0.0.1
PGPORT=5432
PGDATABASE=your_database
PGUSER=your_db_user
PGPASSWORD=your_db_password
PGSSLMODE=disable

Start

npm install
npm start

Database permission: The integration can create required tables on first run. The database user must have create and alter permissions.

Launch URL

Open the iframe with the user and the wallet currency that will be used for the session.

PHP launch URL

https://your-domain.com/iframe.php?username=demo_user&platform=desktop&currency=USD&page=en/

Node.js launch URL

https://your-domain.com/iframe?username=demo_user&platform=desktop&currency=USD&page=en/

Parameter	Required	Example	Description
`username`	Yes	`demo_user`	Username that will open the iframe session.
`currency`	Yes	`USD`	Wallet currency used for this session.
`platform`	No	`desktop`, `mobile`	Interface type. Invalid values fall back to desktop.
`page`	No	`en/`, `en/sports/live/`	Initial sportsbook page to open inside the iframe.

Multi Wallet

Each user can have a separate balance for each currency. A transaction only affects the wallet matching its currency.

TRYUSDGBPEURTNDKWDBRLCADAUD

Balance check

Checks the selected wallet without changing the balance.

Bet place

Receives a negative delta and decreases the selected wallet.

Win, refund, cashout

Receives a positive delta and increases the selected wallet.

Coupon lost

Stores the result without adding balance.

Callback Flow

Every request is verified by signature, then the matching currency wallet is read or updated.

Balance Check

Sent before a bet is accepted. It does not decrease the wallet.

POST /iframe.php?alva_balance_check=1

POST /iframe/alva_balance_check

Request payload

{
  "site_key": "oEQnt",
  "sw_key": "oEQnt",
  "username": "demo_user",
  "user_id": "532847997",
  "uid": "532847997",
  "stake": 10,
  "amount": 10,
  "currency": "USD",
  "timestamp": 1779791255,
  "signature": "HMAC_SHA256_SIGNATURE"
}

Success response

{
  "ok": true,
  "can_bet": true,
  "balance": 100,
  "stake": 10,
  "currency": "USD",
  "message": "OK"
}

Bet Place

Sent when a coupon is created. The negative delta decreases the selected wallet.

POST /iframe.php?alva_balance_callback=1

POST /iframe/alva_balance_callback

Request payload

{
  "site_key": "oEQnt",
  "sw_key": "oEQnt",
  "username": "demo_user",
  "user_id": "532847997",
  "uid": "532847997",
  "action": "bet_place",
  "amount": 10,
  "delta": -10,
  "currency": "USD",
  "bet_id": "6361622388",
  "transaction_id": "6361622388:bet_place",
  "timestamp": 1779791255,
  "signature": "HMAC_SHA256_SIGNATURE"
}

Coupon Win

Sent when a coupon wins. The amount is added to the wallet used by the coupon.

Request payload

{
  "site_key": "oEQnt",
  "sw_key": "oEQnt",
  "username": "demo_user",
  "user_id": "532847997",
  "uid": "532847997",
  "action": "coupon_win",
  "amount": 14,
  "delta": 14,
  "currency": "USD",
  "bet_id": "6361622388",
  "transaction_id": "6361622388:coupon_win",
  "timestamp": 1779793300,
  "signature": "HMAC_SHA256_SIGNATURE"
}

Refund

Sent when a coupon is refunded. The refund is added to the matching wallet.

Request payload

{
  "site_key": "oEQnt",
  "sw_key": "oEQnt",
  "username": "demo_user",
  "user_id": "532847997",
  "uid": "532847997",
  "action": "coupon_refund",
  "amount": 10,
  "delta": 10,
  "currency": "USD",
  "bet_id": "6361622388",
  "transaction_id": "6361622388:coupon_refund",
  "timestamp": 1779793400,
  "signature": "HMAC_SHA256_SIGNATURE"
}

Coupon Lost

Sent to record the result of a lost coupon. Delta is usually 0.

Request payload

{
  "site_key": "oEQnt",
  "sw_key": "oEQnt",
  "username": "demo_user",
  "user_id": "532847997",
  "uid": "532847997",
  "action": "coupon_lost",
  "amount": 0,
  "delta": 0,
  "currency": "USD",
  "bet_id": "6361622388",
  "transaction_id": "6361622388:coupon_lost",
  "timestamp": 1779793500,
  "signature": "HMAC_SHA256_SIGNATURE"
}

Cashout

Sent after a successful cashout. The cashout amount is added to the original coupon wallet.

Request payload

{
  "site_key": "oEQnt",
  "sw_key": "oEQnt",
  "username": "demo_user",
  "user_id": "532847997",
  "uid": "532847997",
  "action": "cashout",
  "amount": 10,
  "delta": 10,
  "currency": "USD",
  "bet_id": "6361622388",
  "transaction_id": "6361622388:cashout",
  "timestamp": 1779793600,
  "signature": "HMAC_SHA256_SIGNATURE"
}

Payload Fields

Meaning and usage of callback request fields.

Field	Type	Required	Description
`site_key`	string	Yes	Integration site key.
`sw_key`	string	No	May contain the same value as site_key.
`username`	string	Yes	Username related to the transaction.
`user_id` / `uid`	string	Yes	Unique session user identifier.
`currency`	string	Yes	Wallet code used by the transaction.
`amount`	number	Yes	Transaction amount, always sent as a positive value.
`stake`	number	Balance check	Stake amount checked before bet acceptance.
`delta`	number	Callback	Balance effect: negative for bet place, positive for credit operations.
`action`	string	Callback	`bet_place`, `coupon_win`, `coupon_refund`, `coupon_lost`, `cashout`.
`bet_id`	string	Callback	Coupon identifier.
`transaction_id`	string	Callback	Unique transaction identifier. Duplicate IDs are not processed twice.
`timestamp`	integer	Yes	Unix timestamp used for request lifetime validation.
`signature`	string	Yes	HMAC SHA-256 signature.

Signature

Every callback request is verified with an HMAC SHA-256 signature generated with the API token.

Balance check base

site_key|username|user_id|balance_check|stake_4_decimals|currency|timestamp

Transaction callback base

site_key|username|user_id|action|delta_4_decimals|currency|transaction_id|timestamp

PHP signature example

$base = implode('|', [
  $siteKey,
  $username,
  $userId,
  $action,
  number_format($delta, 4, '.', ''),
  $currency,
  $transactionId,
  $timestamp
]);

$signature = hash_hmac('sha256', $base, $apiToken);

Node.js signature example

const base = [
  siteKey,
  username,
  userId,
  action,
  Number(delta).toFixed(4),
  currency,
  transactionId,
  timestamp
].join('|');

const signature = crypto
  .createHmac('sha256', apiToken)
  .update(base)
  .digest('hex');

Responses

Endpoints return JSON responses.

Callback success

{
  "ok": true,
  "transaction_id": "6361622388:bet_place",
  "username": "demo_user",
  "action": "bet_place",
  "delta": -10,
  "currency": "USD",
  "balance_before": 100,
  "balance_after": 90
}

Duplicate transaction

{
  "ok": true,
  "duplicate": true,
  "transaction_id": "6361622388:bet_place",
  "currency": "USD"
}

Error

{
  "ok": false,
  "error": "bad_signature"
}

Error	Meaning
`invalid_json`	Request body is not valid JSON.
`missing_or_wrong_parameters`	A required field is missing or invalid.
`expired_timestamp`	The timestamp is outside the accepted time window.
`bad_signature`	Signature verification failed.
`user_not_found`	The user could not be found.
`insufficient_wallet_balance`	The selected wallet balance is not enough.
`callback_failed`	Unexpected processing error.

Functions

Core functions included in the integration files.

Function	Role
`alva_currency_allowed_codes()`	Returns supported currency codes.
`alva_currency_code()`	Normalizes and validates the currency value.
`alva_pdo()`	Creates the MySQL connection.
`alva_get_user()`	Finds the user by username.
`alva_create_wallet_schema()`	Prepares wallet and transaction tables.
`alva_wallet_locked()`	Locks the selected wallet row inside a transaction.
`alva_wallet_balance()`	Reads the selected wallet balance.
`alva_wallet_adjust()`	Updates the wallet balance and writes ledger history.
`alva_verify_signature()`	Verifies callback signatures.
`alva_curl_post()` / `alva_curl_get()`	Sends HTTP requests.

Function	Role
`normalizeCurrency()`	Normalizes and validates the currency value.
`ensureSchema()`	Prepares wallet and transaction tables.
`getUser()`	Finds the user by username.
`ensureWallet()`	Creates the wallet if it does not exist.
`lockWallet()`	Locks the selected wallet row inside a transaction.
`sign()`	Creates HMAC SHA-256 signatures.
`verifySignature()`	Verifies callback signatures.
`handleBalanceCheck()`	Processes balance check callbacks.
`handleBalanceCallback()`	Processes bet, win, refund, lost and cashout callbacks.
`handleIframe()`	Creates the iframe session response.

Tables

Wallet and transaction records are managed with the following tables.

Table	Purpose	Important fields
`users`	User record.	`username`, `couponlimit`
`user_wallets`	Currency based wallet balances.	`site_key`, `username`, `currency`, `balance`
`wallet_ledger`	Wallet movement history.	`action`, `delta`, `balance_before`, `balance_after`
`alva_sports_transactions`	Unique callback transactions and duplicate control.	`transaction_id`, `currency`, `action`, `raw_payload`

Integration Steps

Recommended order before production use.

Upload file: Place iframe.php in a public web directory.
Configure: Set database credentials, site key and API token.
Open with currency: Send the currency parameter in the launch URL.
Prepare wallet: Create or fund the user wallet for the selected currency.
Test: Test balance check, bet place, win, refund and cashout callbacks.

Install package: Run npm install.
Fill .env: Set site key, API token and PostgreSQL credentials.
Start service: Run npm start to start src/server.js.
Expose routes: Make /iframe, /iframe/alva_balance_check and /iframe/alva_balance_callback publicly reachable.
Test: Test balance check, bet place, win, refund and cashout callbacks.

Final check: A coupon must always use the same currency for history, cashout and balance updates.