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); // "550e8400-e29b-41d4-a716-446655440000"
// 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 (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.worldfypayments.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',
    product_type: 'digital',
    customer: {
      name: 'Comprador Teste',
      email: 'comprador@email.com',
      tax_id: '12345678900',
      phone: '11999998888',
      type: 'individual',
    },
    items: [
      { name: 'Pedido', quantity: 1, unit_price: 15000, tangible: false },
    ],
    payment_details: {
      token: tokenResult.token,
      installments: 1,
    },
    fraud_session_id: fraudResult.sessionId,
  }),
});

curl -X POST https://api.worldfypayments.com/v1/charges \
  -H "Authorization: Basic base64(sk_sua_chave:)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "payment_method": "credit_card",
    "product_type": "digital",
    "customer": {
      "name": "Comprador Teste",
      "email": "comprador@email.com",
      "tax_id": "12345678900",
      "phone": "11999998888",
      "type": "individual"
    },
    "items": [
      { "name": "Pedido", "quantity": 1, "unit_price": 15000, "tangible": false }
    ],
    "payment_details": {
      "token": "tok_abc123...",
      "installments": 1
    },
    "fraud_session_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Tratamento de erros

import { ApiError, NetworkError } from '@worldfy/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);
  }
}