{"id":4535,"date":"2026-10-06T11:31:39","date_gmt":"2026-10-06T11:31:39","guid":{"rendered":"https:\/\/whitelotto.com\/?p=4535"},"modified":"2026-10-06T11:31:39","modified_gmt":"2026-10-06T11:31:39","slug":"lottery-payment-gateway-integration","status":"publish","type":"post","link":"https:\/\/whitelotto.com\/pt-br\/lottery-payment-gateway-integration\/","title":{"rendered":"Gateway de Pagamento para Loteria: Webhooks, Repeti\u00e7\u00f5es e Reembolsos"},"content":{"rendered":"\n

Uma integra\u00e7\u00e3o de gateway de pagamento para loteria est\u00e1 pronta quando os pagamentos, os lan\u00e7amentos da carteira e os relat\u00f3rios de liquida\u00e7\u00e3o concordam \u2014 mesmo ap\u00f3s novas tentativas, respostas expiradas, reembolsos e notifica\u00e7\u00f5es atrasadas. Uma tela de checkout bem-sucedido n\u00e3o comprova, por si s\u00f3, que o operador recebeu os fundos ou creditou a conta correta uma \u00fanica vez.<\/p>\n

Este guia descreve requisitos de integra\u00e7\u00e3o, n\u00e3o campos reais da API WhiteLotto nem uma promessa de suporte a um processador espec\u00edfico. A elegibilidade do fornecedor, os produtos aceitos e as condi\u00e7\u00f5es comerciais precisam ser confirmados separadamente. Leia o guia da arquitetura de pagamentos de loteria<\/a> para a vis\u00e3o operacional e de custos mais ampla.<\/p>\n\n

Separe os registros do processador, da carteira e da \u00e1rea financeira<\/h2>\n

Acorde qual sistema \u00e9 respons\u00e1vel pela tentativa de pagamento, pelo resultado definitivo do fornecedor, pelo lan\u00e7amento na carteira do jogador, pela instru\u00e7\u00e3o de saque e pela concilia\u00e7\u00e3o cont\u00e1bil. Conecte os identificadores sem trat\u00e1-los como equivalentes. Defina valores, moeda, arredondamento e tarifas em cada limite de responsabilidade.<\/p>\n

\n
Estados de pagamento a resolver no contrato de integra\u00e7\u00e3o<\/caption>
Situa\u00e7\u00e3o<\/th>Comportamento necess\u00e1rio<\/th>Evid\u00eancia a preservar<\/th><\/tr><\/thead>
Criado ou pendente<\/th>N\u00e3o confundir uma opera\u00e7\u00e3o iniciada com a conclus\u00e3o da adi\u00e7\u00e3o de fundos.<\/td>ID da opera\u00e7\u00e3o, refer\u00eancia do fornecedor e status atual.<\/td><\/tr>\n
Autorizado ou capturado<\/th>Aplicar a regra acordada de cr\u00e9dito da carteira para o m\u00e9todo de pagamento efetivamente usado.<\/td>Evento verificado do fornecedor e lan\u00e7amento vinculado no livro-raz\u00e3o.<\/td><\/tr>\n
Resposta incerta<\/th>Determinar o resultado original antes de criar uma nova opera\u00e7\u00e3o.<\/td>Hist\u00f3rico de tentativas e consultas, com resolu\u00e7\u00e3o definitiva.<\/td><\/tr>\n
Reembolso ou revers\u00e3o<\/th>Vincular o ajuste ao pagamento original e evitar efeitos duplicados.<\/td>Refer\u00eancia do ajuste, valor, motivo e aprova\u00e7\u00e3o.<\/td><\/tr>\n
Contesta\u00e7\u00e3o ou diferen\u00e7a na liquida\u00e7\u00e3o<\/th>Criar uma exce\u00e7\u00e3o com respons\u00e1vel definido e tratamento financeiro.<\/td>Relat\u00f3rio do fornecedor, registro interno e trilha da resolu\u00e7\u00e3o.<\/td><\/tr>\n<\/tbody><\/table><\/div>\n\n

Projete o tratamento de webhooks para repeti\u00e7\u00f5es e atrasos<\/h2>\n

Verifique a origem do evento pelo mecanismo documentado do fornecedor antes de confiar no conte\u00fado. Valide a conta, o pagamento, o valor e a moeda referenciados. Grave de forma persistente o evento ou a opera\u00e7\u00e3o aceita antes de responder ao remetente que a entrega foi bem-sucedida. Processe trabalhos mais demorados por uma rota recuper\u00e1vel.<\/p>\n

N\u00e3o suponha que os eventos chegam uma \u00fanica vez ou em ordem. A Stripe documenta a verifica\u00e7\u00e3o de assinaturas, os eventos duplicados e a aus\u00eancia de garantia de ordem dos eventos<\/a>. A Adyen documenta suas pr\u00f3prias regras de confirma\u00e7\u00e3o de webhooks e tratamento de duplicidades<\/a>. S\u00e3o refer\u00eancias espec\u00edficas de cada fornecedor, n\u00e3o evid\u00eancia de integra\u00e7\u00e3o da WhiteLotto com qualquer dessas empresas.<\/p>\n

Escolha as chaves de deduplica\u00e7\u00e3o e as regras de transi\u00e7\u00e3o de estado conforme o contrato real do fornecedor. Um novo identificador de entrega pode representar o mesmo evento de neg\u00f3cio. Um evento atrasado n\u00e3o pode fazer uma opera\u00e7\u00e3o j\u00e1 resolvida voltar a um estado anterior. Mantenha falhas vis\u00edveis em uma fila de exce\u00e7\u00f5es e disponibilize um processo controlado de reprocessamento.<\/p>\n\n

Defina novas tentativas seguras e o tratamento de resultados incertos<\/h2>\n

Suponha que o fornecedor conclua uma opera\u00e7\u00e3o de adi\u00e7\u00e3o de fundos, mas a resposta n\u00e3o chegue \u00e0 plataforma. Iniciar um novo pagamento pode cobrar novamente o jogador. Reutilize a refer\u00eancia de opera\u00e7\u00e3o ou o mecanismo de idempot\u00eancia suportado e consulte o resultado original.<\/p>\n

A documenta\u00e7\u00e3o de idempot\u00eancia da Stripe<\/a> ilustra como um fornecedor define o comportamento de repeti\u00e7\u00e3o. N\u00e3o copie sua janela de reten\u00e7\u00e3o nem sua interpreta\u00e7\u00e3o de erros para outro fornecedor. O contrato precisa definir a dura\u00e7\u00e3o da prote\u00e7\u00e3o, o comportamento diante de conte\u00fados conflitantes e a recupera\u00e7\u00e3o depois que essa dura\u00e7\u00e3o terminar.<\/p>\n

Teste concorr\u00eancia al\u00e9m de repeti\u00e7\u00e3o: dois processos podem receber o mesmo evento simultaneamente. Um controle de novas tentativas que funciona apenas em uma sess\u00e3o de navegador n\u00e3o protege suficientemente um livro-raz\u00e3o compartilhado de carteira.<\/p>\n\n

Concilie movimenta\u00e7\u00f5es brutas e diferen\u00e7as<\/h2>\n

Associe as opera\u00e7\u00f5es do fornecedor aos lan\u00e7amentos da carteira e aos relat\u00f3rios de liquida\u00e7\u00e3o do fornecedor. Explique separadamente tarifas, reembolsos parciais, valores contestados, diferen\u00e7as cambiais e diferen\u00e7as de prazo. Dep\u00f3sitos n\u00e3o s\u00e3o vendas de bilhetes; uma adi\u00e7\u00e3o de fundos conclu\u00edda n\u00e3o comprova a aceita\u00e7\u00e3o de uma compra posterior de bilhete.<\/p>\n

A \u00e1rea financeira deve conseguir investigar um valor sem correspond\u00eancia usando refer\u00eancias permitidas, registros de hor\u00e1rio e hist\u00f3rico de status. Use o modelo de KPIs<\/a> para informar o valor n\u00e3o resolvido e o tempo em aberto, sem ocultar diferen\u00e7as de sinais opostos pela compensa\u00e7\u00e3o.<\/p>\n\n

Checklist de aceite de pagamentos<\/h2>\n