Carteira única vs carteira de transferência

Em resumo

Carteira única (seamless)

No modelo de carteira única (seamless), o seu sistema é a carteira. Quando um jogador faz uma aposta, a API da SSG chama o seu endpoint de callback, você altera o saldo no seu próprio livro-razão e responde com o novo saldo. Nenhum fundo sai do seu banco de dados.

Fluxo de chamadas

1. Lançamento: o seu backend pede à SSG uma URL de jogo com um ID de jogador e um token de sessão.
2. Aposta: a cada rodada a SSG chama debit com um txId único. Você verifica os fundos, grava a linha no livro-razão e retorna o novo saldo.
3. Prêmio: a SSG chama credit com o pagamento (que pode ser zero) da mesma rodada.
4. Falha: se uma chamada expirar, a SSG tenta de novo com o mesmo txId e, após o limite de tentativas, envia rollback.

Métodos de callback (ilustrativos)

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

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

Regras que o seu serviço de carteira deve seguir

Idempotência

Um débito ou crédito repetido com o mesmo txId deve retornar o resultado original e não deve movimentar dinheiro de novo. Garanta isso com um índice único em txId.

Gravação atômica no livro-razão

Verifique o saldo, insira a linha no livro-razão e atualize o saldo em uma única transação de banco de dados, para que duas apostas simultâneas nunca estourem o saldo.

Rollback antes do débito

Um rollback pode chegar para um txId que você nunca viu porque o débito original expirou. Guarde um registro marcador para que um débito tardio com esse txId seja rejeitado.

Orçamento de latência

Mire um p99 abaixo de 500 ms, incluindo a rede. Mantenha o caminho do callback em uma leitura indexada e uma gravação, e deixe consultas de relatórios fora dele.

Formato de valores

Trate os valores como strings decimais ou unidades menores inteiras. Nunca use ponto flutuante e valide a moeda contra a conta do jogador.

Bônus e rodadas grátis

Uma rodada grátis é um débito de 0 seguido de um crédito do prêmio. Mantenha os saldos promocionais separados do saldo em dinheiro no seu livro-razão.

Segurança

Verifique uma assinatura HMAC-SHA256 sobre a requisição canônica, rejeite carimbos de data/hora antigos, libere apenas os IPs de origem da SSG e exija TLS 1.2 ou superior.

Conciliação

Compare os relatórios diários de rodadas da SSG com o seu livro-razão por roundId. As diferenças apontam callbacks ou rollbacks perdidos.

Carteira de transferência

No modelo de carteira de transferência, o provedor mantém um saldo de jogo para cada jogador. O seu backend move fundos para dentro antes de jogar e para fora depois. Durante o jogo não há callbacks para o seu sistema, então você só precisa de chamadas REST de saída.

Fluxo de chamadas

1. Transferência de entrada: o seu backend chama transferIn com um txId único e o valor. O resultado é PENDING ou SUCCESS.
2. Jogo: inicie o jogo. Todas as apostas e prêmios alteram o saldo do lado do provedor, sem callbacks para você.
3. Transferência de saída: quando o jogador sair, chame transferOut para o saldo total e credite-o de volta no seu próprio livro-razão em caso de SUCCESS.
4. Resultado desconhecido: se uma chamada de transferência expirar, consulte getTransferStatus com o mesmo txId antes de fazer qualquer outra coisa.

Métodos da API (ilustrativos)

Regras que o seu backend deve seguir

Um txId por intenção

Gere o txId antes da primeira chamada e reutilize-o em cada nova tentativa. Nunca crie um novo txId até que o status do anterior seja conhecido.

Debite primeiro o seu livro-razão

Na transferência de entrada, reserve o valor no seu livro-razão antes de chamar a SSG e depois confirme ou libere quando o status for final.

Varra os saldos presos

Execute uma tarefa que encontre jogadores com saldo de jogo e sem sessão ativa e transfira esse saldo para fora. Isso cobre jogadores que fecham o navegador no meio da sessão.

Apostas acumuladas e relatórios

Como você não vê as apostas ao vivo, calcule o giro, o rollover de bônus e os limites de risco a partir dos relatórios de rodadas obtidos da SSG, não dos callbacks.

Conciliação

Confira cada transferência de entrada e saída com os registros da SSG por txId e dispare um alerta para qualquer PENDING mais antigo que o seu timeout.

Segurança

Assine as requisições com HMAC-SHA256, chame apenas por TLS 1.2 ou superior, guarde as chaves de API em um cofre de segredos e restrinja quais dos seus servidores podem chamar a SSG.

Cenários de falha

Qual escolher

Muitos operadores começam na carteira de transferência para entrar no ar e depois passam para a carteira única quando o seu próprio serviço de carteira estiver pronto. Pergunte-nos como a troca é feita em etapas.

Checklist de integração

• Índice único em txId e handlers idempotentes para toda chamada que movimenta dinheiro
• Verificação de assinatura HMAC, tolerância de carimbo de data/hora e lista de IPs permitidos
• Valores seguros para decimais e validação de moeda
• Testes de timeout, nova tentativa e rollback no sandbox, incluindo uma nova tentativa tardia
• Tarefa diária de conciliação por roundId (única) ou txId (transferência)
• Monitoramento e alertas: latência dos callbacks, taxa de erros, transferências pendentes, saldos presos