Confirmation

Overview

A confirmation is sent to the merchants desired Notification URL if the merchant requested to receive these by providing eComm with their desired setting of the Notification Method to be either `Both` or `Notification`. The confirmation contains the transaction result and any UDF data provided in the original HTTP POST Request sent to the API. A confirmation notification is useful if the merchant wishes to act on the consumers transaction after the transaction has been completed and if the merchant wants an alternative method to determine transaction completion in case of a server fault as the confirmation notification can be then used as a backup. Below explains the data the merchant can expect to be received in the Notification URL, the merchant can use this data to handle the transaction.

The merchant must submit their chosen Notification URL to eCOMM for it to be whitelisted and enabled for use. The notification will be sent via HTTP Form Post in XML format where the merchant should set up a handler to parse the response.

The XML document will be transmitted through a field called data.

Setting Up A Handler

It is up to the merchant to decide what may be the best decision when deciding on how to handle the confirmation notification. The below example is intended to give the merchant an idea on how this can be achieved.

If the merchants notification URL is: http://example.com/Notification-Handler/Confirmation/, the HTTP POST will be sent identical to the below sample URL:

http://example.com/Notification-Handler/Confirmation/?data=<R>...</R>

The XML document will be enclosed in the data parameter which must be parsed in order to pull out the information the merchant may need to proceed.


Sample Notification Handler:
<?php
// Post Request - Confirmation Notification
if(isset($_POST["data"]))
{
	$strData = $_POST["data"]; //Assign the data to variable $strData
	$XMLDataArray = simplexml_load_string($strData); //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...
}
?>
// Post Request - Confirmation Notification
[HttpPost]
public IActionResult NotificationURL(string data)
{
	/* Parse XML from response */
	XmlDocument xDoc = new XmlDocument();
	xDoc.LoadXml(data);
	/* 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();
}

Data Returned

The confirmation notification will POST an XML document, below will help identify what XML fields are included and what to expect.

Successful transactions are marked with 0000 inside the <R1> field.

A well defined XML document response will be returned with the following information:
FieldName Description
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 Merchants own reference code to the transaction.
R4 Transaction status.
R5 Response from AVS and CV2 checks.

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

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

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

  • Match
  • Not Match
R9 Results of the 3D Secure Checks.

  • OK
  • Error
R10 Confirmation Type.

  • Confirm
  • Authorisation
R11 Merchant specified data that will be returned on the Response.
R12 Merchant specified transaction identifier that will be returned on the response.
udf UDF List

Sample XML Document

Below marks a sample successful confirmation notification. The error code 0000 inside the <R1> field marks this transaction as successful.

<!-- Sample XML Document -->
<?xml version="1.0"?>
<R>
  <R1>0000</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>
</R>