Por que a mesma chamada chega duas vezes
Considere o caso comum. A WGC chama a sua Callback URL com uma aposta, você debita o jogador e responde, e a sua resposta se perde no caminho. Do ponto de vista da WGC, a operação é desconhecida: ela não sabe se você a registrou. Um provedor de jogos também pode tentar de novo uma aposta depois de uma falha do seu próprio lado. Nos dois casos a repetição traz o mesmo transactionId. Um manipulador que a trate como uma aposta nova debita o jogador duas vezes, e a disputa que se segue é cara para todos.
Por isso, na carteira da WGC, esta regra que afeta diretamente o dinheiro do jogador não é um desejo, e sim uma condição da integração: o writeBet é registrado uma única vez por transactionId, e uma chamada repetida não debita duas vezes e devolve o mesmo saldo.
Quem repete o quê
Os dois comandos se repetem de maneiras diferentes, e convém mantê-los separados.
writeBeté repetido pelo provedor do jogo, e não pela WGC, e a repetição chega com o mesmotransactionId. A WGC responde a repetição de uma operação que já liquidou a partir do que guardou. Somente quando a tentativa anterior nunca chegou a você a chamada sai de novo, com o mesmotransactionId.rollbacké repetido pela WGC, segundo um calendário fixo que não é um ajuste: cerca de um minuto depois da resposta que faltou, depois aos 5, 15, 60, 360 e 1.440 minutos, e então uma vez por dia até que se passem 30 dias desde a aposta. Depois disso as tentativas param e a equipe da WGC resolve o caso com você.
Guarde os seus próprios registros de cada transação, por transactionId, por pelo menos 30 dias, porque um rollback pode chegar até 30 dias depois da aposta.
As regras de um `writeBet` seguro
- Torne o
transactionIdúnico no seu banco de dados. A maneira fácil de ser idempotente é uma chave única: a segunda inserção falha, e você responde com o que guardou para a primeira. - Responda a uma repetição exatamente como respondeu da primeira vez. O mesmo saldo, sem um segundo débito. A repetição de uma recusa é a mesma recusa.
- Trate duas chamadas idênticas no mesmo instante. Um esquema de verificar e depois gravar, em passos separados, pode deixar as duas passarem. A chave única, ou um bloqueio, decide quem vai primeiro.
- Recuse um
kindque você não conhece.kindéplayourefund, ejackpotsomente depois que o seu gerente ativar os jackpots para a sua conta. - Ignore os campos que você não conhece. Campos novos podem aparecer.
Uma repetição é mostrada abaixo. As duas chamadas trazem o mesmo transactionId, e as duas recebem a mesma resposta.
{ "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 }As regras de um `rollback` seguro
Um rollback pede que você reverta uma aposta por inteiro: a aposta volta ao jogador e o ganho é retirado. Ele também é idempotente: o mesmo transactionId de novo não deve reverter duas vezes.
{ "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- Se você nunca registrou esse
transactionId, não mude nada e mesmo assim responda com o saldo. - A WGC conta um rollback como aceito somente com um HTTP 2xx e um saldo legível. Uma recusa, um tempo limite ou uma resposta ilegível é uma recusa, e o calendário continua, de modo que um rollback repetido também deve ser respondido com um 2xx.
- Um 404, um 405 ou
unknown_commanddiz à WGC que você não implementa rollbacks. A WGC deixa então de repetir, e a equipe resolve o caso com você. - Um
writeBetque chega depois do seu próprio rollback deve ser recusado, como fazem os manipuladores de exemplo públicos.
Tempos limite e o que conta como resposta
A WGC espera 3 segundos pela sua resposta, e uma resposta é tomada como dada somente com um status de 200 a 299. Um 500 com {"ok":true} no corpo não conta: a operação fica desconhecida e um rollback se segue. Uma recusa é uma resposta normal: { "ok": false, "error": "insufficient_funds" } com status 200. Os redirecionamentos não são seguidos; por isso responda diretamente do endereço de Callback, sem redirecionar para outro.
Dois prazos mais curtos protegem o jogador. Uma aposta que esperou mais de 1,5 segundo dentro da WGC não é enviada a você, e nada é tirado. Uma aposta que você aceitou e cuja resposta não conseguiu chegar ao provedor do jogo em 4,5 segundos é cancelada de imediato por meio de um rollback. Os ganhos, os jackpots e os reembolsos não têm esse prazo: eles sempre chegam a você.
Toda chamada é assinada. Verifique a assinatura sobre o corpo bruto antes de analisá-lo, compare em tempo constante e rejeite uma chamada cujo carimbo de tempo tenha mais de 5 minutos.
Abrir uma sessão é outro contrato
Não transfira as regras da carteira para POST /v1/sessions. Ali, o cabeçalho opcional Idempotency-Key vive 24 horas: a mesma chave e o mesmo corpo devolvem a mesma resposta sem uma nova chamada ao provedor do jogo, e a mesma chave com outro corpo é invalid_request. Enquanto uma sessão está aberta, uma segunda abertura do mesmo jogador, jogo, moeda e modo devolve essa sessão e o mesmo link de lançamento. Teste os dois contratos como casos separados; assim você distingue com facilidade de qual deles vem um erro.
Prove antes do jogo real
- Exemplos públicos e uma autoverificação. Os manipuladores em Node.js, PHP e Python e o script
wallet-check.mjssão públicos. A autoverificação envia duas chamadaswriteBetidênticas ao mesmo tempo e espera um único débito e a mesma resposta para as duas. - O teste de integração. No back office, ele executa 14 verificações da sua carteira. Três delas tratam de repetições: o mesmo
transactionIdde novo não é debitado duas vezes, duas apostas iguais no mesmo instante debitam uma só vez, e um rollback repetido não devolve mais nada e é aceito. - O jogo de teste. Uma chave de teste abre o WGC Test Slot, em que cada giro faz duas chamadas reais à sua Callback URL com
"test": true, sem dinheiro. Uma opção para perder a resposta deixa a operação desconhecida, e cerca de um minuto depois chega umrollback. - Integration check. Mostra cada chamada e resposta ao vivo. Depois de uma execução, o status de uma operação e do seu rollback pode ser lido com
GET /v1/transactions/{transactionId}.
Veja o modo demo e de teste, os passos de integração e a visão geral da API de cassino; o contrato está na página da carteira seamless.