🛡️ Autenticação 3DS (3D Secure)

📋 Visão Geral

O 3D Secure é um protocolo de autenticação que adiciona uma camada extra de segurança às transações de cartão de crédito. Implementamos o 3DS 2.0 para reduzir fraudes e aumentar a taxa de aprovação das transações.

🔒

Redução de Fraudes

Autenticação adicional reduz significativamente chargebacks

📈

Taxa de Aprovação

Transações 3DS têm maior taxa de aprovação pelos bancos

⚡

Experiência Otimizada

Fluxo transparente com challenge apenas quando necessário

🚀 Fluxo Completo

O 3DS deve ser usado em conjunto com a tokenização. O fluxo recomendado é:

1. Incluir SDK → Adiciona a biblioteca ao projeto
2. Configurar Chave Pública → Define a chave pública
3. Verificar se 3DS está disponível → Verifica se deve usar o fluxo 3DS
4. Inicializar 3DS → Define parâmetros da transação
5. Autenticar 3DS → Autentica o cartão
6. Finalizar 3DS → Completa o processo
7. Tokenizar Cartão → Inclui dados do 3DS no token

Diagrama do Fluxo

🔧 Implementação

1. Incluir a Biblioteca

Adicione nosso SDK JavaScript ao seu HTML:

<!-- Produção -->
<script src="https://js.fastsoftbrasil.com/security.js"></script>

2. Configurar Chave Pública

Configure sua chave pública antes de usar o 3DS:

// Aguarde o carregamento do SDK
document.addEventListener('DOMContentLoaded', async function() {
  try {
    // Configure sua chave pública (carrega scripts de segurança automaticamente)
    await FastSoft.setPublicKey('pk_live_sua_chave_publica_aqui');
    
    console.log('FastSoft SDK inicializado - 3DS pronto para uso');
  } catch (error) {
    console.error('Erro ao inicializar SDK:', error.message);
  }
});

3. Verificar se 3DS está disponível

Antes de inicializar, verifique se o 3DS está disponível:

function checkThreeDSAvailability() {
  if (!FastSoft.isThreeDSEnabled()) {
    console.log('3DS não está disponível - prosseguir direto para tokenização');
    return false;
  }
  
  console.log('3DS está disponível - iniciar fluxo de autenticação');
  return true;
}

4. Inicializar 3DS

Configure os parâmetros da transação antes de processar:

async function initializeThreeDS() {
  // Verificar se 3DS está disponível usando a função auxiliar
  if (!checkThreeDSAvailability()) {
    console.log('3DS não disponível - pulando para tokenização');
    return await tokenizeWithoutThreeDS();
  }

  const threeDSData = {
    amount: 1000,        // Valor em centavos
    currency: "BRL",     // Moeda da transação
    installments: 1      // Número de parcelas
  };

  try {
    await FastSoft.initializeThreeDS(threeDSData);
    console.log('3DS inicializado com sucesso');
    
    // Agora pode processar o 3DS
    await authenticateThreeDS();
    
  } catch (error) {
    console.error('Erro ao inicializar 3DS:', error.message);
    throw error;
  }
}

5. Autenticar 3DS

Execute a autenticação 3DS com os dados do cartão:

async function authenticateThreeDS() {
  const cardData = {
    number: "4000000000002503",
    expMonth: "12",
    expYear: "2028",
    holderName: "JOAO DA SILVA"
  };

  try {
    const threeDSResult = await FastSoft.authenticateThreeDS(cardData);
    
    console.log('Resultado 3DS:', threeDSResult);
    
    // Processar baseado no tipo de resposta
    handleThreeDSResponse(threeDSResult);
    
  } catch (error) {
    console.error('Erro ao autenticar 3DS:', error.message);
  }
}

6. Finalizar 3DS

Após processar o 3DS, finalize o processo:

async function finalizeThreeDS() {
  try {
    // Finalizar 3DS após autenticar
    await FastSoft.finalizeThreeDS();
    console.log('3DS finalizado com sucesso');
    
    // Agora pode tokenizar o cartão
    await tokenizeWithThreeDS();
    
  } catch (error) {
    console.error('Erro ao finalizar 3DS:', error.message);
    throw error;
  }
}

