The DCC Query API is only required if the merchant wants to offer DCC via the Sale API, our Hosted Payments Page API handles DCC automatically for the merchant if requested to do so.

DCC is the user-friendly, point-of-purchase service whereby international Visa & MasterCard card users can choose to pay in their own currency, rather than the domestic currency of where they are making their purchase.

DCC Query Process

The process of the DCC Query API is real simple and straight forward. In order to successfully cater for DCC, please ensure you make the DCC Query request before making the sale request as you must supply additional fields into the sale request. Below demonstrates the steps required in order to successfully make the request.

  1. The merchant will decide if they wish to offer DCC to the consumer and provide this information to eCOMM365.
  2. The merchant will make a request using our DCC Query API including the consumers Card Number, Amount & Vendor ID. If DCC is applicable, the response back from the server will include "0000 - DCC Conversion Successful" and the DCC Token which will be required within the Sale API request which will allow catering for DCC.
  3. If DCC was successful and the merchant receives the DCC Token, the merchant must supply this DCC Token into the sale request in order to accept DCC.

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 `DCC Query` 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 = DccQuery
  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 `DCC Query` 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" => "DccQuery", //API Signature - Please notice the `DccQuery` signature here for the DCC Query 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/
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=DccQuery"; //API Signature - Please notice the `DccQuery` signature here for the DCC Query 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.

	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 `DCC Query` request.

FieldName Description Required FieldDefinition
R1 Current Alpha Currency Code Of The Vendor
Complete list of Alpha Currency Codes are available.
Y AN(3)
R2 Vendor ID Y AN(50)
Sale Amount (Without Decimals).

E.g: €100.00 = [10000], €123.67 = [12367], €0.99 = [99].
R4 Card Number. Y N(19)

Available Form Data Fields - Validation

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

FieldName Description Validation
R1 Current Alpha Currency Code Of The Vendor ^[A-Za-z0-9]{3}$
R2 Vendor ID ^[a-zA-Z0-9 ,'._-]{0,50}$
Sale Amount (Without Decimals). ^[0-9]{0,20}$
R4 Card Number. Luhn Algorithm

Sample `DCC Query` 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.

<!-- DCC Query Request Demonstration -->

Data Returned

Below are the expected XML fields returned from the request.

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.
R3 DCC Token

Token that will identify DCC conversion within the Sale Request.
R4 DCC Conversion Date/Time

Date/Time when the conversion took place.
R5 Sale Amount AN(250)
R6 Numeric Currency Code Of The Vendor AN(250)
R7 Sale Amount Converted With DCC AN(250)
R8 Numeric Currency Code Of The Converted Sale Amount AN(250)
R9 Exchange Rate AN(250)
R10 Markup Exchange Rate AN(250)
R11 MarkUp Percentage AN(250)
R12 Card Issuer Country

Reserved for future use, will return 0 for now.
R13 Clearing Numeric Currency Code AN(250)
R14 DCC Valid Hours

Number of hours DCC conversion will remain valid.

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. 0000 - Indicates a successful DCC Query, included will also contain the DCC Token in R3 which will be required in the sale request.

Sample XML Response (0000):
<!-- Sample Server Response, XML Document -->
<?xml version="1.0"?>
	<R2>DCC Conversion Successful</R2>

Applying DCC To A Sale

This section demonstrates how to apply the generated DCC Token to the Sale Request once the request has passed validations.

After receiving the DCC Token which is returned in the R3 field of the XML Document, you must now supply this generated DCC Token when making the Sale Request. At the end of the XML Document within the data parameter of the sale request, you must supply the following fields encapsulated inside the <DCC>.

Below is an example that demonstrates how the XML Document should look when forming the Sale Query.

<!-- Applying DCC In A Sale Request Demonstration -->
<?xml version="1.0"?>