The Refund API is only required if the merchant wants to refund a transaction. The refund API is the most commonly used and is a must have if you intend on building an administration panel.

The process of the Refund 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 - Refund Received" if the notification method is set to: Notification, a confirmation notification will be sent to the merchants Notification URL with the transaction result. The Merchant will receive a response of "0054 - Successful Refund" if the notification method is set to BOTH or Server, indicating a successful refund, you will also receive a confirmation notification. The confirmation notification will contain the response: "0000 - Successful" indicating that the transaction in question is now refunded, any other response indicates a failed refund.

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.

1. Username = SomeName
2. Password = SomePassword
3. MessageID = *GUID (e.g. 30dd879c-ee2f-11db-8314-0800200c9a66)
4. APISignature = Refund
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.

https://staging.ecomm365.com/acqapi/service.ashx?Username=SomeName&Password=SomePassword&MessageID=30dd879c-ee2f-11db-8314-0800200c9a66&APISignature=refund&Data=<R>...</R>

<?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" => "Refund", //API Signature - Please notice the `Refund` signature here for the Refund 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=Refund"; //API Signature - Please notice the `Refund` signature here for the Refund 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();
}

Below is a table containing all the available fields for passing POST data into the data parameter within the `Refund` request. The value you enter for the Amount field must not exceed the total used in the sale request as the request will fail.

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

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.

<!-- Refund Request Demonstration -->
<R>
	<R1>43DAAL4B-78CF-4000-AC6B-EBA1F1116229</R1>
	<R2>100</R2>
	<R3>1</R3>
	<R4>1000596</R4>
	<R5>http://domain.com/NotificationURL/</R5>
</R>

Below are the expected XML fields returned from the request.

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

Expected error code responses:

1. 0054 - Indicates that the notification method is set to "Notification". The confirmation notification will be sent to the Notification URL.
2. 0023 - Indicates a successful refund, you will also receive a confirmation notification to the Notification URL.

Sample XML Response (0054):

<!-- Sample Server Response, XML Document -->
<?xml version="1.0"?>
<R>
	<R1>0054</R1>
	<R2>Successful refund</R2>
</R>

Sample XML Response (0023):

<!-- Sample Server Response, XML Document -->
<?xml version="1.0"?>
<R>
	<R1>0023</R1>
	<R2>Refund received</R2>
</R>

Sample XML Response (Confirmation Notification):

The below indicates a successful refund notification, expected to return to the Notification URL.

<!-- Sample Confirmation Notification, XML Document -->
<?xml version="1.0"?>
<R>
  <R1>0000</R1>
  <R2>Successful</R2>
  <R3>43DAAL4B-78CF-4000-AC6B-EBA1F1116229</R3>
  <R4>Successful</R4>
  <R11>MerchantData</R11>
  <R12>MerchantReferenceNumber</R12>
</R>