Aynı çağrı neden iki kez gelir

Yaygın durumu ele alalım. WGC, Callback URL'nize bir bahisle çağrı yapar, siz oyuncuyu borçlandırıp yanıtlarsınız ve yanıtınız yolda kaybolur. WGC'nin gözünde işlem bilinmezdir: onu kaydedip kaydetmediğinizi bilmez. Bir oyun sağlayıcısı da kendi tarafındaki bir hatadan sonra bir bahsi yeniden deneyebilir. Her iki durumda da tekrar, aynı transactionId ile gelir. Onu yeni bir bahis olarak ele alan bir işleyici oyuncuyu iki kez borçlandırır ve ardından çıkan uyuşmazlık herkes için pahalıdır.

Bu nedenle, oyuncunun parasını doğrudan ilgilendiren bu kural, WGC cüzdanında bir dilek değil, entegrasyonun bir koşuludur: writeBet, transactionId başına bir kez kaydedilir; tekrar edilen bir çağrı oyuncuyu iki kez borçlandırmaz ve aynı bakiyeyi döndürür.

Kim neyi tekrarlar

İki komut farklı biçimde tekrarlanır ve onları birbirinden ayrı tutmak işe yarar.

  • writeBet tekrarı WGC tarafından değil, oyun sağlayıcısı tarafından yapılır ve tekrar aynı transactionId ile gelir. WGC, daha önce yerleştirdiği bir işlemin tekrarını sakladığı kayıttan yanıtlar. Çağrı yeniden yalnızca önceki deneme size hiç ulaşmadıysa gider; yine aynı transactionId ile.
  • rollback tekrarı WGC tarafından, bir ayar olmayan sabit bir takvimle yapılır: eksik yanıttan yaklaşık bir dakika sonra, ardından 5, 15, 60, 360 ve 1.440 dakika sonra, sonra da bahisten itibaren 30 gün geçene kadar günde bir kez. Bundan sonra denemeler durur ve durumu WGC personeli sizinle birlikte çözer.

Her işlemin kaydını transactionId ile en az 30 gün kendiniz saklayın; çünkü bir rollback bahisten 30 güne kadar sonra gelebilir.

Güvenli bir `writeBet` için kurallar

  1. transactionId'yi veritabanınızda benzersiz yapın. İdempotent olmanın kolay yolu benzersiz bir anahtardır: ikinci ekleme başarısız olur ve siz ilk işlem için sakladığınızı yanıtlarsınız.
  2. Bir tekrarı, ilkini yanıtladığınız gibi yanıtlayın. Aynı bakiye, ikinci bir borçlandırma yok. Bir retin tekrarı da aynı rettir.
  3. Aynı anda gelen iki özdeş çağrıyı ele alın. Ayrı adımlarda yapılan bir kontrol-sonra-yaz düzeni, ikisini de geçirebilir. Kimin önce olduğuna benzersiz anahtar ya da bir kilit karar verir.
  4. Tanımadığınız bir kind değerini reddedin. kind, play ya da refund olur; jackpot ise yalnızca yöneticiniz hesabınız için jackpot'ları açtıktan sonra gelir.
  5. Tanımadığınız alanları yok sayın. Yeni alanlar ortaya çıkabilir.

Bir tekrar aşağıda gösterilmiştir. İki çağrı da aynı transactionId'yi taşır ve ikisi de aynı yanıtı alır.

{ "command": "writeBet", "playerId": "casino-side-player-42", "currency": "USD", "bet": 1.00, "win": 0.00, "roundId": "3f1c2a64-8d0b-4e57-9b7a-5c2e1d0f9a41", "gamePublicId": "sweet-bonanza-1", "transactionId": "5f0b1c2e-7a64-4d6e-9a3b-0c1d2e3f4a5b", "kind": "play", "requestId": "req_…", "timestamp": "2026-10-12T10:15:01.000Z" }
← { "ok": true, "balance": 122.45 }
(the same call again)
← { "ok": true, "balance": 122.45 }

Güvenli bir `rollback` için kurallar

Bir rollback, bir bahsi tümüyle geri almanızı ister: bahis oyuncuya döner ve kazanç geri alınır. O da idempotent'tir: aynı transactionId bir kez daha geldiğinde iki kez geri almamalıdır.

