Pragmatic Integration Guide

Panduan Integrasi Pragmatic

Connect an operator, create players, launch Sweet Bonanza 1000, and integrate either a transfer or seamless wallet using the production API contract.

Hubungkan operator, buat pemain, launch Sweet Bonanza 1000, dan integrasikan transfer atau seamless wallet menggunakan kontrak API production.

Overview

Gambaran Umum

The authenticated operator determines wallet mode, currency, player ownership, and access. Game launch and wallet endpoints never accept a client-selected wallet strategy.

Operator yang terautentikasi menentukan mode wallet, currency, kepemilikan pemain, dan akses. Endpoint game launch dan wallet tidak menerima strategi wallet pilihan client.

Transfer wallet: this backend owns the playable balance and updates it atomically in PostgreSQL alongside a per-round ledger.

Transfer wallet: backend ini menjadi pemilik saldo bermain dan memperbaruinya secara atomik di PostgreSQL bersama ledger per-round.

Seamless wallet: the operator owns the balance. This backend sends signed callbacks to the operator's configured callback URL on every debit, credit, and rollback.

Seamless wallet: operator menjadi pemilik saldo. Backend ini mengirim callback bertanda tangan ke callback URL operator setiap debit, credit, dan rollback.

Native gameplay: after launch, the Pragmatic game client speaks directly with this backend over the /gs2c/ge/v4/gameService endpoint using action=doInit, doSpin, and doCollect. Every bet, tumble, free spin, and apply step is settled through the same wallet gateway.

Gameplay native: setelah launch, client game Pragmatic berkomunikasi langsung dengan backend ini melalui endpoint /gs2c/ge/v4/gameService dengan action=doInit, doSpin, dan doCollect. Setiap bet, tumble, free spin, dan apply step diselesaikan melalui wallet gateway yang sama.

Authentication

Autentikasi

All operator endpoints under /api/v1/users, /api/v1/game, and /api/v1/wallet require an active API token as a bearer token.

Semua endpoint operator di bawah /api/v1/users, /api/v1/game, dan /api/v1/wallet memerlukan API token aktif sebagai bearer token.

Keep API tokens and secret keys on a trusted server. Never embed them in browser JavaScript, mobile applications, launch URLs, logs, or public repositories.

Simpan API token dan secret key di server tepercaya. Jangan menaruhnya di JavaScript browser, aplikasi mobile, launch URL, log, atau repository publik.

If an operator has an IP allowlist, requests must arrive from an allowed address. X-Request-ID is optional and is returned in the response headers.

Jika operator memiliki IP allowlist, request harus berasal dari alamat yang diizinkan. X-Request-ID opsional dan dikembalikan pada header respons.

The native gameplay endpoint /gs2c/ge/v4/gameService does not use an operator bearer token; it is authenticated by the mgckey the launch URL embeds. The mgckey carries the auth token, style name, and session ID issued by POST /api/v1/game/launch.

Endpoint gameplay native /gs2c/ge/v4/gameService tidak memakai bearer token operator; autentikasi dilakukan dengan mgckey yang tertanam di launch URL. Mgckey membawa auth token, stylename, dan session ID dari POST /api/v1/game/launch.

Required headersHeader wajib
Authorization: Bearer <operator_api_token>
Content-Type: application/json
X-Request-ID: 6ca6a797-a9d6-4b16-ae51-f4184472ba23
Mgckey format (issued by launch)Format mgckey (dari launch)
AUTHTOKEN@<auth_token_hex64>~stylename@<style>~SESSION@<session_uuid>~SN@<sn>

Common Response Format

Format Respons Umum

Every operator API outcome uses HTTP 200 OK. Read the JSON status and code; do not infer the result from HTTP status.

Semua hasil operator API menggunakan HTTP 200 OK. Baca status dan code pada JSON; jangan menentukan hasil dari HTTP status.

A success response has data and no error. An error response has error and no data.

Respons sukses memiliki data tanpa error. Respons gagal memiliki error tanpa data.

Native gameplay responses use a Pragmatic key-value text body (tw=...&balance=...&na=...) and are documented separately under Gameplay Protocol.