7. Tokenizar com 3DS

Após finalizar o 3DS, tokenize o cartão (os dados 3DS são incluídos automaticamente):

async function tokenizeWithThreeDS() {
  const cardData = {
    number: "4000000000002503",
    holderName: "JOAO DA SILVA",
    expMonth: "12",
    expYear: "2028",
    cvv: "123"
  };

  try {
    // O SDK automaticamente inclui os dados do 3DS no token
    const cardToken = await FastSoft.encrypt(cardData);
    
    console.log('Token com 3DS:', cardToken);
    return cardToken;
    
  } catch (error) {
    console.error('Erro na tokenização:', error.message);
    throw error;
  }
}

8. Tokenizar sem 3DS

Quando 3DS não está disponível, tokenize diretamente:

async function tokenizeWithoutThreeDS() {
  const cardData = {
    number: "4000000000002503",
    holderName: "JOAO DA SILVA",
    expMonth: "12",
    expYear: "2028",
    cvv: "123"
  };

  try {
    // Tokenização direta sem dados 3DS
    const cardToken = await FastSoft.encrypt(cardData);
    
    console.log('Token criado sem 3DS:', cardToken);
    return cardToken;
    
  } catch (error) {
    console.error('Erro na tokenização:', error.message);
    throw error;
  }
}

📊 Tipos de Resposta 3DS

O 3DS pode retornar diferentes tipos de resposta:

Success (Sucesso)

{
  type: "success",
  // Dados da autenticação bem-sucedida
  // Token pode ser usado normalmente
}

Failure (Falha)

{
  type: "failure",
  // Autenticação falhou
  // Deve ser enviado para processamento mesmo assim
}

⚠️ Importante: Em caso de failure, a transação deve ser enviada normalmente para o gateway. Se a adquirente principal tiver 3DS obrigatório, a transação será recusada automaticamente pelo gateway. Mesmo assim, os dados devem ser repassados para análise e processamento.

Unenrolled (Não Inscrito)

{
  type: "unenrolled",
  // Cartão não inscrito no 3DS
  // Pode prosseguir sem 3DS
}

Error (Erro)

{
  type: "error",
  // Erro durante processamento
  // Recomendado: Tentar novamente
}

UnsupportedBrand (Bandeira não suportada)

{
  type: "unsupportedBrand",
  // Bandeira do cartão não suporta 3DS
  // Pode prosseguir sem 3DS
}

Disabled (Desabilitado)

{
  type: "disabled",
  // 3DS desabilitado para este cartão
  // Pode prosseguir sem 3DS
}

🎯 Tratamento de Respostas

function handleThreeDSResponse(result) {
  switch (result.type) {
    case 'success':
      console.log('✅ 3DS autenticado com sucesso');
      // Prosseguir com a transação
      break;
      
    case 'failure':
      console.log('❌ Autenticação 3DS falhou');
      // Continuar com o processamento - o gateway decidirá se aceita ou rejeita
      break;
      
    case 'unenrolled':
    case 'disabled':
    case 'unsupportedBrand':
      console.log('⚠️ 3DS não disponível, prosseguindo sem autenticação');
      // Continuar sem 3DS
      break;
      
    case 'error':
      console.log('🔄 Erro no 3DS, tentando novamente');
      // Implementar retry logic
      break;
      
    default:
      console.log('❓ Resposta 3DS desconhecida');
      // Tratar como erro
  }
}

🔍 Exemplo Completo

