3D Secure Confirm (3DS Version 2)


Before reading this section, please ensure you have read our 3D Secure documentation, this section explains what is required and lists each step in great depth to allow merchants to fully understand how to successfully integrate using 3D Secure.

The 3D Secure Confirm API is required to ensure the consumer has passed authentication. You must make the 3D Secure Confirm request inside your TermURL as this is where the consumer will be redirected after they input their unique secure code. When redirecting, 3D Secure will POST the PaRes to your TermURL where you must obtain and supply this value for the <R1> field of the 3D Secure Confirm request. The PARes is the reply received from the Issuing Bank after the card holder has been authenticated. The merchant must then provide the Transaction Code they generated when making the sale request and supply this value for the <R2> field, the Vendor ID is then required for the <R3> field within the XML document. Value for <R4> should contain Cardinal Transaction ID present in the initial Sale response.

Making The Request

HTTP is used as the request-response protocol between a merchants site and the eCOMM API. In the back end, a merchant submits a HTTP POST request to the eCOMM server, the server will then return an XML document where the merchant must parse the data inside and act accordingly. The response contains key information about the request and also contains the requested content.

The request string that is sent for the `3D Secure Confirm` call must be composed of the following information:
  1. Username = SomeName
  2. Password = SomePassword
  3. MessageID = *GUID (e.g. 30dd879c-ee2f-11db-8314-0800200c9a66)
  4. APISignature = confirm
  5. Data = Form data in XML format (See sample here)

The above parameters are required when sending HTTP POST data to our API in order to receive a successful response. The data parameter must be composed using our Available Form Data fields.

A fully formatted HTTP POST request should look identical to the below sample URL:

Sample `3D Secure Confirm` Request
function httpPost($url, $params) //Post method
	$params = urldecode(http_build_query($params)); //Convert our array of params into query string, URL decode the result to prevent data corruption
	$ch = curl_init($url); //create a new cURL resource
	//set appropriate options
	curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
	curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
	curl_setopt($ch, CURLOPT_HEADER, 0);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	$response = curl_exec($ch); //grab URL and pass it to the browser while assigning the response to `$response`
	curl_close($ch); //close cURL resource, and free up system resources
    return $response;

$APIURL = "https://staging.ecomm365.com/acqapi/service.ashx"; //Set API URL to eComm staging environment
$params = array(
"APISignature" => "Confirm", //API Signature - Please notice the `Confirm` signature here for the 3D Secure Confirm request
"MessageID" => GUID(), //A new GUID is required for every new API Call
"Username" => "SomeName", //API Username
"Password" => "SomePassword", //API Password
"Data" => "<R><R1>".$_POST["PaRes"]."</R1>...</R>" //Data fields required for request

$Response = httpPost($APIURL, $params); //User defined function used to POST data to API and assign the response to `$Response` variable
$XMLDataArray = simplexml_load_string($Response); //Used to parse XML at ease

/* Obtain information from response fields */
$ResponseR1 = (string)$XMLDataArray->R1;
$ResponseR2 = (string)$XMLDataArray->R2;
//... etc

//Or loop through the elements
/* END */

//More Code...
// Location: /TermURL/
public IActionResult index(string PaRes)
	HttpWebRequest httpWReq = (HttpWebRequest)WebRequest.Create("https://staging.ecomm365.com/acqapi/service.ashx"); //Create webrequest while setting the API URL to eComm staging environment
	UTF8Encoding encoding = new UTF8Encoding(); //Represents a UTF-8 encoding of Unicode characters.

	string pData = "username=SomeName"; //API Username
	pData += "&password=SomePassword"; //API Password
	pData += "&messageId=" + System.Guid.NewGuid().ToString();  //A new GUID is required for every new API Call
	pData += "&ApiSignature=Confirm"; //API Signature - Please notice the `Confirm` signature here for the 3D Secure Confirm request
	pData += "&Data=" + WebUtility.UrlEncode(@"<R><R1>" + PaRes + @"</R1>...</R>"); //Data fields required for request

	byte[] data = encoding.GetBytes(pData); //Getting Bytes for data

	httpWReq.Method = "POST"; //HTTP Method - POST
	httpWReq.ContentType = "application/x-www-form-urlencoded"; //Setting the correct Content Type
	httpWReq.ContentLength = data.Length; //Getting Content Length

	//Create POST data and convert it to a byte array.
	byte[] byteArray = Encoding.UTF8.GetBytes(pData);

	// Get the request stream.
	Stream dataStream = httpWReq.GetRequestStream();

	// Write the data to the request stream.
	dataStream.Write(byteArray, 0, byteArray.Length);

	// Close the Stream object.

	HttpWebResponse response = (HttpWebResponse)httpWReq.GetResponse(); //Assign response to `response` variable
	string responseString = new StreamReader(response.GetResponseStream()).ReadToEnd(); //Obtain response from post

	/* Parse XML from response */
	XmlDocument xDoc = new XmlDocument();
	/* END */

	/* Obtain information from response fields */
	XmlNodeList ResponseR1 = xDoc.GetElementsByTagName("R1");
	XmlNodeList ResponseR2 = xDoc.GetElementsByTagName("R2");
	//... etc

	//Or loop through the elements
	/* END */

	//More code...
	return View();

Available Form Data Fields

Below is a table containing all the available fields for passing POST data into the data parameter within the `3D Secure Confirm` request.

FieldName Description Required FieldDefinition
R1 PARes generated by the external system that processed the authentication with the Consumer. Y AN(10240)
R2 Transaction Code.

The Transaction Code used in the Sale request.
Y AN(40)
R3 Vendor ID Y AN(50)
R4 Cardinal Transaction ID Y AN(20)

Available Form Data Fields - Validation

Below is a table containing all the available fields for the data parameter within the `3D Secure Confirm` request including its validation. These are used when constructing the data.

FieldName Description Validation
R1 PARes N/A
R2 Transaction Code ^[-_0-9A-Za-z]{0,40}$
R3 Vendor ID ^[a-zA-Z0-9 ,'._-]{0,50}$
R4 Cardinal Transaction ID ^[a-zA-Z0-9 ,'._-]{0,20}$

Sample `3D Secure Confirm` XML Document

The below sample demonstrates what is expected when passing POST data into the data parameter.
When forming the data parameter, please refer to our guidelines above.

<!-- 3D Secure Confirm Request Demonstration -->

Data Returned

Below are the expected XML documents returned from the request. Please have a read of our Expected XML Documents on our sale API documentation, here you can find more information about all the expected success responses.

FieldName Description FieldDefinition
R1 Error Code

Please see Appendix A for a list of available error codes.
R2 Description

Please see Appendix A for a list of descriptions.