Home

Visão Geral

Manual de Teste da API de 3DS.

Este manual foi criado para ajudar você a testar a API 3DS em seu ambiente de desenvolvimento. Com este manual, você será capaz de entender como a API funciona e como usá-la para realizar testes em seu sistema de pagamento.

Ao seguir as instruções deste manual, você poderá garantir que sua integração com a API do 3DS seja confiável e segura para seus usuários.

Atenção:

Os testes serão realizados em um ambiente de homologação do CARAT, o qual oferece um ambiente mais controlado e seguro para a realização dos testes.

Tabela com diferentes cartões para testes:

IDBANDEIRANÚMERO CARTÂO
1Visa4551820000009478
2Mastercard5555555555555555
41Elo5091490000009011
3Amex3766001349171000

Tabela com os valores em centavos que podem ser utilizados para simular diferentes status no 3DS:

VALORSTATUSDESCRIÇÂO
10000AUYAutenticação bem-sucedida
10004AUCSerá necessário um desafio, seguindo o fluxo "challenge"
10001AUNNão autenticada/conta não verificada; transação negada

Exemplos#

Abaixo, apresentaremos exemplos de testes nos fluxos Frictionless e Challenge, e um teste com um número de cartão que não está dentro do intervalo de cartões suportados para autenticação 3DS 2.0. Todos os testes serão realizados utilizando a ferramenta cURL.

Frictionless [Criando a transação]#

Tipo de requisição: POST

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

Headers:

  • Content-Type: application/json
  • merchant_id: {seu código de loja solicitar para equipe de suporte}
  • merchant_key: {chave da sua loja solicitar para equipe de suporte}

Cartão Mastercard: 5555555555555555

Requisição:

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"cardholder":{
"acct":{
"number":"5555555555555555"
}
},
"brand_id":"2"
}
--verbose

Resposta:

{
"three_ds_method_url": "https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/3dsmethod.se",
"three_ds_server": {
"trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
"status": "NEW"
},
"acs": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"device_channel": "02",
"ds": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
}
}

Saiba mais sobre esse serviço.

Frictionless [Fazendo a autenticação]#

Tipo de requisição: PUT

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/fb26dfb6-2486-442a-8887-d1241c940a61

Na URL acima, o ID da transação 3DS Server foi preenchido com o valor fb26dfb6-2486-442a-8887-d1241c940a61, que foi obtido durante a criação da transação

Headers:

  • Content-Type: application/json
  • merchant_id: {seu código de loja solicitar para equipe de suporte}
  • merchant_key: {chave da sua loja solicitar para equipe de suporte}

Requisição:

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/fb26dfb6-2486-442a-8887-d1241c940a61"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"three_ds_comp_ind" : "Y",
"notification_url" : "https://3dsnotification.requestcatcher.com/test?trans_id=fb26dfb6-2486-442a-8887-d1241c940a61",
"decoupled_notification_url" : "decoupledNotificationURLParaPasso10",
"trans_type" : "01",
"three_ds_requestor" : {
"authentication_ind" : "01",
"decoupled_max_time" : "10",
"id" : "2",
"name" : "e-SiTef",
"url" : "https://teste.com.br"
},
"acquirer" : {
"bin" : "12343",
"merchant_id" : "555555"
},
"browser" : {
"accept_header" : "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
"ip" : "192.168.50.141",
"javascript_enabled" : true,
"java_enabled" : "false",
"language" : "en-US",
"color_depth" : "30",
"screen_height" : "1080",
"screen_width" : "1920",
"tz" : "180",
"user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Firefox/102.0"
},
"cardholder" : {
"card_expiry_date" : "2202",
"email" : "email@email.com",
"mobile_phone" : {
"cc" : "55",
"subscriber" : "11111111111"
},
"name" : "Nome do Cartao",
"acct" : {
"type" : "02",
"number":"5555555555555555"
},
"bill_addr" : {
"city" : "Guarulhos",
"country" : "076",
"line1" : "rua xxx",
"line2" : "99",
"line3" : "complemento",
"post_code" : "22222-222",
"state" : "SP"
},
"ship_addr" : {
"city" : "Rio de Janeiro",
"country" : "076",
"line1" : "Rua yyy",
"line2" : "88",
"line3" : "complemento 2",
"post_code" : "33333-333",
"state" : "RJ"
}
},
"merchant" : {
"mcc" : "0121",
"country_code" : "076",
"name" : "Loja de Teste"
},
"message" : {
"category" : "01"
},
"purchase" : {
"amount" : "10000",
"currency" : "986",
"exponent" : "2",
"date" : "20221006163646"
}
}