async function processThreeDSAndTokenize() {
  const transactionData = {
    amount: 1000,
    currency: "BRL",
    installments: 1
  };
  
  const cardData = {
    number: "4000000000002503",
    holderName: "JOAO DA SILVA",
    expMonth: "12",
    expYear: "2028",
    cvv: "123"
  };

  try {
    // 1. Verificar se 3DS está disponível
    if (!await FastSoft.isThreeDSEnabled()) {
      console.log('⚠️ 3DS não disponível - tokenizando diretamente');
      const cardToken = await FastSoft.encrypt(cardData);
      return cardToken;
    }

    // 2. Inicializar 3DS
    console.log('🔒 Inicializando 3DS...');
    await FastSoft.initializeThreeDS(transactionData);
    
    // 3. Autenticar 3DS
    console.log('🚀 Autenticando 3DS...');
    const threeDSResult = await FastSoft.authenticateThreeDS(cardData);
    
    // 4. Verificar resultado
    if (threeDSResult.type === 'failure') {
      console.log('⚠️ Autenticação 3DS falhou - continuando processamento');
      // Continua o fluxo - o gateway decidirá se aceita ou rejeita
    }
    
    // 5. Finalizar 3DS
    console.log('🏁 Finalizando 3DS...');
    await FastSoft.finalizeThreeDS();
    
    // 6. Tokenizar cartão (inclui dados 3DS automaticamente)
    console.log('🔐 Tokenizando cartão...');
    const cardToken = await FastSoft.encrypt(cardData);
    
    console.log('✅ 3DS autenticado e token criado com sucesso!', cardToken);
    return cardToken;
    
  } catch (error) {
    console.error('❌ Erro no fluxo 3DS:', error.message);
    throw error;
  }
}

🔧 Métodos Disponíveis

FastSoft.setPublicKey(key)

Define a chave pública e carrega scripts de segurança.

Parâmetros:

• key (string): Sua chave pública

Retorno:

• Promise que resolve quando scripts são carregados

FastSoft.isThreeDSEnabled()

Verifica se existe a necessidade do uso do fluxo de 3DS.

Parâmetros:

• Nenhum parâmetro necessário

Retorno:

• boolean: true se o 3DS está disponível e deve ser usado, false caso contrário

FastSoft.initializeThreeDS(data)

Inicializa o 3DS com parâmetros da transação.

Parâmetros:

• data.amount (number): Valor em centavos
• data.currency (string): Código da moeda (BRL, USD, EUR)
• data.installments (number): Número de parcelas

Retorno:

• Promise que resolve quando 3DS está pronto

FastSoft.authenticateThreeDS(card)

Processa a autenticação 3DS.

Parâmetros:

• card.number (string): Número do cartão
• card.expMonth (string): Mês de expiração
• card.expYear (string): Ano de expiração
• card.holderName (string): Nome do portador

Retorno:

• Promise que resolve com o resultado da autenticação

FastSoft.finalizeThreeDS()

Finaliza o processo 3DS.

Parâmetros:

• Nenhum parâmetro necessário

Retorno:

• Promise que resolve em caso de sucesso ou rejeita em caso de erro

FastSoft.encrypt(cardData)

Tokeniza os dados do cartão incluindo informações do 3DS.

Parâmetros:

• cardData (object): Dados do cartão
  • number (string): Número do cartão
  • holderName (string): Nome no cartão
  • expMonth (string): Mês de expiração
  • expYear (string): Ano de expiração
  • cvv (string): CVV

Retorno:

• Promise que resolve com o token (string)

🚨 Tratamento de Erros

// Verificar disponibilidade do 3DS
if (!FastSoft.isThreeDSEnabled()) {
  console.log('3DS não disponível - possíveis razões:');
  console.log('- Scripts de segurança não carregados');
  console.log('- 3DS não configurado para esta conta');
  console.log('- Erro ao carregar componentes 3DS');
  // Prosseguir direto para tokenização
}

// Tratamento de erros na inicialização
try {
  await FastSoft.initializeThreeDS(data);
} catch (error) {
  switch (error.message) {
    case 'amount, currency e installments são obrigatórios.':
      // Parâmetros obrigatórios não fornecidos
      break;
    case 'Classe de 3DS não encontrada.':
      // Erro no carregamento dos scripts 3DS
      break;
    case '3DS não inicializado.':
      // Tentativa de processar sem inicializar
      break;
    default:
      // Outros erros
      console.error('Erro 3DS:', error.message);
  }
}

// Tratamento de erros para finalizeThreeDS
try {
  await FastSoft.finalizeThreeDS();
} catch (error) {
  console.error('Erro ao finalizar 3DS:', error.message);
  throw error;
}

💡 Dica: Em caso de 3DS failure, não interrompa o fluxo da aplicação. Continue com a finalização e tokenização. O gateway processará automaticamente baseado na configuração da adquirente.

