Seamless Wallet/bet

Bahis (debit)

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

POST{callback_url}/bet

Oyuncu bir tur başlattığında Boss Hub, bahis tutarını oyuncunun bakiyesinden düşmeniz için bu uç noktayı çağırır. Temiz yanıt gelmezse (zaman aşımı, 5xx, INTERNAL_ERROR) istek hemen tekrar edilir: varsayılan olarak her deneme 3 sn bekler ve 2 tekrar yapılır, tümü en çok 20 sn içinde. Yine sonuç alınamazsa bahis iptal edilir ve rollback gönderilir.

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	Bu çağrının kimliği. Tekrar denemelerde aynı kalır
X-Api-Key	Callback’i imzalayan API anahtarınız. Birden çok anahtarınız varsa doğru secret’ı seçer

Gövde parametreleri

transaction_idstringzorunlu

Benzersiz işlem kimliği, idempotency anahtarı. Biçimi tx_<tur>-b1 gibidir; kimliği ayrıştırmayın.

round_idstringzorunlu

Oyun turu. Aynı tura ait bet/win işlemlerini bağlar.

session_idstringzorunlu

launch ile açılan oyun oturumu.

player_idstringzorunlu

Operatör tarafındaki oyuncu kimliği.

game_idstringzorunlu

Oyun kodu, örn. sultans-ember.

amountdecimal(18,2)zorunlu

Düşülecek tutar, oturum para biriminde; iki ondalıklı JSON sayısı. Free round bahsinde 0.00.

currencyISO 4217zorunlu

Oturum para birimi: USD, EUR, TRY.

site_idstring

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

is_freeroundboolean

true ise free round dönüşüdür: amount 0’dır, bakiyeden bir şey düşmeyin.

campaign_idstring | null

Boss Hub free round kampanyası. Normal bahiste ve sağlayıcının Boss Hub kampanyası dışında kendi yürüttüğü free round’da null.

freeround_bet_valuedecimal(18,2)

Yalnız free round bahsinde: dönüşün nominal bahis değeri. Sağlayıcının kendi free round’unda değeri bildirmediyse gelmez.

freeround_grant_idstring

Yalnız free round bahsinde: oyuncunun kampanyadaki hakkının kimliği.

jackpotobject | null

Bahiste her zaman null.

round_closedboolean

Tur bu işlemle kapanıyorsa true. Çağrı oluşturulduğu andaki değerdir, tekrarlarda değişmez.

created_atdate-time

İşlemin oluştuğu an (UTC).

Idempotency: Oyuncu kaydını kilitleyin, sonra transaction_id’ye bakın. Aynı kimlik aynı gövdeyle gelirse bakiyeyi tekrar düşmeyin, ilk yanıtı aynen döndürün. Aynı kimlik farklı gövdeyle gelirse DUPLICATE_TRANSACTION dönün. Kimlik için önce bir rollback geldiyse TRANSACTION_ROLLED_BACK dönün ve düşmeyin. Reddettiğiniz bir kimlik yeniden gelirse baştan değerlendirin.

Para birimi: Oyuncunun para birimi ilk launch’ta sabitlenir; Boss Hub oturum para birimi dışında bahis göndermez. Yine de currency cüzdanınızınkiyle uyuşmazsa düşmeyin ve ERROR dönün (test paketi BET-03).

POST /bossgaming/bet HTTP/1.1
Content-Type: application/json
X-Operator-Id: op_meridyen
X-Timestamp: 1762344000
X-Signature: 9f2c0b…e41a
X-Request-Id: req_01HF3KA2
X-Api-Key: pk_test_…

{
  "transaction_id": "tx_01HF3K9QZ2-b1",
  "round_id": "rnd_01HF3K9QZ2",
  "session_id": "ses_01HF3K7M",
  "site_id": "site_mrd01",
  "player_id": "u_88213",
  "game_id": "sultans-ember",
  "amount": 2.00,
  "currency": "USD",
  "is_freeround": false,
  "campaign_id": null,
  "jackpot": null,
  "round_closed": false,
  "created_at": "2026-11-05T14:22:05.120Z"
}