Resposta:

{
"three_ds_server": {
"trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
"status": "AUY"
},
"acs": {
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "8a1c3ef2-25ff-46e8-ba9e-463f5172dab0"
},
"eci": "02",
"device_channel": "02",
"authentication": {
"value": "kFOAbf75KviDMXVzmGEoG3NIjJTF"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "d57be3da-6c42-4dbb-8372-1ff7c840ff6a"
},
"transaction": {
"status": "Y"
}
}

Saiba mais sobre esse serviço.

Cartão não suportado para autenticação 3DS 2.0. [Criando a transação]#

Tipo de requisição: POST

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

Headers:

  • Content-Type: application/json
  • merchant_id: {seu código de loja solicitar para equipe de suporte}
  • merchant_key: {chave da sua loja solicitar para equipe de suporte}

Cartão Mastercard: 5251743209931344

Requisição:

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"cardholder":{
"acct":{
"number":"5251743209931344"
}
},
"brand_id":"2"
}
--verbose

Resposta:

{
"three_ds_server": {
"trans_id": "9e696005-da29-48f1-a796-5d5f2e2ccf21",
"status": "INV"
},
"device_channel": "02",
"error": {
"code": "305",
"component": "S",
"description": "Cardholder Account Number is not in a range belonging to Issuer",
"detail": "acctNumber"
}
}

Saiba mais sobre os códigos de erros.

Challenge [Criando a transação]#

Tipo de requisição: POST

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

Headers:

  • Content-Type: application/json
  • merchant_id: {seu código de loja solicitar para equipe de suporte}
  • merchant_key: {chave da sua loja solicitar para equipe de suporte}

Cartão Mastercard: 5555555555555555

Requisição:

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"cardholder":{
"acct":{
"number":"5555555555555555"
}
},
"brand_id":"2"
}
--verbose

Resposta:

{
"three_ds_method_url": "https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/3dsmethod.se",
"three_ds_server": {
"trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
"status": "NEW"
},
"acs": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
},
"device_channel": "02",
"ds": {
"protocol_version": {
"start": "2.1.0",
"end": "2.2.0"
}
}
}

Saiba mais sobre esse serviço.

Challenge [Fazendo a autenticação]#

Tipo de requisição: PUT

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/fb26dfb6-2486-442a-8887-d1241c940a61

Na URL acima, o ID da transação 3DS Server foi preenchido com o valor fb26dfb6-2486-442a-8887-d1241c940a61, que foi obtido durante a criação da transação

Atenção

Para simular o fluxo de Challenge, é necessário passar no campo purchase.amounto valor 10014 da transação , conforme indicado na tabela apresentada no início deste manual.

Headers:

  • Content-Type: application/json
  • merchant_id: {seu código de loja solicitar para equipe de suporte}
  • merchant_key: {chave da sua loja solicitar para equipe de suporte}

Requisição:

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/fb26dfb6-2486-442a-8887-d1241c940a61"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"three_ds_comp_ind" : "Y",
"notification_url" : "https://3dsnotification.requestcatcher.com/test?trans_id=fb26dfb6-2486-442a-8887-d1241c940a61",
"decoupled_notification_url" : "decoupledNotificationURLParaPasso10",
"trans_type" : "01",
"three_ds_requestor" : {
"authentication_ind" : "01",
"decoupled_max_time" : "10",
"id" : "2",
"name" : "e-SiTef",
"url" : "https://teste.com.br"
},
"acquirer" : {
"bin" : "12343",
"merchant_id" : "555555"
},
"browser" : {
"accept_header" : "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
"ip" : "192.168.50.141",
"javascript_enabled" : true,
"java_enabled" : "false",
"language" : "en-US",
"color_depth" : "30",
"screen_height" : "1080",
"screen_width" : "1920",
"tz" : "180",
"user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Firefox/102.0"
},
"cardholder" : {
"card_expiry_date" : "2202",
"email" : "email@email.com",
"mobile_phone" : {
"cc" : "55",
"subscriber" : "11111111111"
},
"name" : "Nome do Cartao",
"acct" : {
"type" : "02",
"number":"5555555555555555"
},
"bill_addr" : {
"city" : "Guarulhos",
"country" : "076",
"line1" : "rua xxx",
"line2" : "99",
"line3" : "complemento",
"post_code" : "22222-222",
"state" : "SP"
},
"ship_addr" : {
"city" : "Rio de Janeiro",
"country" : "076",
"line1" : "Rua yyy",
"line2" : "88",
"line3" : "complemento 2",
"post_code" : "33333-333",
"state" : "RJ"
}
},
"merchant" : {
"mcc" : "0121",
"country_code" : "076",
"name" : "Loja de Teste"
},
"message" : {
"category" : "01"
},
"purchase" : {
"amount" : "10014",
"currency" : "986",
"exponent" : "2",
"date" : "20221006163646"
}
}

