# Como funciona a integração de carteira de cassino: seamless vs transfer

> Carteira seamless vs transfer, o fluxo bet-win-rollback, idempotência e reconciliação — o que o operador precisa construir e testar antes do go-live.

Canonical: https://crocogames.com/pt/articles/casino-wallet-integration-guide  
Integration · 2026-08-22 · by CROCO Games

Markdown mirror of https://crocogames.com/pt/articles/casino-wallet-integration-guide — CROCO Games (crocogames.com), a B2B slot provider for online casino operators. Machine-readable site index: https://crocogames.com/llms.txt

Toda integração de jogos de cassino é, por baixo da marca, uma conversa sobre dinheiro entre dois sistemas que não confiam nos relógios um do outro. O servidor do jogo diz "este jogador acabou de apostar 2,00 e ganhou 5,60"; a carteira do operador responde "prove, exatamente uma vez, na ordem certa, mesmo que a rede tenha caído no meio do caminho". Acerte essa conversa e ninguém nunca mais pensa nela. Erre e você vai passar a semana de lançamento reconciliando apostas fantasmas às 3 da manhã enquanto o suporte reembolsa jogadores irritados.

Este guia explica os dois modelos de carteira por trás de toda [API de jogos de cassino](https://crocogames.com/pt/glossary/casino-game-api), o que de fato trafega no fluxo bet–win–rollback e o punhado de decisões de engenharia — idempotência, ordenação, reconciliação — que separam uma integração confiável e sem graça de um incidente famoso. Foi escrito para o lado do operador na mesa: o que perguntar, o que testar e onde as integrações realmente quebram.

## Seamless vs transfer: a única decisão de arquitetura que importa

Integrações de carteira vêm em dois formatos, e todo o resto decorre da escolha.

**Carteira transfer** (também chamada de "wallet-to-wallet") é o modelo mais antigo. O jogador move fundos do saldo do cassino para um saldo específico do jogo, joga contra esse saldo no lado do provedor e transfere o restante de volta ao sair. A carteira do operador só vê dois eventos: dinheiro saiu, dinheiro voltou. É simples de integrar — e os jogadores detestam. Os saldos se fragmentam entre jogos, os depósitos parecem sumir e cada transferência é um momento para repensar se vale a pena jogar. Carteiras transfer sobrevivem principalmente em plataformas legadas e em alguns mercados regulados com regras específicas de segregação.

**[Carteira seamless](https://crocogames.com/pt/glossary/seamless-wallet)** é o padrão moderno. O jogador tem um único saldo — o do operador — e o jogo consulta a API de carteira do operador a cada transação: cada aposta debita, cada prêmio credita, em tempo real. O jogador vê um número só em todo lugar, que é o que ele espera. O preço é que a carteira do operador agora está no caminho crítico de cada giro: precisa responder rápido (a rodada não resolve até o débito confirmar) e precisa responder corretamente sob retries, entregas duplicadas e timeouts.

Praticamente todo agregador e toda API direta hoje — incluindo a da CROCO — é seamless. Então a pergunta real para o operador não é "qual modelo", e sim "meu endpoint de carteira está pronto para o que seamless implica". É disso que trata o resto deste artigo.

## Anatomia de uma rodada: bet, win, rollback

Uma única rodada de slot em uma integração seamless são, no mínimo, duas chamadas de carteira, com uma terceira de reserva para falhas:

1. **Bet (débito).** O servidor do jogo chama sua carteira: ID do jogador, ID do jogo, ID da rodada, ID da transação, valor, moeda. Você confere o saldo, retém ou deduz a aposta e responde com o novo saldo. Só então a rodada resolve — os rolos são decididos matematicamente no servidor, mas o jogador nunca pode ver um resultado cuja aposta não foi capturada.
2. **Win (crédito).** O mesmo ID de rodada volta com uma transação de prêmio — possivelmente 0,00 num giro perdedor, possivelmente vários créditos numa feature em etapas. Você aplica e devolve o novo saldo. Apostas e prêmios referenciam a mesma rodada para o seu razão amarrar o par.
3. **Rollback (cancelamento).** O caminho da falha. Se a aposta foi debitada mas a rodada não pôde se completar — timeout no lado do provedor, sessão que caiu, partição de rede entre o débito e a resolução — o provedor envia um rollback daquele ID de transação específico. Sua carteira deve devolver a aposta e marcar a transação como anulada, mesmo que nunca tenha visto a aposta original (um rollback de transação desconhecida deve ser reconhecido e registrado, não rejeitado).

Features complicam a coreografia, mas não o contrato. Um [bonus buy](https://crocogames.com/pt/glossary/bonus-buy) é uma transação de aposta grande como qualquer outra; uma sequência de respins de Hold & Win resolve em um ou vários créditos; um jackpot de um [jackpot em rede](https://crocogames.com/pt/glossary/jackpot-network) normalmente chega como um crédito rotulado à parte. Se o protocolo do provedor os distingue (a maioria distingue, com um campo de tipo de transação), seu reporting agradecerá depois.

## Idempotência: a propriedade que sua carteira não consegue fingir

Redes fazem retry. Load balancers estouram timeout e reenviam. Um servidor de jogo que nunca recebeu o seu "OK" vai mandar a mesma aposta de novo — com o mesmo ID de transação. **Idempotência significa que a segunda, a terceira e a décima entrega da mesma transação produzem exatamente o estado da primeira: um débito, uma linha no razão, o mesmo corpo de resposta.**

Essa é a falha de integração mais comum que vemos em testes de certificação, e vale ser preciso sobre a regra: a unicidade mora no ID de transação do provedor, não em heurísticas de (jogador, valor, timestamp). A implementação correta armazena o ID de transação com uma constraint de unicidade e, em conflito, retorna o resultado registrado do processamento original — não um erro, e absolutamente não um segundo débito. A infraestrutura de pagamentos funciona igual; a documentação de [idempotent requests](https://docs.stripe.com/api/idempotent_requests) da Stripe é uma descrição limpa do padrão em outra indústria.

Três regras adjacentes completam o contrato:

- **Ordenação não é garantida.** Um prêmio pode chegar antes do retry da sua aposta, um rollback antes da aposta que cancela. Processe o que der, estacione o que não der, nunca presuma a sequência.
- **Timeouts não são falhas.** Se você estourou o tempo respondendo a uma aposta, o provedor não sabe se você debitou. Ele vai tentar de novo e depois fazer rollback. Se a sua primeira tentativa de fato funcionou internamente, só a idempotência evita a cobrança dupla, e só um caminho de rollback funcional devolve o dinheiro.
- **Responda rápido.** A latência da carteira é visível ao jogador — ela fica entre o toque e os rolos. Orce dezenas de milissegundos para o caminho feliz e tire verificações de saldo, regras de fraude e logging da seção crítica síncrona onde puder.

## Reconciliação: confie, mas verifique toda noite

Mesmo um protocolo em tempo real perfeito deriva: rollbacks que cruzaram um deploy, créditos aplicados a uma conta fechada, uma regra de arredondamento de moeda interpretada diferente em cada lado. Integrações maduras fecham o ciclo com **reconciliação** — uma comparação diária (no mínimo) do log de transações do provedor contra o seu razão, por jogador, por rodada, por valor.

O que combinar antes do go-live, porque é péssimo negociar durante um incidente:

| Item | Como é quando está bom |
|---|---|
| Relatório de transações | Via API ou arquivo agendado, itemizado por ID de transação, disponível no mesmo dia |
| Vida útil da rodada | Quanto tempo uma rodada pode ficar aberta antes de o provedor forçar resolução ou anular |
| Janela de rollback | Quão tarde um rollback pode legitimamente chegar (horas, não dias) |
| Caminho de disputa | Contatos nomeados, formato de evidência combinado: IDs de transação e timestamps, não prints |
| Regras de moeda | Precisão decimal por moeda, e quem arredonda onde |

Um provedor que não consegue produzir um relatório limpo por transação está dizendo algo sobre os próprios internals. Trate como sinal de due diligence, não como inconveniente.

## O que testar antes de virar a chave

O caminho feliz vai funcionar na primeira demo. Lançamentos afundam nos caminhos infelizes, então um checklist de go-live deve forçar cada um deles pelo menos uma vez contra uma carteira de staging:

- Mesma aposta entregue duas vezes (idempotência): um débito, respostas idênticas.
- Aposta debitada, timeout do provedor, rollback: saldo restaurado, rodada anulada.
- Prêmio entregue antes do retry da aposta: sem crash, razão consistente quando ambos pousarem.
- Rollback de uma transação que você nunca viu: reconhecido, registrado, sem loop de erro.
- Saldo insuficiente: código de rejeição limpo, sem débito parcial, jogo mostra a mensagem certa.
- Moeda com três decimais e o menor degrau da sua escada de apostas, de ponta a ponta.

Rode a lista por mercado em que você lança, não por integração — jurisdições reguladas adicionam as próprias variações (limites de sessão, reality checks, logout forçado) que interagem com rodadas abertas. Nosso [checklist de QA de go-live](https://crocogames.com/pt/articles/slot-launch-qa-checklist) cobre o gêmeo desta lista no lado do jogo, e o [guia de anatomia da integração](https://crocogames.com/pt/articles/casino-game-api-integration-anatomy) percorre a pilha inteira acima da carteira: início de sessão, URLs de lançamento de jogo e reporting.

## Direto ou via agregador — a carteira muda?

Rotear por um [agregador](https://crocogames.com/pt/glossary/game-aggregator) não remove o contrato seamless; ele o realoca. Você implementa uma API de carteira — a do agregador — e o agregador fala com cada estúdio atrás dele. Isso é genuinamente menos trabalho de integração para muitos provedores, ao custo de um salto extra de latência em cada giro, uma parte a mais em cada disputa e uma margem a mais em cada acordo comercial. Os trade-offs estão tratados com honestidade em [API direta vs agregador](https://crocogames.com/pt/articles/direct-api-vs-aggregator); a versão curta é que operadores de alto volume geralmente terminam híbridos — cauda longa agregada, linhas diretas com os estúdios que importam comercialmente.

Seja qual for a rota, o endpoint de carteira que você constrói é o mesmo, e a qualidade dele é o teto de todo provedor que você vier a integrar: uma implementação sólida de débito, crédito, rollback e reconciliação serve a todos. Os detalhes da integração REST da própria CROCO — uma API, sandbox primeiro, go-live típico em até 24 horas depois que os testes de carteira passam — estão na [página de integração de API](https://crocogames.com/pt/casino-game-api-integration).

## Perguntas frequentes

### Qual é a diferença entre carteira seamless e carteira transfer?
A carteira transfer move fundos para um saldo separado por jogo contra o qual o jogador aposta, e depois transfere o restante de volta. A carteira seamless mantém um único saldo no lado do operador que o jogo debita e credita em tempo real a cada aposta e prêmio. Seamless é o padrão moderno porque o jogador vê um saldo consistente; o custo é que a API de carteira do operador precisa ser rápida e idempotente.

### O que é um rollback em uma integração de jogos de cassino?
Um rollback cancela uma transação anterior específica — geralmente uma aposta cuja rodada não pôde se completar por timeout ou queda. A carteira deve devolver a aposta, marcar a transação como anulada e aceitar rollbacks até de transações que nunca registrou, porque a falha pode ter acontecido antes de a aposta chegar.

### Por que idempotência importa em uma API de carteira?
Porque redes fazem retry. A mesma aposta ou prêmio pode ser entregue várias vezes com o mesmo ID de transação, e a carteira deve produzir o estado de exatamente um processamento: um débito, uma linha no razão, a mesma resposta sempre. Sem isso, retries viram cobranças duplas e a reconciliação vira arqueologia.

### Quanto tempo leva uma integração de API de jogos de cassino?
Com uma carteira seamless funcional já no lugar, adicionar um provedor é principalmente configuração e certificação dos caminhos infelizes — dias, não meses. Construir bem a carteira na primeira vez é o projeto de verdade; depois disso, a integração típica da CROCO entra no ar em cerca de 24 horas.

## Principais conclusões

- Seamless é o modelo padrão de carteira: um saldo, cada aposta e prêmio bate na API de carteira do operador em tempo real — o que coloca essa API no caminho crítico de cada giro.
- Uma rodada é um débito de aposta mais um ou mais créditos de prêmio amarrados pelo ID da rodada, com rollback como caminho de falha obrigatório — incluindo rollbacks de transações que você nunca viu.
- Idempotência chaveada no ID de transação do provedor é inegociável; retries devem repetir o resultado registrado, nunca reexecutar o débito.
- Nunca presuma ordenação, trate seus próprios timeouts como resultado desconhecido e mantenha a latência da carteira em dezenas de milissegundos.
- Combine a mecânica de reconciliação — relatórios, janelas de rollback, formato de disputa — antes do go-live, e teste cada caminho infeliz por mercado, não por demo.

## Trabalhe com a CROCO Games

**Nossa integração foi feita para o time que leu até aqui.** Uma API REST com contrato de carteira seamless, semântica explícita de idempotência e rollback, um sandbox que permite forçar timeouts e retries sob demanda, e reporting por transação que você reconcilia desde o primeiro dia — certificada por GLI, BMM, eCOGRA e iTech Labs e no ar com 600+ operadores em 50+ mercados.

O go-live típico leva cerca de 24 horas depois que os testes de carteira passam: integre uma vez, e todos os títulos CROCO — Hold & Win, crash e instant — chegam pelo mesmo cano.

[Solicitar a documentação da API](https://crocogames.com/pt/contact) [Ver o fluxo de integração →](https://crocogames.com/pt/casino-game-api-integration)