Integração com 3DS

O 3DS (3-Domain Secure) é um protocolo de segurança para transações financeiras realizadas no comércio eletrônico com o objetivo de autenticar e fornecer ao usuário uma boa experiência de compra.

Existem dois tipos de autenticação:

Sem desafio (sem atrito): quando o banco emissor entende que as informações fornecidas são suficientes para autenticar o consumidor.

Com desafio (com atrito): quando é necessária uma etapa de validação adicional, uma ação que o consumidor precisa realizar, por exemplo fornecer algum dado enviado via SMS ou a abertura do aplicativo para confirmação da compra. A decisão sobre a aplicação do desafio, o tipo e a tela de desafio no checkout são de responsabilidade do banco emissor do cartão.

Nota

Quando o Banco Emissor entender que o processo de autenticação deverá passar por um desafio, nem a Marlim, a PagSeguro, ou o MB podem ou conseguem modificar a UI das telas e modais que irão aparecer durante esse processo.

O Parceiro da Marlim para o 3DS é a Cybersource e é uma solução que permite o envio das transações autenticadas para a API de Transações da Marlim e essa integração será direto no checkout do MB, utlizando os processos descritos nessa documentação.

Importante

Antes de fazer a chamada para a API de Transações da Marlim, será necessário fazer a Autenticação com o 3DS, ou seja, todas as transações do seu cliente devem passar por esse processo para ser o parâmetro (threeds_session_id) no body da request da API de transações.

Fluxo de Autenticação com 3DS

O fluxo de Autenticação com 3DS é composto por 4 etapas:

1º Criptografar os dados do cartão (card_hash) para poder criar a sessão;
2º Chamar o endpoint da API da Marlim com os dados do cartão criptografados, para receber um TOKEN, URL e o ID SESSÃO para montar uma SESSÃO;
3º Recuperar dados do device do usuário para enviar na API de Transações;
4º Anexar o ID da sessão e os dados do device na API de Transações da Marlim;

1º Cryptografar os dados do cartão

Para criptografar os dados do cartão, siga o passo-a-passo através deste link até conseguir gerar um card_hash.

Dados do cartão criptografado (card_hash)

fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=

2º Montar uma Sessão

A construção de uma sessão envolve uma série de processos essenciais para garantir a correta configuração e execução da autenticação 3DS.

1º Chamar o endpoint de sessão na API da Marlim:

Ao enviar o card_hash pelo body da request, você irá receber quatro atributos. Dois deles, token e url, são importantes para a próxima etapa, enquanto o terceiro session_id e o quarto card_id serão utilizados na etapa final ao chamar a API de Transações.

Atributo	Descrição
token	Token de acesso fornecido pelo parceiro Cybersource, necessário para a inicialização do 3DS.
url	Endpoint a ser utilizado no envio do formulário POST durante a inicialização do 3DS. O valor da URL varia conforme o ambiente: https://centinelapistag.cardinalcommerce.com (SANDBOX) ou https://centinelapi.cardinalcommerce.com (PROD).
session_id	Identificador único da sessão 3DS, utilizado para rastrear e validar o processo de autenticação.
card_id	Identificador único gerado após o cliente fornecer os dados do cartão criptografado, será utilizado no endpoint de Transações da API.

Request

curl -X POST "https://api.crypto.mb.marlim.co/v3/3ds/sessions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_hash": "fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM="
}'

Response200

{
  "card_id": "card_6aazixgu9gei64m01lm1ha6c4",
  "token": "eyJhbGciOiJIUzI1....80Yl8zdI4A1b0IzXqMnHXgWu3xkB5rjFj5lr6CJdj7M",
  "session_id": "a80f428d...8b3a-ac8ad263918b",
  "url": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect"
}

Atenção!

Utlize essa chamada para API no seu Back-End, evitando expor a sua API KEY da Marlim no Client-Side de sua aplicação.

2º Iniciar um form POST em um "hidden" iframe

Com o token e a url em mãos, você deve inserir o seguinte código HTML para preparar a inicialização do 3DS.

<iframe name="ddc-iframe" height="1" width="1" style="display: none;" />

<form id="ddc-form" target=”ddc-iframe” method="POST" action="{{url}}">
  <input type="hidden" name="JWT" value="{{token}}" />
</form>

3º Enviar o formulário acima

Agora que o formulário está preenchido corretamente, basta enviá-lo. Veja o exemplo de código abaixo:

<script>
  window.onload = function() {
    const ddcForm = document.querySelector('#ddc-form');
    if (ddcForm) { // valide se o #ddc-form existe
      ddcForm.submit();
    }
  }
</script>

4º Validar a autenticação do formulário

Para garantir que o formulário foi enviado corretamente, é necessário adicionar este código JavaScript que valide a submissão do formulário. Lembrando que a URL de origem quando for SANDBOX é centinelapistag.cardinalcommerce.com, e a de PROD é centinelapi.cardinalcommerce.com

  <script>
    window.addEventListener("message", (event) => {
      if (event.origin === "https://centinelapistag.cardinalcommerce.com") {
        let data = JSON.parse(event.data);
        console.log('Merchant received a message:', data);
        if (data !== undefined && data.Status) {
          console.log('3DS authenticated successfully');
        }
      } else {
        console.log('Message from different origin.');
      }
    }, false)
  </script>

3º Dados do device do usuário

Neste passo, você precisa capturar algumas informações do navegador do usuário. Confira na tabela abaixo quais dados são esses.

Atributo	Tipo	Descrição
http_browser_color_depth	number	Quantidade de bits utilizados para exibição de imagens
http_browser_screen_height	number	Altura da resolução da tela do usuário
http_browser_screen_width	number	Largura da resolução da tela do usuário
http_browser_time_difference	number	Diferença em minutos entre o horário GMT e o do browser do usuário
http_browser_java_enabled	boolean	Se JAVA está habilitado no browser do usuário
http_browser_javascript_enabled	boolean	Se o JAVASCRIPT está habilitado no browser do usuário

Abaixo contém um snippet de código que você pode utilizar para está capturando estes dados com facilidade.

const device = {
  http_browser_color_depth: window.screen.colorDepth,
  http_browser_screen_height: window.screen.height,
  http_browser_screen_width: window.screen.width,
  http_browser_time_difference: new Date().getTimezoneOffset(),
}

4º API de Transações Marlim

Com todas as informações reunidas, basta enviá-las no corpo da requisição para que a transação seja processada com autenticação 3DS.

Nota

Mantenha sempre o valor da propriedade channel como BROWSER, pois os dados da autenticação 3DS foram capturados no navegador.

Request

curl -X POST "https://api.crypto.mb.marlim.co/v2/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "...": "...",
  "threeds_session_id": "c556ee1f-e9ef...8a05-3a3f9c42f31f",
  "device": {
    "channel": "BROWSER",
    "http_browser_java_enabled": false,
    "http_browser_javascript_enabled": true,
    "http_browser_color_depth": 24,
    "http_browser_screen_height": 1080,
    "http_browser_screen_width": 2560,
    "http_browser_time_difference": 180
  }
}'