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'

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 '@soarlabz/security-sdk';

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

  switch (result.status) {
    case 'authenticated':
      // Prossiga com a cobrança
      break

Moedas suportadas