Home

Visão Geral

3DS Server

Visão Geral#

Para realizar transações de autenticação no 3DS 2.0, é necessário integrar com uma aplicação 3DS Server, como a fornecida pela FISERV. Essa aplicação estabelece comunicação com a bandeira do cartão e o emissor para autenticar o titular do cartão, reduzindo ocorrências de fraude e viabilizando pagamentos com cartões de débito. Ela é independente da aplicação de pagamento e o integrador terá que realizar e gerenciar a orquestração em sua aplicação.

Esse modelo necessita de um maior esforço de integração (necessidade de integração de API), mas permite uma maior flexibilidade no fluxo de pagamento (gerenciamento pela loja), e o checkout de pagamento é da própria loja.

A versão 2.0 do protocolo 3DS se diferencia da sua versão 1.0 ao permitir uma autenticação frictionless (sem atritos), ou seja, um processo que não requer interações adicionais por parte do comprador.

Este documento se concentra nas interações com o 3DS Server. Para obter informações adicionais sobre os outros componentes do fluxo, consulte os documentos oficiais da EMVCo.

E para saber mais sobre essas nomenclaturas (Bin, Software Express, Carat, e-Sitef) Saiba mais

Comunicação#

Para realizar uma transação Web Service, toda a comunicação será realizada via HTTPS/SSL. É importante que o servidor do lojista suporte criptografia com no mínimo 128 bits. O servidor da loja deverá realizar chamadas em endereços específicos para transações REST.

Cada serviço deve ser chamado utilizando a URL base concatenada do recurso desejado (veja o capítulo referente ao serviço a ser consumido). O método HTTP (GET, POST ou PUT) indica a ação esperada sobre o recurso escolhido. Abaixo estão as URLs base do 3DS Server:

URL base de Produção:

https://3ds.softwareexpress.com.br/

URL base de Homologação:

https://mpi-homolog.softwareexpress.com.br/3ds-server/

Todas as chamadas realizadas para os serviços serão respondidas de forma síncrona.

Atenção:

Nunca utilize o IP ao invés do domínio 3ds.softwareexpress.com.br. O IP pode mudar a qualquer momento e sem aviso prévio, portanto é importante a utilização do domínio para acesso ao 3DS Server.

Durante a validação do cartão, é possível que o código de erro 305 seja retornado, indicando que o cartão não está dentro do intervalo de cartões suportados para autenticação 3DS 2.0 pelo emissor, impossibilitando a realização do processo de autenticação. A decisão de cancelar a transação ou prosseguir com o pagamento sem o uso do 3DS cabe ao 3DS Requestor.

Importante:

Além dos parâmetros de retorno dos serviços descritos nesta especificação o 3DS Server poderá devolver outros parâmetros sem aviso prévio.

É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.

Fluxos#

O protocolo 3DS 2.0 conta com 2 principais fluxos:

  • Frictionless (sem atrito): toda a autenticação é feita sem a exigência de interações adicionais por parte do comprador.
  • Challenge (desafio): as informações coletadas pelo emissor não são suficientes para autenticar o portador do cartão. Logo, o comprador deverá fornecer mais dados, diretamente no site do emissor.

Glossário:

  • 3DS Requestor: loja ou gateway (como o Carat)
  • DS: Directory Server; representa a bandeira
  • ACS: Access Control Server; representa o emissor
  • AReq: Authentication Request, conforme o protocolo 3DS 2.0
  • ARes: Authentication Response, conforme o protocolo 3DS 2.0
  • CReq: Challenge Request, conforme o protocolo 3DS 2.0
  • CRes: Challenge Response, conforme o protocolo 3DS 2.0
  • RReq: Results Request, conforme o protocolo 3DS 2.0
  • RRes: Results Response, conforme o protocolo 3DS 2.0

