Autenticação 3DS 2.2

Redirecionando para https://docs.cielo.com.br/ecommerce-cielo/docs/3ds-sobre ...

As documentações da API E-commerce Cielo estão em um novo portal

Acesse o novo portal de desenvolvedores E-commerce docs.cielo.com.br.

Atenção: O conteúdo desta página está sendo descontinuado e não receberá atualizações a partir de 14/08/2024. Visite a nova documentação em docs.cielo.br.

Autenticação 3DS

O que é 3D Secure 2.2?

É um protocolo de autenticação que confirma se o comprador é de fato o portador do cartão (de crédito ou débito). O objetivo do 3DS (também chamado de EMV 3DS) é evitar fraudes em transações de cartão não presente (CNP).

Por meio do 3DS, os dados do comprador são enviados para as bandeiras e emissores do cartão, que irão realizar a autenticação.

3DS significa 3-D Secure Protocol e foi desenvolvido pela EMVCo, um corpo técnico formado pelas principais bandeiras de cartão e que cria especificações para a interoperabilidade e aceitação de pagamentos de forma segura no mundo todo.

Para realizar a autenticação, a loja precisa enviar os dados do comprador para a bandeira por meio de um serviço intermediário, o 3DS Server, que faz a comunicação com a bandeira. É possível usar um 3DS Server externo ou o 3DS Server Cielo

Se sua loja usa um 3DS Server externo à Cielo para autenticação de cartões, você deve infomar o Cavv retornado pelo seu 3DS Server na requisição de autorização do Gateway. Para mais informações, pule para a etapa de Autorização com Autenticação.

Principais benefícios:

• A responsabilidade em caso de chargeback de uma transação autenticada é do emissor ou da bandeira;
• Integração facilitada via JavaScript;
• Possibilidade de autenticação silenciosa (autenticação sem desafio);
• Minimiza transações com fraudes.

Palavras chaves: Autenticação de cartão de crédito e débito, EMVCO, 3DS, Visa, Mastercard, Elo, E-commerce.

Importante:

• O chargeback é a contestação de uma compra de cartão de débito ou crédito feita pelo portador do cartão, ao não reconhecer determinada compra. A autenticação 3DS ajuda a diminuir a ocorrência de chargeback por fraude, uma vez que a responsabilidade em caso de chargeback para a ser do emissor, e não da loja. Essa transferência de responsabilidade em caso de chargeback é chamada de liability shift;
• A autenticação 3DS não é uma análise de fraude; para aumentar a segurança das suas transações, recomendamos o uso da Autenticação 3DS e também de um serviço de análise de fraude, como o Antifraude Gateway.

Quem pode usar o 3DS?

Qualquer e-commerce pode usar a solução como uma camada extra de segurança para as suas transações.

Quais são requisitos para a utilização do 3DS?

O e-commerce deve atender aos seguintes requisitos:

• Ter afiliação com uma das adquirentes atendidas;
• Concluir a integração técnica do protocolo de autenticação;
• Concluir a integração técnica da autorização.

Quando usar?

A Autenticação 3DS é obrigatória para todas as transações de cartão de débito e opcional para transações de cartão de crédito.

Como saber se a transação foi autenticada?

Isso irá depender do resultado da Tabela de ECI.

O 3DS autentica o portador em transações recorrentes?

Sim. Se todos os campos obrigatórios forem enviados corretamente, o 3DS 2.2 autentica todas as transações recorrentes. Se algum campo obrigatório não for enviado, acontece o downgrade para 3DS 2.0, que autentica apenas a primeira transação de uma série de transações recorrentes.

Como as transações seguintes (a partir da segunda) não são autenticadas no 3DS 2.0, se houver chargeback a partir da segunda transação, a responsabilidade é da loja. Usando o 3DS 2.2, a responsabilidade do chargeback é sempre do emissor.

Tipos de autenticação do portador