{ "command": "rollback", "transactionId": "5f0b1c2e-7a64-4d6e-9a3b-0c1d2e3f4a5b", "playerId": "casino-side-player-42", "currency": "USD", "bet": 1.00, "win": 0.00, "reason": "unknown_outcome", "requestId": "rb:5f0b1c2e-7a64-4d6e-9a3b-0c1d2e3f4a5b:1", "timestamp": "2026-10-12T10:16:01.000Z" }
← 200 { "balance": 123.45 }                                # taken
← 200 { "ok": false, "error": "insufficient_funds" }      # a refusal: WGC asks again
← 404, 405, or { "error": "unknown_command" }             # not implemented: not a failure
  • O transactionId'yi hiç kaydetmediyseniz hiçbir şeyi değiştirmeyin ve yine de bakiyeyle yanıtlayın.
  • WGC bir rollback'i yalnızca HTTP 2xx ve okunabilir bir bakiyeyle kabul edilmiş sayar. Bir ret, bir zaman aşımı ya da okunamayan bir yanıt ret sayılır ve takvim sürer; bu yüzden tekrarlanan bir rollback da 2xx ile yanıtlanmalıdır.
  • 404, 405 ya da unknown_command, rollback'i uygulamadığınızı WGC'ye bildirir. WGC bundan sonra tekrarı bırakır ve durumu personel sizinle birlikte çözer.
  • Kendi rollback'inden sonra gelen bir writeBet reddedilmelidir; herkese açık örnek işleyiciler de böyle yapar.

Zaman aşımları ve neyin yanıt sayıldığı

WGC yanıtınız için 3 saniye bekler ve bir yanıt yalnızca 200 ile 299 arasındaki bir durumla verilmiş sayılır. Gövdesinde {"ok":true} olan bir 500 sayılmaz: işlem belirsiz hale gelir ve bir rollback izler. Ret normal bir yanıttır: { "ok": false, "error": "insufficient_funds" } ve durum 200. Yönlendirmeler izlenmez; bu yüzden yanıtı, başka bir adrese yönlendirmeden doğrudan Callback adresinden verin.

Oyuncuyu iki daha kısa süre korur. WGC'nin içinde 1,5 saniyeden uzun bekleyen bir bahis size gönderilmez ve hiçbir şey alınmaz. Kabul ettiğiniz, ancak yanıtı 4,5 saniye içinde oyun sağlayıcısına ulaşamayan bir bahis ise hemen bir rollback ile iptal edilir. Kazançların, jackpot'ların ve iadelerin böyle bir süresi yoktur: onlar her zaman size ulaşır.

Her çağrı imzalıdır. İmzayı ham gövde üzerinde, ayrıştırmadan önce denetleyin, sabit sürede karşılaştırın ve zaman damgası 5 dakikadan eski olan bir çağrıyı reddedin.

Oturum açmak farklı bir sözleşmedir

Cüzdan kurallarını POST /v1/sessions çağrısına taşımayın. Orada isteğe bağlı Idempotency-Key başlığı 24 saat yaşar: aynı anahtar ve aynı gövde, oyun sağlayıcısına yeni bir çağrı yapılmadan aynı yanıtı döndürür; aynı anahtarla farklı bir gövde ise invalid_request olur. Bir oturum açıkken, aynı oyuncu, oyun, para birimi ve mod için ikinci bir açılış o oturumu ve aynı başlatma bağlantısını döndürür. İki sözleşmeyi ayrı vakalar olarak test edin; böylece bir hatanın hangi sözleşmeden geldiğini kolayca ayırt edersiniz.

Gerçek oyundan önce kanıtlayın

  • Herkese açık örnekler ve bir öz kontrol. Node.js, PHP ve Python işleyicileri ile wallet-check.mjs betiği herkese açıktır. Öz kontrol aynı anda iki özdeş writeBet çağrısı gönderir ve bir borçlandırma ile ikisine de aynı yanıtı bekler.
  • Entegrasyon testi. Back office'te cüzdanınızın 14 kontrolünü çalıştırır. Bunlardan üçü tekrarlarla ilgilidir: aynı transactionId bir kez daha geldiğinde iki kez borçlandırılmaz, aynı anda gelen iki eşit bahis bir kez borçlandırır ve tekrarlanan bir rollback artık hiçbir şey geri vermez ve kabul edilir.
  • Test oyunu. Bir test anahtarı, her döndürmede Callback URL'nize "test": true ile iki gerçek çağrı yapan WGC Test Slot'u para olmadan açar. Yanıtı kaybetme seçeneği işlemi belirsiz yapar ve yaklaşık bir dakika sonra bir rollback gelir.
  • Integration check. Her çağrıyı ve yanıtı canlı gösterir. Bir çalıştırmadan sonra bir işlemin ve rollback'inin durumu GET /v1/transactions/{transactionId} ile okunabilir.

Demo ve test modu, entegrasyon adımları ve Casino API genel bakışı sayfalarına bakın; sözleşme seamless wallet sayfasındadır.