SpinLabs - Seamless Wallet & Callback API Dokümantasyonu

1. Güvenlik Protokolü & HMAC-SHA256 İmzası

SpinLabs Spor Bahis Altyapısı, bayi sitelerinize atılan tüm Server-to-Server Webhook isteklerinde yüksek güvenlik sağlamak amacıyla HMAC-SHA256 veri imzalama algoritmasını kullanır. Bu sayede üçüncü şahısların sahte bakiye veya kupon isteği göndermesi tamamen engellenir.

Nasıl Çalışır? SpinLabs motoru, istek gövdesindeki (JSON Payload) signature parametresi dışındaki tüm anahtarları alfabetik olarak (ksort) sıralar, JSON formatına dönüştürür ve bayinize ait API Secret Key ile HMAC-SHA256 imzasını oluşturur.

İmza Doğrulama Kod Örneği (PHP):

$API_SECRET = "SPOR_BAHIS_PANELINDEN_ALINAN_SECRET_KEY"; $input = file_get_contents('php://input'); $data = json_decode($input, true); $receivedSignature = $data['signature']; unset($data['signature']); ksort($data); // Anahtarları alfabetik sırala $expectedSignature = hash_hmac('sha256', json_encode($data, JSON_UNESCAPED_UNICODE), $API_SECRET); if (!hash_equals($expectedSignature, $receivedSignature)) { http_response_code(403); echo json_encode(['status' => 'error', 'message' => 'Geçersiz güvenlik imzası!']); exit; }

2. Canlı Bakiye Sorgulama (get_balance)

Kullanıcı spor bültenine girdiğinde veya sayfada bakiye yenilediğinde altyapımız sitenizin Callback URL'sine bu eylemi gönderir. Siteniz kullanıcının güncel bakiyesini döndürür.

İstek Parametreleri (POST JSON):

Parametre	Tip	Açıklama
`action`	string	Her zaman `"get_balance"` değerindedir.
`user_id`	string	İframe başlatırken gönderdiğiniz kullanıcı ID / Kullanıcı adı.
`signature`	string	HMAC-SHA256 güvenlik imzası.

Beklenen Başarılı Yanıt (JSON):

{
  "status": "success",
  "balance": 250.50
}

3. Bahis Yapıldığında Bakiyeden Düşme (debit)

Kullanıcı bültende kupon yatırdığında, kupon tutarı sitenizdeki hesabından düşülmek üzere debit aksiyonu tetiklenir.

İstek Parametreleri (POST JSON):

Parametre	Tip	Açıklama
`action`	string	`"debit"`
`user_id`	string	Kullanıcı Kimliği
`amount`	float	Kupon Tutar (Örn: 50.00)
`coupon_id`	string	Benzersiz Kupon Numarası (Örn: `SP-854721`)

Yetersiz Bakiye Uyarısı: Eğer kullanıcının sitenizdeki bakiyesi amount tutarından az ise, "status": "error" yanıtı vererek kuponu reddetmelisiniz.

Başarılı Yanıt Örneği:

{
  "status": "success",
  "new_balance": 200.50
}

4. Kazanç & Cashout Yükleme (credit)

Kullanıcının kuponu kazandığında veya Erken Bahis Bozdurma (Cashout) yaptığında elde ettiği kazanç tutarını kullanıcının ana bakiyesine eklemek için tetiklenir.

İstek Parametreleri (POST JSON):

Parametre	Tip	Açıklama
`action`	string	`"credit"`
`user_id`	string	Kullanıcı Kimliği
`amount`	float	Kazanç Tutarı (Örn: 420.00)
`coupon_id`	string	İlgili Kupon Numarası

Başarılı Yanıt Örneği:

{
  "status": "success",
  "new_balance": 620.50
}

5. Canlı/Maç Öncesi Kupon Bildirimi (bet_placed)

Bahis kuponu başarıyla tamamlandığında, kuponun Canlı kupon mu yoksa Maç Öncesi mi olduğunu (is_live), kupondaki tüm maç seçimlerini ve bahis detaylarını sitenizin veritabanına kaydedebilmeniz için bu webhook tetiklenir.