• Autenticação sem desafio (autenticação silenciosa): quando o emissor realiza a autenticação sem a necessidade de validação complementar do portador;
• Autenticação com desafio: quando o emissor precisa realizar uma validação complementar do portador do cartão e apresenta um desafio, que pode ser a confirmação de um código enviado pelo aplicativo do banco, por SMS etc.

Como funciona a autorização com autenticação via 3D Secure 2?

O processo de autorização de cartão autenticada via 3D Secure 2 ocorre em duas etapas:

1. Etapa de autenticação: por meio do protocolo 3DS, a bandeira ou o emissor autentica que o comprador é de fato o titular do cartão. O protocolo é integrado ao e-commerce por meio de um script em JavaScript, que retorna o resultado da autenticação e alguns parâmetros que devem ser enviados na autorização. Saiba mais em Integração do script;
2. Etapa de autorização: a loja submete a transação para autorização, informando os parâmetros retornados pelo script na etapa de autenticação. Saiba mais em Autorização com Autenticação.

O fluxo a seguir descreve as etapas de autenticação em alto nível:

1. O comprador escolhe pagar com cartão de crédito ou débito;
2. A loja executa um script, solicitando à Cielo autenticação através da solução 3DS 2.2;
3. A loja envia requisição com dados do comprador para a bandeira;
4. A bandeira envia a requisição para avaliação de risco do emissor;
5. O emissor avalia as informações e determina se fluxo será com ou sem desafio ao portador;
5.1. Se o emissor solicitar desafio, cria e envia a URL para a loja;
5.2. A loja apresenta lightbox do desafio na página de checkout para obter resposta do comprador;
5.3. O comprador responde o desafio, completando a autenticação;
6. O emissor envia o resultado da autenticação para o 3DS Server;
7. O 3DS Server envia resultado da autenticação. A loja decide seguir ou não para autorização.

A loja pode optar por submeter uma transação não autenticada para autorização; no entanto, nesse caso, a loja será responsável em caso de chargeback.

Bandeiras disponíveis

As bandeiras disponíveis para autenticação via 3DS 2.2 são:

• Visa;
• Mastercard;
• Elo;
• Amex.

Stand-in pela bandeira (válido para Visa e Mastercard): Além das bandeiras, o emissor do cartão também precisa processar o protocolo 3DS 2.2. Caso o emissor ainda não esteja apto a responder um pedido de autenticação usando 3DS 2.2, a bandeira avalia os dados enviados, como por exemplo o histórico transacional e comportamental do portador do cartão, classificando os pedidos de autenticação como “Baixo Risco” e “Não Baixo Risco”. A partir dessas informações, os emissores poderão contar com uma proteção mesmo não possuindo uma solução própria de 3DS 2.2, e terão uma maior confiança nas transações autenticadas. Em casos de stand-in, a autenticação ocorre de forma silenciosa (sem desafio para o portador) e, uma vez que a transação foi autenticada, o liability em caso de fraude ficará com o emissor.

O que é o Data Only – somente notificação

O que é?

O Data Only é um campo opcional que poderá ser utilizado para contribuir para o banco de dados da bandeira e emissor, melhorando a performance da autenticação.

O Data Only pode ser usado quando o emissor não realiza a autenticação. Nesse caso, se o campo Data only foi parametrizado no script, a bandeira vai receber os dados parametrizados e vai compartilhar essas informações com o emissor. Com o tempo, o emissor terá mais dados de transações daquele cartão e da pessoa titular do cartão e terá mais elementos para realizar a autenticação.

Como usar o Data Only?

Basta parametrizar o bpmpi_auth_notifyonly. A autorização ocorre da mesma forma que qualquer [Autorização com Autenticação].

Para usar o Data Only, na Integração do script parametrize o campo bpmpi_auth_notifyonly descrito no item Etapa de Autenticação – passo 3 – Mapeamento de classes.

No modelo Data Only, os campos adicionais do 3DS 2.2 são mapeados da mesma forma, e enviados para a bandeira, porém, sem solicitar a autenticação.

O Data Only é válido para as bandeiras Mastercard e Visa.