Fluxo Frictionless#

  1. 3DS Requestor cria a transação de autenticação no 3DS Server, passando o número do cartão do comprador e seu ID de bandeira.
  2. 3DS Server valida se o cartão recebido pode ser autenticado pela bandeira indicada. Caso positivo, retorna o ID da transação 3DS Server (three_ds_server.trans_id) e o 3DS Method URL (three_ds_method_url) correspondente ao cartão.
  3. O 3DS Method URL deve ser exibido no navegador do comprador em um frame "invisível" de 1 pixel.
  4. Isso permitirá que o ACS colete diretamente as informações do dispositivo do portador do cartão.
  5. 3DS Requestor envia informações para a realização da autenticação.
  6. 3DS Server gera um AReq e o envia para o DS, que em seguida propaga ao ACS. O resultado da autenticação volta para o 3DS Server como conteúdo do ARes.
  7. Caso a autenticação seja bem-sucedida, será retornado o status (campo three_ds_server.status) com valor Y. Os seguintes campos devem ser enviados ao adquirente: o ECI (campo eci), o CAVV (campo authentication.value) e o reference_id (campo ds.trans_id).

Recomendação:

Para melhorar o desempenho e permitir que as informações sejam coletadas em segundo plano, recomendamos executar os passos 1 e 4 imediatamente após o preenchimento do cartão, em vez de esperar para executar tudo de uma vez.

Fluxo Frictionless com autorização do pagamento.#

Atenção:

No fluxo Frictionless, durante a etapa 1 da autenticação no serviço de criação da transação no 3DS Server, o reference_id (ID da transação ds.trans_id) é retornado. Já no retorno do serviço de autenticação no 3DS Server, o campo eci (Electronic Commerce Indicator) e o campo authentication.value (CAVV) é retornado. Cabe a aplicação do lojista guardar essas informações e repassá-las ao serviço de efetivação do pagamento na etapa 2 mostra acima.

  • Na etapa 2 da autorização a aplicação do lojista cria a transação no Carat passando informações como código da loja, número de parcelas e código de pedido e obtém como resposta um NIT (Número Identificador de Transação). Saiba mais.
  • As informações obtidas no serviço de criação da transaão no Carat, a aplicação do lojista prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT, os dados do cartão do comprador, o ECI (campo eci) e o CAVV (campo authentication.value) e o reference_id (ID da transação 3DS Server ds.trans_id). Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada). Saiba mais.

Fluxo Challenge#

Os passos 1 até 6 são os mesmos do fluxo frictionless.

  1. Será retornado o status (campo three_ds_server.status) com valor C, URL do desafio preenchida (campo acs.url) e o reference_id (campo ds.trans_id), esse último campo que deve ser enviado ao adquirente.
  2. 3DS Requestor prepara o CReq para ser submetido pelo navegador do comprador para a URL de desafio.
  3. ACS exibe sua tela de desafio para que o comprador forneça mais informações. Note que podem ser necessárias múltiplas interações para conclusão desse processo
  4. ACS envia o RReq para o DS, que por sua vez propaga ao 3DS Server. Essa chamada se trata de uma notificação informando o resultado da autenticação.
  5. ACS envia o CRes ao 3DS Requestor em sua URL informada no passo 5 (campo notification_url). Este objeto contém o ID da transação 3DS Server.
  6. 3DS Requestor consulta a transação do 3DS Server para obter o resultado da autenticação.
  7. 3DS Server retorna as informações de sua transação.

Fluxo Challenge com autorização do pagamento.#

Atenção:

No fluxo Challenge, durante a etapa 1 da autenticação no serviço de criação da transação no 3DS Server, o reference_id (ID da transação ds.trans_id) é retornado. Após o desafio é necessário realizar uma consulta no serviço de consulta do 3DS Server para obter as informações da autenticação, retornando o campo ECI (Electronic Commerce Indicator) e o campo authentication.value (CAVV). Cabe à aplicação do lojista guardar essas informações e repassá-las ao serviço responsável pela efetivação do pagamento

  • Na etapa 2 da autenticação a aplicação do lojista cria a transação passando informações como código da loja, número de parcelas e código de pedido e obtém como resposta um NIT (Número Identificador de Transação). Saiba mais.
  • As informações obtidas no serviço de criação da transação no Carat, a aplicação do lojista prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT, os dados do cartão do comprador, o ECI (campo eci) e o CAVV (campo authentication.value) e o reference_id (ID da transação 3DS Server ds.trans_id). Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada). Saiba mais.