O 3DS é um protocolo de segurança que visa proteger compras online com cartões de débito e crédito. Esta tecnologia adiciona uma camada extra de autenticação durante o processo de pagamento para garantir que é realmente o titular do cartão quem está realizando a transação.
Este manual tem como objetivo orientar o desenvolvedor na integração do 3DS, apresentando o passo a passo que deve ser seguido para garantir uma integração simples e fluida.
Antes de seguir para a integração em si, vale destacar alguns conceitos que podem surgir ao longo do desenvolvimento e que podem ser interessantes que o desenvolvedor esteja familiarizado.

Glossário

• Autorização: processo que sensibiliza o limite de crédito do portador do cartão junto ao banco emissor, geralmente utilizado para análise de prevenção, análise de limite de crédito e validação dos dados de cartão utilizado. A autorização não gera cobrança na fatura do comprador.
• Captura: processo que confirma uma transação autorizada. Após a captura o valor é debitado dos créditos do portador do cartão gerando a cobrança na fatura do mesmo.
• Emissor: é a instituição financeira que emite o cartão de crédito ou débito.
• Portador: é o proprietário do cartão, comprador do produto.
• Estabelecimento Comercial: é a entidade responsável pelo e-commerce
• MPI: sistema responsável em autenticar junto ao emissor as transações de crédito e débito.
• Postback: Retorno síncrono da API, por exemplo, no fluxo de autenticação 3DS.
• Callback: Retorno assíncrono da API, por exemplo, na API de cancelamento.
• SK: Secret Key, é a chave da API do lojista
• Liability Shift: Trata-se de transferência de responsabilidade, associado ao 3DS significa que o emissor se torna o responsável pela transação, inclusive em possíveis casos de fraude.

Pré-requisitos técnicos para integração

Adiante será descrito o passo a passo para a integração. De todo modo, é importante que os desenvolvedores responsáveis tenham conhecimentos em linguagem de programação para web, requisições HTTPS e manipulação de objetos em JSON.

Iniciando a Integração

Como obter as chaves da API

Antes de começar, você precisa obter suas chaves de API. Para isso, siga os seguintes passos:

1. Acesse este link e faça login com seu usuário;
2. Após acessar o Dash, navegue até a área de Desenvolvimento e em seguida clique em Chaves.

🚧

Atenção:

Caso você já é cliente Pagar.me e está integrado na versão anterior da API, entre em contato com o nosso time de suporte.

Tipos de Chave

Chaves para utilizar em ambiente de testes (Sandbox)

• Exemplo de prefixo da Chave Secreta de Sandbox: sktest*

Chaves para utilizar em ambiente de produção

• Exemplo de prefixo da Chave Secreta de Produção: sk_*
• Exemplo de prefixo da Chave Pública de Produção: pk_*

Gerando JWT

O Backend do integrador deve enviar a Chave de API (secret_key) no cabeçalho Authorization, seguindo o padrão universal HTTP Basic Authentication.

Faça um GET na rota: https://api.pagar.me/test/3ds2/tds-token

const fs = require('fs');
const request = require("request");

const options = {
  method: 'GET',
  uri: 'https://api.pagar.me/test/3ds2/tds-token',
  headers: {
    'Authorization': 'Basic ' + Buffer.from("sk_test_*:").toString('base64'),
    'Content-Type': 'application/json'
  }
};

