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 é:

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

O ThreatMetrix coleta dados do dispositivo em segundo plano enquanto o usuário preenche o formulário de pagamento. Quanto mais cedo você chamar setup(), mais dados serão coletados e melhor será a avaliação de risco.

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`)

Campo	Tipo	Descrição
`sessionId`	`string`	Identificador da sessão de fraude. Envie junto com a cobrança no campo `fraud_session_id`.

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():

Dado	Descrição
`ip_address`	IP público do comprador (obtido via `api.ipify.org`).
`type`	Tipo do navegador (`Chrome`, `Firefox`, `Safari`, `Edge`, `Opera`, `Other`).
`host_name`	Hostname da página onde o SDK está executando.
`cookies_accepted`	Se o navegador aceita cookies.
`user_agent`	User agent completo do navegador.

Quando chamar o setup

Chame setup() o mais cedo possível na jornada de pagamento — idealmente logo após a inicialização do SDK. O ThreatMetrix precisa de tempo para coletar o fingerprint em segundo plano.

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 (client.isFraudAnalysisAvailable()) {
  const fraud = await client.fraudAnalysis.setup();
  fraudSessionId = fraud.sessionId;
}

// 3. Enquanto isso, o usuário preenche o formulário...

// 4. Ao submeter, use o sessionId na cobrança
await criarCobranca({
  // ... dados da cobrança
  fraud_session_id: fraudSessionId,
});

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.accithus.com/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('sk_sua_chave:'),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 15000,
    payment_method: 'credit_card',
    card_token: tokenResult.token,
    installments: 1,
    fraud_session_id: fraudResult.sessionId,
    customer: {
      name: 'Comprador Teste',
      email: '[email protected]',
      document: '12345678900',
    },
  }),
});

curl -X POST https://api.accithus.com/v1/charges \
  -H "Authorization: Basic base64(sk_sua_chave:)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "payment_method": "credit_card",
    "card_token": "tok_abc123...",
    "installments": 1,
    "fraud_session_id": "braspag_abc123...uuid",
    "customer": {
      "name": "Comprador Teste",
      "email": "[email protected]",
      "document": "12345678900"
    }
  }'

Tratamento de erros

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

try {
  const result = await client.fraudAnalysis.setup();
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`Erro ${error.code}: ${error.message}`);
  } else if (error instanceof NetworkError) {
    // Falha de rede — tente novamente
    console.error('Erro de conexão:', error.message);
  }
}

Se a análise de fraude falhar, a cobrança ainda pode ser criada sem o fraud_session_id (desde que o merchant não tenha configurado a análise como obrigatória). Porém, a transação não terá a proteção antifraude.

Começando

Cobranças

Submerchants

Financeiro

Configuração

SDK de Segurança

Webhooks

Análise de fraude

Como funciona

Uso básico

Retorno (`FraudSetupResult`)

O que o ThreatMetrix coleta

Dados coletados pelo SDK

Quando chamar o setup

Sessão de fraude

Usando na cobrança

Tratamento de erros

​Como funciona

​Uso básico

​Retorno (FraudSetupResult)

​O que o ThreatMetrix coleta

​Dados coletados pelo SDK

​Quando chamar o setup

​Sessão de fraude

​Usando na cobrança

​Tratamento de erros

Como funciona

Uso básico

Retorno (`FraudSetupResult`)

O que o ThreatMetrix coleta

Dados coletados pelo SDK

Quando chamar o setup

Sessão de fraude

Usando na cobrança

Tratamento de erros