200Başarılı yanıt

{
  "status": "OK",
  "balance": 148.60,
  "currency": "USD",
  "operator_tx_id": "op_tx_9921844"
}

200İş kuralı hatası (HTTP 200 + kod)

{
  "status": "ERROR",
  "code": "INSUFFICIENT_FUNDS",
  "balance": 0.40
}

Yanıt kuralları

İş 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.

Idempotency örneği

→ POST /bossgaming/bet  transaction_id: tx_01HF3K9QZ2-b1  amount: 2.00
← 200 {"status":"OK","balance":148.60,"currency":"USD","operator_tx_id":"op_tx_9921844"}
  (yanıt yolda kayboldu; Boss Hub aynı gövde ve aynı X-Request-Id ile tekrar dener)

→ POST /bossgaming/bet  transaction_id: tx_01HF3K9QZ2-b1  amount: 2.00
← 200 {"status":"OK","balance":148.60,"currency":"USD","operator_tx_id":"op_tx_9921844"}
  (ilk yanıtın aynısı: ikinci kez düşülmedi, bakiye bu arada değişmiş olsa da 148.60)

→ POST /bossgaming/bet  transaction_id: tx_01HF3K9QZ2-b1  amount: 5.00
← 200 {"status":"ERROR","code":"DUPLICATE_TRANSACTION"}
  (aynı kimlik, farklı gövde)

Tekrar ve otomatik iptal

Zaman aşımı ve tekrar sayısı portalda Uç noktalar & cüzdan kartında seçilir: 3 sn (varsayılan) veya 5 sn; 2 (varsayılan) veya 3 tekrar. Tekrarlar beklemeden yapılır; gövde ve X-Request-Id aynı kalır.
Bahsin toplam süre bütçesi en çok 20 sn’dir (sağlayıcının bütçesi daha kısaysa o). Bütçe dolarsa kalan denemeler yapılmaz.
Belirsiz biten bahis için rollback, son denemenin süresi dolduktan sonra gönderilir. Hiç gönderilmemiş bahis için rollback gitmez.
INVALID_SIGNATURE ve DUPLICATE_TRANSACTION tekrar edilmez: bahis belirsiz kalır, o denemenin zaman aşımı penceresi geçince otomatik rollback gönderilir.
Önceki bir deneme belirsiz kaldıysa sonradan gelen reddiniz (INSUFFICIENT_FUNDS vb.) de belirsiz sayılır: tekrar durur, rollback gönderilir.

Hata kodları

Kod	Anlam	Boss Hub davranışı
INSUFFICIENT_FUNDS	Bakiye yetersiz	Temiz red: tur başlamaz, kod oyuna iletilir, rollback yok
LIMIT_EXCEEDED	Sorumlu oyun limiti aşıldı	Temiz red: tur başlamaz, kod oyuna iletilir
PLAYER_BLOCKED	Oyuncu kısıtlı / self-exclusion	Temiz red: tur başlamaz, kod oyuna iletilir
INVALID_TOKEN	Oturum geçersiz/süresi dolmuş	Temiz red: tur başlamaz, kod oyuna iletilir
TRANSACTION_ROLLED_BACK	Bu kimlik için iptal kaydınız var	Red sayılır, rollback gönderilmez, uyarı üretilir
DUPLICATE_TRANSACTION	Aynı kimlik farklı içerikle	Tekrar yok; otomatik rollback gönderilir, kalem manuel incelemeye düşer (duplicate_conflict)
INVALID_SIGNATURE	İmza doğrulanamadı	Tekrar yok; otomatik rollback, alarm ve güvenlik kaydı
INTERNAL_ERROR	Operatör hatası	Belirsiz: tekrar edilir, sonuç yoksa otomatik rollback

Tüm yanıtların sınıflandırması: Hata kodları.

← Öncekibalance Sonraki →win