Gateway de Pagamento para Loteria: Webhooks, Repetições e Reembolsos

Uma integração de gateway de pagamento para loteria está pronta quando os pagamentos, os lançamentos da carteira e os relatórios de liquidação concordam — mesmo após novas tentativas, respostas expiradas, reembolsos e notificações atrasadas. Uma tela de checkout bem-sucedido não comprova, por si só, que o operador recebeu os fundos ou creditou a conta correta […]

Uma integração de gateway de pagamento para loteria está pronta quando os pagamentos, os lançamentos da carteira e os relatórios de liquidação concordam — mesmo após novas tentativas, respostas expiradas, reembolsos e notificações atrasadas. Uma tela de checkout bem-sucedido não comprova, por si só, que o operador recebeu os fundos ou creditou a conta correta uma única vez.

Este guia descreve requisitos de integração, não campos reais da API WhiteLotto nem uma promessa de suporte a um processador específico. A elegibilidade do fornecedor, os produtos aceitos e as condições comerciais precisam ser confirmados separadamente. Leia o guia da arquitetura de pagamentos de loteria para a visão operacional e de custos mais ampla.

Separe os registros do processador, da carteira e da área financeira

Acorde qual sistema é responsável pela tentativa de pagamento, pelo resultado definitivo do fornecedor, pelo lançamento na carteira do jogador, pela instrução de saque e pela conciliação contábil. Conecte os identificadores sem tratá-los como equivalentes. Defina valores, moeda, arredondamento e tarifas em cada limite de responsabilidade.

Projete o tratamento de webhooks para repetições e atrasos

Verifique a origem do evento pelo mecanismo documentado do fornecedor antes de confiar no conteúdo. Valide a conta, o pagamento, o valor e a moeda referenciados. Grave de forma persistente o evento ou a operação aceita antes de responder ao remetente que a entrega foi bem-sucedida. Processe trabalhos mais demorados por uma rota recuperável.

Não suponha que os eventos chegam uma única vez ou em ordem. A Stripe documenta a verificação de assinaturas, os eventos duplicados e a ausência de garantia de ordem dos eventos. A Adyen documenta suas próprias regras de confirmação de webhooks e tratamento de duplicidades. São referências específicas de cada fornecedor, não evidência de integração da WhiteLotto com qualquer dessas empresas.

Escolha as chaves de deduplicação e as regras de transição de estado conforme o contrato real do fornecedor. Um novo identificador de entrega pode representar o mesmo evento de negócio. Um evento atrasado não pode fazer uma operação já resolvida voltar a um estado anterior. Mantenha falhas visíveis em uma fila de exceções e disponibilize um processo controlado de reprocessamento.

Defina novas tentativas seguras e o tratamento de resultados incertos

Suponha que o fornecedor conclua uma operação de adição de fundos, mas a resposta não chegue à plataforma. Iniciar um novo pagamento pode cobrar novamente o jogador. Reutilize a referência de operação ou o mecanismo de idempotência suportado e consulte o resultado original.

A documentação de idempotência da Stripe ilustra como um fornecedor define o comportamento de repetição. Não copie sua janela de retenção nem sua interpretação de erros para outro fornecedor. O contrato precisa definir a duração da proteção, o comportamento diante de conteúdos conflitantes e a recuperação depois que essa duração terminar.

Teste concorrência além de repetição: dois processos podem receber o mesmo evento simultaneamente. Um controle de novas tentativas que funciona apenas em uma sessão de navegador não protege suficientemente um livro-razão compartilhado de carteira.

Concilie movimentações brutas e diferenças

Associe as operações do fornecedor aos lançamentos da carteira e aos relatórios de liquidação do fornecedor. Explique separadamente tarifas, reembolsos parciais, valores contestados, diferenças cambiais e diferenças de prazo. Depósitos não são vendas de bilhetes; uma adição de fundos concluída não comprova a aceitação de uma compra posterior de bilhete.

A área financeira deve conseguir investigar um valor sem correspondência usando referências permitidas, registros de horário e histórico de status. Use o modelo de KPIs para informar o valor não resolvido e o tempo em aberto, sem ocultar diferenças de sinais opostos pela compensação.

Checklist de aceite de pagamentos

• Exercite jornadas de adição de fundos concluídas, recusadas, canceladas e pendentes.
• Faça a primeira resposta se perder e depois consulte ou repita com segurança a operação original.
• Envie eventos de teste duplicados, concorrentes, atrasados e fora de ordem.
• Rejeite assinaturas inválidas, moedas incorretas e referências de contas não relacionadas.
• Teste reembolsos totais e parciais, falhas de saque e diferenças de conciliação.
• Confirme que segredos não estejam presentes no código do navegador nem em logs sem restrição de acesso.

Execute esses casos em ambientes de testes autorizados dos fornecedores, com dados fictícios. As orientações da OWASP para testes de pagamento são uma referência útil para verificar lógica de negócio e temporização. Registre os resultados financeiros efetivos no pacote de aceite UAT; esta checklist não autoriza pagamentos em produção.

Perguntas frequentes sobre integração de pagamentos

Um redirecionamento do navegador deve creditar a carteira?

A decisão de crédito precisa de evidência autoritativa no servidor, conforme o contrato acordado. Uma página de sucesso no navegador, sozinha, não constitui essa evidência.

A integração de um gateway garante a aceitação de um negócio de loteria?

Não. Elegibilidade, aprovação de mercado e produto e integração comercial são decisões separadas do fornecedor e dos responsáveis pertinentes.

Apresente seus métodos de pagamento, mercados e requisitos de liquidação à WhiteLotto. Comece pela arquitetura de integração. CONTATO.