Respons gameplay native memakai body teks key-value Pragmatic (tw=...&balance=...&na=...) dan didokumentasikan terpisah di Protokol Gameplay.

SuccessSukses
{
  "status": true,
  "code": "SUCCESS",
  "data": {}
}
Error
{
  "status": false,
  "code": "VALIDATION_ERROR",
  "error": {}
}

Integer Money Rules

Aturan Nominal Integer

All wallet amounts are signed 64-bit JSON integers in minor units. Never send floating-point values or numeric strings. A mutation amount must be from 1 through 1000000000000.

Semua nominal wallet adalah integer JSON 64-bit dalam minor unit. Jangan mengirim floating-point atau string angka. Amount mutasi harus dari 1 sampai 1000000000000.

  • IDR: configured with two decimal places (minor units = cents). 100000 minor units means IDR 1,000.00.
  • Currency: exactly three uppercase ASCII letters and must match the player.
  • Overflow: credits that exceed integer balance capacity are rejected with BALANCE_OVERFLOW.
  • Gameplay: the native doSpin bet is c * l (coin value × lines) in minor units. The wallet sees the same integer amount.
  • IDR: dikonfigurasi dengan dua angka desimal (minor unit = sen). 100000 minor unit berarti IDR 1.000,00.
  • Currency: tepat tiga huruf ASCII kapital dan harus sama dengan currency pemain.
  • Overflow: credit yang membuat saldo melewati kapasitas integer ditolak dengan BALANCE_OVERFLOW.
  • Gameplay: bet doSpin native adalah c * l (coin value × lines) dalam minor unit. Wallet menerima amount integer yang sama.

Idempotency

reference_id is the operator-scoped idempotency key for debit, credit, deposit, and withdraw. rollback_reference_id is the key for rollback. The native game engine uses references shaped round:<round_uuid>:debit and round:<round_uuid>:credit for every bet and settlement.

reference_id adalah idempotency key per operator untuk debit, credit, deposit, dan withdraw. rollback_reference_id adalah key untuk rollback. Game engine native memakai reference berbentuk round:<round_uuid>:debit dan round:<round_uuid>:credit untuk setiap bet dan settlement.

  • Retry an identical request with the same key to receive the original result.
  • Reusing a key with different user, amount, currency, or operation returns IDEMPOTENCY_CONFLICT.
  • One completed transaction can be rolled back only once.
  • A seamless mutation timeout is an unknown outcome. Reconcile it before retrying.
  • Retry request identik dengan key yang sama untuk menerima hasil awal.
  • Memakai ulang key dengan user, amount, currency, atau operasi berbeda menghasilkan IDEMPOTENCY_CONFLICT.
  • Satu transaksi completed hanya dapat di-rollback satu kali.
  • Timeout mutasi seamless adalah hasil yang belum diketahui. Lakukan rekonsiliasi sebelum retry.

Games: Hosts & Base URLs

Game: Host & Base URL

A single production host serves the operator API, the launch URL, the native gameplay endpoint, and the Pragmatic HTML5 client assets. The documentation host serves this guide and its protected trial launcher.

Satu host production melayani operator API, launch URL, endpoint gameplay native, dan aset client HTML5 Pragmatic. Host dokumentasi melayani panduan ini dan trial launcher yang terlindungi.

Production hostsHost production
Operator API     https://pragmatic.ohmybet.online
Game launch      https://pragmatic.ohmybet.online/gs2c/html5Game.do
Native gameplay  https://pragmatic.ohmybet.online/gs2c/ge/v4/gameService
Game assets      https://pragmatic.ohmybet.online/gs2c/common/...
Documentation    https://pragmatic-docs.pages.dev
https://pragmatic.ohmybet.online/api/v1

Create a Player

Buat Pemain

Create the player before launch. external_user_id is the stable identity within one operator. A duplicate identity returns USER_ALREADY_EXISTS.

Buat pemain sebelum launch. external_user_id adalah identitas stabil di dalam satu operator. Identitas duplikat menghasilkan USER_ALREADY_EXISTS.