Para Data Only Mastercard, o ECI será sempre 4;
Para Data Only Visa, o ECI será sempre 7.

Qual é o benefício?

• Zerar qualquer tipo de fricção com o comprador, que não visualiza nenhuma alteração;
• Melhorar a conversão por enriquecimento da base de dados do emissor.

Importante:

• Nas transações Data Only o risco de chargeback por fraude permanece com a loja;
  
• É possível usar Antifraude nas transações de Autenticação 3DS com Data Only.

Integração do script

O protocolo de autenticação 3DS 2.2 está disponível na versão browser-based, ou seja, a loja deverá incluir o script do 3DS no arquivo HTML da página de pagamento (checkout). O protocolo 3DS, ao processar o script, permite a troca de dados entre a loja e o emissor para autenticar o portador do cartão.

A integração do script do protocolo de autenticação é composta pelas seguintes etapas:

1. Criação do token de acesso: o token de acesso deverá ser inserido no script (JavaScript) e no HTML na classe bpmpi_accesstoken. Veja as tabelas XXX para mais informações;
2. Mapeamento de classes: aqui você deve preparar o seu ambiente para coletar os dados do comprador e executar o script no navegador do comprador;
3. Implementação do script: insira as classes no HTML (tag body) e referencie o arquivo JavaScript com as classes mapeadas.
4. Implementação da chamada ao evento de autenticação: usando os dados retornados no resultado da autenticação, envie a transação para autorização (aprovação da adquirente).

1. Criando o token de acesso

Obtenha o valor do Authorization concatenando o valor do “ClientID”, sinal de dois-pontos (“:”) e “ClientSecret”.

Ex: dba3a8db-fa54-40e0-8bab-7bfb9b6f2e2e:D/ilRsfoqHlSUChwAMnlyKdDNd7FMsM7cU/vo02REag

Em seguida, codifique o resultado na base 64. Esse código alfanumérico será utilizado na requisição do access token:

Requisição

{
  "EstablishmentCode": "1006993069",
  "MerchantName": "Loja Exemplo Ltda",
  "MCC": "5912"
}

curl
--request POST "https://mpisandbox.braspag.com.br/v2/auth/token"
--header "Content-Type: application/json"
--header "Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{
     "EstablishmentCode":"1006993069",
     "MerchantName": "Loja Exemplo Ltda",
     "MCC": "5912"
}

Response

{
      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
      "token_type": "bearer",
      "expires_in": "2018-07-23T11:29:32"
}

--header "Content-Type: application/json"
--data-binary
{
      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
      "token_type": "bearer",
      "expires_in": "2018-07-23T11:29:32"
}

2. Mapeando as classes

A solução disponibiliza dezenas de classes que devem ser mapeadas em seu código HTML.

Uma vez que a classe é mapeada em determinado campo, o script é capaz de recuperar o valor contido no campo e submetê-lo para compor a requisição de autenticação.

O caracter # indicado no campo deve ser substituído pelo número que representa o índice do item. Exemplo: bpmpi_item_1_productName representa o nome do item 1 do carrinho

3. Implementando o script

Neste passo, implemente o script e faça o mapeamento de classes responsáveis pela comunicação com as plataformas de autenticação das bandeiras e emissor. Siga o exemplo a seguir, que demonstra a implementação básica. Recomenda-se que o trecho seja colocado no final do código HTML de seu checkout:

Para baixar o código HTML de exemplo completo, no GitHub Cielo

A imagem mostra um trecho HTML de uma implementação básica:

Descrição dos eventos

Os eventos são ações que o script toma como resposta para acompanhamento do processo de autenticação, mas não indicam se a transação foi autenticada com sucesso.

O valor retornado no ECI (E-commerce Indicator) é o que indica se a transação foi autenticada ou não e de quem é o risco de chargeback. Para submeter a transação para autorização, considere o valor do ECI e use os eventos apenas como complemento para auxiliar na tomada de decisão.

Descrição dos parâmetros de entrada

