Product API Tek cüzdan ve transfer cüzdanı

Tek cüzdan ve transfer cüzdanı

Bir operatörün oyuncu bakiyesini casino oyun API'sine bağlamak için kullanılan iki cüzdan modelinin teknik karşılaştırması: parayı kim tutar, bir bahis sırasında ağdan hangi çağrılar geçer, hatalar nasıl giderilir ve sizin tarafınızda ne geliştirmeniz gerekir.

Bir bakışta

Konu	Tek cüzdan	Transfer cüzdanı
Bakiyenin tutulması	Tek bakiye sizin veritabanınızda tutulur. Sağlayıcı oyuncu fonlarını asla tutmaz.	Sağlayıcı ayrı bir oyun bakiyesi tutar. Fonlar transfer çağrılarıyla girip çıkar.
Bahis sırasındaki çağrılar	Her bahis ve kazanç size sunucudan sunucuya bir callback tetikler (balance, debit, credit, rollback).	Yok. Oyun sağlayıcı tarafındaki bakiyeyle çalışır. Çağrılar yalnızca transfer giriş ve çıkışında yapılır.
Gereken erişilebilirlik	Cüzdan endpoint'leriniz her callback'i, normalde birkaç yüz milisaniye içinde yanıtlamalıdır. Kapalı olurlarsa oyun durur.	Yalnızca transferler için gerekir. Sisteminiz kısa süre çevrim dışı olsa da turlar devam eder.
Tutarlılık modeli	Defteriniz gerçek zamanlı tek doğru kaynaktır. Yalnızca oyun turlarının mutabakatı gerekir, bakiyelerin değil.	Yalnızca transfer sınırlarında uyuşan iki defter. Transfer düzeyinde mutabakat gerekir.
Hata kurtarma	Zaman aşımları, işlem kimliğine bağlı idempotent yeniden denemeler ve rollback çağrılarıyla çözülür.	Transferler iki aşamalıdır: beklemede, sonra başarılı veya başarısız. Bir durum sorgusu bilinmeyen sonuçları çözer.
Entegrasyon eforu	Daha yüksek. İdempotency ve defter içeren düşük gecikmeli bir callback servisi geliştirir ve işletirsiniz.	Daha düşük. Üç veya dört REST endpoint'i çağırırsınız; güvenceye alınacak veya ölçeklenecek gelen trafik yoktur.
Oyuncu deneyimi	Tek bakiye, transfer adımı yok. Bonuslara, ürünler arası oyuna ve canlı bakiye gösterimine uygundur.	Fonlar oyundan önce aktarılır, sonra geri çekilir. Kısa bir gecikme ve oyuncu oturum ortasında ayrılırsa bakiyenin takılı kalma riski ekler.
Tipik uyum	Kendi cüzdanı veya platformu olan ve fonlar ile promosyonlar üzerinde sıkı kontrol isteyen operatörler.	Hızlı lansman isteyen veya gerçek zamanlı bir cüzdan servisi olmayan operatörler.

Tek cüzdan (seamless)

Tek cüzdan (seamless) modelinde cüzdan sizin sisteminizdir. Oyuncu bahis yaptığında SSG API'si callback endpoint'inizi çağırır, siz kendi defterinizde bakiyeyi değiştirir ve yeni bakiyeyle yanıt verirsiniz. Fonlar veritabanınızdan asla çıkmaz.

Çağrı akışı

Başlatma: backend'iniz oyuncu kimliği ve oturum token'ı ile SSG'den bir oyun URL'si ister.
Bahis: her tur için SSG benzersiz bir txId ile debit çağırır. Fonları kontrol eder, defter satırını yazar ve yeni bakiyeyi döndürürsünüz.
Kazanç: SSG aynı tur için ödemeyle (sıfır olabilir) credit çağırır.
Hata: bir çağrı zaman aşımına uğrarsa SSG aynı txId ile yeniden dener, deneme sınırından sonra rollback gönderir.

Callback yöntemleri (açıklayıcı)

Yöntem	Amaç	Temel alanlar	İdempotent
`balance`	Oyuncunun güncel bakiyesini döndürür.	`playerId, currency`	Evet (salt okunur)
`debit`	Bahis yapar: tutarı düşer.	`playerId, txId, roundId, gameId, amount, currency`	txId ile
`credit`	Kazancı kesinleştirir: tutarı ekler.	`playerId, txId, roundId, amount, currency`	txId ile
`rollback`	Bir hatadan sonra önceki debit veya credit'i iptal eder.	`txId, refTxId`	txId ile

