ENOQ PayDocs
v3

Biblioteca ENOQ

Ir para a página da ENOQ

Biblioteca 3DS

Introdução à Biblioteca 3DS 2.0

Em situações específicas, além do antifraude, é necessário utilizar a Biblioteca 3DS 2.0 para transações como vendas em cartões de débito. Essa implementação é feita através de uma biblioteca JavaScript fornecida por ENOQ Pay, projetada para minimizar fraudes sem comprometer a taxa de conversão.

O que é o 3DS 2.0?

O 3DS 2.0 é uma tecnologia avançada que segue normas rigorosas de segurança, principalmente vindas da Europa. Seu objetivo é facilitar a identificação de fraudes por bancos emissores enquanto mantém a experiência do cliente fluida e segura.

Funcionamento

  1. Informações do cliente: O cliente preenche os dados do cartão (crédito ou débito) e confirma a compra.
  2. Coleta de dados: O processador de pagamentos reúne até 100 informações sobre a transação (ex.: número do cartão, endereço IP, entre outros).
  3. Envio ao banco: Essas informações são enviadas ao banco emissor com tecnologia certificada.
  4. Validação: Em alguns casos, um "desafio" é solicitado para o cliente confirmar sua identidade, garantindo máxima segurança.

Fluxos Possíveis

Para a autenticação 3DS, há dois cenários principais:

  1. Sem desafio: O banco emissor não solicita nenhuma ação adicional do cliente.
  2. Com desafio: O cliente precisa validar a transação, como confirmar um código enviado ao celular.

Fluxo de Pagamento com e sem Desafio

Exemplo de implementação

Confira um exemplo de implementação do 3DS ENOQ:

https://cdn.sopague.com.br/POC/POCs-3DS-SOPAGUE-EXEMPLOS-v-1-1.zip

No arquivo ZIP, você encontrará duas pastas:

  • POC_3DS_EXPLAIN

    • Apresenta, de forma didática e passo a passo, a jornada de implementação do 3DS.
    • Nesse exemplo, você interagirá com a aplicação pelo navegador e enviará algumas requisições à API utilizando Postman ou Insomnia.
    • O objetivo é facilitar a compreensão das etapas, dos dados envolvidos e das responsabilidades de cada componente da integração.

  • POC_3DS_SOPAGUE

    • Apresenta uma implementação mais próxima de um cenário real de uso.
    • O fluxo de integração está automatizado: basta configurar as credenciais do ambiente de homologação, preencher os dados do checkout e, quando solicitado, concluir a autenticação 3DS no aplicativo do banco emissor.

Uso e finalidade demonstrativa

Esses códigos precisam ser usados em uma IDE, como o Visual Studio Code.

Os códigos têm finalidade exclusivamente demonstrativa e educacional. Eles foram desenvolvidos para apresentar a integração de maneira simples e objetiva e não devem ser considerados uma implementação pronta para produção.

A adaptação para a arquitetura do integrador, assim como validações, tratamento de erros, observabilidade, proteção de credenciais, conformidade e demais boas práticas de desenvolvimento e segurança, é de responsabilidade do integrador.

Ambiente de homologação

Recomendamos utilizar exclusivamente credenciais e cartões de teste do ambiente de homologação durante a avaliação dos exemplos.

Coleta de Dados do Navegador

Antes de processar o pagamento, a biblioteca coleta informações do navegador do cliente, que são enviadas ao endpoint /payments/3ds. Os dados necessários incluem:

  • Cabeçalho Accept do navegador (httpAcceptBrowserValue) — string
  • Conteúdo aceito (httpAcceptContent) — string
  • Idioma do navegador (httpBrowserLanguage) — string
  • Suporte a Java (httpBrowserJavaEnabled) — boolean
  • Suporte a JavaScript (httpBrowserJavaScriptEnabled) — boolean
  • Profundidade de cor (httpBrowserColorDepth) — string
  • Resolução da tela (httpBrowserScreenHeight e httpBrowserScreenWidth) — string
  • Diferença de fuso horário (httpBrowserTimeDifference) — string
  • Agente do navegador (userAgentBrowserValue) — string
  • Endereço IP do cliente (ipAddress) — string

É necessário obter alguns dados através do navegador do cliente para enviar para o endpoints de pagamento /payments/3ds, tais como:

const browserData = {
  httpAcceptBrowserValue: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
  httpAcceptContent: "*/*",
  httpBrowserLanguage: navigator.language || navigator.userLanguage,
  httpBrowserJavaEnabled: navigator.javaEnabled(),
  httpBrowserJavaScriptEnabled: true,
  httpBrowserColorDepth: String(screen.colorDepth),
  httpBrowserScreenHeight: String(window.innerHeight),
  httpBrowserScreenWidth: String(window.innerWidth),
  httpBrowserTimeDifference: String(new Date().getTimezoneOffset()),
  userAgentBrowserValue: navigator.userAgent,
  ipAddress: "177.200.69.102"
};

Tipos esperados

Envie httpBrowserJavaEnabled e httpBrowserJavaScriptEnabled como booleanos, sem aspas e sem converter para "Y" ou "N". Os campos de profundidade de cor, resolução e fuso horário devem ser enviados como strings. Substitua o IP do exemplo pelo endereço IP real do cliente, obtido pela aplicação ou pelo backend.

Além disso, a biblioteca 3DS irá gerar um "code3ds" que também deve ser enviado ao backend. Complementar ao serviço de 3DS, também deve ser implementada a biblioteca do antifraude.

Benefícios do 3DS 2.0

  • Maior segurança: Reduz o risco de fraudes em transações online.
  • Experiência otimizada: Integração fluida entre sites e aplicativos.
  • Conformidade internacional: Alinhado às normas de segurança mais rigorosas.

Dicas para Desenvolvedores

  • Certifique-se de que o ambiente de integração seja seguro e compatível.
  • Realize testes abrangentes em cenários comuns e raros.
  • Consulte atualizações da biblioteca para garantir que está usando a versão mais recente.

Para dúvidas ou suporte, entre em contato com a equipe técnica da ENOQ Pay.