POST/api/v1/users

Request fields

Field request

operator_id      string  required  Authenticated operator UUID
external_user_id string  required  Stable player identity
username         string  optional  Display name
currency         string  required  Exact uppercase currency
operator_id      string  wajib     UUID operator terautentikasi
external_user_id string  wajib     Identitas pemain yang stabil
username         string  opsional  Nama tampilan
currency         string  wajib     Currency kapital yang tepat
Request bodyBody request
{
  "operator_id": "<operator_uuid>",
  "external_user_id": "player-1001",
  "username": "Player 1001",
  "currency": "IDR"
}
Success responseRespons sukses
{
  "status": true,
  "code": "SUCCESS",
  "data": {
    "id": "7cf96ba7-9bca-4eb8-9823-65423fdc32f1",
    "operator_id": "<operator_uuid>",
    "external_user_id": "player-1001",
    "username": "Player 1001",
    "currency": "IDR",
    "balance_amount": 0,
    "status": "active",
    "created_at": "2026-06-15T12:00:00Z",
    "updated_at": "2026-06-15T12:00:00Z"
  }
}

Launch a Game

Launch Game

Request a fresh launch URL from your trusted backend, then redirect or open it in the player's browser. The launch session expires after 30 minutes by default.

Minta launch URL baru dari backend tepercaya Anda, lalu redirect atau buka URL tersebut di browser pemain. Sesi launch default berakhir setelah 30 menit.

POST/api/v1/game/launch

Request fields

Field request

game_code        string  required  Canonical game symbol, e.g. "vs20fruitswx"
external_user_id string  required  Existing active player
currency         string  required  Must match player currency
stylename        string  optional  Pragmatic skin, e.g. "master_master"
lobby_url        string  optional  Return-to-lobby URL embedded in client
game_name        string  optional  Display name override
game_code        string  wajib     Symbol game kanonik, mis. "vs20fruitswx"
external_user_id string  wajib     Pemain aktif yang sudah ada
currency         string  wajib     Harus sama dengan currency pemain
stylename        string  opsional  Skin Pragmatic, mis. "master_master"
lobby_url        string  opsional  URL kembali ke lobby di client
game_name        string  opsional  Nama tampilan override

Unknown games return NOT_FOUND. Unknown players return USER_NOT_FOUND. Currency mismatch returns CURRENCY_MISMATCH.

Game tidak dikenal menghasilkan NOT_FOUND. Pemain tidak dikenal menghasilkan USER_NOT_FOUND. Currency berbeda menghasilkan CURRENCY_MISMATCH.

Request bodyBody request
{
  "game_code": "vs20fruitswx",
  "external_user_id": "player-1001",
  "currency": "IDR",
  "stylename": "master_master",
  "lobby_url": "https://your-lobby.example/return"
}
Success responseRespons sukses
{
  "status": true,
  "code": "SUCCESS",
  "data": {
    "launch_url": "https://pragmatic.ohmybet.online/gs2c/html5Game.do?jackpotid=0&gname=Sweet+Bonanza+1000&extGame=1&ext=0&cb_target=exist_tab&symbol=vs20fruitswx&jurisdictionID=99&lobbyUrl=&minilobby=false&mgckey=AUTHTOKEN@...~stylename@master_master~SESSION@...~SN@...&tabName=",
    "game_code": "vs20fruitswx",
    "currency": "IDR",
    "session_id": "6e790ffa-a2a3-4ae2-adaa-2ca581ba4863",
    "expires_at": "2026-06-15T12:30:00Z"
  }
}
curl
curl -sS https://pragmatic.ohmybet.online/api/v1/game/launch \
  -H "Authorization: Bearer <operator_api_token>" \
  -H "Content-Type: application/json" \
  --data '{
    "game_code":"vs20fruitswx",
    "external_user_id":"player-1001",
    "currency":"IDR",
    "stylename":"master_master"
  }'

Native Gameplay Protocol

Protokol Gameplay Native

After launch, the Pragmatic HTML5 client posts application/x-www-form-urlencoded requests directly to POST /gs2c/ge/v4/gameService. Operators should not call this endpoint and should not parse or modify its payloads. Responses are Pragmatic-format key-value bodies (tw=...&w=...&na=...).

