Autenticação 3DS

O que é 3D Secure

O 3D Secure (3DS) é um protocolo de autenticação que verifica a identidade do portador do cartão junto ao banco emissor durante uma transação online. Ele oferece:

• Liability shift — a responsabilidade por chargebacks é transferida para o emissor quando a autenticação é bem-sucedida
• Redução de fraudes — adiciona uma camada de verificação biométrica, SMS ou app bancário
• Conformidade regulatória — atende requisitos de Strong Customer Authentication (SCA)

O SDK integra o 3DS 2.0 via BP.Mpi (Braspag MPI), que suporta fluxos frictionless (sem interação do usuário) e challenge (com interação).

Fluxo de autenticação

Status possíveis

Uso básico

const result = await client.threeds.authenticate({
  amount: 15000, // R$ 150,00 em centavos
  currency: 'BRL',
  installments: 1,
  card: {
    number: '4000000000002701',
    expirationMonth: '12',
    expirationYear: '2030',
  },
  customer: {
    name: 'Comprador Teste',
    email: 'teste@email.com',
    phone: '5511999999999',
  },
});

if (result.status === 'authenticated') {
  console.log('CAVV:', result.cavv);
  console.log('ECI:', result.eci);
  // Prossiga com a cobrança usando o CAVV
}

Parâmetros da autenticação

Endereço (opcional, recomendado)

Opções adicionais

const result = await client.threeds.authenticate(dados, {
  timeout: 120000, // Timeout em ms (padrão: 120s)
});

Retorno (ThreeDSResult)

Fluxo frictionless vs. challenge

O emissor decide se o fluxo será frictionless (sem interação) ou challenge (com interação). Essa decisão é baseada em:

• Perfil de risco da transação
• Histórico do portador do cartão
• Valor da transação
• Dados do dispositivo e navegador

No fluxo frictionless, a autenticação acontece em segundo plano e o resultado é retornado diretamente. No fluxo challenge, o SDK exibe automaticamente um modal com o iframe do banco emissor para que o usuário complete a verificação (SMS, biometria, app bancário etc.).

Informações coletadas automaticamente

O SDK coleta e envia automaticamente dados do navegador necessários para a avaliação de risco do emissor:

• User Agent, idioma e fuso horário
• Resolução de tela e profundidade de cor
• Suporte a Java e JavaScript
• Endereço IP público (via api.ipify.org)

Nenhuma ação adicional é necessária — essas informações são coletadas transparentemente pelo método authenticate().

Cartões de teste

Tratamento de erros

import { ThreeDSError, TimeoutError } from '@worldfy/security-sdk';

try {
  const result = await client.threeds.authenticate(dados);

  switch (result.status) {
    case 'authenticated':
      // Prossiga com a cobrança
      break;
    case 'unenrolled':
      // Cartão não suporta 3DS — decida se aceita sem autenticação
      break;
    case 'failed':
      // Autenticação negada pelo emissor
      break;
    case 'cancelled':
      // Usuário cancelou ou timeout
      break;
    case 'error':
      // Erro técnico — tente novamente
      break;
  }
} catch (error) {
  if (error instanceof TimeoutError) {
    // Timeout na comunicação com a API
  } else if (error instanceof ThreeDSError) {
    // Erro no fluxo 3DS
    console.error(`Status: ${error.status}`, error.message);
  }
}

Moedas suportadas