IMPORTANTE:

O arquivo JavaScript deve ser salvo no servidor onde está a aplicação da loja. Para baixar o arquivo, acesse https://bit.ly/2CSOp2n.

Descrição das saídas

Exemplo de retorno do script

Exemplo de evento OnSuccess

{
  Cavv: 'Y2FyZGluYWxjb21tZXJjZWF1dGg=',
  Xid: null,
  Eci: '01',
  Version: '2',
  ReferenceId: '973cf83d-b378-43d5-84b6-ce1531475f2a'
}

Exemplo de evento OnFailure

{
  Xid: null,
  Eci: null,
  ReturnCode: '231',
  ReturnMessage: 'Unexpected error ocurred',
  ReferenceId: null
}

Exemplo de retorno para bandeira não suportada

Quando a bandeira não é suportada pelo 3DS, o MPI retorna o código “MPI 600” e a mensagem “Brand not supported for authentication”.

{
  Xid: null,
  Eci: null,
  ReturnCode: 'MPI600',
  ReturnMessage: 'Brand not supported for authentication',
  ReferenceId: null
}

Confira os valores possíveis de ReturnCodes na tabela Lista de Return Codes.

Tabela de ECI

O ECI (Electronic Commerce Indicator) é um código retornado pelas bandeiras e indica o resultado da autenticação 3DS do portador do cartão junto ao emissor ou bandeira.

Com base no resultado do ECI a loja deve decidir se vai prosseguir com a transação submetendo-a para autorização ou não. É possível enviar uma transação não autenticada para autorização, mas a responsabilidade em caso de chargeback é do estabelecimento.

Confira na tabela a seguir os ECIs correspondentes à cada bandeira e o resultado da autenticação.

Posteriormente, envie o valor do ECI na requisição da transação no campo Payment.ExternalAuthentication.Eci.

4. Implementando chamada ao evento de autenticação

O evento **bpmpi_Authenticate()** deve ser chamado no momento de finalização do checkout (finalização da compra). Vide exemplo abaixo:

<input type="button"onclick="bpmpi_authenticate()" />

Autorização com Autenticação

Após a conclusão da autenticação do portador do cartão, a loja deve submeter a transação ao processo de autorização, enviando os dados de autenticação no modelo de “autenticação externa” (nó ExternalAuthentication), tanto para 3DS Server interno quanto para 3DS Server externo.

Veja a seguir um exemplo de requisição de autorização à API 3.0:

Requisição

{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "Authenticate":true,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
       "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
       "Eci":"5",
       "Version":"2",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
     }
   }
}

curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "MerchantKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "Authenticate":true,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
       "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
       "Eci":"5",
       "Version":"2",
       "ReferenceId":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
     }
   }
}

Resposta

Consulte o Manual da API E-commerce 3.0 para exemplos detalhados de resposta de autorização com autenticação.

Autorização para transações Data Only

Após a conclusão da autenticação do portador do cartão no modelo Data Only (com o campo bpmpi_auth_notifyonly como “true”), a loja deve submeter a transação ao processo de autorização, enviando os dados de autenticação no modelo de “autenticação externa” (nó ExternalAuthentication), tanto para 3DS Server interno quanto para 3DS Server externo.

Veja a seguir um exemplo de requisição de autorização à API 3.0:

Requisição

{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "Authenticate":false,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Eci":"4",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
       "dataonly":true
     }
   }
}

curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "MerchantKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "Authenticate":false,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Eci":"4",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
       "dataonly":true
     }
   }
}

Resposta

Consulte o Manual da API E-commerce 3.0 para exemplos detalhados de resposta de autorização com autenticação.

Cartões de teste

Use os cartões de teste a seguir para simular diversos cenários no ambiente sandbox.

Cartões de teste com desafio

Cartões de Teste sem desafio

ANEXO

Lista de Return Codes

São retornados como resposta à execução do script e também após autorização.

Na tabela a seguir, apresentamos os Return Codes que podem retornar como resultado de uma requisição.