Pular para o conteúdo principal

🛡️ 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 e dados do cartã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
    card: {              // Dados do cartão
      number: "4000000000002503",
      holderName: "JOAO DA SILVA",
      expMonth: "12",
      expYear: "2028"
    }
  };

  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 consumidor e endereço:

async function authenticateThreeDS() {
  const authData = {
    customer: {                // Dados do consumidor
      name: "JOAO DA SILVA",
      email: "joao.silva@email.com",
      phoneNumber: "11999999999"
    },
    address: {                 // Dados do endereço
      street: "Avenida Paulista",
      streetNumber: "123",
      complement: "Apto 101",
      zipCode: "01000-000",
      neighborhood: "Bela Vista",
      city: "São Paulo",
      state: "SP",
      country: "BR"
    }
  };

  try {
    const threeDSResult = await FastSoft.authenticateThreeDS(authData);
    
    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 cardData = {
    number: "4000000000002503",
    holderName: "JOAO DA SILVA",
    expMonth: "12",
    expYear: "2028",
    cvv: "123"
  };

  const transactionData = {
    amount: 1000,
    currency: "BRL",
    installments: 1,
    card: {              // Dados do cartão para inicialização
      number: cardData.number,
      holderName: cardData.holderName,
      expMonth: cardData.expMonth,
      expYear: cardData.expYear
    }
  };

  const authData = {
    customer: {          // Dados do consumidor
      name: "JOAO DA SILVA",
      email: "joao.silva@email.com",
      phoneNumber: "11999999999"
    },
    address: {           // Dados do endereço
      street: "Avenida Paulista",
      streetNumber: "123",
      complement: "Apto 101",
      zipCode: "01000-000",
      neighborhood: "Bela Vista",
      city: "São Paulo",
      state: "SP",
      country: "BR"
    }
  };

  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 (com dados do cartão)
    console.log('🔒 Inicializando 3DS...');
    await FastSoft.initializeThreeDS(transactionData);
    
    // 3. Autenticar 3DS (com dados do cliente e endereço)
    console.log('🚀 Autenticando 3DS...');
    const threeDSResult = await FastSoft.authenticateThreeDS(authData);
    
    // 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 e dados do cartã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
  • data.card (object): Dados do cartão
    • card.number (string): Número do cartão
    • card.holderName (string): Nome do portador
    • card.expMonth (string): Mês de expiração
    • card.expYear (string): Ano de expiração

Retorno:

  • Promise que resolve quando 3DS está pronto

FastSoft.authenticateThreeDS(data)​

Processa a autenticação 3DS com dados do consumidor e endereço.

Parâmetros:

  • data.customer (object): Dados do consumidor
    • customer.name (string): Nome completo
    • customer.email (string): Email
    • customer.phoneNumber (string): Telefone
  • data.address (object): Dados do endereço
    • address.street (string): Rua/Avenida
    • address.streetNumber (string): Número
    • address.complement (string): Complemento
    • address.zipCode (string): CEP
    • address.neighborhood (string): Bairro
    • address.city (string): Cidade
    • address.state (string): Estado (UF)
    • address.country (string): País (código ISO)

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) {
  console.error('Erro ao inicializar 3DS:', error.message);
  
  // Possíveis erros:
  // - 'amount, currency e installments são obrigatórios.'
  // - 'Classe de 3DS não encontrada.'
  // - 'card.number é obrigatório.'
  // - 'card.holderName é inválido.'
  // - 'card.expMonth é inválido. Precisa ser menor ou igual a 2 caracteres.'
  // - 'card.expYear é inválido. Precisa ter 4 caracteres.'
}

// Tratamento de erros na autenticação
try {
  await FastSoft.authenticateThreeDS(authData);
} catch (error) {
  console.error('Erro ao autenticar 3DS:', error.message);
  
  // Possíveis erros:
  // - '3DS não inicializado.'
  // - 'Dados do cartão são obrigatórios. Forneça os dados como parâmetro ou durante a inicialização.'
  // - 'customer.name é obrigatório.'
  // - 'customer.email é obrigatório.'
  // - 'customer.phoneNumber é obrigatório.'
  // - 'address.street é obrigatório.'
  // - 'address.streetNumber é obrigatório.'
  // - 'address.complement é obrigatório.'
  // - 'address.zipCode é obrigatório.'
  // - 'address.neighborhood é obrigatório.'
  // - 'address.city é obrigatório.'
  // - 'address.state é obrigatório.'
  // - 'address.country é obrigatório.'
}

// Tratamento de erros na tokenização
try {
  const cardToken = await FastSoft.encrypt(cardData);
} catch (error) {
  console.error('Erro ao tokenizar cartão:', error.message);
  
  // Possíveis erros:
  // - 'card é obrigatório.'
  // - 'card.number é obrigatório.'
  // - 'card.holderName é inválido.'
  // - 'card.expMonth é inválido. Precisa ser menor ou igual a 2 caracteres.'
  // - 'card.expYear é inválido. Precisa ter 4 caracteres.'
  // - 'card.cvv é inválido. Precisa ter entre 3 e 4 caracteres.'
}

💡 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ãoBandeiraResultadoCenário
4000000000002503
5200000000002151
6505290000002190		VISA
MASTER
ELO		SUCCESSAutenticação com desafio e portador autenticado com sucesso.
4000000000002370
5200000000002490
6505290000002208		VISA
MASTER
ELO		FAILUREAutenticação com desafio e portador autenticado com falha.*
4000000000002420
5200000000002664
6505290000002257		VISA
MASTER
ELO		UNENROLLEDAutenticação com desafio indisponível no momento.
4000000000002644
5200000000002656
6505290000002265		VISA
MASTER
ELO		ERRORErro de sistema durante a etapa de autenticação.

Cartões de teste sem desafio​

CartãoBandeiraResultadoCenário
4000000000002701
5200000000002235
6505290000002000		VISA
MASTER
ELO		SUCCESSAutenticação sem desafio e portador autenticado com sucesso.
4000000000002925
5200000000002276
6505290000002018		VISA
MASTER
ELO		FAILUREAutenticaçã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

Última atualização em por Ícaro Sant'Ana