Örnek debit isteği

{
  "method": "debit",
  "playerId": "p_839201",
  "txId": "tx_20261007_000184",
  "roundId": "r_77f3a1",
  "gameId": "slots_fruit_01",
  "currency": "MYR",
  "amount": "2.50",
  "ts": 1791338577,
  "sign": "hex(HMAC-SHA256(secret, canonical))"
}

Örnek yanıt

{
  "status": "OK",
  "txId": "tx_20261007_000184",
  "balance": "97.50",
  "currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
//         DUPLICATE_TX (return original result), INTERNAL_ERROR

Cüzdan servisinizin uyması gereken kurallar

İdempotency: Aynı txId ile tekrarlanan bir debit veya credit orijinal sonucu döndürmeli ve parayı tekrar hareket ettirmemelidir. Bunu txId üzerinde benzersiz bir indeksle sağlayın.
Atomik defter yazımı: Bakiyeyi kontrol etmeyi, defter satırını eklemeyi ve bakiyeyi güncellemeyi tek bir veritabanı işleminde yapın; böylece eşzamanlı iki bahis asla eksi bakiyeye düşüremez.
Debit'ten önce rollback: Orijinal debit zaman aşımına uğradığı için hiç görmediğiniz bir txId için rollback gelebilir. O txId ile gecikmeli gelen bir debit'in reddedilmesi için bir iz kaydı saklayın.
Gecikme bütçesi: Ağ dahil p99 değerini 500 ms'nin altında tutmayı hedefleyin. Callback yolunu tek indeksli okuma ve tek yazmayla sınırlayın, raporlama sorgularını bu yoldan uzak tutun.
Para formatı: Tutarları ondalık dizeler veya tam sayı küçük birimler olarak işleyin. Asla kayan nokta kullanmayın ve para birimini oyuncu hesabına göre doğrulayın.
Bonuslar ve free spinler: Bir free spin, 0 tutarlı bir debit ve ardından kazancın credit'idir. Promosyon bakiyelerini defterinizde nakit bakiyeden ayrı tutun.
Güvenlik: Kanonik istek üzerinde HMAC-SHA256 imzasını doğrulayın, eski zaman damgalarını reddedin, SSG kaynak IP'lerini izin listesine alın ve TLS 1.2 veya üstünü zorunlu kılın.
Uzlaştırma: SSG'nin günlük tur raporlarını roundId ile defterinizle karşılaştırın. Farklar kaçırılmış callback'lere veya rollback'lere işaret eder.

Transfer cüzdanı

Transfer cüzdanı modelinde sağlayıcı her oyuncu için bir oyun bakiyesi tutar. Backend'iniz oyundan önce fon aktarır, sonra geri çeker. Oyun sırasında sisteminize callback gelmez; yalnızca giden REST çağrılarına ihtiyacınız olur.

Çağrı akışı

Transfer girişi: backend'iniz benzersiz bir txId ve tutarla transferIn çağırır. Sonuç PENDING veya SUCCESS olur.
Oyun: oyunu başlatın. Tüm bahisler ve kazançlar size callback olmadan sağlayıcı tarafındaki bakiyeyi değiştirir.
Transfer çıkışı: oyuncu ayrıldığında tüm bakiye için transferOut çağırın ve SUCCESS olduğunda kendi defterinize geri yazın.
Bilinmeyen sonuç: bir transfer çağrısı zaman aşımına uğrarsa başka bir şey yapmadan önce aynı txId ile getTransferStatus sorgulayın.

API yöntemleri (açıklayıcı)

Yöntem	Amaç	Temel alanlar	İdempotent
`transferIn`	Cüzdanınızdan oyuncunun oyun bakiyesine fon aktarır.	`playerId, txId, amount, currency`	txId ile
`transferOut`	Oyun bakiyesinden cüzdanınıza fon geri aktarır.	`playerId, txId, amount \| all`	txId ile
`getBalance`	Oyuncunun oyun bakiyesini okur.	`playerId`	Evet (salt okunur)
`getTransferStatus`	Bir txId için PENDING, SUCCESS veya FAILED döndürür.	`txId`	Evet (salt okunur)

Backend'inizin uyması gereken kurallar

Her niyet için tek txId: txId'yi ilk çağrıdan önce oluşturun ve her yeniden denemede kullanın. Öncekinin durumu bilinmeden asla yeni bir txId oluşturmayın.
Önce defterinizden düşün: Transfer girişinde, SSG'yi çağırmadan önce tutarı defterinizde ayırın; durum kesinleşince onaylayın veya serbest bırakın.
Takılı kalan bakiyeleri toplayın: Oyun bakiyesi olan ve aktif oturumu olmayan oyuncuları bulup bakiyeyi dışarı aktaran bir iş çalıştırın. Bu, oturum ortasında tarayıcıyı kapatan oyuncuları kapsar.
Çevrim ve raporlar: Bahisleri canlı görmediğiniz için ciroyu, bonus çevrimini ve risk limitlerini callback'lerden değil, SSG'den alınan tur raporlarından hesaplayın.
Uzlaştırma: Her transfer giriş ve çıkışını txId ile SSG kayıtlarıyla eşleştirin ve zaman aşımı sürenizden eski her PENDING için uyarı verin.
Güvenlik: İstekleri HMAC-SHA256 ile imzalayın, yalnızca TLS 1.2 veya üstü üzerinden çağırın, API anahtarlarını bir gizli anahtar deposunda tutun ve SSG'yi hangi sunucularınızın çağırabileceğini sınırlayın.

Hata senaryoları

Senaryo	Tek cüzdan	Transfer cüzdanı
Ağ zaman aşımı	Bahis sırasında SSG aynı txId ile yeniden dener, deneme sınırından sonra rollback gönderir. İdempotent olmalısınız.	Yalnızca transferler etkilenir. Aynı txId ile getTransferStatus sorgulayın, sonra işlem yapın.
Sisteminiz kapalı	Oyuncular tur başlatamaz veya devam ettiremez. Açık turlar geri alınır.	Oyuncular mevcut oyun bakiyeleriyle oynamaya devam eder. Yeni transferler engellenir.
Tekrarlanan istek	O txId için saklanan yanıtı döndürün ve hiçbir şeyi değiştirmeyin.	O txId için saklanan sonucu döndürün ve hiçbir şeyi değiştirmeyin.
Oyuncunun tur ortasında bağlantısı kopar	Tur sağlayıcıda tamamlanır ve credit normal şekilde gönderilir.	Tur tamamlanır ve fonlar bir transfer çıkışına veya toplama işine kadar oyun bakiyesinde kalır.
Bakiye uyuşmazlığı	Genellikle kaçırılmış bir callback veya rollback. Tur raporlarını roundId ile karşılaştırarak bulunur.	Genellikle takılı kalmış veya beklemedeki bir transfer. Transferleri txId ile karşılaştırarak bulunur.

Hangisini seçmelisiniz

Şu durumlarda tek cüzdanı seçin

Zaten gerçek zamanlı bir cüzdan veya defter servisi işletiyorsunuz.
Spor bahisleri, casino ve promosyonlarda tek bakiyeye ihtiyacınız var.
Risk, bonus çevrimi veya sorumlu oyun limitleri için canlı bahis verisine ihtiyacınız var.
Ekibiniz yüksek erişilebilirliğe sahip düşük gecikmeli bir servis işletebilir.

Şu durumlarda transfer cüzdanını seçin

En az mühendislik eforuyla hızlı lansman istiyorsunuz.
Henüz gerçek zamanlı bir cüzdan servisiniz yok.
Güvenceye alınacak açık bir callback olmadan yalnızca giden çağrıları tercih ediyorsunuz.
Kısa süreli takılı bakiye aralıkları kabul edilebilir ve bir toplama işi çalıştırabilirsiniz.

Birçok operatör yayına geçmek için transfer cüzdanıyla başlar, kendi cüzdan servisi hazır olunca tek cüzdana geçer. Geçişin nasıl aşamalandırıldığını bize sorun.

Entegrasyon kontrol listesi

txId üzerinde benzersiz indeks ve para hareket ettiren her çağrı için idempotent işleyiciler
HMAC imza kontrolü, zaman damgası toleransı ve IP izin listesi
Ondalık açıdan güvenli tutarlar ve para birimi doğrulaması
Gecikmeli bir yeniden deneme dahil sandbox'ta zaman aşımı, yeniden deneme ve rollback testleri
roundId (tek) veya txId (transfer) ile günlük mutabakat işi
İzleme ve uyarılar: callback gecikmesi, hata oranı, bekleyen transferler, takılı bakiyeler

Bir entegrasyon mühendisiyle görüşün

Mühendislerinize sandbox'ı adım adım gösterebilir ve platformunuza uyan modeli seçmenize yardımcı olabiliriz. Entegrasyon yedi günden kısa sürede garanti edilir.

Satış ekibine e-posta Telegram'da yazın Product API'ye dön

sales@ssggaming.com