Seamless Wallet/balance

Bakiye sorgulama

Callback · Sağlayıcı → Operatör

POST{callback_url}/balance

Oyun, oyuncunun güncel bakiyesini istediğinde Boss Hub bu uç noktayı çağırır. Çağrı yalnız okuma yapar: bakiye değişmez, işlem kaydı oluşmaz.

Başlıklar

Başlık	Açıklama
Content-Type	application/json
X-Operator-Id	Operatör kimliğiniz
X-Timestamp	Unix saniye. ±30 sn dışını reddedin
X-Signature	hex(HMAC_SHA256(secret, ts + "." + "POST" + "." + path + "." + body)). path, callback adresinizin taban yolu dahil tam yoludur, örn. /bossgaming/bet. Bkz. İmza
X-Request-Id	İsteğin kimliği. Bu çağrı tekrar edilmez
X-Api-Key	Callback’i imzalayan API anahtarınız. Birden çok anahtarınız varsa doğru secret’ı seçer

Gövde parametreleri

player_idstringzorunlu

Operatör tarafındaki oyuncu kimliği.

currencyISO 4217zorunlu

Oturum para birimi: USD, EUR, TRY.

session_idstring

launch ile açılan oyun oturumu.

site_idstring

Site kodu, örn. site_mrd01. Aynı callback adresini paylaşan siteleri ayırt eder.

Yanıt: balance ve currency zorunludur; currency istekteki para birimi olmalıdır. Tanımadığınız oyuncuya ERROR dönün (örn. INVALID_TOKEN). operator_tx_id bu çağrıda gerekmez.

Tek deneme: Bu çağrı tekrar edilmez. OK dışındaki her yanıtta, zaman aşımında veya HTTP 200 dışı yanıtta oyuna bakiye iletilmez; hata kodu oyuna aktarılmaz.

POST /bossgaming/balance HTTP/1.1
Content-Type: application/json
X-Operator-Id: op_meridyen
X-Timestamp: 1762344000
X-Signature: 7be014…c5d8
X-Request-Id: req_01HF3K8P
X-Api-Key: pk_test_…

{
  "player_id": "u_88213",
  "currency": "USD",
  "session_id": "ses_01HF3K7M",
  "site_id": "site_mrd01"
}

200Başarılı yanıt

{
  "status": "OK",
  "balance": 150.60,
  "currency": "USD"
}

200Hata (HTTP 200 + kod)

{
  "status": "ERROR",
  "code": "INVALID_SIGNATURE"
}

İş kuralı hatası da HTTP 200: Reddi (INSUFFICIENT_FUNDS, PLAYER_BLOCKED, LIMIT_EXCEEDED…) HTTP 200 gövdesinde status: ERROR ve code ile verin. HTTP 400, 402, 403, 409 veya 500 ile dönülen yanıt, gövdesinde ne yazarsa yazsın belirsiz sayılır: bahis tekrar edilir ve otomatik rollback gelir, kazanç ve rollback takvimle tekrar edilir, bakiye oyuna gitmez. Tek istisna rollback’te 409 TRANSACTION_NOT_FOUND’dur.

Başka her HTTP durumu (3xx, 4xx, 5xx, WAF veya bakım sayfası) da belirsizdir.
status: OK yanıtında currency zorunludur ve istekteki para birimiyle aynı olmalıdır. Eksik veya farklıysa yanıt belirsiz sayılır ve alarm üretilir.
balance: işlem sonrası bakiye; JSON sayısı (148.60) veya sayı metni ("148.60"), en çok iki ondalık, üs (1e3) yok. balance çağrısında zorunludur, diğerlerinde gönderin.
Kendi işlem kimliğinizi operator_tx_id alanında dönün. Yanıta transaction_id koyarsanız istektekiyle aynı olmalıdır.
Çözülemeyen gövde, bilinmeyen status veya code dışı bir hata belirsiz sayılır ve alarm üretir. Tanımadığınız istek alanlarını yok sayın.
İstekteki tutarlar her zaman iki ondalıklı JSON sayısıdır (2.00, 0.00), metin değildir. Gövdeyi kayıpsız okuyun, float kullanmayın.