Setelah launch, client HTML5 Pragmatic mengirim request application/x-www-form-urlencoded langsung ke POST /gs2c/ge/v4/gameService. Operator tidak perlu memanggil, membaca, atau mengubah payload-nya. Respons memakai body key-value format Pragmatic (tw=...&w=...&na=...).

  • action=doInit — first call after launch. Returns reels, paytable, bet levels, ante and bonus-buy availability, balance.
  • action=doSpin — one request per visible frame. Carries c (coin value), l (lines), bl (bet level), and optional pur=0|1 for bonus buy. Streams one tumble or one free-spin frame per request until na=c.
  • action=doCollect — settles the open round, credits the accumulated win, returns the new balance.
  • action=doInit — panggilan pertama setelah launch. Mengembalikan reel, paytable, bet level, ketersediaan ante & bonus buy, saldo.
  • action=doSpin — satu request per frame visual. Membawa c (coin value), l (lines), bl (bet level), dan opsional pur=0|1 untuk bonus buy. Streaming satu tumble atau satu free-spin frame per request sampai na=c.
  • action=doCollect — settle round terbuka, kredit total kemenangan, kembalikan saldo baru.

Each frame includes na=s (next action = spin) when more frames are pending or na=c (next action = collect) when the client must call doCollect. Free spins also carry fs, fsmax, fsmul, fswin, optional rmul (multiplier bombs), and terminal totals fs_total, fswin_total, fsend_total.

Setiap frame menyertakan na=s (next action = spin) saat masih ada frame berikutnya atau na=c (next action = collect) saat client harus memanggil doCollect. Free spins juga membawa fs, fsmax, fsmul, fswin, opsional rmul (multiplier bombs), serta totals terminal fs_total, fswin_total, fsend_total.

doSpin request (form-encoded)Request doSpin (form-encoded)
action=doSpin&symbol=vs20fruitswx&c=10&l=20&sInfo=n&bl=0&index=2&counter=2&mgckey=AUTHTOKEN@...~stylename@master_master~SESSION@...
doSpin response (winning frame)Respons doSpin (frame menang)
tw=10.50&rs_iw=8.00&balance=99,990.00&rs_more=1&index=2&reel_set=0&s_mark=tmb~11:1,11:6,11:12&na=s&l0=0~8.00~1~6~12~17~18~23~27~29&rs_p=0&bl=0&sa=10,8,10,11,5,11&sb=10,4,3,4,9,6&rs_c=1&sh=5&rs_m=1&st=rect&c=10.00&sw=6&sver=5&counter=2&l=20&s=...&w=8.00
Terminal frame (collect)Frame terminal (collect)
tw=10.50&balance=99,990.00&index=4&reel_set=0&na=c&rs_t=2&rs_win=2.50&c=10.00&l=20&w=0.00
doCollect responseRespons doCollect
balance=100,000.50&index=99&balance_cash=100,000.50&balance_bonus=0.00&na=s&sver=5&counter=100

Supported Games

Game Tersedia

The production catalog currently exposes one Pragmatic title with full bonus-buy, ante-bet, and tumble support.

Katalog production saat ini menyediakan satu judul Pragmatic dengan dukungan bonus buy, ante bet, dan tumble lengkap.

game_code            vs20fruitswx
name                 Sweet Bonanza 1000
grid                 6 reels x 5 rows (30 positions)
win system           scatter pay (no paylines)
lines                20 (fixed)
currency             IDR
bet levels (bl)      0 = normal (20x), 1 = ante (25x)
coin values (c)      0.01 .. 50.00 (configured per market)
bonus buy            pur=0 regular (100x bet), pur=1 super (500x bet)
free spins           10 spins, retrigger +5 on 3+ scatter
multiplier bombs     2x .. 1000x, summed at end of tumble sequence
max win              25,000x bet (normal), 20,000x bet (ante)

Live Trial

Coba Langsung

This demo button calls the operator launch API directly and opens the game in a new tab. Production integrations must keep the operator token server-side instead.

