PrefectAPI Integration Guide
One seamless-wallet API for casino, live dealer, slots, sports and matka. This guide walks you through authentication, callbacks, launching games, reporting, and error handling.
Overview #
PrefectAPI provides a single integration that connects your platform to 160+ game providers and 17,000+ games. Instead of integrating each provider separately, you integrate once with PrefectAPI and switch providers on or off from your panel.
The API uses the seamless wallet model — all bets, wins, and rollbacks are settled against your player wallets in real time via HTTPS callbacks. PrefectAPI never holds player funds.
HMAC-SHA256 signatures on every request. IP whitelisting available.
Median latency < 45 ms. Global edge nodes in Mumbai, Singapore, Frankfurt.
Casino, live dealer, sports, matka, slots, mini games — all currencies.
Clear endpoint specs, sample payloads, and error codes for every call.
https://api.preferapi.info/v1 unless stated otherwise.Quick start #
You're five steps away from a live game. Each step links to the relevant section below.
- Get your credentialsYou'll receive an
agent_idandsecret_keyin your panel dashboard. - Configure your callbacksSet your callback endpoint URLs in the panel so PrefectAPI knows where to send balance/bet requests.
- Create a playerRegister a player on your side. PrefectAPI uses
player_idas the identity, so no separate registration call is needed. - Launch a gameCall
POST /game/launchwith the player id and game code. You'll get back a URL to embed in an iframe. - Handle the walletWhen the player bets, PrefectAPI calls your callback. Debit or credit their wallet, and reply with the new balance.
Hello world request
# Launch a Pragmatic Play game for player "P1001" curl -X POST https://api.preferapi.info/v1/game/launch \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "player_id": "P1001", "game_code": "vs20doghouse", "provider": "PRAGMATIC", "currency": "INR", "lang": "en" }'
Authentication #
Every request to the PrefectAPI must include a Bearer token in the Authorization header. The token is issued by the panel and is tied to your account.
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Content-Type: application/json X-Agent-Id: AGT_00123
Rotating your token
Tokens don't expire automatically but can be rotated from the panel at any time. When you rotate, the old token stays valid for 10 minutes to allow rolling deploys, then it's invalidated.
Environments #
Two environments are available. Use sandbox while building and live for production traffic. They use separate credentials, separate wallets, and separate callback endpoints.
| Environment | Base URL | Purpose |
|---|---|---|
| Sandbox | https://sandbox.preferapi.info/v1 | Testing, QA, integration smoke tests |
| Live | https://api.preferapi.info/v1 | Real player traffic, real money |
How the seamless wallet works #
In a seamless wallet, your system owns the player balance. PrefectAPI never holds funds — it simply notifies you when a bet is placed or a win is settled, and you reply with the new balance.
- Player opens a gameYou call
POST /game/launch. PrefectAPI returns a URL to embed in an iframe. - Player places a betPrefectAPI calls your
/callback/betendpoint. You debit the wallet and reply with the new balance. - Player winsPrefectAPI calls
/callback/win. You credit the wallet and reply with the new balance. - Rollback (if needed)For cancelled rounds, PrefectAPI calls
/callback/rollback. You reverse the earlier debit. - ReportingPull your bet history and GGR reports any time via
GET /reports/*.
transaction_id. Always store it and reject duplicates.Callbacks you must implement #
You must expose these HTTPS endpoints on your server. PrefectAPI calls them to sync wallet balances. All responses must be JSON with a status field.
Balance
Ask your system for the current balance of a player. Called at game launch and periodically while a session is open.
Request body
{
"agent_id": "AGT_00123",
"player_id": "P1001",
"currency": "INR",
"signature": "a1b2c3d4..."
}
Expected response
{
"status": "OK",
"balance": 12500.00,
"currency": "INR"
}
Place bet
Called when a player places a bet. Debit the wallet by amount and reply with the new balance. Reject if insufficient funds.
Request body
{
"agent_id": "AGT_00123",
"player_id": "P1001",
"transaction_id": "txn_8f9a2c1d",
"round_id": "rnd_77b21e",
"game_code": "vs20doghouse",
"provider": "PRAGMATIC",
"amount": 100.00,
"currency": "INR",
"signature": "e4f5g6h7..."
}
Expected response
{
"status": "OK",
"balance": 12400.00,
"transaction_id": "txn_8f9a2c1d"
}
Settle bet (win)
Called when a round settles with a win amount. Credit the wallet by amount.
Request body
{
"agent_id": "AGT_00123",
"player_id": "P1001",
"transaction_id": "txn_9a1b3d2e",
"round_id": "rnd_77b21e",
"bet_transaction_id": "txn_8f9a2c1d",
"amount": 450.00,
"currency": "INR",
"signature": "..."
}
Rollback
Called when a bet must be reversed (e.g. provider cancels a round). Reverse the referenced bet_transaction_id.
{
"agent_id": "AGT_00123",
"player_id": "P1001",
"transaction_id": "txn_rollback_01",
"bet_transaction_id": "txn_8f9a2c1d",
"amount": 100.00,
"currency": "INR",
"signature": "..."
}
Launch a game #
Returns a URL that you can load in an iframe. The player then plays inside the iframe with their wallet auto-connected to your callback endpoints.
Body parameters
| Field | Type | Req | Description |
|---|---|---|---|
player_id | string | REQ | Your player's unique ID |
game_code | string | REQ | Game slug, e.g. vs20doghouse |
provider | string | REQ | Provider key, e.g. PRAGMATIC |
currency | string | REQ | ISO code: INR, PKR, BDT, USDT |
lang | string | OPT | ISO 639-1 lang code (default en) |
return_url | string | OPT | Where to send the player when they exit |
lobby_url | string | OPT | Where the iframe "Home" button goes |
curl -X POST https://api.preferapi.info/v1/game/launch \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "player_id": "P1001", "game_code": "vs20doghouse", "provider": "PRAGMATIC", "currency": "INR" }'
<?php $payload = [ 'player_id' => 'P1001', 'game_code' => 'vs20doghouse', 'provider' => 'PRAGMATIC', 'currency' => 'INR', ]; $ch = curl_init('https://api.preferapi.info/v1/game/launch'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $token, 'Content-Type: application/json', ], CURLOPT_RETURNTRANSFER => true, ]); $response = json_decode(curl_exec($ch), true); curl_close($ch); // $response['url'] is the game URL to embed
const res = await fetch('https://api.preferapi.info/v1/game/launch', { method: 'POST', headers: { 'Authorization': `Bearer ${TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ player_id: 'P1001', game_code: 'vs20doghouse', provider: 'PRAGMATIC', currency: 'INR', }), }); const data = await res.json(); console.log(data.url); // embed in iframe
import requests r = requests.post( 'https://api.preferapi.info/v1/game/launch', headers={'Authorization': f'Bearer {TOKEN}'}, json={ 'player_id': 'P1001', 'game_code': 'vs20doghouse', 'provider': 'PRAGMATIC', 'currency': 'INR', }, ) print(r.json()['url'])
Sample response
{
"status": "OK",
"url": "https://play.preferapi.info/launch?token=abc123",
"session_id": "sess_8b21a4c",
"expires_at": "2026-11-10T15:32:00Z"
}
Demo launch #
Same as /game/launch but in demo mode — no wallet, no callbacks, virtual credits. Useful for testing game rendering before going live.
curl -X POST https://api.preferapi.info/v1/game/demo \ -H "Authorization: Bearer $TOKEN" \ -d '{ "game_code": "vs20doghouse", "provider": "PRAGMATIC" }'
Game list #
Fetch the games you have access to. Use the game_code from this list when launching.
| Query param | Type | Description |
|---|---|---|
provider | string | Filter by provider key |
category | string | slots · live_casino · sports · mini_game · matka |
search | string | Free-text search by game name |
limit | int | 1–500, default 50 |
page | int | 1-based, default 1 |
{
"status": "OK",
"total": 175,
"page": 1,
"games": [
{
"game_code": "vs20doghouse",
"name": "Dog House",
"provider": "PRAGMATIC",
"category": "slots",
"thumbnail": "https://cdn.preferapi.info/games/vs20doghouse.jpg"
}
]
}
Bet history #
Paginated list of every bet placed by your players in the range. Includes bet amount, win amount, provider, and transaction IDs.
{
"status": "OK",
"page": 1,
"total_pages": 42,
"bets": [
{
"transaction_id": "txn_8f9a2c1d",
"player_id": "P1001",
"game_code": "vs20doghouse",
"provider": "PRAGMATIC",
"bet_amount": 100.00,
"win_amount": 450.00,
"currency": "INR",
"status": "SETTLED",
"placed_at": "2026-11-10T14:22:11Z"
}
]
}
GGR report #
Aggregate GGR (Gross Gaming Revenue = total bets − total wins) for the range, broken down by provider. Your account is billed from the wallet at your GGR rate (from 5%).
{
"status": "OK",
"currency": "INR",
"total_bets": 1250000.00,
"total_wins": 1180000.00,
"ggr": 70000.00,
"by_provider": [
{
"provider": "PRAGMATIC",
"bets": 500000.00,
"wins": 460000.00,
"ggr": 40000.00
}
]
}
Error codes #
Every error returns HTTP 4xx/5xx with a JSON body containing status, code, and message.
{
"status": "ERROR",
"code": "INSUFFICIENT_FUNDS",
"message": "Player balance is too low for this bet."
}
| Code | HTTP | Meaning |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid Bearer token |
FORBIDDEN | 403 | Token valid but not allowed for this resource |
NOT_FOUND | 404 | Player, game, or transaction not found |
VALIDATION_ERROR | 422 | Missing or malformed field |
INSUFFICIENT_FUNDS | 422 | Bet amount > player balance |
DUPLICATE_TRANSACTION | 409 | Same transaction_id was already processed |
PROVIDER_UNAVAILABLE | 503 | Provider not available for your account |
RATE_LIMITED | 429 | Too many requests — slow down |
INTERNAL_ERROR | 500 | Unexpected server error — retry after a few seconds |
Retry strategy
For 500, 502, 503, and 504, retry with exponential backoff (1s, 2s, 4s, 8s) up to 5 attempts. For 4xx errors do not retry — fix the request instead.
Signature verification #
Every callback from PrefectAPI includes a signature field. It is an HMAC-SHA256 of the JSON body using your secret_key. Verify it before processing — this protects you from forged callbacks.
// $rawBody is the raw JSON string from the request // $signature is the value of the "signature" field $secret = 'YOUR_SECRET_KEY'; $expected = hash_hmac('sha256', $rawBody, $secret); if (!hash_equals($expected, $signature)) { http_response_code(401); echo json_encode(['status' => 'ERROR', 'code' => 'BAD_SIGNATURE']); exit; }
hash_equals (constant-time compare). Never use == for signatures — it leaks timing info.FAQ #
How fast is account activation?
Once your UPI payment is confirmed and the UTR is submitted, your panel is provisioned automatically — usually within a few minutes.
What's the GGR rate?
From 5% on every game — slots, live casino, sports, matka and mini games. The exact rate is set on your account and can be seen in your panel.
Can I resell to sub-users?
Yes. Create sub-users from your reseller panel — each gets their own wallet, login and GGR spread. Up to 200 sub-users per account.
What currencies are supported?
Primary billing currencies: INR (base), PKR (×3), BDT (×3). Player wallets can be any currency your providers accept.
What's the uptime SLA?
99.9% monthly. Status is published at status.preferapi.info.
How do I get support?
Telegram: @Preferapi · WhatsApp: +91 6000658349. Both are staffed 24/7.