Passo 1: Setup da Sessão 3DS2
Antes de criar uma cobrança (transação) com 3DS2, é necessário iniciar uma sessão de autenticação. Essa etapa de setup prepara o provedor de autenticação 3DS e retorna parâmetros que serão usados nas próximas etapas. Você deve chamar o endpoint/v1/charges/3ds/setup
informando a fonte do cartão. Essa fonte pode ser um cartão tokenizado (sourceType: "token"
) ou um cartão previamente cadastrado (sourceType: "card"
), junto com o identificador correspondente (tokenId
ou cardId
).
Exemplo de requisição (Setup 3DS2):
- Exemplo com tokenId
- Exemplo com cardId
cardId
, poderia usá-lo alterando sourceType
para card
.
Resposta do Setup: Ao chamar o setup, a API retorna um objeto contendo informações essenciais para prosseguir. Um exemplo simplificado de resposta JSON seria:
id
– Identificador único da sessão 3DS2 criada. Este Setup ID será usado posteriormente ao criar a cobrança 3DS2.token
– Um token JWT fornecido pelo provedor de autenticação 3DS. Este token deverá ser usado na próxima etapa de coleta de dados no navegador do cliente.collectUrl
– URL para a qual os dados do dispositivo do cliente deverão ser enviados. Também será usada na etapa de coleta de dados no front-end.providerType
– Indica qual provedor de 3DS2 está sendo utilizado (ex: CYBERSOURCE, etc).error
– Em caso de falha na criação da sessão, este campo trará detalhes do erro; caso contrário virá como null.
id
retornado (Setup ID), pois ele será necessário no passo de criação da cobrança. Em seguida, prossiga imediatamente para a etapa de coleta de dados do dispositivo no navegador.
Passo 2: Coleta de Dados do Dispositivo (Data Collection)
Com otoken
e o collectUrl
retornados no setup, é preciso coletar informações do dispositivo/navegador do comprador. Essa coleta é feita no front-end do seu checkout, normalmente via um formulário invisível e um iframe, e serve para o provedor 3DS reunir dados de contexto para a autenticação.
Para implementar essa etapa, inclua no HTML do seu checkout um bloco de código semelhante ao abaixo:
collectUrl
e token3DS
pelos valores reais obtidos no Passo 1. Ao executar esse script, o formulário é enviado em background (iframe oculto) para a URL de coleta do provedor 3DS, junto com o token JWT. O provedor então coleta atributos do navegador (como informações de dispositivo, IP, etc.) automaticamente. Um event listener é adicionado para ouvir a mensagem de retorno indicando que a coleta terminou (o provedor geralmente envia um evento de mensagem para a janela original ao concluir a coleta).
Essa etapa é fundamental para a autenticação 3DS: ela fornece ao emissor do cartão os dados contextuais do dispositivo do cliente, auxiliando na decisão de aprovar diretamente (autenticação frictionless) ou exigir um desafio.
Passo 3: Criação da Cobrança (Transação com 3DS2)
Com a sessão criada (Setup ID) e a coleta de dados realizada, você pode prosseguir para criar a cobrança (transação de pagamento). A requisição de cobrança é feita no endpoint padrão/v1/charges
, porém deve conter um objeto adicional threeDSecure2
com os campos necessários.
Na cobrança 3DS2, o provedor de pagamento tentará autenticar o portador do cartão junto ao banco emissor. Dependendo do resultado, o pagamento poderá ser autenticado de forma silenciosa (frictionless) ou o emissor pode solicitar um desafio adicional ao cliente (challenge).
Montar a requisição corretamente é crucial. Segue um exemplo de requisição cURL para criar uma cobrança com 3DS2:
Indica se você exige o liability shift. Se
true
, a transação só prosseguirá se houver mudança de responsabilidade para o emissor.O ID da sessão de setup obtido no Passo 1. Obrigatório; vincula a transação atual com os dados coletados anteriormente.
A URL para a qual o cliente será redirecionado de volta após completar a autenticação 3DS (no caso de desafio). Normalmente é uma página do seu site (por exemplo, a página de confirmação de pedido ou de checkout) que irá processar a resposta. O provedor/autenticador usará esta URL para retornar o controle ao seu sistema após o desafio.
URL do domínio do lojista (merchant), geralmente o endereço do seu site. Esse valor pode ser usado internamente pelo provedor 3DS2 durante a autenticação para verificar a origem da requisição.
Endereço de cobrança do portador do cartão. Campos como cidade, país, CEP, etc. (Dados importantes para análise de risco e autenticação).
Objeto contendo informações do navegador do comprador, coletadas preferencialmente do próprio navegador do cliente. Inclua exatamente os dados requeridos:
ip
: IP do cliente.userAgent
: String do agente de usuário do navegador.acceptHeader
: Conteúdo do header HTTP “Accept” enviado pelo browser.language
: Idioma preferido do navegador (por exemplo, “pt-BR”).colorDepth
,screenHeight
,screenWidth
: Profundidade de cor e resolução de tela do dispositivo.timeZoneOffset
: Fuso horário do usuário em minutos (ex.: Brasil = “180” minutos atrasados em relação a UTC).javaEnabled
: Se Java (Applet) está habilitado no browser (geralmentefalse
hoje em dia).javaScriptEnabled
: Se o navegador tem JavaScript habilitado (true
na maioria dos casos).
Informações do portador do cartão, como email e telefone celular. Esses dados podem ser utilizados pelo emissor durante a autenticação (por exemplo, enviar um OTP via SMS).
Observação: No exemplo acima, usamos valores simulados (como IP e userAgent abreviado). Em um cenário real, você deve capturar esses dados do navegador do cliente no front-end e passá-los corretamente na requisição. A Malga não coleta esses dados automaticamente, portanto sua aplicação cliente deve fornecê-los (por exemplo, usando
window.navigator
para obter userAgent
, screen.width
etc., e APIs do browser para IP se disponível, ou obtendo IP do lado servidor).threeDSecure2.authData
com informações sobre a autenticação. Em particular, duas situações podem ocorrer:
- Transação Autorizada de imediato (Frictionless): O campo status da transação vem como
authorized
oupre_authorized
indicando que o banco emissor não exigiu desafio.
- Transação Pendente (Desafio necessário): O campo status da transação virá como
pending
, indicando que o emissor solicitou um desafio (challenge) de autenticação. Nesse caso, o objetothreeDSecure2.authData.response
trará os camposstepUrl
etoken
que serão usados para iniciar o desafio. A transação ficará pendente até a conclusão do desafio pelo cliente.
pending
, prossiga para o Passo 4 abaixo para realizar o desafio de autenticação. Se a transação foi autorizada sem desafio, você pode pular o próximo passo e apenas informar o cliente do resultado (ou confirmar pagamento, etc.).
Passo 4: Desafio de Autenticação (Challenge 3DS2)
Quando o banco emissor exige uma validação adicional, é preciso apresentar ao cliente o desafio 3DS - normalmente uma tela onde ele deve, por exemplo, inserir um código SMS, senha ou outro fator de autenticação. A Malga simplifica esse processo fornecendo a URL e o token necessários para abrir a interface do banco emissor em um iframe dentro do seu site (ou via redirecionamento). Assim como na coleta de dados, a implementação do desafio é feita no front-end, inserindo um formulário que será automaticamente enviado para ostepUrl
do desafio, contendo o token de autorização. Esses valores foram retornados na resposta da cobrança (Passo 3) dentro de threeDSecure2.authData.response.stepUrl
e ...response.token
.
Você pode implementar de forma similar à abaixo no seu HTML (por exemplo, abrindo um modal ou sobreposição com um iframe para o desafio):
stepUrl
(threeDSecure2.authData.response.stepUrl
) e stepToken
(threeDSecure2.authData.response.token
) devem ser preenchidos com os valores retornados na resposta da criação da cobrança pendente (obtidos no Passo 3). Ao executar formStep.submit()
, o navegador irá redirecionar o iframe para o endereço do desafio do emissor, efetivamente carregando a página de autenticação do banco dentro do iframe. O cliente então interage com essa página (por exemplo, digitando a senha do cartão ou um código enviado por SMS).
Durante o desafio, o navegador do cliente está se comunicando diretamente com o banco emissor (via provedor 3DS). Uma vez concluído (sucesso, falha ou expirado), o fluxo de 3DS2 providenciará um redirecionamento de volta para a URL que você configurou em redirectURL
no Passo 3.
Passo 5: Verificando o Resultado Final
Após o cliente completar (ou tentar) o desafio e retornar para o seu site (URL de retorno configurada), é necessário verificar o status final da transação para saber se o pagamento foi autorizado ou negado pelo emissor. A Malga permite consultar a transação a qualquer momento via API, então você deve fazer uma requisição GET para o endpoint/v1/charges/{chargeId}
usando o ID da cobrança criada no Passo 3.
Por exemplo, suponha que o ID da cobrança retornado no Passo 3 foi 6607c9b8-f6a3-48e2-9918-518d41d2fa60
. Você pode consultá-la assim:
status
atualizado (que após o desafio provavelmente estará como authorized
se o cliente autenticou com sucesso e o pagamento foi aprovado, ou outro status final como declined
em caso de falha). Você também poderá ver dentro de threeDSecure2
detalhes como authenticated: true/false
, liabilityShift: true/false
, etc., indicando o resultado da autenticação 3DS2.