İstek Payload Örneği (POST JSON):

{
  "action": "bet_placed",
  "user_id": "kullanici123",
  "coupon_id": "SP-948271",
  "is_live": 1,
  "amount": 50.00,
  "total_odds": 3.45,
  "potential_winnings": 172.50,
  "items": [
    {
      "match_id": 9845210,
      "game_name": "Galatasaray vs Fenerbahçe",
      "sport_id": 1,
      "market_name": "Maç Sonucu (1X2)",
      "pick_name": "1",
      "odds": 1.85,
      "is_live": 1
    },
    {
      "match_id": 9845211,
      "game_name": "Real Madrid vs Barcelona",
      "sport_id": 1,
      "market_name": "Toplam Gol 2.5",
      "pick_name": "Üst",
      "odds": 1.86,
      "is_live": 0
    }
  ],
  "signature": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

6. Hazır Referans Callback Kodu (PHP)

Aşağıdaki PHP kodunu kendi sunucunuzda (Örn: https://siteniz.com/api/sportsbook_callback.php) kaydederek anında Seamless Wallet bakiye ve kupon entegrasyonunuzu tamamlayabilirsiniz.

<?php /** * SpinLabs Sportsbook - Seamless Wallet Callback Handler Reference Script */ header('Content-Type: application/json; charset=utf-8'); // Spor Bahis Paneli'nden (sportsbook.spinlabsgame.com/panel/) aldığınız Secret Key $API_SECRET = "YOUR_API_SECRET_KEY_HERE"; $input = file_get_contents('php://input'); $data = json_decode($input, true); if (!$data || !isset($data['action']) || !isset($data['signature'])) { echo json_encode(['status' => 'error', 'message' => 'Geçersiz istek.']); exit; } // 1. İMZA DOĞRULAMA (HMAC-SHA256) $receivedSignature = $data['signature']; unset($data['signature']); ksort($data); $expectedSignature = hash_hmac('sha256', json_encode($data, JSON_UNESCAPED_UNICODE), $API_SECRET); if (!hash_equals($expectedSignature, $receivedSignature)) { http_response_code(403); echo json_encode(['status' => 'error', 'message' => 'Geçersiz güvenlik imzası!']); exit; } // 2. AKSİYON İŞLEME $action = $data['action']; $username = $data['user_id'] ?? ''; if ($action === 'get_balance') { // Kendi DB'nizden canlı bakiye çekin $currentBalance = 500.00; echo json_encode([ 'status' => 'success', 'balance' => $currentBalance ]); exit; } if ($action === 'debit') { $amount = floatval($data['amount']); $couponId = $data['coupon_id']; $currentBalance = 500.00; // DB'den çekin if ($currentBalance < $amount) { echo json_encode([ 'status' => 'error', 'message' => 'Yetersiz bakiye (Sisteminizden reddedildi).' ]); exit; } $newBalance = $currentBalance - $amount; // $db->query("UPDATE users SET balance = $newBalance WHERE username = '$username'"); echo json_encode([ 'status' => 'success', 'new_balance' => $newBalance ]); exit; } if ($action === 'credit') { $amount = floatval($data['amount']); $couponId = $data['coupon_id']; $newBalance = 500.00 + $amount; // $db->query("UPDATE users SET balance = balance + $amount WHERE username = '$username'"); echo json_encode([ 'status' => 'success', 'new_balance' => $newBalance ]); exit; } if ($action === 'bet_placed') { $couponId = $data['coupon_id']; $isLive = intval($data['is_live'] ?? 0); // 1 = Canlı Kupon, 0 = Maç Öncesi $amount = floatval($data['amount']); $totalOdds = floatval($data['total_odds']); $potentialWinnings = floatval($data['potential_winnings']); $items = $data['items']; // Kendi DB'nize ve kullanıcı profil geçmişine kaydedin echo json_encode([ 'status' => 'success', 'message' => 'Kupon ve canlı bilgisi başarıyla kaydedildi.' ]); exit; } echo json_encode(['status' => 'error', 'message' => 'Bilinmeyen eylem.']);