Resposta:

{
"three_ds_server": {
"trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
"status": "AUC"
},
"acs": {
"challenge_mandated": "Y",
"operator_id": "acsOperatorID",
"reference_number": "acsReferenceNumber",
"trans_id": "f215fa24-88ff-4045-b8a2-f400a9c421ae",
"url": "https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/challenge.se?brandId=2&sleepTime=120000"
},
"device_channel": "02",
"authentication": {
"type": "01"
},
"broad_info": "broadInfo",
"ds": {
"reference_number": "dsReferenceNumber",
"trans_id": "081ed552-eaed-4548-8680-e89ae6309890"
},
"transaction": {
"status": "C"
}
}

Challenge [Desafio]#

Tipo de requisição: POST

URL: https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/challenge.se?brandId=2

Na URL acima, é preciso inserir valor do brandId, que no nosso teste é definido como 2, já que estamos utilizando o cartão da bandeira Mastercard.

Headers:

  • Content-Type: application/x-www-form-urlencoded

Envio do CReq

Para obter o desafio deve ser enviado o parâmetro creq, cujo conteúdo é o CReq codificado em Base64 URL-safe encoding.

CReq Json

Nesse JSON colocamos o mesmo ID da transação do 3DS Server three_ds_server.trans_id e o ID da transação do ACS acs.trans_id que foram obtidos nas duas etapas anteriores.

{
"threeDSServerTransID":"fb26dfb6-2486-442a-8887-d1241c940a61",
"acsTransID":"081ed552-eaed-4548-8680-e89ae6309890",
"challengeWindowSize":"05",
"messageType":"CReq",
"messageVersion":"2.2.0"
}

CReq Base64:

ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImZiMjZkZmI2LTI0ODYtNDQyYS04ODg3LWQxMjQxYzk0MGE2MSIsCiAgImFjc1RyYW5zSUQiOiIwODFlZDU1Mi1lYWVkLTQ1NDgtODY4MC1lODlhZTYzMDk4OTAiLAogICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICJtZXNzYWdlVHlwZSI6IkNSZXEiLAogICJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIgp9

Saiba mais sobre esse serviço.

Após o CReq Json codificado em Base64 criamos a requisição abaixo.

Requisição:

curl --location --request POST 'https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/challenge.se?brandId=2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: JSESSIONID=3cfQENgsLzfHjQ2WxBr-M-OfkHbcb6a2hRkw2dZV.ip-10-53-55-113' \
--data-urlencode 'creq=ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImZiMjZkZmI2LTI0ODYtNDQyYS04ODg3LWQxMjQxYzk0MGE2MSIsCiAgImFjc1RyYW5zSUQiOiIwODFlZDU1Mi1lYWVkLTQ1NDgtODY4MC1lODlhZTYzMDk4OTAiLAogICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICJtZXNzYWdlVHlwZSI6IkNSZXEiLAogICJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIgp9'

Resposta:

Na resposta retornará um script do nosso simulador que simula um desafio do ACS (Emissor). Normalmente, este script seria adicionado na aplicação em um iframe, mas para fins de teste, vamos salvar como um arquivo HTML e abra ele no browser, após isso, selecione o status do desafio desejado - vamos escolher o Status Y, indicando sucesso - e clique no botão enviar

Arquivo HTML aberto no browser:

Atenção

