Seamless Wallet/rollback
Geri alma (rollback)
Callback · Sağlayıcı → OperatörPOST{callback_url}/rollback
Boss Hub bir bahsi veya kazancı geri almanız için bu uç noktayı çağırır: bet yanıtı alınamadığında, sağlayıcı işlemi iptal ettiğinde veya onaylı bir sonuç iptalinde. Referans işlemi bilmiyorsanız bile OK dönün ve kaydedin.
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 |
Bilinmeyen işlem: Zaman aşımına uğrayan bir bahis sizde hâlâ işleniyor olabilir. ref_transaction_id bilinmiyorsa OK dönün ve kaydedin; aynı kimlikle sonradan gelen bet veya win için TRANSACTION_ROLLED_BACK döndürün. Aksi hâlde bahis işlenir ve oyuncu parasını kaybeder.
Idempotency: Aynı transaction_id aynı gövdeyle tekrar gelirse yeniden iade etmeyin; ilk yanıtı aynen döndürün, güncel bakiyeyi değil. Aynı kimlik farklı gövdeyle gelirse DUPLICATE_TRANSACTION dönün.
Token süresi: Oyuncunun token’ı veya oturumu dolmuş olsa da rollback’i kabul edin; INVALID_TOKEN dönmeyin.
200İşlem geri alındı
{
"status": "OK",
"balance": 150.60,
"currency": "USD",
"operator_tx_id": "op_tx_9921846"
}200Bilinmeyen işlem: OK, kayıt tutuldu
{
"status": "OK",
"balance": 150.60,
"currency": "USD"
}200Belirsiz hata: takvimle tekrar edilir
{
"status": "ERROR",
"code": "INTERNAL_ERROR"
}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.
Bilinmeyen işlemin geri alınması
→ POST /bossgaming/rollback transaction_id: tx_01HF3K9QZ2-r1 ref_transaction_id: tx_01HF3K9QZ2-b1
(sizde tx_01HF3K9QZ2-b1 yok: bahis isteği hâlâ yolda veya hiç ulaşmadı)
← 200 {"status":"OK","balance":150.60,"currency":"USD"}
(ve iptal kaydı tutun: tx_01HF3K9QZ2-b1)
→ POST /bossgaming/bet transaction_id: tx_01HF3K9QZ2-b1 amount: 2.00
(geç ulaşan bahis isteği)
← 200 {"status":"ERROR","code":"TRANSACTION_ROLLED_BACK","balance":150.60}
(düşmeyin)Ne zaman gelir, nasıl işlenir
- Belirsiz bahis: bet tüm denemelerde (ilk deneme + seçtiğiniz tekrar sayısı) temiz yanıt almazsa, süre bütçesi dolarsa ya da INVALID_SIGNATURE veya DUPLICATE_TRANSACTION dönerse otomatik rollback oluşur. Son denemenin süresi dolmadan gönderilmez. Hiç gönderilmemiş bahis için rollback gitmez.
- Kazanç iadesi: ref_transaction_id bir win olabilir. Bu durumda tutarı bakiyeden düşersiniz.
- Kazançlı tur: Sizin OK verdiğiniz bir bahsin turunda ödenmiş veya ödenecek kazanç varsa bahis otomatik iade edilmez; çözüm bekleyen kalem açılır (rollback_after_win, jackpot düşen turda rollback_after_jackpot). Belirsiz bahis ise kazanç olsa da iade edilir. Sonuç iptal edilirse sıra önce kazançlar, en sonda bahislerdir. Bir adım başarısız olursa dizi durur.
- Free round: Free round bahsinde amount 0’dır, rollback nakit iade etmez. Kullanılan dönüş oyuncuya geri verilir.
- Tekrar: Rollback, win takvimiyle tekrar edilir. Gövde ve X-Request-Id her denemede aynıdır. Gövdede tanımadığınız alanları yok sayın.
Hata kodları
| Kod | Anlam | Boss Hub davranışı |
|---|---|---|
| TRANSACTION_ROLLED_BACK | İşlem zaten geri alınmış | OK sayılır |
| TRANSACTION_NOT_FOUND | HTTP 409 veya HTTP 200 + kod. Sözleşme ihlali: bilinmeyen işlemde OK dönülmeli | Tekrar yok, tur takılı olur (rollback_rejected) |
| PLAYER_BLOCKED | Oyuncu kısıtlı / self-exclusion | Tekrar yok, tur takılı olur (rollback_rejected) |
| LIMIT_EXCEEDED | Sorumlu oyun limiti aşıldı | Tekrar yok, tur takılı olur (rollback_rejected) |
| INSUFFICIENT_FUNDS | Bakiye yetersiz (kazanç iadesi) | Tekrar yok, tur takılı olur (rollback_rejected) |
| INVALID_TOKEN | Sözleşme ihlali: rollback token yüzünden reddedilmez | Tekrar yok, tur takılı olur (rollback_rejected) |
| DUPLICATE_TRANSACTION | Aynı işlem farklı içerikle | Takvim durur, manuel incelemeye düşer (duplicate_conflict) |
| INVALID_SIGNATURE | İmza doğrulanamadı | Belirsiz sayılır: takvim sürer, alarm üretilir |
| INTERNAL_ERROR | Operatör hatası | Belirsiz sayılır: takvim sürer |
4. denemeden sonra bahis rollback’inde bet_timeout, kazanç rollback’inde rollback_rejected kalemi açılır; takvim biterse kalem elle çözüme kalır. Tüm yanıtların sınıflandırması: Hata kodları.