Análise de fraude

Como funciona

A análise de fraude coleta informações do dispositivo do comprador (fingerprint) usando a tecnologia ThreatMetrix da CyberSource. Esse fingerprint é usado pelo mecanismo antifraude para avaliar o risco da transação durante a criação da cobrança.

O fluxo é:

1. O SDK solicita uma sessão de fraude à API
2. A API retorna as credenciais do ThreatMetrix
3. O SDK carrega o script do ThreatMetrix no navegador
4. O ThreatMetrix coleta dados do dispositivo em segundo plano
5. O sessionId retornado é enviado junto com a cobrança para análise

Uso básico

const result = await client.fraudAnalysis.setup();

console.log(result.sessionId); // "braspag_abc123...uuid"
// Armazene o sessionId para enviar com a cobrança

O método setup() não requer nenhum parâmetro — os dados do navegador são coletados automaticamente.

Retorno (FraudSetupResult)

O que o ThreatMetrix coleta

O ThreatMetrix é carregado automaticamente e coleta informações como:

• Tipo de navegador e versão
• Sistema operacional
• Endereço IP e geolocalização
• Configurações de idioma e fuso horário
• Resolução de tela e fontes instaladas
• Plugins e extensões do navegador
• Comportamento de navegação e padrões de digitação
• Indicadores de proxy, VPN ou emulador

Essas informações geram um perfil de risco do dispositivo que é cruzado com a base global da CyberSource para identificar dispositivos suspeitos.

Dados coletados pelo SDK

Além do fingerprint do ThreatMetrix, o SDK envia para a API os seguintes dados do navegador no momento do setup():

Quando chamar o setup

O padrão recomendado é:

// 1. Inicialize o SDK quando a página de checkout carregar
const client = new Client({ publicKey: 'pk_...' });
await client.initialize();

// 2. Inicie a coleta de fraude imediatamente
let fraudSessionId: string | undefined;
if

Sessão de fraude

Cada sessão de fraude tem um TTL de 30 minutos. Se o comprador demorar mais do que isso para finalizar a compra, será necessário criar uma nova sessão.

A sessão é de uso único — após ser consumida na criação de uma cobrança, não pode ser reutilizada.

Usando na cobrança

Envie o sessionId no campo fraud_session_id ao criar a cobrança:

const response = await fetch('https://api.payhubrasil.com.br/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('sk_sua_chave:'),
    'Content-Type': 'application/json',
  },
  body: JSON

Tratamento de erros

import { ApiError, NetworkError } from '@soarlabz/security-sdk';

try {
  const result = await client.fraudAnalysis.setup();
} catch (error) {
  if (error instanceof ApiError) {
    console.