How to Test the 3DS API

This manual has been created to assist you in testing the 3DS API in your development environment. With this manual, you will be able to understand how the API works and how to use it to perform tests on your payment system.

By following the instructions in this manual, you will be able to ensure that your integration with the 3DS API is reliable and secure for your users.

Attention:

The tests will be conducted in a CARAT staging environment, which provides a more controlled and secure environment for conducting the tests.

Table with different cards for testing:

ID	BRAND	CARD NUMBER
`1`	Visa	4551820000009478
`2`	Mastercard	5555555555555555
`41`	Elo	6091490000009011
`3`	Amex	3766001349171000

Table with values in cents that can be used to simulate different statuses in 3DS:

AMOUNT	STATUS	DESCRIPTION
`10000`	AUY	Successful Authentication
`10004`	AUC	Challenge Required, following the "challenge" flow
`10001`	AUN	Not Authenticated/Account Not Verified; Transaction Denied

Examples

Below, we will provide examples of tests in the Frictionless and Challenge flows, as well as a test with a card number that is not within the range of cards supported for 3DS 2.0 authentication. All tests will be performed using the cURL tool.

Frictionless [Creating the Transaction]

Request Type: POST

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

Headers:

Content-Type: application/json
merchant_id: {Please request your store code from the support team.}
merchant_key: {Please request your merchant key from the support team.}

Mastercard Card: 5555555555555555

Request:

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

Response:

{
  "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"
    }
  }
}

Learn more about this service.

Frictionless [Performing the authentication.]

Request Type: PUT

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

In the above URL, the 3DS Server transaction ID was filled with the value fb26dfb6-2486-442a-8887-d1241c940a61, which was obtained during the transaction creation.

Headers:

Content-Type: application/json
merchant_id: {Please request your store code from the support team.}
merchant_key: {Please request your merchant key from the support team.}

Request:

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 protected]",
    "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"
  }
}

Response:

{
  "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"
  }
}

Learn more about this service.

Card not supported for 3DS 2.0 authentication. [Creating the transaction]

Request Type: POST

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

Headers:

Content-Type: application/json
merchant_id: {Please request your store code from the support team.}
merchant_key: {Please request your merchant key from the support team.}

Mastercard Card: 5251743209931344

Request:

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

Response:

{
  "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"
  }
}

Learn more about this service.

Challenge [Creating the transaction.]

Request Type: POST

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

Headers:

Content-Type: application/json
merchant_id: {Please request your store code from the support team.}
merchant_key: {Please request your merchant key from the support team.}

Mastercard Card: 5555555555555555

Request:

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

Response:

{
  "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"
    }
  }
}

Learn more about this service.

Challenge [Performing the authentication.]

Request Type: PUT

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

In the above URL, the 3DS Server transaction ID was filled with the value fb26dfb6-2486-442a-8887-d1241c940a61, which was obtained during the transaction creation.

Attention

To simulate the Challenge flow, it is necessary to pass the value 10014 in the purchase.amount field of the transaction, as indicated in the table presented at the beginning of this manual.

Headers:

Content-Type: application/json
merchant_id: {Please request your store code from the support team.}
merchant_key: {Please request your merchant key from the support team.}

Request:

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 protected]",
    "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"
  }
}

Response:

{
  "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

Request Type: POST

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

In the above URL, you need to insert the value of brandId, which in our test is defined as 2, as we are using a Mastercard card.

Headers:

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

Sending the CReq.

To obtain the challenge, the parameter creq must be sent, which contains the CReq encoded in Base64 URL-safe encoding.

CReq Json

In this JSON, we include the same transaction ID from the 3DS Server three_ds_server.trans_id and the transaction ID from the ACS acs.trans_id, which were obtained in the previous two steps.


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

CReq Base64:

ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImZiMjZkZmI2LTI0ODYtNDQyYS04ODg3LWQxMjQxYzk0MGE2MSIsCiAgImFjc1RyYW5zSUQiOiIwODFlZDU1Mi1lYWVkLTQ1NDgtODY4MC1lODlhZTYzMDk4OTAiLAogICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICJtZXNzYWdlVHlwZSI6IkNSZXEiLAogICJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIgp9

Learn more about this service.

After encoding the CReq JSON in Base64, we create the following request.

Request:

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'

Response:

The response will return a script from our simulator that simulates an ACS (Issuer) challenge. Normally, this script would be added to the application in an iframe, but for testing purposes, let's save it as an HTML file and open it in the browser. After that, select the desired challenge status - let's choose Status Y, indicating success - and click the submit button.

HTML file opened in the browser:

Attention

This is just a CARAT simulator to simulate the challenge.

Script response to simulate the challenge as represented in the image above.:

Attention

This script is returned to the response of the CReq submission.

<!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>

Query the transaction status after the challenge.

Request Type: GET

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

In the URL above, the ID of the 3DS Server transaction was filled with the value fb26dfb6-2486-442a-8887-d1241c940a61, which was obtained during the transaction creation.

Headers:

Content-Type: application/json
merchant_id: {Please request your store code from the support team.}
merchant_key: {Please request your merchant key from the support team.}

Request:

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'

Response:

{
    "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

Updated 5 days ago