Push Gaming Integration Guide

Panduan Integrasi Push Gaming

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

Hubungkan operator, buat pemain, launch Razor Ways, 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.

Gameplay: after launch, the Razor Ways client speaks to this backend over the hive game endpoints. A base spin posts to POST /hive/b2c/game/razorways-01/api/actions-v2 and a feature purchase posts to .../actions-v2/buy-feature, both authenticated by the launch session token. Each spin settles the bet and win through the same wallet gateway.

Gameplay: setelah launch, client Razor Ways berkomunikasi dengan backend ini melalui endpoint hive. Base spin mengirim ke POST /hive/b2c/game/razorways-01/api/actions-v2 dan pembelian fitur ke .../actions-v2/buy-feature, keduanya diautentikasi dengan launch session token. Setiap spin menyelesaikan bet dan win 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 hive gameplay endpoints do not use an operator bearer token; they are authenticated by the opaque launch session token issued by POST /api/v1/game/launch as the lt query parameter, then sent as a bearer token on the spin and buy-feature calls.

Endpoint gameplay hive tidak memakai bearer token operator; autentikasi dilakukan dengan launch session token opaque yang diterbitkan oleh POST /api/v1/game/launch sebagai query lt, lalu dikirim sebagai bearer token pada panggilan spin dan buy-feature.

Required headersHeader wajib
Authorization: Bearer <operator_api_token>
Content-Type: application/json
X-Request-ID: 6ca6a797-a9d6-4b16-ae51-f4184472ba23
Launch URL format (issued by launch)Format launch URL (dari launch)
https://push-gaming.ohmybet.online/games/play/razor-ways.html?lt=<session_token_uuid>

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.

Hive gameplay responses use an actions array carrying wallet snapshot, totals, and the spin steps. They are documented under Gameplay Protocol.

Respons gameplay hive memakai array actions berisi snapshot wallet, total, dan steps spin. Didokumentasikan 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: denominator is 1 (whole rupiah, NOT cents). 100000000 minor units means Rp 100,000,000.
  • USD: denominator is 100. 10000 minor units means USD 100.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 spin bet is an integer in minor units. A feature buy costs bet * costMultiplier / 100 in minor units.
  • IDR: denominator 1 (rupiah utuh, BUKAN sen). 100000000 minor unit berarti Rp 100.000.000.
  • USD: denominator 100. 10000 minor unit berarti USD 100.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 spin adalah integer dalam minor unit. Buy feature berbiaya bet * costMultiplier / 100 dalam minor unit.

Idempotency

reference_id is the operator-scoped idempotency key for debit, credit, deposit, and withdraw. rollback_reference_id is the key for rollback. The game engine reflects every spin as a debit (bet) and an optional credit (win) in the same wallet ledger, using a round-scoped reference.

reference_id adalah idempotency key per operator untuk debit, credit, deposit, dan withdraw. rollback_reference_id adalah key untuk rollback. Game engine mencatat setiap spin sebagai debit (bet) dan opsional credit (win) di ledger wallet yang sama, dengan reference per-round.

  • 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

One production host serves the operator API, the launch URL, the game client, and the hive gameplay endpoints. The documentation host serves this guide and its trial launcher.

Satu host production melayani operator API, launch URL, client game, dan endpoint gameplay hive. Host dokumentasi melayani panduan ini dan trial launcher.

Production hostsHost production
Operator API     https://push-gaming.ohmybet.online/api/v1
Game launch      https://push-gaming.ohmybet.online/games/play/razor-ways.html
Gameplay (hive)  https://push-gaming.ohmybet.online/hive/b2c/game/razorways-01/api
Documentation    https://pushgaming-docs.pages.dev
https://push-gaming.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. The new player starts with a zero balance; fund it with a deposit (transfer mode).