request(options, function(error, response, body) {
  console.log(response.body);

O retorno obtido deverá ser:

{
	tds_token: JWT gerado pelo 3DS - Pagar.me
}

Com isso, será gerado um JWT pela rota tds-token que será usado na inicialização do SDK e tem validade de 20 segundos. Ou seja, caso o request enviado demore mais do que 20s haverá retorno de erro conforme imagem abaixo:

faltou a imagem no doc em word

A correção deste erro é apenas garantir que não haja expiração do JWT, ou seja, que os 20s serão respeitados.

Parametrizações

Na tag <form> insira o atributo data-pagarmecheckout-form para que o script identifique de onde serão extraídos os dados.

<form action="{{url de sua action}}" method="POST" data-pagarmecheckout-form>
</form>

🚧

Lembre-se

Nunca trafegar os dados abertos de qualquer cartão no servidor (número, cvv, vencimento e nome do titular).

Uma vez que foi definido onde ocorrerá a extração dos dados, coloque nos campos <input> do seu formulário os atributos "data-pagarmecheckout-element" correspondentes a cada um dos campos do cartão, conforme HTML abaixo. Estes serão capturados pelo script para a geração do token na submissão do formulário.

<form action="{{url de sua action}}" method="POST" data-pagarmecheckout-form>
    <input type="text" name="holder-name" data-pagarmecheckout-element="holder_name">
    <input type="text" name="card-number" data-pagarmecheckout-element="number">
    <span  data-pagarmecheckout-element="brand"></span>
    <input type="text" name="card-exp-month" data-pagarmecheckout-element="exp_month">
    <input type="text" name="card-exp-year" data-pagarmecheckout-element="exp_year">
    <input type="text" name="cvv" data-pagarmecheckout-element="cvv">
    <input type="text" name="buyer-name">
    <button type="submit">Enviar</button>
</form>

Como o protocolo 3DS é suscetível ao desafio, reserve um espaço no checkout para comportá-lo, caso seja uma solicitação do emissor. Ao exibir a página deixe o iFrame oculto para o portador.

<iframe id="challengeIframe" data-pagarmecheckout-element="challengeIframe">
</iframe>
// css para o iFrame ficar oculto
#challengeIframe { display: none; }

Durante os testes é importante garantir que o desafio esteja sendo exibido na mesma página do checkout, dessa forma garantimos o correto funcionamento da integração.

Informações importantes a respeito da configuração do Checkout

• Quaisquer outros campos podem ser adicionados ao mesmo formulário, sem o atributodata-pagarmecheckout-element, e estes serão enviados normalmente ao seu servidor, sem a intervenção do script, como, por exemplo, buyer-name.
• O campo referente a data da expiração do cartão pode ser informado de duas formas:
  • Em campo único, marcado como exp_date (O formato esperado é YYYY-MM);
  • Futuramente, em dois campos, exp_month e exp_year.

Após realizar as parametrizações referentes ao checkout, deve-se inserir no final da sua página uma tag <script> com o pagarme3ds.js.

/// Script para Sandbox:
<script src="https://3ds2-sdx.pagar.me/v1/3ds2.min.js"></script>
/// Script para produção:

Lembre-se de sempre utilizar cartões de teste em ambiente de Sandbox. Para ambiente produtivo utilizar cartões aptos a transacionar.

Lista de cartões teste:

Após inserir o script é preciso iniciar a detecção dos campos com a chamada da função PagarmeCheckout.init(). Com isso o método init(), receberá os 4 parâmetros, abaixo:

1. JWT : Token gerado pelo back-end do lojista para ser usado no processo do 3DS.
2. tdsData: JSON com as informações do Pedido para serem autenticadas pelo 3DS
3. Callback(data): Para execução após a finalização do processo 3DS.
4. ChallengeWindowSize: Indicação do tamanho da janela do desafio.

A tabela abaixo detalha os dados que devem ser enviados no parâmetro tdsData:

Phone é um array de objetos phone

Purchase

🚧

Atenção

Campos indicados como Required são obrigatórios, Optional são opcionais e Conditional são obrigatórios, caso não for adicionado a tag data-pagarmecheckout-element.

Quando a função de callback é chamada recebe por parâmetro um objeto data, que é um JSON com o tds_id, trans_status. Indicando o ID do 3DS que deve ser usado na criação do Pedido e o Status da autenticação.

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

É possível que a tela tenha uma das dimensões citadas abaixo:

• 250 x 400
• 390 x 400
• 500 x 600
• 600 x 400
• Full screen

Retorno do JS

Resposta do SDK JavaScript é um JSON no Formato abaixo:

{
  trans_status: 'Y', 
  tds_server_trans_id: 'uuid-3ds-123',
  error: 'MENSAGEM DE ERROR AQUI'
}

URLS importantes:

3ds-js

• sdx: https://3ds2-sdx.pagar.me/v1/3ds2.min.js
• prd: https://3ds2.pagar.me/v1/3ds2.min.js

Formulário para testes

• sdx: https://3ds2-sdx.pagar.me/index.html
• prd: https://3ds2.pagar.me/index.html

Status das transações 3DS

Abaixo a descrição do que significa cada um dos status disponíveis no 3DS.

Vale destacar que as transações que possuem Liability Shift são as transações com retorno “Y”, ou seja, essas são as transações que o emissor do cartão de crédito se responsabiliza por eventuais fraudes.

Cadastro

Para garantir que todos os testes funcionem corretamente, não se esqueça de validar junto ao time comercial responsável por sua conta que o cadastro da account está realizado tanto em ambiente de Sandbox como em ambiente de Produção.

📘

Importante:

Erros do tipo “Account not Found” em geral estão atrelados a ausência de cadastro, logo basta validar se o cadastro está efetuado. Caso receba este retorno de erro, lembre-se de se certificar junto ao comercial que o cadastro foi solicitado na account correta!