Guides
GuidesSuporteAPI Reference

Guia de Migração 3DS – Diferenças entre Versões

Saiba como migrar sua integração 3DS para a versão mais atual.

Suggest Edits

Índice

  1. Visão Geral
  2. Alteração de URL para GET Token
  3. Troca de URLs da Biblioteca
  4. Mudança nos Elementos de Exibição do Challenge e Execução do TDSMethod
  5. Mudança na Estrutura da Função init
  6. Envio do Objeto Order Diretamente na Função
  7. Mudança no Retorno da Função init
  8. Exemplo Completo

Visão Geral

Este documento é destinado a clientes que já possuem integração com o 3DS e desejam migrar para a nova versão da solução. Aqui você encontrará um resumo objetivo e detalhado das principais mudanças que precisam ser aplicadas para garantir compatibilidade com a nova implementação.
O objetivo é facilitar o processo de atualização, reduzindo retrabalho e evitando comportamentos inesperados durante a migração.
Este documento fornece uma visão clara e organizada das mudanças necessárias ao migrar de uma versão anterior para a nova integração 3DS.

Alteração de URL para GET Token

As URLs base usadas para obter o token foram alteradas.

AmbienteURL Base
Sandboxhttps://3ds-sdx.stone.com.br/v2
Produçãohttps://3ds.stone.com.br/v2

Troca de URLs da Biblioteca

As URLs da biblioteca 3DS também foram atualizadas.

AmbienteURL da Biblioteca
Sandboxhttps://3ds-nx-js.stone.com.br/test/v2/3ds2.min.js
Produçãohttps://3ds-nx-js.stone.com.br/live/v2/3ds2.min.js

Mudança nos Elementos de Exibição do Challenge e Execução do TDSMethod

Agora a integração requer dois containers específicos no HTML:

<!-- Container invisível para o 3DS Method -->
<div id="tdsMethodContainer" style="display: none;"></div>
<!-- Container para o Challenge -->
<div id="challengeContainer"></div>

Isso quer dizer que além da adição desses novos containers, a tag do iframe para visualização do challenge pode ser removida.

- <iframe
-  id="challengeIframe"
-  name="challengeIframe"
-  data-pagarmecheckout-element="challengeIframe">
- </iframe>

Mudança na Estrutura da Função init

A função init mudou um pouco a estrutura, e na nova versão recebemos os parâmetros da seguinte forma

window.TDS.init(
  {
    token: token, // Token gerado
    tds_method_container_element: tdsMethodContainer, // Referência do tdsMethodContainer anteriormente adicionado
    challenge_container_element: challengeContainer, // Referência do challengeContainer anteriormente adicionado
    use_default_challenge_iframe_style: true, // Opção true ou false para style referente ao challenge gerado
    challenge_window_size: '03', // Tamanho da janela do challenge
  },
  orderData, // Informações do order passadas diretamente
);

Envio do Objeto Order Diretamente na Função

Como comentado no item anterior, agora os dados dos pedidos devem ser enviados diretamente via orderData dentro da chamada window.TDS.init().

A nova versão não captura mais valores via data- attributes.

Isso significa que, atributos como data-pagarmecheckout-form e data-pagarmecheckout-element antes usados para coleta de informações do pedido diretamente do formulário, agora podem ser removidos.

Essa mudança tem como intuito que o tratamento e organização dos dados fiquem sob responsabilidade do cliente, oferecendo mais flexibilidade para adaptar a implementação ao próprio fluxo e regras de negócio, de acordo com a tecnologia utilizada na integração.

Exemplo de Objeto Order

const orderData = {
  "payments": [
    {
      "payment_method": "credit_card",
      "credit_card": {
        "card": {
          "number": "3000100811112072", // Cartão de teste que gera challenge manual
          "holder_name": "JOAO SILVA",
          "exp_month": 12,
          "exp_year": 2028,
          "billing_address": {
            "country": "BR",
            "state": "SP",
            "city": "São Paulo",
            "zip_code": "01234567",
            "line_1": "123, Rua das Flores, Centro",
            "line_2": "Apartamento 45"
          }
        },
      },
      "amount": 20000
    }
  ],
  "customer": {
    "name": "João Silva",
    "email": "[email protected]",
    "code": "CUST-001",
    "document": "12345678901",
    "phones": {
      "home_phone": {
        "country_code": "55",
        "area_code": "11",
        "number": "987654321"
      },
      "mobile_phone": {
        "country_code": "55",
        "area_code": "11",
        "number": "123456789"
      }
    }
  },
  "items": [
    {
      "amount": 15000,
      "description": "Smartphone Samsung Galaxy",
      "quantity": 1,
      "code": "ITEM-001"
    },
    {
      "amount": 5000,
      "description": "Capa Protetora",
      "quantity": 2,
      "code": "ITEM-002"
    }
  ],
  "shipping": {
    "recipient_name": "João Silva",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "zip_code": "01234567",
      "line_1": "123, Rua das Flores, Centro",
      "line_2": "Apartamento 45"
    }
  }
};

Para mais informações sobre a estrutura do orderData, acesse a página de integração 3DS.

Mudança no Retorno da Função init

Com as alterações feitas na função init, deixamos de utilizar o padrão baseado em callback e passamos a retornar o resultado por meio de uma Promise. Além disso, o tipo de retorno também mudou: em vez de um único objeto, agora a função passa a retornar um array de objetos.
Por isso, é necessário ajustar a forma como essas informações são recebidas e tratadas no código.

Exemplo Completo

- <script src="https://3ds2-sdx.pagar.me/v1/3ds2.min.js"></script>
+ <script src="https://3ds-nx-js.stone.com.br/test/v2/3ds2.min.js"></script>

+ <div id="tdsMethodContainer" style="display:none;"></div>
+ <div id="challengeContainer"></div>

- <iframe
-  id="challengeIframe"
-  name="challengeIframe"
-  data-pagarmecheckout-element="challengeIframe">
- </iframe>

<script>
-  function callback(data) {
-    return true;
-  };   
-  tdsData = { ... }
-  init3ds(tdsToken, tdsData, callback, challengeWindowSize)

+  window.TDS.init(
+    {
+      token: 'SEU_TOKEN_AQUI',
+      tds_method_container_element:
+      document.getElementById('tdsMethodContainer'),
+      challenge_container_element:
+      document.getElementById('challengeContainer'),
+      use_default_challenge_iframe_style: true,
+      challenge_window_size: '03',
+    },
+    orderData,
+  )
+  .then((results) => {
+    // results é um array de objetos com os resultados da autenticação
+    results.forEach((result) => {
+      console.log('ID da transação:', result.tds_server_trans_id);
+      console.log('Status:', result.trans_status);
+      console.log('Cartão autenticado:', result.authenticated_card);
+      console.log('Challenge cancelado:', result.challenge_canceled);
+    });
+  })
+  .catch((error) => {
+    console.error('Erro na autenticação 3DS:', error);
+  });
</script>

Para mais informações sobre a nova versão do 3DS, sua integração e testes, acesse o Manual de Integração 3DS

Updated 2 days ago