Tombol demo ini memanggil API launch operator secara langsung dan membuka game di tab baru. Integrasi production wajib menyimpan token operator di server.

game        Sweet Bonanza 1000
game_code   vs20fruitswx
currency    IDR
player      trial-player-001

Sweet Bonanza 1000

slot

Production trial using a dedicated transfer-wallet player.

Trial production menggunakan pemain transfer-wallet khusus.

Transfer Wallet Flow

Alur Transfer Wallet

Transfer mode stores the authoritative balance locally. Create the player, deposit funds, launch the game, and use the ledger endpoints for audit or controlled corrections. Every doSpin bet and every doCollect settlement is reflected as a debit or credit row in the wallet ledger.

Mode transfer menyimpan saldo utama secara lokal. Buat pemain, deposit dana, launch game, lalu gunakan endpoint ledger untuk audit atau koreksi terkontrol. Setiap bet doSpin dan settlement doCollect tercatat sebagai row debit atau credit di ledger wallet.

  1. Create the player with POST /api/v1/users.
  2. Fund it with POST /api/v1/wallet/deposit.
  3. Launch game vs20fruitswx.
  4. Use balance and transactions for reconciliation.
  5. Rollback one completed debit or credit only when required.
  1. Buat pemain dengan POST /api/v1/users.
  2. Isi dana dengan POST /api/v1/wallet/deposit.
  3. Launch game vs20fruitswx.
  4. Gunakan balance dan transactions untuk rekonsiliasi.
  5. Rollback satu debit atau credit completed hanya bila diperlukan.

Balance

Returns the current authoritative local balance. This read does not create a ledger row.

Mengembalikan saldo lokal utama saat ini. Operasi baca ini tidak membuat row ledger.

GET/api/v1/wallet/balance
external_user_id string required
currency         string required
RequestRequest
GET /api/v1/wallet/balance?external_user_id=player-1001&currency=IDR
Success responseRespons sukses
{
  "status": true,
  "code": "SUCCESS",
  "data": {
    "balance_amount": 10000000,
    "currency": "IDR",
    "timestamp": "2026-06-15T12:00:00Z"
  }
}

Deposit

Credits a transfer player's local balance and creates one completed credit ledger row.

Menambah saldo lokal pemain transfer dan membuat satu row ledger credit berstatus completed.

POST/api/v1/wallet/deposit
operator_id      string  required
external_user_id string  required
reference_id     string  required, unique per operator
amount           integer required, 1..1000000000000
currency         string  required
Request bodyBody request
{
  "operator_id": "<operator_uuid>",
  "external_user_id": "player-1001",
  "reference_id": "deposit-20260615-0001",
  "amount": 10000000,
  "currency": "IDR"
}
Response data fieldsField data respons
id, operator_id, user_id, external_user_id,
wallet_type, type, amount, currency,
balance_before, balance_after, reference_id,
status, failure_code, metadata,
created_at, completed_at

Withdraw

Debits the local balance for an operator-controlled transfer-out. Insufficient funds do not change the balance.

Mengurangi saldo lokal untuk transfer-out yang dikontrol operator. Saldo tidak cukup tidak mengubah balance.

POST/api/v1/wallet/withdraw

The body shape is identical to deposit. Use a new reference_id for every distinct transfer.

Bentuk body sama dengan deposit. Gunakan reference_id baru untuk setiap transfer yang berbeda.

Request bodyBody request
{
  "operator_id": "<operator_uuid>",
  "external_user_id": "player-1001",
  "reference_id": "withdraw-20260615-0001",
  "amount": 1000000,
  "currency": "IDR"
}

Debit & Credit

These provider-neutral wallet operations are used for game financial movement. Debit removes funds; credit adds funds. The native game engine uses the same wallet gateway internally with reference IDs of the form round:<round_uuid>:debit and round:<round_uuid>:credit.

Operasi wallet netral-provider ini digunakan untuk pergerakan finansial game. Debit mengurangi dana; credit menambah dana. Game engine native memakai wallet gateway yang sama secara internal dengan reference ID berbentuk round:<round_uuid>:debit dan round:<round_uuid>:credit.