HTTP	Yanıt gövdesi	Boss Hub ne yapar
200	{"status":"OK","balance":148.60,"currency":"USD","operator_tx_id":"op_tx_9921844"}	Başarılı.
200	{"status":"OK","balance":"148.60","currency":"USD"}	Başarılı. balance sayı metni de olabilir; operator_tx_id isteğe bağlıdır.
200	{"status":"ERROR","code":"INSUFFICIENT_FUNDS","balance":0.40}	Temiz red. Bahis düşülmedi, tur başlamaz, rollback gelmez.
400	{"status":"ERROR","code":"INSUFFICIENT_FUNDS"}	Belirsiz: HTTP 200 değil, gövdeye bakılmaz. Bahis tekrar edilir, sonra otomatik rollback gelir.
200	{"status":"OK","balance":148.60}	Belirsiz + alarm: currency yok.
200	{"status":"OK","balance":148.60,"currency":"EUR"}	Belirsiz + alarm: istek USD idi, para birimi tutmuyor.
200	{"status":"OK","balance":148.605,"currency":"USD"}	Belirsiz + alarm: üç ondalık; en çok iki ondalık olur.
200	{"status":"OK","balance":1.486e2,"currency":"USD"}	Belirsiz + alarm: üslü sayı.
200	{"status":"OK","transaction_id":"tx_other","balance":148.60,"currency":"USD"}	Belirsiz + alarm: transaction_id istektekiyle aynı değil.
200	{"status":"ERROR"}	Belirsiz + alarm: code yok.

Oturum eşleme ve imza yolu

Yetki başlığı yok: Callback’lerde Authorization başlığı ve oyuncu token’ı yoktur. Çağrıyı yalnız X-Signature doğrular; token’ı yalnız authenticate taşır.
`session_id` ile eşleyin: authenticate isteği token ile session_id’yi birlikte getirir. Cüzdanınız token’a bağlıysa o anda session_id → token / oyuncu eşlemesini saklayın. balance, bet, win ve rollback aynı session_id’yi, launch’taki player_id’yi ve site_id’yi taşır.
Oturum kapanmış olabilir: win ve rollback oturumunuz veya token’ınız düştükten sonra da gelir; session_id artık canlı değil diye reddetmeyin. Oyuncuyu player_id ile bulun.
Ters vekil ve taban yol: İmza, Boss Hub’ın çağırdığı adresin tam yolu üzerindendir: callback adresiniz https://casino.example.com/bossgaming ise bahis /bossgaming/bet üzerinden imzalanır. Önünüzdeki vekil, API ağ geçidi veya çatı uygulamanın bağlama noktası öneki kesip uygulamanıza /bet iletiyorsa imzayı /bossgaming/bet ile yeniden kurun (önek ayarınızdan veya X-Forwarded-Prefix’ten) ya da öneki korumasını sağlayın. Boss Hub callback’e sorgu dizesi eklemez; alan adı imzaya girmez.

Hata kodları

Kod	Anlam	Boss Hub davranışı
INVALID_SIGNATURE	İmza doğrulanamadı	Bakiye oyuna iletilmez; portalda Wallet sağlığı ekranında hata olarak görünür
INVALID_TOKEN	Oturum geçersiz, süresi dolmuş veya oyuncu bilinmiyor	Bakiye oyuna iletilmez
PLAYER_BLOCKED	Oyuncu kısıtlı / self-exclusion	Bakiye oyuna iletilmez
INTERNAL_ERROR	Operatör hatası	Bakiye oyuna iletilmez; Wallet sağlığı ekranında hata olarak görünür

Test paketinin imza senaryoları (SIG-01…04) ve REQ-02 bu uca gider. Ayrıntı: Test paketi.

← Öncekiauthenticate Sonraki →bet

Bakiye sorgulama

Başlıklar

Gövde parametreleri

Yanıt kuralları

Oturum eşleme ve imza yolu

Hata kodları