Buat pemain sebelum launch. external_user_id adalah identitas stabil di dalam satu operator. Identitas duplikat menghasilkan USER_ALREADY_EXISTS. Pemain baru memiliki saldo nol; isi dengan deposit (mode transfer).

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": "player001",
  "username": "Player 001",
  "currency": "USD"
}
Success responseRespons sukses
{
  "status": true,
  "code": "SUCCESS",
  "data": {
    "id": "a9375dd8-0973-4bbf-9cf0-cd60f50b2414",
    "operator_id": "<operator_uuid>",
    "external_user_id": "player001",
    "username": "Player 001",
    "currency": "USD",
    "balance_amount": 0,
    "rtp": 96.00,
    "status": "active",
    "created_at": "2026-06-21T12:00:00Z",
    "updated_at": "2026-06-21T12: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 is idle-based and slides on each activity; it expires after 30 minutes of inactivity by default.

Minta launch URL baru dari backend tepercaya Anda, lalu redirect atau buka URL tersebut di browser pemain. Sesi launch berbasis idle dan diperpanjang setiap ada aktivitas; default berakhir setelah 30 menit tanpa aktivitas.

POST/api/v1/game/launch

Request fields

Field request

game_id          string  required  Canonical game id, "razor-ways"
external_user_id string  required  Existing active player
language         string  optional  Letters, '-' or '_'; defaults to "en"
game_id          string  wajib     Game id kanonik, "razor-ways"
external_user_id string  wajib     Pemain aktif yang sudah ada
language         string  opsional  Huruf, '-' atau '_'; default "en"

An unknown game id returns NOT_FOUND. A missing player id returns VALIDATION_ERROR. A player that does not exist returns USER_NOT_FOUND. An inactive player returns USER_INACTIVE.

Game id tidak dikenal menghasilkan NOT_FOUND. Player id kosong menghasilkan VALIDATION_ERROR. Pemain tidak ada menghasilkan USER_NOT_FOUND. Pemain non-aktif menghasilkan USER_INACTIVE.

Request bodyBody request
{
  "game_id": "razor-ways",
  "external_user_id": "player001",
  "language": "en"
}
Success responseRespons sukses
{
  "status": true,
  "code": "SUCCESS",
  "data": {
    "launch_url": "https://push-gaming.ohmybet.online/games/play/razor-ways.html?lt=c462c6f0-70f7-451d-8e33-7940e97d9809"
  }
}
curl
curl -sS https://push-gaming.ohmybet.online/api/v1/game/launch \
  -H "Authorization: Bearer <operator_api_token>" \
  -H "Content-Type: application/json" \
  --data '{
    "game_id":"razor-ways",
    "external_user_id":"player001",
    "language":"en"
  }'

Gameplay Protocol

Protokol Gameplay

After launch, the Razor Ways client initializes a session, then drives spins. Operators do not normally call these endpoints; the client does. The launch session token is sent as a bearer token on the spin and buy-feature calls.

Setelah launch, client Razor Ways menginisialisasi sesi, lalu menjalankan spin. Operator biasanya tidak memanggil endpoint ini; client yang menjalankannya. Launch session token dikirim sebagai bearer token pada panggilan spin dan buy-feature.

  • POST /hive/b2c/game/razorways-01/api/sessions — resolve the session and return the wallet snapshot (balance, funds, sessionId, currencyCode). The launch token is sent in the body as authToken.
  • POST /hive/b2c/game/razorways-01/api/actions-v2 — one base spin. Bearer is the launch token. Body is {"bet":<minor units>,"action":"spin"}.
  • POST .../actions-v2/buy-feature — buy a feature. See Buy Feature.
  • PUT .../actions-v2/{actionId} — settle a pending action by id.
  • POST /hive/b2c/game/razorways-01/api/sessions — resolve sesi dan kembalikan snapshot wallet (balance, funds, sessionId, currencyCode). Launch token dikirim di body sebagai authToken.
  • POST /hive/b2c/game/razorways-01/api/actions-v2 — satu base spin. Bearer adalah launch token. Body {"bet":<minor unit>,"action":"spin"}.
  • POST .../actions-v2/buy-feature — beli fitur. Lihat Buy Feature.
  • PUT .../actions-v2/{actionId} — settle action pending berdasarkan id.

The bet is debited and any win is credited in the same wallet ledger. walletData.walletBalance is always the authoritative server-side balance in minor units.

Bet didebit dan win dikredit di ledger wallet yang sama. walletData.walletBalance selalu balance otoritatif sisi server dalam minor unit.

sessions requestRequest sessions
POST /hive/b2c/game/razorways-01/api/sessions
Content-Type: application/json

{
  "type": "init",
  "igpCode": "pg-com",
  "gameCode": "razorways-01",
  "authToken": "<launch_token>",
  "currency": "USD",
  "lang": "en",
  "mode": "demo",
  "jurisdiction": "NA"
}
sessions responseRespons sessions
{
  "wallet": {
    "balance": 100000000,
    "funds": [{"type": "CASH", "balance": 100000000}]
  },
  "sessionId": "c462c6f0-70f7-451d-8e33-7940e97d9809",
  "currencyCode": "USD"
}
base spin requestRequest base spin
POST /hive/b2c/game/razorways-01/api/actions-v2
Authorization: Bearer <launch_token>
Content-Type: application/json

{"bet": 100, "action": "spin"}
spin responseRespons spin
{
  "actions": [{
    "timestamp": "2026-06-21T19:46:36Z",
    "walletData": {
      "walletBalance": 99999900,
      "walletFunds": [{"balance": 99999900, "type": "CASH"}]
    },
    "availableActions": ["spin"],
    "totalBet": 100,
    "actionId": 4338747140720652,
    "playId": 4338747140720652,
    "hivePlayId": "11248-0107-4338747140720652",
    "actionComplete": false,
    "prevActionId": 0,
    "actionName": "spin",
    "cumulativeWin": 40,
    "autoCompleted": false,
    "endOfPlay": true,
    "nextAllowedPlayTime": "2026-06-21T19:46:38Z",
    "jurisdiction": "NA",
    "steps": []
  }]
}

Buy Feature

Buy Feature

A feature purchase posts to POST .../actions-v2/buy-feature with the launch token as the bearer. The body field is featureId (not buyFeatureId) plus the base bet. The total cost is bet * costMultiplier / 100 in minor units and is returned as featureCost.

Pembelian fitur mengirim ke POST .../actions-v2/buy-feature dengan launch token sebagai bearer. Field body adalah featureId (bukan buyFeatureId) ditambah bet dasar. Total biaya adalah bet * costMultiplier / 100 dalam minor unit dan dikembalikan sebagai featureCost.

POST/hive/b2c/game/razorways-01/api/actions-v2/buy-feature

Feature IDs and cost multipliers

Feature ID dan cost multiplier

featureId        costMultiplier  description
instants-part    5000   Razor Reveal
instants-full    15000  Grand Razor Reveal
three-scatters   7300   Free Spins (6 FS, x1)
four-scatters    8150   Free Spins (8 FS, x3)
five-scatters    16400  Free Spins (10 FS, x5)
six-scatters     46600  Free Spins (10 FS, x10)
random-scatters  15000  Free Spins (random tier)
push-bet-1       300    Push Bet (mystery)
push-bet-2       140    Push Bet (scatter)
push-bet-3       400    Push Bet (mystery + scatter)
converters       6700   Converters into Wild
Request bodyBody request
POST /hive/b2c/game/razorways-01/api/actions-v2/buy-feature
Authorization: Bearer <launch_token>
Content-Type: application/json

{"featureId": "instants-part", "bet": 100}
Response (abridged)Respons (ringkas)
{
  "actions": [{
    "walletData": {"walletBalance": 994900, "walletFunds": [{"balance": 994900, "type": "CASH"}]},
    "totalBet": 100,
    "featureCost": 5000,
    "actionId": 3186667020680573,
    "buyFeatureId": "instants-part",
    "cumulativeWin": 1100,
    "endOfPlay": true,
    "availableActions": ["spin"],
    "jurisdiction": "NA",
    "steps": []
  }]
}

Supported Games

Game Tersedia

The production catalog currently exposes one Push Gaming title, Razor Ways, with the hive gameplay protocol, base spins, and the feature buys listed above.

Katalog production saat ini menyediakan satu judul Push Gaming, Razor Ways, dengan protokol gameplay hive, base spin, dan buy feature di atas.

game_id        razor-ways
name           Razor Ways
rgs game id    razorways-01
provider       pushgaming
protocol       hive actions-v2
launch path    /games/play/razor-ways.html?lt=<session_token>
session path   POST /hive/b2c/game/razorways-01/api/sessions
spin path      POST /hive/b2c/game/razorways-01/api/actions-v2
buy path       POST /hive/b2c/game/razorways-01/api/actions-v2/buy-feature

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        Razor Ways
game_id     razor-ways
player      player001

Razor Ways

slot

Production trial using a dedicated transfer-wallet player on the live VPS.

Trial production menggunakan pemain transfer-wallet khusus di VPS live.

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 spin reflects the bet as a debit row and any win as a 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 spin mencatat bet sebagai row debit dan kemenangan sebagai row 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 razor-ways.
  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 razor-ways.
  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=player001&currency=USD
Success responseRespons sukses
{
  "status": true,
  "code": "SUCCESS",
  "data": {
    "balance_amount": 100000000,
    "currency": "USD",
    "timestamp": "2026-06-21T12: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": "player001",
  "reference_id": "deposit-20260621-0001",
  "amount": 100000000,
  "currency": "USD"
}
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": "player001",
  "reference_id": "withdraw-20260621-0001",
  "amount": 1000000,
  "currency": "USD"
}

Debit & Credit

These provider-neutral wallet operations are used for game financial movement. Debit removes funds; credit adds funds. The game engine uses the same wallet gateway internally with a round-scoped reference of the form round:<actionId>:bet.

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

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": "player001",
  "reference_id": "round:4338747140720652:bet",
  "amount": 100,
  "currency": "USD"
}
Response dataData respons
{
  "transaction_id": "659c881f-8afd-44f5-b35e-57f75dd07aa2",
  "balance_after": 99999900,
  "currency": "USD",
  "timestamp": "2026-06-21T12: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": "player001",
  "original_reference_id": "round:4338747140720652:bet",
  "rollback_reference_id": "round:4338747140720652: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=player001&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 player and verify duplicate creation returns USER_ALREADY_EXISTS.
  • Deposit, balance-check, withdraw, debit, credit, and rollback.
  • Launch razor-ways, perform a spin that wins, and verify both the debit and credit rows exist in the ledger.
  • Buy a feature and verify the featureCost equals bet * costMultiplier / 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 aktif dan pastikan duplikat menghasilkan USER_ALREADY_EXISTS.
  • Uji deposit, balance, withdraw, debit, credit, dan rollback.
  • Launch razor-ways, lakukan satu spin yang menang, lalu pastikan row debit dan credit muncul di ledger.
  • Beli fitur dan pastikan featureCost sama dengan bet * costMultiplier / 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.