3DS Server

Visão Geral

Para fazer transações de autenticação 3DS 2.0, é necessária a integração com uma aplicação 3DS Server, como a fornecida pela Software Express. Essa aplicação se comunica com a bandeira e o emissor para autenticar o portador do cartão, reduzindo incidências de fraude e possibilitando pagamentos com cartões de débito.

O protocolo 3DS 2.0 se difere de sua versão 1.0 na possibilidade de permitir uma autenticação frictionless (sem fricção), ou seja, um processo que não exige interações adicionais por parte do comprador.

Esta documentação é focada nas interações com o 3DS Server. Para mais informações referentes aos outros componentes do fluxo, consulte os documentos oficiais da EMVCo.

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.

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 3 principais fluxos:

  • Frictionless (sem fricção): 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.
  • Decoupled (desacoplado): a autenticação é feita fora do protocolo 3DS.

Glossário:

  • 3DS Requestor: loja ou gateway (como o e-SiTef)
  • 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, o ECI (campo eci) e o CAVV (campo authentication.value), que devem ser então enviados ao adquirente.

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 e a URL do desafio preenchida (campo acs.url).
  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 Decoupled

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

  1. Será retornado o status (campo three_ds_server.status) com valor D.
  2. ACS conduzirá seu próprio processo de autenticação, por fora do protocolo 3DS 2.0.
  3. ACS envia o RReq para o DS, que por sua vez propaga ao 3DS Server, informando o resultado da autenticação.
  4. 3DS Server informa o resultado ao 3DS Requestor através de sua URL de notificação informada no passo 5 (campo decoupled_notification_url).
  5. 3DS Requestor responde a notificação com código HTTP 200.
← Códigos da APIQuick start →