Quem chama quem

Há duas direções. O seu servidor chama a WGC para abrir um jogo e para consultar o que aconteceu com uma operação. A WGC chama a sua Callback URL para pedir o saldo do jogador e para cada aposta e cada ganho, porque no modelo de carteira seamless o dinheiro do jogador fica no seu cassino e a WGC não guarda um saldo de jogador. As chamadas de carteira são três comandos: getBalance, writeBet e rollback. Ter a direção clara explica quase toda a rodada: o primeiro passo é você quem inicia, nos passos dois a quatro a WGC pergunta a você, e o último passo é você perguntando à WGC. Se algo der errado durante uma rodada, vale olhar primeiro qual chamada está faltando em qual direção.

Passo 1: o lançamento

O seu servidor chama POST /v1/sessions com um identificador de jogador, uma moeda, um modo e o número de um jogo. A resposta traz um link de lançamento e um identificador de sessão.

POST /v1/sessions
{"publicId":"sweet-bonanza-1","playerId":"casino-side-player-42","currency":"USD","mode":"demo","language":"en"}
→ 200 { "ok": true, "requestId": "req_…", "data": { "url": "https://play.worldgamingconnect.com/play/Zk3p9xQ2vL8mTn4r", "sessionId": "cmgq3r8v40001l8xyz5k2abcd", "expiresAt": "2026-10-12T10:45:00.000Z" } }

O identificador do jogador tem de 1 a 64 caracteres ASCII imprimíveis e nomeia um jogador do seu próprio sistema. O link é aberto no navegador do jogador, não é buscado pelo seu servidor. Um link que nenhum navegador abriu funciona por 5 minutos; depois de aberto, ele vive enquanto o jogador continua jogando. Neste passo você não responde nada; quem chama é você e a resposta chega diretamente. Abrir o jogo a partir do lobby do seu cassino também faz parte deste passo.

Passo 2: o saldo

Quando o jogo começa, ele pede o saldo do jogador, e a WGC envia getBalance para a sua Callback URL.

{ "command": "getBalance", "playerId": "casino-side-player-42", "currency": "USD", "requestId": "req_…", "timestamp": "2026-10-12T10:15:00.500Z" }
← { "ok": true, "balance": 123.45, "currency": "USD" }

Toda chamada é assinada, e você verifica a assinatura sobre o corpo bruto antes de analisá-lo. Uma recusa é escrita no corpo, por exemplo { "ok": false, "error": "insufficient_funds" }, com status 200. A resposta de saldo determina qual saldo o jogo mostra ao jogador, por isso o valor deve ser o saldo atual do seu próprio sistema.

Passo 3: a aposta

O jogador aperta girar, e a WGC envia writeBet com uma aposta acima de zero e um ganho de zero. A chamada traz um transactionId novo e um roundId.

{ "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 }

Você debita o jogador uma vez por esse transactionId e responde com o saldo novo. Se recusar, nada é debitado e a rodada não segue. O número da transação deste passo é a chave para reconhecer repetições e um possível rollback, então guarde-o nos seus registros. kind é play ou refund, e jackpot somente depois que o seu gerente ativar os jackpots para a sua conta.

Passo 4: o resultado

O resultado chega como outro writeBet com o mesmo roundId: um transactionId novo, uma aposta de zero e um ganho que é o pagamento.

{ "command": "writeBet", "playerId": "casino-side-player-42", "currency": "USD", "bet": 0.00, "win": 2.50, "roundId": "3f1c2a64-8d0b-4e57-9b7a-5c2e1d0f9a41", "gamePublicId": "sweet-bonanza-1", "transactionId": "9a1d7c33-52b8-4f0e-8c64-2d7e0b5a1f93", "kind": "play", "requestId": "req_…", "timestamp": "2026-10-12T10:15:02.000Z", "roundFinished": true }
← { "ok": true, "balance": 124.95 }

Alguns jogos enviam a aposta e o resultado em uma só chamada. Outros os enviam separados, e a WGC os une em uma única rodada, de modo que as duas chamadas viajam sob um mesmo roundId. roundFinished: true marca o fim da rodada, e quando a chave está ausente você trata a rodada como ainda aberta. O ganho é creditado uma única vez por identificador de transação, e você responde com o saldo novo.

Passo 5: sem resposta a tempo

A WGC espera 3 segundos pela sua resposta, e uma resposta só conta com status 2xx. Se a resposta não vier a tempo, ou não puder ser lida, a aposta é recusada ao provedor do jogo e a operação passa a unknown: a WGC não sabe se você a registrou. Ainda não se pede nada a você. Dentro da WGC funcionam dois prazos mais curtos: uma aposta que esperou mais de 1,5 segundo antes do seu Callback não é enviada a você, e nada é tirado do jogador; uma aposta aceita cuja resposta não conseguiu chegar ao provedor do jogo em 4,5 segundos é cancelada de imediato por meio de um rollback.

Passo 6: o rollback

Depois de um resultado desconhecido, a WGC envia rollback para o mesmo endereço com o mesmo transactionId.

{ "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 }

Se você registrou esse transactionId, reverte-o por inteiro: a aposta volta e o ganho é retirado. Se nunca o registrou, não muda nada e mesmo assim responde com o saldo. O motivo é unknown_outcome quando a sua resposta nunca chegou à WGC; um provedor de jogos que cancela uma transação já liquidada tem um motivo próprio. A WGC repete um rollback que não é aceito: 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. Por isso guarde os seus registros de operações por pelo menos 30 dias. Um cassino também pode responder 404, 405 ou unknown_command para indicar que não implementa rollbacks, e isso não é um erro. Para os detalhes do rollback e para receber as repetições com segurança, veja o artigo sobre idempotência e novas tentativas na carteira.

Passo 7: a conciliação

A qualquer momento o seu servidor pode perguntar à WGC o que ela registrou, usando os números que o seu cassino viu.

GET /v1/rounds/3f1c2a64-8d0b-4e57-9b7a-5c2e1d0f9a41
→ 200 { "ok": true, "requestId": "req_…", "data": { "roundId": "3f1c2a64-…", "status": "closed", "bet": "1.00", "win": "0.00", "ggr": "1.00", "transactions": [ { "transactionId": "5f0b1c2e-…", "status": "accepted", "balance": "122.45", … } ], "actions": ["bet","no_win"], … } }

Uma operação tem o status accepted, refused, failed ou unknown, e uma rodada mostra também ggr, que é a aposta menos o ganho. A lista actions diz com palavras da própria WGC o que aconteceu, por exemplo bet, win, no_win ou rollback; trate um código desconhecido como informação e não baseie decisões de dinheiro nele. As consultas alcançam 65 dias para trás; eventos mais antigos ficam no arquivo da WGC e são procurados manualmente, sob solicitação. O número de outra conta é lido exatamente como um número que não existe.

Ensaie a rodada sem dinheiro

Uma chave de teste abre um jogo de teste, o WGC Test Slot, em que cada giro faz duas chamadas reais à sua Callback URL, uma aposta e depois um resultado, marcadas com "test": true. Nenhum dinheiro se move. Uma opção para perder a resposta testa o seu rollback: a operação passa a unknown, e cerca de um minuto depois chega um rollback. No back office, o Integration check mostra cada chamada ao vivo, e o teste de integração executa 14 verificações da sua carteira. Veja o modo demo e de teste, os passos de integração e a visão geral da API de cassino.