Documentação

Um script no navegador, uma chamada de API do seu servidor. Tudo o que você precisa para entrar no ar, em uma única página.

Início rápido

Você precisa da sua chave pública (pk_...) para o navegador e da sua chave secreta (sk_...) para o servidor. As duas ficam no painel, em Sites e chaves.

1. Adicione o script

Coloque esta tag nas páginas onde os usuários se cadastram, entram, clicam em ofertas ou pedem um saque. Ele se inicializa sozinho a partir de data-key

<script src="https://cashoutguard.com/v1/agent.js" data-key="pk_live_YOUR_PUBLIC_KEY" async></script>

2. Colete e envie o request_id ao seu servidor

Chame collect() no momento que importa, com o nome do evento. Ele resolve para { request_id, visitor_id }

const { request_id } = await CashoutGuard.collect({ event: 'cashout' });

collect() nunca rejeita. Em caso de falha (bloqueio, offline, timeout) ele resolve com request_id: null e uma string de erro. Envie o formulário mesmo assim e deixe o seu servidor decidir.

3. Peça uma decisão a partir do seu servidor

Faça POST do evento para /v1/evaluate com a sua chave secreta no header Authorization: Bearer sk_live_...

Nunca coloque a chave secreta em código de navegador ou em um app mobile. Só o seu servidor deve chamar /v1/evaluate.

Requisição evaluate

POST https://cashoutguard.com/v1/evaluate pontua um evento de uma conta, vincula esse evento ao dispositivo, à rede e ao endereço de pagamento, e retorna uma decisão. Envie JSON.

Resposta

A resposta tem sempre o mesmo formato. Campos que não se aplicam vêm como null.

• score vai de 0 a 100. Os motivos são combinados para que vários sinais médios somem sem passar de 100.
• reasons lista cada sinal disparado, do mais forte para o mais fraco, com seu peso, detalhes e um rótulo em inglês simples que você pode mostrar como está.
• device.confidence indica o quão único o dispositivo parece. Fingerprints podem ser falsificados, então nunca afirmamos certeza.
• linked_accounts lista outras contas que compartilham dispositivo, endereço de pagamento ou e-mail com esta.
• cashout só vem preenchido em eventos de cashout e informa o status na sua fila de revisão.

Decisões e ações

Aja com base no campo action, não em decision. Os limites abaixo são os padrões e podem ser alterados por site no painel.

No modo sombra o action é sempre allow, então o mesmo código pode ir para produção com segurança antes de você começar a bloquear. Quando mudar para o modo ativo, nada no seu código muda.

Tipos de evento

Envie os eventos que você tiver. Cadastro e saque são os mais importantes; as conversões alimentam as checagens de velocidade de ofertas.

Offerwalls e postbacks

As conversões de offerwall chegam por postback, de servidor para servidor, sem navegador. O CashoutGuard vincula cada conversão ao clique que a iniciou, então ela é avaliada com o dispositivo e a rede desse clique.

1. Quando o usuário abre uma oferta

Colete no navegador e envie um offer_click com a oferta e seu id de clique.

2. Quando o postback chega

Envie uma conversion do seu handler de postback com o mesmo account_id e click_id. Não precisa de request_id. Envie o IP do usuário se a offerwall fornecer.

As conversões são verificadas para: concluída rápido demais para a oferta, conversão sem clique, clique e conversão de países diferentes, ganhos muito acima do dia normal da conta e ids de transação duplicados.

Redes de offerwall

Se você opera uma rede com muitos publishers, envie ids de conta que incluam o publisher e ative o "Modo rede de offerwall" em Sites. Assim as contas só são vinculadas dentro do mesmo publisher, porque é normal uma pessoa usar vários sites dos seus publishers. Formato: publisher_id:user_id

Catálogo de ofertas

POST /v1/offers envia os nomes das suas ofertas (até 1.000 por chamada). Eventos passados e futuros mostram o nome real mesmo quando trazem só o id.

Códigos de motivo

Estes códigos aparecem em reasons[].code. Mostre o texto aos seus moderadores; use o código na sua lógica.

Os pesos são combinados com um noisy-OR: score = 100 x (1 - produto de (1 - weight/100)). Dois sinais de 40 dão 64, não 80. Uma ocorrência na lista de bloqueio sempre dá 100.

Webhooks

Defina um URL de webhook no painel. Enviamos um POST por cada evento classificado como block (event.blocked), quando uma conta passa a block (account.blocked) e quando a sua equipa decide um levantamento (cashout.decided). Ignore os tipos que não usa.

Cada requisição é assinada com o seu segredo de webhook. O HMAC-SHA256 em hex do corpo bruto vem no header X-CashoutGuard-Signature

Responda com qualquer status 2xx. Entregas com falha são tentadas de novo até 5 vezes: após 10 segundos, 1 minuto, 5 minutos e 15 minutos.

Status da conta

GET /v1/accounts/{account_id} retorna a visão de risco atual de uma conta sem criar um evento.

POST /v1/accounts/{account_id}/status permite que as suas próprias ferramentas de moderação mudem o status de uma conta.

• active: Pontuação normal.
• allowlisted: As pontuações ficam limitadas abaixo do limite de revisão. Para usuários de confiança e para a equipe.
• blocked: Todo evento retorna block com pontuação 100.

Estornos e precisão

POST /v1/outcomes informa o que aconteceu com as conversões depois de pontuadas: estornadas pelo offerwall ou anunciante (chargeback) ou confirmadas como válidas. Cruzamos seus ids com as conversões e medimos o motor no seu próprio tráfego na página Precisão.

Sem código: envie na página Precisão o export mensal de estornos dos seus offerwalls (CSV ou Excel). Encontramos a coluna de ids automaticamente.

PHP, Node.js, Python, Android

Não precisa de SDK. Uma chamada HTTP simples com timeout curto basta. Exemplo completo de saque:

• cashoutguard.php: PHP 7.4+, um arquivo, sem Composer. É só dar require.
• composer require cashoutguard/cashoutguard-php: o mesmo cliente PHP com README, para sua pasta vendor.
• npm install @cashoutguard/node: Node 18+, com tipos TypeScript.
• cashoutguard-wordpress.zip: plugin de WordPress: o script do navegador em todas as páginas, cadastros e logins pontuados, e hooks para saques, conversões de offerwall e reversões.

Erros e limites

Fail open: se a chamada der timeout ou erro, permita a ação e registre. Nunca deixe uma queda nossa travar os seus usuários.