POST/api/v1/wallet/debit
POST/api/v1/wallet/credit

Unlike deposit and withdraw, these bodies do not contain operator_id.

Berbeda dari deposit dan withdraw, body ini tidak memiliki operator_id.

Debit or credit bodyBody debit atau credit
{
  "external_user_id": "player-1001",
  "reference_id": "round:7cf96ba7-9bca-4eb8-9823-65423fdc32f1:debit",
  "amount": 200000,
  "currency": "IDR"
}
Response dataData respons
{
  "transaction_id": "659c881f-8afd-44f5-b35e-57f75dd07aa2",
  "balance_after": 9800000,
  "currency": "IDR",
  "timestamp": "2026-06-15T12:00:00Z"
}

Rollback

Reverses one eligible completed debit or credit. The backend derives the original amount and currency; do not send them.

Membalik satu debit atau credit completed yang memenuhi syarat. Backend mengambil amount dan currency dari transaksi awal; jangan mengirimkannya.

POST/api/v1/wallet/rollback
Request bodyBody request
{
  "external_user_id": "player-1001",
  "original_reference_id": "round:7cf96ba7-9bca-4eb8-9823-65423fdc32f1:debit",
  "rollback_reference_id": "round:7cf96ba7-9bca-4eb8-9823-65423fdc32f1:rollback"
}
Important codesKode penting
TRANSACTION_NOT_FOUND
TRANSACTION_NOT_ROLLBACKABLE
TRANSACTION_ALREADY_ROLLED_BACK
IDEMPOTENCY_CONFLICT

Transactions

Lists operator-owned ledger rows. Filters are optional. Default limit is 20; maximum limit is 100; maximum offset is 10000.

Menampilkan row ledger milik operator. Filter bersifat opsional. Limit default 20; limit maksimum 100; offset maksimum 10000.

GET/api/v1/wallet/transactions
external_user_id optional
type             optional: credit, debit, rollback
status           optional: pending, completed, failed,
                           reversed, mismatch
reference_id     optional
limit            optional: 1..100
offset           optional: 0..10000
RequestRequest
GET /api/v1/wallet/transactions?external_user_id=player-1001&status=completed&limit=20&offset=0
Response shapeBentuk respons
{
  "status": true,
  "code": "SUCCESS",
  "data": {
    "items": [],
    "limit": 20,
    "offset": 0
  }
}

Transfer Wallet Test Checklist

Checklist Pengujian Transfer Wallet

  • Create one active IDR player and verify duplicate creation returns USER_ALREADY_EXISTS.
  • Deposit, balance-check, withdraw, debit, credit, and rollback.
  • Launch vs20fruitswx, perform a doSpin with a win and a doCollect, and verify both ledger rows exist.
  • Trigger bonus buy (pur=0) and verify the debit amount equals c * l * 100.
  • Repeat identical idempotent requests concurrently and verify one financial effect.
  • Reuse a key with a different amount and expect IDEMPOTENCY_CONFLICT.
  • Verify insufficient debit leaves balance unchanged.
  • Buat satu pemain IDR aktif dan pastikan duplikat menghasilkan USER_ALREADY_EXISTS.
  • Uji deposit, balance, withdraw, debit, credit, dan rollback.
  • Launch vs20fruitswx, jalankan doSpin yang menang dan doCollect, pastikan kedua row ledger ada.
  • Trigger bonus buy (pur=0) dan pastikan amount debit sama dengan c * l * 100.
  • Ulangi request idempotent identik secara concurrent dan pastikan hanya ada satu efek finansial.
  • Pakai ulang key dengan amount berbeda dan harapkan IDEMPOTENCY_CONFLICT.
  • Pastikan debit dengan saldo tidak cukup tidak mengubah balance.

Error Codes

Kode Error

Handle errors by stable code. Do not depend on a human-readable message because public API errors intentionally do not include one.

Tangani error berdasarkan code yang stabil. Jangan bergantung pada pesan untuk manusia karena error API publik memang tidak menyertakannya.