Complete Pre-Auth

Overview

The Complete Pre-Auth API is only required if the transaction was made using our Sale API while providing "CA" into the R1 field of the XML Document for the data parameter. The "CA" identifier tells us that the transaction is going to be a Pre-Auth and that the funds will be frozen in a "Pending" state within the consumers bank account. You must then use our Complete Pre-Auth API to process the funds from the consumers account.

Complete Pre-Auth Process

The process of the Complete Pre-Auth API is real simple and straight forward. Below demonstrates the steps required in order to successfully make the request.

  1. The transaction information is submitted to our API.
  2. The merchant will receive a response of "0023 - Clear Received" if the notification method is set to: Notification, a confirmation notification will be sent to the merchants Notification URL with the overall result. The merchant will receive a response of "0044 - Successful Transaction" if the notification method is set to BOTH or Server, depending on the notification method setup, the merchant may also receive a confirmation notification. The confirmation notification may contain the response: "0000 - Successful" indicating that the transaction in question has now completed the Pre-Auth with the amount specified.

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 `Complete Pre-Auth` 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 = Clear
  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:
https://staging.ecomm365.com/acqapi/service.ashx?Username=SomeName&Password=SomePassword&MessageID=30dd879c-ee2f-11db-8314-0800200c9a66&APISignature=clear&Data=<R>...</R>

Sample `Complete Pre-Auth` Request
<?php
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" => "Clear", //API Signature - Please notice the `Clear` signature here for the Complete Pre-Auth request
"MessageID" => GUID(), //A new GUID is required for every new API Call
"Username" => "SomeName", //API Username
"Password" => "SomePassword", //API Password
"Data" => "<R>...</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/
[HttpPost]
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=Clear"; //API Signature - Please notice the `Clear` signature here for the Complete Pre-Auth request
	
	pData += "&Data=" + WebUtility.UrlEncode(@"<R>...</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.
	dataStream.Close();

	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();
	xDoc.LoadXml(responseString);
	/* 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 `Complete Pre-Auth` request. The Amount (field) value must not exceed the total used in the sale request as the request will fail.

FieldName Description Required FieldDefinition
R1 Transaction Code.

The Transaction Code used in the Sale request.
Y AN(40)
R2 Amount To Complete (Without Decimals).

E.g: €100.00 = [10000], €123.67 = [12367], €0.99 = [99].
Y N(20)
R3 Vendor ID Y AN(50)

Available Form Data Fields - Validation

Below is a table containing all the available fields for the data parameter within the `Complete Pre-Auth` request including its validation. These are used when constructing the data.

FieldName Description Validation
R1 Transaction Code ^[-_0-9A-Za-z]{0,40}$
R2 Total Transaction Amount (Without Decimals) ^[0-9]{0,20}$
R3 Vendor ID ^[a-zA-Z0-9 ,'._-]{0,50}$

Sample `Complete Pre-Auth` 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.

<!-- Complete Pre-Auth Request Demonstration -->
<R>
	<R1>43DAAL4B-78CF-4000-AC6B-EBA1F1116229</R1>
	<R2>100</R2>
	<R3>1000596</R3>
</R>

Data Returned

Below are the expected XML fields returned from the request, depending on what way the merchant has requested the notification method to be setup will determine what type of data is returned.

The merchant will receive 0023 - Clear Received if the notification method is set to: Notification, meaning the Confirmation Notification will be sent to the Notification URL. Otherwise, the merchant will receive the transaction result, 0044 - Successful Transaction directly back in the server response and depending on the Notification Methods setup, the merchant may also receive the Confirmation Notification sent to the Notification URL.

Response from request (Notification Set: Notification):
FieldName Description FieldDefinition
R1 Error Code

Please see Appendix A for a list of available error codes.
N(4)
R2 Description

Please see Appendix A for a list of descriptions.
AN(250)
Response from request (Transaction Result):

The merchant will receive the Transaction Result if the request passed validation checks.

FieldName Description FieldDefinition
R1 Error Code

Please see Appendix A for a list of available error codes.
N(4)
R2 Description

Please see Appendix A for a list of descriptions.
AN(250)
R3 Merchants own reference code to the transaction. AN(40)
R4 The transaction status. AN(20
R5 Response from AVS and CV2 checks.

  • All Match MATCH
  • Security Code Match Only
  • Address Match Only
  • No Data Matches
  • Data Not Checked
AN(50)
R6 Result of the checks on the cardholders address numeric from the AVS/CV2 checks.

  • Match
  • Not Match
AN(20)
R7 Result of the checks on the cardholders Postcode from the AVS/CV2 checks.

  • Match
  • Not Match
AN(20)
R8 Result of the checks on the cardholders CV2 code from the AVS/CV2 checks.

  • Match
  • Not Match
AN(20)
R9 Results of the 3D Secure Checks.

  • OK
  • Error
AN(50)
R10 Confirmation Type.

  • Confirm
  • Authorisation
AN(10)
R11 Merchant specified data that will be returned on the Response. AN(20)
R12 Merchant specified transaction identifier that will be returned on the response. AN(20)
udf UDF List AN(50)

Expected XML Documents

This section demonstrates the expected XML document responses returned from the HTTP POST once the request has passed validations.

Expected error code responses:
  1. 0023 - Means that the notification method is set to "Notification". The confirmation notification will be sent to the Notification URL.
  2. 0044 - Means the transaction was successful and the funds are now processed, the merchant may also receive a confirmation notification depending on the notification method setup.

Sample XML Response If Notification Method Set: Notification (0023):
<!-- Sample XML Document If Notification Method Set: Notification, Confirmation Notification will be sent to the Notification URL -->
<?xml version="1.0"?>
<R>
	<R1>0023</R1>
	<R2>Clear received</R2>
</R>
Sample XML Response If Its The Transaction Result (0044):
<!-- Sample XML Document If Its The Transaction Result -->
<?xml version="1.0"?>
<R>
	<R1>0044</R1>
	<R2>Successful</R2>
	<R3>43DAAL4B-78CF-4000-AC6B-EBA1F1116229</R3>
	<R4>Successful</R4>
	<R5>Data Not Checked</R5>
	<R8>Match</R8>
	<R9>Ok</R9>
	<R10>Confirm</R10>
	<R11>MerchantData</R11>
	<R12>MerchantReferenceNumber</R12>
	<udf>
		<I>UDF Data</I>
	</udf>
</R>