Casplay Sports API
Embed a live sportsbook into your site with an iframe and process every bet through your own wallet (seamless wallet). REST + callback API, Luck Sports compatible.
Casplay never holds player money. On every money movement Casplay calls your wallet (balance / debit / credit). The endpoints, command-based callbacks and response codes follow the Luck Sports format.
Glossary
| Term | Meaning |
|---|---|
| Operator | You — the betting site embedding Casplay. In the panel an operator account is called a “firma”. |
| Reseller | The account that created your operator account, manages your credit/subscription and currency (“bayi” in the panel). |
| Seamless wallet | The player’s money stays with you; Casplay asks your wallet on every bet and payout. |
| userCode / userName | A player’s identity, always operatorCode:player (e.g. acme:john). The prefix routes callbacks to you. |
| gameUrl | The personal launch URL returned by game-url; valid for 120 seconds. Put it into the iframe. |
| trans_id / trans_hist_id | Transaction ids in callbacks (the bet / this payout). Use them for idempotency — see Transaction IDs. |
What you need
- Two secrets from the panel: SPORTS_API_TOKEN and SPORTS_CALLBACK_TOKEN.
- On your server: one small endpoint that returns a gameUrl, and one callback endpoint (getBalance / bet / win).
- In the panel: your callback URL, your server’s public IP, and your site’s domain.
- On your sports page: the iframe snippet below.
Quick start
- Get your tokens. Log in to the panel (/panel) → Integration. Copy SPORTS_API_TOKEN (you → Casplay) and SPORTS_CALLBACK_TOKEN (Casplay → you). Keep both on the server only.
- Save your callback URL. Same tab: the address of your wallet endpoint (e.g. https://yoursite.com/casplay-callback). Leave it empty to test with the built-in demo wallet first.
- Add your server IP. Same tab → Allowed IPs. With an empty list the /v1 API is closed.
- Add your domain. Same tab → Allowed domains (e.g. yoursite.com). Guests are then recognised automatically.
- Set the player language (Overview → Language) — see Languages. The default is Turkish.
- Paste the iframe + server code from Add to your site, then place a small test bet end-to-end.
How it works
- The player opens your sports page (on your site, with your own login).
- Your server requests a game URL — POST /v1/game/game-url for that player → a personal gameUrl valid for 120 s. This call is made from your server so the token stays secret.
- You put the gameUrl into the iframe. On load the launch token is exchanged for a session (sid); the player now sees the sportsbook inside your site.
- The player bets → Casplay calls your bet callback → you debit the wallet. If you refuse (e.g. insufficient balance) the bet is not placed.
- The event settles → Casplay calls win with the winnings / refund / cash-out → you credit the wallet. Lost bets are reported with amount 0.
Who does what
Four parts work together. Knowing who owns what makes integration and support much easier.
Player ─▶ your site (login, deposits) ─▶ iframe: Casplay sportsbook
(odds, bet slip, settlement)
your server ── REST /v1 game-url ─────────────────▶ Casplay
your wallet ◀── callbacks: getBalance / bet / win ── Casplay
| Area | Casplay | You (operator) |
|---|---|---|
| Player accounts & login | — | ✔ your own system; you pass the player to Casplay with game-url |
| Money: balances, deposits, withdrawals | — (never holds money) | ✔ your wallet, called on every bet and payout |
| KYC, responsible gaming, player limits | — | ✔ (you can also refuse a bet in your bet callback) |
| Sports, events, odds, markets | ✔ live feed, updated continuously | — |
| Bet acceptance (odds check, closed markets) | ✔ | you confirm the debit |
| Settlement, refunds, cash-out | ✔ from official results | you credit what we send |
| Sportsbook UI, languages, themes | ✔ | you choose language / theme / design |
| Betting risk limits per operator | ✔ enforced | you set them (optional) |
| Commercial terms (credit / subscription) | your reseller | — |
Add to your site
Embed the iframe once — the game URL is generated on your server for every logged-in player. No manual work per player.
1 · Page code — paste into your sports page
<!-- Paste into your sports page -->
<iframe id="casplay" style="width:100%;height:100vh;border:0" allow="fullscreen"></iframe>
<script>
var f = document.getElementById('casplay');
if (USER_IS_LOGGED_IN) { // ← your own login state (you provide this variable)
// Logged-in player → personal game URL (from your server, token stays secret)
fetch('/casplay-game-url').then(r => r.json()).then(({ gameUrl }) => { f.src = gameUrl });
} else {
// GUEST → plain base URL. Your operator is recognised from the embedding site's domain
f.src = 'https://spor.casplay.net/';
}
</script>
2 · Server code — one endpoint that creates the game URL
// Add to your server (Node/Express) — the API token is SECRET and never leaves the server
app.get('/casplay-game-url', async (req, res) => {
const username = req.session.user // the player logged in on your site
const r = await fetch('https://spor.casplay.net/sportsAPI/v1/game/game-url', {
method: 'POST',
headers: { 'Authorization': 'Bearer {SPORTS_API_TOKEN}', 'Content-Type': 'application/json' },
body: JSON.stringify({ userCode: '{operatorCode}:' + username, language: 'en', domain: req.headers.host })
}).then(x => x.json())
if (r.code !== 0) return res.status(503).json({ error: r.message }) // e.g. account inactive / IP not allowed
res.json({ gameUrl: r.data.gameUrl }) // launch URL for the iframe
})
Replace {operatorCode} with your operator code and {SPORTS_API_TOKEN} with the value from the panel. The domain field is optional (see Generate Game URL).
URL parameters
Optional parameters you can append to the iframe src (guest URL or {gameUrl}&…).
| Parameter | What it does |
|---|---|
| ?f=OPERATOR | Guest fallback: sets the operator context (theme + currency) when domain recognition is not possible. |
| ?lang=xx | Player language (see Languages). Used when your language mode is From API. |
| ?fabgap=<px> | Mobile: height of the floating bet-slip pill from the bottom, so it isn’t hidden behind your site’s bottom navigation. Default 76 (+ iOS safe area). |
| ?accent=…&page=… | Theme colors (see Via iframe URL). |
| ?theme=<b64> | Full theme palette as base64url JSON. |
| ?cpui=2 / 1 / 0 | Preview the new design (2) or the classic one (1) for this player; 0 clears the preview. Without it, the design chosen in your panel is used. |
<!-- Example: operator with a tall mobile bottom bar -->
<iframe src="https://spor.casplay.net/?fabgap=95" style="width:100%;height:100vh;border:0" allow="fullscreen"></iframe>
Languages
The sportsbook — menus, bet slip, messages and market names — is available in 13 languages. Arabic, Persian, Hebrew and Urdu are shown right-to-left automatically.
Dates and times (kick-off times, bet times) are shown in each player’s own device time zone, in the date format of the page language and in 24-hour format — players connecting from different countries each see their local time. No setting is needed; it works inside the iframe as well.
You choose how the language is decided in the panel: Overview → Language → Language source (step-by-step: Changing the language).
| Mode | Behaviour |
|---|---|
| Fixed (default) | Every player sees the language selected in the panel. The default is Turkish — change it if your players use another language. |
| From API | Each player sees the language you send in game-url (or ?lang= on the guest URL). Missing or unsupported values use your fallback language. |
Codes: tr en de fr es pt ar fa he ur hi zh ko — see Language codes. The operator panel has its own language, chosen by each account (see Operator panel).
Currency
Each operator uses one currency, set by your reseller in the panel. Players see all balances and amounts in it; callback amount values are in the same currency. Supported: TRY ₺ USD $ EUR € GBP £ RUB ₽ AZN ₼ UAH ₴ USDT ₮ ARS $ PYG ₲ PEN S/.
Authentication
Two tokens for two directions. Both are in the panel (Integration) and both are secret.
Base URL for all REST calls: https://spor.casplay.net/sportsAPI (the /sportsAPI prefix is optional — https://spor.casplay.net/v1/… works too).
SPORTS_API_TOKEN — REST (you → Casplay)
Authorization: Bearer {SPORTS_API_TOKEN}
Content-Type: application/jsonSent by your server on every /v1 call. Only accepted from your allowed IPs.
SPORTS_CALLBACK_TOKEN — Callbacks (Casplay → you)
Callback-Token: {SPORTS_CALLBACK_TOKEN}
Content-Type: application/jsonSent by Casplay on every callback. Verify it and reject requests without the correct value.
Response codes
Common codes for API calls and callback responses. /v1 always answers HTTP 200; the result is in code.
| Code | Message | Description |
|---|---|---|
| 0 | OK / Success | Request succeeded. |
| 1001 | Authentication / access denied | Invalid token · account inactive · IP not allowed · rate limit · credit limit · subscription expired. The message tells which one — see “Account status & limits”. |
| 1002 | Username not found | Invalid name (2–50 characters: letters, digits, underscore). |
| 1003 | Usercode not found | userCode is not prefixed with your operator code (e.g. "operatorCode:player"), or the player is blocked. |
| 9999 | Unknown Error | Unknown endpoint or error. |
User Create
Returns the player’s user_code (your operator code is added as prefix: test → operatorCode:test) and the current balance from your wallet. Safe to call repeatedly.
Request
POST https://spor.casplay.net/sportsAPI/v1/user/create
Authorization: Bearer {SPORTS_API_TOKEN}
Content-Type: application/json
{ "name": "test" }
name: 2–50 characters, letters / digits / underscore.
Response · 200
{
"code": 0,
"message": "ok",
"data": {
"user_code": "operatorCode:test",
"name": "test",
"balance": 1000
}
}
Errors: 1002 invalid name · 1001 token / IP / account status.
Generate Game URL
The key endpoint. Call it every time a logged-in player opens the sportsbook and put the returned gameUrl into the iframe. The player’s identity inside (balance, bets) comes from this URL.
No third-party cookies needed: the session travels in the iframe URL, so it works in Safari and in browsers that block third-party cookies. Treat the iframe address as private — don’t log or share it.
Session length: a session is valid for 24 hours after launch (reloading the page does not extend it). After that the player appears logged out inside the iframe until your page requests a new gameUrl — which normally happens on the next page load.
Request
POST https://spor.casplay.net/sportsAPI/v1/game/game-url
Authorization: Bearer {SPORTS_API_TOKEN}
Content-Type: application/json
{
"userCode": "operatorCode:test",
"language": "en",
"domain": "yoursite.com"
}
| Field | Required | Description |
|---|---|---|
| userCode | yes | operatorCode:player — must start with your operator code. |
| language | no | Player language (en, tr, de …). Applied only when your language mode is From API; otherwise the fixed panel language is used. See Languages. |
| domain | no | The domain your site runs on. If it isn’t in your allowed-domain list yet, it is added automatically — useful for domain rotation. A domain can belong to one operator only (otherwise skipped); the list keeps the latest 50. |
Response · 200
{
"code": 0,
"message": "ok",
"data": {
"gameUrl": "https://spor.casplay.net/embed?token=eyJhbGciOi..."
}
}
iframe
<iframe src="{gameUrl}" style="width:100%;height:100vh;border:0" allow="fullscreen"></iframe>
Errors: 1003 “Usercode not found” (prefix doesn’t match) or “User is blocked” · 1001 token / IP / account status.
Callbacks — overview
The money side. Casplay sends a POST to the single callback URL saved in your panel. The command field says what is needed:
| command | When | You |
|---|---|---|
| getBalance | Page load / balance refresh | Return the player’s balance |
| bet | The player places a bet | Debit the amount (refuse if insufficient) |
| win | A bet settles (win, loss, refund, cash-out) or a debit is rolled back | Credit the amount (0 = information only) |
- Verify the Callback-Token header on every request.
- Always answer HTTP 200 with JSON { "code": 0, … }. Any other HTTP status or code ≠ 0 counts as a refusal.
- Answer within ~8 seconds. On timeout: bet is refused (the bet is not placed), getBalance shows 0, win is queued and retried every 30 seconds until you accept it.
- Be idempotent: bet by trans_id, win by trans_hist_id. A repeated id must return the earlier answer without moving money again.
- The callback URL must be http(s) and resolve to a public IP — private / internal addresses are blocked (SSRF protection). HTTPS is strongly recommended.
- Refusing a bet with a message containing insufficient / balance shows the player an “insufficient balance” notice with the real balance.
- Callbacks come from 72.61.82.236 — you may allow-list it, but the Callback-Token check is the primary protection (the IP could change in the future; we will announce it).
- Amounts are decimal numbers (up to 2 decimals) in your operator currency; dates are ISO 8601 in UTC.
Example handler
A complete callback endpoint. wallet and tx stand for your own wallet and transaction store.
// Callback endpoint (Node/Express) — getBalance / bet / win. "wallet" and "tx" are your own layers.
app.post('/casplay-callback', express.json(), async (req, res) => {
if (req.get('Callback-Token') !== process.env.SPORTS_CALLBACK_TOKEN)
return res.json({ code: 1001, message: 'Invalid callback token' })
const { command, data } = req.body
if (command === 'getBalance') { // note: userName (capital N)
const balance = await wallet.balance(data.userName)
return res.json({ code: 0, message: 'success', data: { balance } })
}
if (command === 'bet') { // DEBIT — idempotency key: trans_id
const done = await tx.find(data.trans_id); if (done) return res.json(done)
const bal = await wallet.balance(data.username)
if (bal < data.amount) return res.json({ code: 1, message: 'Insufficient balance', data: { balance: bal } })
const balance = await wallet.debit(data.username, data.amount)
const out = { code: 0, message: 'OK', data: { name: data.username, balance } }
await tx.save(data.trans_id, out); return res.json(out)
}
if (command === 'win') { // CREDIT — idempotency key: trans_hist_id
const done = await tx.find(data.trans_hist_id); if (done) return res.json(done)
const balance = data.amount > 0 ? await wallet.credit(data.username, data.amount) : await wallet.balance(data.username)
const out = { code: 0, message: 'OK', data: { name: data.username, balance } }
await tx.save(data.trans_hist_id, out); return res.json(out)
}
res.json({ code: 9999, message: 'Unknown command' })
})
Callback · Get Balance
Read-only: return the current balance of userName.
Casplay → you
Callback-Token: {SPORTS_CALLBACK_TOKEN}
Content-Type: application/json
{
"command": "getBalance",
"data": { "userName": "operatorCode:test" }
}
Your response · 200
{
"code": 0,
"message": "success",
"data": { "balance": 1500 }
}
Callback · Bet
Debit amount. Return code ≠ 0 to refuse; the bet is then not placed. balance in your answer is the balance after the debit.
Casplay → you
Callback-Token: {SPORTS_CALLBACK_TOKEN}
Content-Type: application/json
{
"command": "bet",
"data": {
"username": "operatorCode:test",
"amount": 20,
"trans_id": "combo-1790123456789-k3d9:stake",
"betList": [ /* see betList structure */ ]
}
}
Your response · 200
{
"code": 0,
"message": "OK",
"data": { "name": "operatorCode:test", "balance": 480 }
}
Refusal example: { "code": 1, "message": "Insufficient balance", "data": { "balance": 12.5 } }
Callback · Win
Credit amount (winnings, refund or cash-out value). balance in your answer is the balance after the credit.
- Lost bet (single, combo or system combination): sent with amount: 0 and betList status 2 — information only, the stake was already debited. Use it to close the bet on your side.
- Rollback: if the debit succeeded but the bet could not be recorded, the stake is returned with a win whose ids end with :rollback — credit it like any other win.
- betList can be empty for some refunds.
Casplay → you
{
"command": "win",
"data": {
"username": "operatorCode:test",
"amount": 70.4,
"trans_id": "combo-1790123456789-k3d9:stake",
"trans_hist_id": "combo-1790123456789-k3d9:win",
"betList": [ /* status 1 = win */ ]
}
}
Your response · 200
{
"code": 0,
"message": "OK",
"data": { "name": "operatorCode:test", "balance": 550.4 }
}
Transaction IDs
trans_id identifies the debit (the bet slip); trans_hist_id identifies this payout. Use trans_id to find the bet and trans_hist_id for win idempotency.
| Callback | trans_id | trans_hist_id | amount |
|---|---|---|---|
| bet | <slip>:stake | — | stake (total of the slip) |
| win · won | <slip>:stake | <bet>:win | payout |
| win · lost | <slip>:stake | <bet>:loss | 0 |
| win · refund | <slip>:stake | <bet>:void | stake back |
| win · cash-out | <slip>:stake | <bet>:cashout | cash-out value |
| win · rollback | <slip>:rollback | <slip>:rollback | stake back |
<slip> starts with bet-, combo- or sys-. <bet> is the single’s id, the combo id, or a system combination id (sys-…-c0, sys-…-c1 …).
Bet lifecycle & failures
Normal path
- The player adds selections and presses Place bet. Casplay checks that the markets are still open and takes the current odds.
- Casplay sends bet → you debit and answer code: 0 → the bet is recorded as open.
- When the events finish, Casplay settles from official results and sends win (winnings, amount 0 for a loss, refund or cash-out value).
- The player may close the page at any time — open bets still settle and pay out.
What happens when something fails
| Situation | What Casplay does | What you do |
|---|---|---|
| You refuse the bet (code ≠ 0) | Bet is not placed; the player sees the reason (e.g. insufficient balance). | Nothing. |
| Your bet endpoint is slower than 8 s, errors or is unreachable | Bet is not placed. It is never settled and never retried. | If your system did debit, refund it yourself — no bet exists for that trans_id. Keep the bet endpoint fast. |
| Your debit succeeded but Casplay could not record the bet | Returns the stake with a win (:rollback). | Credit it like any win. |
| Your win endpoint fails or is down | The payout is queued and retried every 30 s until you accept it. | Fix the endpoint; stay idempotent on trans_hist_id. |
| Your getBalance fails | The player sees balance 0 until it works again; betting still goes through the bet callback. | Check the endpoint / Logs tab. |
| Event cancelled / result not determinable | Refund (:void, status 18). | Credit the refund. |
| Market closed / selection suspended while placing | Bet is refused before any debit; the slip marks the selection. | Nothing. |
| Odds moved | The bet slip refreshes and highlights the new price; the bet is accepted at the current odds, which are the ones sent in betList. | Nothing. |
| Account closed (credit, subscription, inactive) | New bets and /v1 refused; open bets keep settling and paying. | Contact your reseller. |
Bet types
| Type | Rules |
|---|---|
| Single | One selection. Several singles can be placed together (each with its own stake) — one debit, separate settlements. |
| Combo | 2 or more selections, all must win; odds are multiplied. A refunded leg counts as odds 1.00. |
| System K/N | At least 3 selections; every combination of K out of N is a separate combo with the entered stake. Total cost = stake × number of combinations. Each combination settles on its own. |
Asian handicap / total quarter lines (e.g. -0.25, 2.75) can only be played as singles. Markets that cannot be settled reliably are not offered.
Limits
Optional risk limits you set yourself in the panel (Overview → Betting limits). Empty = unlimited. They apply only to your own players.
| Limit | Message shown to the player |
|---|---|
| Max stake | “Maximum stake: X” |
| Max payout | “Potential payout limit (X) exceeded” |
| Max selections per slip | “A bet slip can contain at most X matches” |
Fixed platform limits: ~30 bets per minute per player, ~120 /v1 requests per minute per IP.
Settlement & cash-out
- Bets are settled automatically from official results, usually within a few minutes after the event (some markets wait for the confirmed result).
- If an event is cancelled or its result cannot be determined, the stake is refunded (status 18).
- Cash-out: players can close an open bet early when an offer is available; the value is based on the current odds. It is paid with a win (:cashout, status 4).
- Open bets keep settling and paying out even if your account is closed for new bets (credit limit, subscription end or inactive account).
Settings & changes — who can change what
Most settings are changed by you in the operator panel; money-related ones by your reseller. Nothing needs a new deployment on our side, and open bets are never affected — they always settle and pay out.
| Setting | Who | Where | Takes effect |
|---|---|---|---|
| Player language | You | Overview → Language | Next page load / next game-url |
| Color theme | You | Color Theme | Next page load |
| Design (classic / new) | You (and the platform admin) | Overview → New design | Next page load |
| Currency | Reseller | Reseller panel (currency badge next to your name) | Immediately |
| Callback URL | You | Integration | Next wallet call |
| Tokens | You | Integration → Regenerate tokens | Immediately (old tokens stop) |
| Allowed IPs / domains | You (domain check on/off: platform admin) | Integration | Immediately |
| Betting limits | You | Overview → Betting limits | Next bet |
| Block a player | You | Users | Immediately |
| Credit, commission rate, subscription days, billing model | Reseller | Reseller panel | Immediately |
| Account active / inactive | Reseller (reseller accounts: platform admin) | Reseller / admin panel | Immediately |
| Panel language | Each account for itself | Top bar of the panel | Immediately |
Changing the language
Step by step
- Panel → Overview → Language card.
- One language for everybody: Language source → Fixed language from this panel, pick the Language, save.
- Multilingual site: Language source → From API (launch language), pick a Fallback language (used when a launch sends no or an unsupported language), save. Then send language in every game-url call.
What changes, and when
- Menus, bet slip, messages, sport and market names switch to the new language on the player’s next page load (an open page switches when the player refreshes or navigates).
- Arabic, Persian, Hebrew and Urdu switch the whole layout to right-to-left automatically.
- Nothing else changes: balances, open bets, theme and currency stay as they are.
Per-player language (From API)
Send the player’s language in every launch:
POST /v1/game/game-url
{ "userCode": "operatorCode:john", "language": "de" }
For guests add ?lang=de to the guest URL. A multilingual site usually sends the language the player currently uses on your site.
• The default is Turkish — if nobody changed it, all players see Turkish.
• In Fixed mode the language field is ignored — switch to From API if you want to send it.
• Use the two-letter codes from Language codes (en, not en-US or English); anything else uses the fallback language.
• The operator panel language is a separate, personal setting (top bar) — it does not change what players see.
Changing the color theme
For all players (panel)
- Panel → Color Theme.
- Click a preset, or open Custom and set the 6 base colors (live preview on the right).
- Save. Players get the new colors on their next page load. Reset to default removes your theme.
For one launch / player (iframe URL)
Append colors to the gameUrl: {gameUrl}&accent=%23e11d48&page=%230b0f19. The theme is remembered for that player’s session; to change it, launch again with other values.
Without reloading (postMessage)
Ideal for a light/dark switch on your site — see Live theme.
Which one wins?
By default the panel theme wins over URL colors. If you want URL colors to win (e.g. different brands on different domains), turn on “Let the iframe URL theme override the panel theme” — see Priority.
• URL colors “don’t work” → a panel theme is saved and the override switch is OFF.
• # must be written as %23 in URLs.
• Only hex, rgb(), hsl() or color names are accepted; invalid values are ignored silently.
• Guests see the default theme → your domain is not in Allowed domains (or the browser strips the referrer — use ?f=).
• Parameters added only to the guest URL are not carried into the gameUrl — add them to both.
Changing the currency
Each operator account has one currency, set by your reseller. Ask your reseller to change it.
• all amounts are shown with the new symbol immediately;
• balances are not converted — your wallet decides the numbers;
• open bets keep their stake and payout numbers;
• your betting limits are numbers too — review them;
• reports show totals in the current currency (history is not converted).
Recommendations
- Choose the currency before going live; change it only when there are no open bets and together with your wallet.
- Several currencies on one site? Use one operator account per currency (each with its own tokens and callback), and launch each player with the account matching their wallet currency.
Switching the design (classic ↔ new)
- Preview first: open a launch with {gameUrl}&cpui=2 — only that player sees the new design.
- Panel → Overview → New design switch. All players get it on their next page load.
- Switching back is instant and safe — bets, balances and settings are shared by both designs.
Theme, language, currency, URL parameters and postMessage work the same in both designs.
Changing the callback URL (demo → live)
With an empty callback URL every player uses the built-in demo wallet. As soon as you save a URL, the next wallet call of every player goes to your wallet.
Moving to a new wallet endpoint
- Payouts that are waiting for a retry go to the new URL — it must recognise the same trans_id / trans_hist_id values (shared idempotency store).
- The new URL must be public, http(s), and answer within 8 s.
- Check it: open a game URL — if the balance shows correctly, getBalance works; then place a small test bet.
Regenerating tokens
Integration → Regenerate tokens replaces both tokens at once:
- /v1 calls with the old SPORTS_API_TOKEN fail immediately (1001 · Authentication token not found).
- Callbacks immediately carry the new SPORTS_CALLBACK_TOKEN — your endpoint must accept it.
Update both values on your servers right after rotating (a short planned window avoids refused launches). Rotate whenever a token may have leaked.
Changing IPs and domains
- New server / new IP: add the new IP first, switch traffic, then remove the old one. An empty list closes the API.
- New domain: add it under Allowed domains before you start embedding there — or send domain in game-url and it is added automatically.
- A domain can belong to one operator only; if it is registered elsewhere it is skipped.
- When your platform admin turns on the domain check, unlisted sites show an “Unauthorised” page — keep the list complete.
Limits and players
- Betting limits (max stake, max payout, max selections): apply to new bets; open bets are not touched. Leave a field empty for no limit.
- Blocking a player (Users tab): game-url returns 1003 · User is blocked and bets are refused; the player’s open bets still settle. Unblocking restores access immediately.
Billing and account changes (reseller)
Your reseller manages the commercial side of your account. You see the result on your panel Overview.
| Change | Effect |
|---|---|
| Credit added / taken back (GGR) | Remaining credit changes at once; if it goes above zero again, a closed account reopens automatically. |
| Commission rate | Used for the commission from now on. |
| Switch to subscription | Unlimited use until the end date; bets from this period do not count for GGR commission. |
| Days added / removed | New end date is calculated automatically; an expired subscription extended again starts from today. |
| Switch back to GGR | Your credit is used again; commission counts only bets placed in the GGR model. |
| Account deactivated | New bets and /v1 are closed (Operator account is inactive); open bets settle and are paid. Reactivation reopens at once. |
Color theme — how it works
All sportsbook colors can be customised per operator. A theme can come from three sources; you choose the priority in the panel.
| Source | How | Scope |
|---|---|---|
| Panel | Panel → Color Theme | All your players |
| iframe URL | ?accent=…&page=… / ?theme= on the iframe src | That launch / player |
| postMessage | From your page, live, without reload | That open iframe |
You only provide 6 base colors; the other shades are derived automatically.
Theme from the panel
The simplest way: Panel → Color Theme — pick one of 20 preset themes or define a custom theme (6 color pickers + live preview). It applies to all your players immediately; no code needed.
The same page has the new design switch (classic ↔ new sportsbook layout) — you can preview the new design first with ?cpui=2.
Guest theme
For visitors who are not logged in, embed the base URL without a token. Your theme and currency are applied automatically from the embedding site’s domain (registered under Integration → Allowed domains):
<iframe src="https://spor.casplay.net/" style="width:100%;height:100vh;border:0" allow="fullscreen"></iframe>
Theme via iframe URL
For a per-player / per-embed theme, add color parameters to the gameUrl.
Individual colors
<iframe src="{gameUrl}&accent=%237c5cfc&page=%230a0910&card=%2314121d&ink=%23f6f5fb&odd=%2335d29a&live=%23ff4066"
style="width:100%;height:100vh;border:0"></iframe>
%23 = # (hex colors are URL-encoded). Add only the keys you want to change.
Full palette (base64)
<iframe src="{gameUrl}&theme=<base64url(JSON palette)>" ...></iframe>
Live theme (postMessage)
Change colors of an open iframe without reloading — e.g. when your site switches between light and dark mode:
document.getElementById('casplay').contentWindow.postMessage(
{ type: 'casplay-theme', theme: { accent: '#e11d48', page: '#0b0f19', card: '#141a2a', ink: '#f5f7fb' } },
'*'
)
Same keys as the URL theme. Works in both the classic and the new design.
Priority & override
Panel theme or iframe-URL theme? Set it in Color Theme → “Let the iframe URL theme override the panel theme”.
| Switch | Priority (left wins) |
|---|---|
| OFF (default) | panel theme → iframe URL → default |
| ON | iframe URL → panel theme → default |
IP whitelist
Panel → Integration → Allowed IPs. SPORTS_API_TOKEN is accepted only from these server IPs.
Enter your server’s public outbound IP (not a browser IP). IPv4 and CIDR (203.0.113.0/24) are supported; IPv6 addresses must match exactly.
Allowed domains
Controls which sites may embed the sportsbook. On a site that is not allowed, players see an “Unauthorised” page instead of the sportsbook.
- You manage the list (Integration → Allowed domains). A domain covers its sub-domains (yoursite.com → m.yoursite.com). One domain can belong to one operator only.
- Domain check off (default): no restriction — the list is still used to recognise guests.
- Domain check on (switched by the platform admin): only listed domains can embed. Fail-closed: with an empty list the sportsbook opens nowhere.
Login requirement
Only players launched with game-url (identity operatorCode:player) can bet. Visitors without a token are guests: they can browse, the bet slip asks them to log in.
You can block individual players in the panel (Users tab): game-url then returns 1003 · User is blocked and bets are refused.
Account status & limits
Your token and IP can be correct and a request can still be refused for operational reasons. The code is usually 1001; the message tells which reason applies.
| Status | Response (message) | What to do |
|---|---|---|
| Rate limit | /v1: “Rate limit exceeded” · bet: HTTP 429 | Slow down: ~120 /v1 requests/min per IP, ~30 bets/min per player. |
| Credit limit reached | /v1: “GGR credit limit exceeded” · bet: “Operator credit exhausted” | GGR model: your credit is used up. Ask your reseller to add credit — it reopens automatically. |
| Subscription expired | /v1: “Subscription expired” · bet: “Betting is temporarily closed” | Subscription model: the period has ended. Ask your reseller to extend it — it reopens automatically. |
| Account inactive | /v1: “Operator account is inactive” · bet: “Betting is temporarily closed” | Your account (or your reseller’s account) has been deactivated. Contact your reseller. |
| IP not allowed | “IP not allowed” / “IP whitelist empty” | Add your server’s public IP under Allowed IPs. |
| Player blocked | game-url: 1003 “User is blocked” | You blocked this player in the Users tab; unblock to allow again. |
Billing models
Your reseller chooses one of two models for your account. You can see yours on the panel Overview.
| Model | How it works |
|---|---|
| GGR | Your reseller loads credit. Commission = real GGR (stakes − payouts) × commission rate; it is deducted from the credit. When the remaining credit falls below zero, new bets and /v1 are closed. |
| Subscription | Unlimited use until the end date (no credit or commission). The panel shows the days left and warns during the last 3 days. When it ends, new bets and /v1 are closed. |
In every closed state, open bets still settle and are paid to your wallet.
Operator panel
https://spor.casplay.net/panel — log in with the credentials from your reseller. Each account chooses its own panel language (13 languages) from the top bar.
| Tab | What you do there |
|---|---|
| Overview | Billing status (credit or subscription), betting limits, player language, new design switch. |
| Users | Your players with balance and bet count; block / unblock players. |
| Integration | Tokens (copy / rotate), callback URL, allowed IPs, allowed domains, ready-to-paste code. |
| Color Theme | Preset or custom theme, iframe-URL override switch. |
| GGR History | Credit and subscription movements on your account. |
| Game History | All bets of your players with status, payout and legs. |
| Reports | Turnover, GGR and commission for any date range, per day. |
| Logs | Integration events: game-url calls, refused bets with reason, IP / domain problems, wallet errors. |
Testing (demo wallet)
Leave the callback URL empty to test without your wallet: Casplay then uses a built-in demo wallet — every player starts with 10,000, no real money is involved.
- Get a game-url, open it in the iframe, place bets and watch balance, wins, refunds and cash-outs.
- Try your theme, language and guest view.
- When ready, save your callback URL — from then on every balance and money movement goes through your real wallet.
Go-live checklist
- Callback URL saved (public, HTTPS), token verified, answers within 8 s, idempotent on trans_id / trans_hist_id.
- Allowed IPs contain your server’s public IP; allowed domains contain every domain you embed on.
- Player language set (Fixed or From API) and currency confirmed with your reseller.
- Theme and design chosen; mobile bottom bar checked (?fabgap=).
- One real end-to-end test with a small amount: bet → debit → settlement → credit; check the Logs tab for errors.
Troubleshooting
Most answers are visible in the panel Logs tab — every refused launch or bet is logged with its reason.
| Symptom | Cause and fix |
|---|---|
| Players see Turkish | Language mode is Fixed with Turkish (the default). Pick your language, or switch to From API and send language. |
| language is ignored | Mode is Fixed, or the code is not a two-letter code from the list. |
| Theme / colors not applied | Panel theme wins while the override switch is OFF; # not encoded as %23; the player needs a new launch for new URL colors. |
| Guests see the default theme or wrong currency | Domain not in Allowed domains, or referrer stripped → add the domain or use ?f=OPERATOR_CODE. |
| “Unauthorised” page inside the iframe | Domain check is on and this site isn’t listed — add the domain. |
| Balance shows 0 | getBalance fails: wrong URL, token check rejects, non-200 answer, answer slower than 8 s, or the URL resolves to a private IP. |
| “Insufficient balance” although the player has money | Your bet callback returned code ≠ 0, timed out, or returned a wrong balance. |
| “Betting is temporarily closed” | Account closed: subscription expired, account (or reseller) inactive — see Account status. |
| game-url returns IP not allowed | Add your server’s public outbound IP (behind NAT / cloud it differs from the server’s local IP). |
| A win was not received | It is retried every 30 s until your endpoint answers code: 0 with HTTP 200 — check your endpoint errors. |
| A win was credited twice | Your endpoint does not de-duplicate trans_hist_id — see Transaction IDs. |
| Bet slip hidden behind your mobile bottom bar | Increase ?fabgap= (e.g. 95) on both the guest URL and the gameUrl. |
| URL parameters lost after login | Add them to the gameUrl as well, not only to the guest URL. |
| Player suddenly appears logged out in the iframe | The 24-hour session ended — make sure your page requests a fresh gameUrl on every page load (don’t cache it). |
betList structure
Every bet / win callback carries a betList describing the bet — use it for your own bet history. Not required to process the callback.
"betList": [
{
"id": "combo-1790123456789-k3d9",
"type": 1,
"status": 0,
"totalStake": 20,
"totalOdds": 3.52,
"selections": [
{
"status": 0,
"price": 1.60,
"name": "Arsenal — Chelsea · Full-time result · Arsenal @ 1.60",
"marketName": "Full-time result",
"eventName": "Arsenal vs Chelsea",
"eventDate": "2026-10-04T16:30:00.000Z",
"sportTypeId": 1,
"eventScore": ""
},
{
"status": 0,
"price": 2.20,
"name": "Lakers — Celtics · Total points · Over 220.5 @ 2.20",
"marketName": "Total points",
"eventName": "Lakers vs Celtics",
"eventDate": "2026-10-05T01:00:00.000Z",
"sportTypeId": 12,
"eventScore": ""
}
]
}
]
| Field | Description |
|---|---|
| id | Bet id (single id, combo id or system combination id). |
| type | 0 single · 1 multiple (combo and system combinations). |
| status | Bet status code (see below). |
| totalStake | Stake of this bet. |
| totalOdds | Total odds (product of the selections). |
| selections[] | status price name marketName eventName eventDate sportTypeId eventScore. |
For a system bet the bet callback lists all selections in one item; each combination is then settled with its own win and betList.
name, marketName and eventName are written in the player’s language (your fixed language, or the language sent at launch in API mode). They are display text — do not parse them; use id, status and price for logic.
Bet status codes
| Code | Status | Description |
|---|---|---|
| 0 | Bet | Bet placed (stake debited). |
| 1 | Win | Bet won (payout credited). |
| 2 | Lose | Bet lost (reported with amount 0). |
| 4 | CashOut | Cashed out early by the player. |
| 18 | Refund | Refunded (event cancelled / result not determinable). |
Sport type IDs
sportTypeId values in betList selections.
| ID | Sport |
|---|---|
| 1 | Football |
| 4 | Tennis |
| 12 | Basketball |
| 17 | Handball |
| 19 | Volleyball |
| 317 | eSports |
| 34 | Table Tennis |
| 20 | American Football |
| 5 | Rugby |
| 35 | Badminton |
| 21 | Cricket |
| 91 | Boxing |
| 118 | MMA |
| 90 | Darts |
| 0 | Other sports |
Theme color keys
The 6 base colors (panel, iframe URL or postMessage). 13 further shades are derived automatically. Values are hex (#rrggbb).
| Key | Meaning |
|---|---|
| accent | Accent / main brand color (buttons, selected odd, links) |
| page | Page background |
| card | Card / panel surface |
| ink | Main text color |
| odd | Odds / positive tone (winnings, green) |
| live | Live / negative tone (red, live badge) |
Derived keys (can also be set explicitly): accent2 accentSoft card2 card3 line ink2 muted oddbg good up down red warn.
Language codes
| Code | Language | |
|---|---|---|
| tr | Türkçe | Turkish |
| en | English | English |
| de | Deutsch | German |
| fr | Français | French |
| es | Español | Spanish |
| pt | Português | Portuguese |
| ar | العربية | Arabic (RTL) |
| fa | فارسی | Persian (RTL) |
| he | עברית | Hebrew (RTL) |
| ur | اردو | Urdu (RTL) |
| hi | हिन्दी | Hindi |
| zh | 中文 | Chinese (Simplified) |
| ko | 한국어 | Korean |
Currency codes
| Code | Symbol |
|---|---|
| TRY | ₺ |
| USD | $ |
| EUR | € |
| GBP | £ |
| RUB | ₽ |
| AZN | ₼ |
| UAH | ₴ |
| USDT | ₮ |
| ARS | $ |
| PYG | ₲ |
| PEN | S/ |
Casplay Sportsbook · Seamless Wallet · Base URL https://spor.casplay.net/sportsAPI
Error reporting & liability
If you notice an error you believe is caused by our system (wrong odds, wrong settlement, wrong cash-out amount, missing or excess payments, etc.), simply report it to us.
- Reporting window: within 24 hours of the error occurring. Include the relevant transaction IDs (trans_id) and player codes and a short description.
- Compensation: for errors reported within this window and confirmed by our review to be caused by us, your net loss is credited to your account according to your plan: as GGR credit on the GGR plan, or as subscription time on the subscription plan. No cash refunds are made.
- Net loss is the amount remaining after deducting what can be recovered from the players who benefited from the error. Where an error has been knowingly and repeatedly exploited, we expect you to recover the related payouts from those players.
- We accept no liability for losses arising from errors not reported in time (within 24 hours).