🔧 Nota: Quando isThreeDSEnabled() retorna false, o SDK automaticamente tokeniza sem incluir dados 3DS. Isso é normal e a transação pode prosseguir normalmente.

❓ FAQ

O 3DS é obrigatório?

Não, mas é altamente recomendado para reduzir fraudes e aumentar aprovação. Use FastSoft.isThreeDSEnabled() para verificar se o 3DS está disponível em sua configuração.

Quais bandeiras suportam 3DS?

Visa, Mastercard e Elo são as principais bandeiras testadas com os cartões fornecidos.

O 3DS aumenta a conversão?

Sim, transações 3DS têm maior taxa de aprovação pelos bancos emissores.

Como testar o 3DS?

Use os cartões de teste específicos listados na seção "Cartões de Teste". Há cartões para simular cenários com e sem desafio, incluindo SUCCESS, FAILURE, UNENROLLED e ERROR.

O 3DS funciona com parcelas?

Sim, o número de parcelas é configurado na inicialização.

Qual a diferença entre cartões com e sem desafio?

Cartões com desafio simulam o fluxo completo de autenticação 3DS onde o usuário precisa inserir senha/código no banco emissor. Cartões sem desafio simulam autenticação automática baseada no perfil de risco, sem interação do usuário.

E se o 3DS falhar (failure)?

Mesmo em caso de failure, a transação deve ser enviada normalmente para o gateway. Se a adquirente principal tiver 3DS obrigatório, a transação será automaticamente recusada pelo gateway. Independentemente disso, os dados devem sempre ser repassados para análise e processamento.

Quando usar isThreeDSEnabled?

A função isThreeDSEnabled() deve ser chamada antes de iniciar o fluxo 3DS para verificar se o 3DS está disponível e configurado. Se retornar false, você pode pular direto para a tokenização.

Quando usar finalizeThreeDS?

A função finalizeThreeDS() deve ser chamada após autenticar o 3DS e antes de tokenizar o cartão. Ela completa o processo de autenticação 3DS.

🧪 Cartões de Teste

Use os cartões de teste a seguir para simular diversos cenários no ambiente sandbox.

Cartões de teste com desafio

Cartão	Bandeira	Resultado	Cenário
4000000000002503 5200000000002151 6505290000002190	VISA MASTER ELO	SUCCESS	Autenticação com desafio e portador autenticado com sucesso.
4000000000002370 5200000000002490 6505290000002208	VISA MASTER ELO	FAILURE	Autenticação com desafio e portador autenticado com falha.*
4000000000002420 5200000000002664 6505290000002257	VISA MASTER ELO	UNENROLLED	Autenticação com desafio indisponível no momento.
4000000000002644 5200000000002656 6505290000002265	VISA MASTER ELO	ERROR	Erro de sistema durante a etapa de autenticação.

Cartões de teste sem desafio

Cartão	Bandeira	Resultado	Cenário
4000000000002701 5200000000002235 6505290000002000	VISA MASTER ELO	SUCCESS	Autenticação sem desafio e portador autenticado com sucesso.
4000000000002925 5200000000002276 6505290000002018	VISA MASTER ELO	FAILURE	Autenticação sem desafio e portador autenticado com falha.*

Dados de Teste Padrão

Para todos os cartões de teste, use:

• Nome: JOAO DA SILVA
• Mês: 12
• Ano: 2028
• CVV: 123

💡 Diferença entre desafio e sem desafio: Cartões com desafio simulam o fluxo completo de autenticação 3DS onde o usuário precisa inserir senha/código. Cartões sem desafio simulam autenticação automática baseada no perfil de risco.

🔧 Dica de uso: Para testar diferentes cenários, troque o número do cartão no objeto cardData pelos números listados nas tabelas acima.

*Importante sobre Failure: Cartões que retornam "failure" devem ser enviados normalmente para o gateway. Se a adquirente tiver 3DS obrigatório, a transação será automaticamente recusada. Caso contrário, pode ser aprovada normalmente.

---

📚 Próximos passos: Tokenização de Cartões | Criar Primeira Transação | Webhooks