Esse é apenas um simulador do CARAT para simular o desafio.

"Simulador 3ds" -no-filter

Script da resposta para simular o desafio conforme representado na imagem acima:

Atenção

Esse script é retornado na resposta do envio do CReq.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script type="text/javascript">
function updateStatusReason() {
var optionSelected = $("#result option:selected").val();
if (optionSelected == "Y" || optionSelected == "A" || optionSelected == "E") {
$("#labelStatusReason").hide();
$("#statusReason").hide();
$("#labelChallengeCancel").hide();
$("#challengeCancel").hide();
} else {
$("#labelStatusReason").show();
$("#statusReason").show();
if (optionSelected == "N") {
$("#labelChallengeCancel").show();
$("#challengeCancel").show();
}
}
}
</script>
<html>
<head>
<title>Simulador 3DS</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<fmt:setLocale value="pt_BR" scope="session" />
<META NAME="Copyright" CONTENT="Software Express">
<link rel="stylesheet"
href='/e-sitef-homologacao/css/main.css;jsessionid=3cfQENgsLzfHjQ2WxBr-M-OfkHbcb6a2hRkw2dZV.ip-10-53-55-113' />
<style type="text/css">
.watermark {
position: relative;
z-index: 1;
}
.watermark:before {
z-index: -1;
position: absolute;
left: 20%;
top: 20%;
content: url('/e-sitef-homologacao/images/simulado.png');
opacity: 0.2;
}
</style>
</head>
<body>
<div class="watermark">
<h2>Simulador 3DS</h2>
<p>Qual ser&aacute; o resultado?</p>
<form id="finalizar" name="finalizar"
action="https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/endChallenge.se" method="POST">
<select id="result" name="result" onchange="updateStatusReason();">
<option value="Y">Status Y - Sucesso</option>
<option value="A">Status A - N&atilde;o conseguiu autenticar, mas recebeu CAVV</option>
<option value="N">Status N - Negado</option>
<option value="R">Status R - Rejeitado pelo emissor</option>
<option value="U">Status U - Problemas t&eacute;cnicos</option>
<option value="E">Mensagem de erro</option>
</select>
<br/><br/>
<label id="labelStatusReason" for="statusReason" style="display: none;">Status Reason:&nbsp;</label>
<input type="text" id="statusReason" name="statusReason" value="01" maxlength="2" size="2" style="display: none;"/>
<br/><br/>
<label id="labelChallengeCancel" for="challengeCancel" style="display: none;">Challenge Cancel:&nbsp;</label>
<select id="challengeCancel" name="challengeCancel" style="display: none;">
<option value=""></option>
<option value="01">Cardholder selected Cancel</option>
<option value="03">Timed Out - Decoupled Authentication</option>
<option value="04">Timed Out at ACS - other timeouts</option>
<option value="08">Timed Out at 3DS SDK</option>
</select>
<input type="hidden" id="id" name="id" value="a8aea0fa-f785-4375-bb12-804c0ce89950" />
<input type="hidden" id="brandId" name="brandId" value="2" />
<tr>
<td colspan="2">
<div class="formButton"><button type="submit" id="botaoenviar" name="method:endChallenge" value="Submit">
Enviar
</button>
</div>
</td>
</tr>
</form>
</div>
</body>
</html>

Consulta o status da transação após o desafio

Tipo de requisição: GET

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/transaction/fb26dfb6-2486-442a-8887-d1241c940a61

Na URL acima, o ID da transação 3DS Server foi preenchido com o valor fb26dfb6-2486-442a-8887-d1241c940a61, que foi obtido durante a criação da transação

Headers:

  • Content-Type: application/json
  • merchant_id: {seu código de loja solicitar para equipe de suporte}
  • merchant_key: {chave da sua loja solicitar para equipe de suporte}

Requisição:

curl --location --request GET 'https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/transaction/fb26dfb6-2486-442a-8887-d1241c940a61' \
--header 'merchant_id: XXXXXXXXX' \
--header 'merchant_key: XXXXXXXX'

Resposta:

{
"three_ds_server": {
"trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
"status": "AUY"
},
"brand_id": "2",
"eci": "02",
"device_channel": "02",
"authentication": {
"value": "kFOAbf75KviDMXVzmGEoG3NIjJTF"
}
}

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