Hosted Payments Page

Overview

This solution allows the merchant to have an embedded iFrame within their website that will load eComms Hosted Payments page. The merchants developer can choose to embed the iFrame within a checkout page or create a pop-up modal that will contain the iFrame.

The consumers data is collected on the merchants website where it is posted to the eCOMM API via our 'registerpayment' API. The response will contain the URL which will be used to load into the iFrame. The consumer must then input their card details and submit the form, if the consumers card is 3D Secure, the consumer must enter their unique secure code and submit in order to authenticate themselves, if successful the consumer will be redirected to a success page which was pre-determined in the initial `registerpayment` request. The transaction result inside the confirmation notification will be sent to the merchants Notification URL. Our Hosted Payments Page handles the flow of 3D Secure.

*Please note that it is required that the merchant provides eCOMM with the desired Notification URL and that the notification method can only be set to: Both.

The merchant can also style the Hosted Payments Page by supplying us with their desired Cascading Style Sheet (CSS), eCOMM will update the merchants profile with the provided Cascading Style Sheet.

Our Hosted Payments Page supports DCC, in order to enable DCC the merchant must supply eCOMM with the currencies the merchant wishes to accept.

Hosted Payments Page Process

The process of the Hosted Payments Page API is real simple and straight forward. Below demonstrates the steps required in order to successfully cater for our Hosted Payments Page.

  1. The consumers information is collected and submitted to our API.
  2. The response will contain the URL required to pass into an iFrame that will load the Hosted Payments Page. Here the consumer must then enter their card details and submit.
  3. If the consumers card is 3D Secure, the consumer must enter their unique secure code and submit in order to authenticate themselves.
  4. If 3D Secure and the transaction is successful, the consumer is redirected to the designated successful page. If the transaction fails, the consumer is redirected to the designated failure page. These pages are pre-determined in the initial 'registerpayment' request.
  5. The overall transaction result will be sent to the merchants Notification URL.

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 then cater for the action listed. The response contains key information about the request and also contains the requested content.

The request string that is sent for the `Hosted Payments Page` 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 = Registerpayment
  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 of the collected information you gathered from the customer while 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=registerpayment&Data=<R>...</R>

Sample `Hosted Payments Page` 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" => "Registerpayment", //API Signature - Please notice the `Registerpayment` signature here for the Hosted Payments Page 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...
?>
[HttpPost]
public IActionResult index()
{
	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=Registerpayment"; //API Signature - Please notice the `Registerpayment` signature here for the Hosted Payments Page 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();
}

Data Required

Sample Hosted Payments Page Form:
Sample Hosted Payments Page Form

When the Hosted Payments Page is loaded inside an iFrame the consumer will be presented with a screen similar to screenshot above.

The consumer must enter their card information and submit the form. The form will then redirect the consumer to the merchants success or failure page depending on the result of the transaction.

The merchant will also receive a confirmation notification via their Notification URL which must be setup to handle the transaction.

Sample Hosted Payments Page (DCC) Form:
Sample Hosted Payments Page (DCC) Form

While using the same information as you would for the normal process of the Hosted Payments Page above, when the card holder enters their Card Number, a quick check is made behind the scenes which checks if DCC is applicable for the entered card.

If the entered card is applicable for DCC then a new section will appear below the Card Expiry, displaying DCC. The consumer will have an option to decide on which currency they wish to proceed with.

Available Form Data Fields

Below is a table containing all the available fields for passing POST data into the data parameter within the `Hosted Payments Page` request. These fields should be filled using collected data from the consumer on a Form Level.

FieldName Description Required FieldDefinition
R1 Transaction Code.

The merchant should provide a unique Transaction Code for each transaction.
Y AN(40)
R3 Sale Amount Numeric Currency Code.
Complete list of ISO 4217 Numeric Currency Codes are available.

E.g: EUR = [978], GBP = [826].
Y N(3)
R4 Total Transaction Amount (Without Decimals).

E.g: €100.00 = [10000], €123.67 = [12367], €0.99 = [99].
Y N(20)
R5 Billing First Name. Y AN(50)
R6 Billing Middle Name. N AN(50)
R7 Billing Last Name. Y AN(50)
R8 Billing Address Line 1. Y AN(50)
R9 Billing Address line 2. N AN(50)
R10 Billing City. Y AN(50)
R11 Billing State/Province. N AN(50)
R12 Billing Postal Code. Y AN(10)
R13 Billing Country Code.
Complete list of ISO 3166 Country Codes are available.

E.g: Ireland = [IE], United Kingdom = [UK].
Y AN(3)
R14 Vendor ID Y AN(50)
R15 Successful URL - Redirects The Consumer If The Transaction Is Successful. Y AN(250)
R16 Non Successful URL - Redirects The Consumer If The Transaction Is Not Successful. Y AN(250)
R17 Originating Merchant URL - Only required for PSPs. N AN(2000)
R18 Originating Merchant IP - Only required for PSPs. N AN(15)
R19 Consumer's Email Address. N AN(250)
R20 Language Code.

E.g: English = [EN], French = [FR], Netherlands = [NL].
N AN(2)
R21 Back URL - URL address of the back button displayed in the iFrame. N AN(2000)
udf UDF List N AN(20)

Available Form Data Fields - Validation

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

FieldName Description Validation
R1 Transaction Code. ^[-_0-9A-Za-z]{0,40}$
R3 Sale Amount Numeric Currency Code. ^[0-9]{3}$
R4 Total Transaction Amount. ^[0-9]{0,20}$
R5 Billing First Name. ^[a-zA-Z0-9 ,'._-]{0,50}$
R6 Billing Middle Name. ^[a-zA-Z0-9 ,'._-]{0,50}$
R7 Billing Last Name. ^[a-zA-Z0-9 ,'._-]{0,50}$
R8 Billing Address Line 1. ^[a-zA-Z0-9"/\s,()'#.`-]{1,255}$
R9 Billing Address line 2. ^[a-zA-Z0-9"/\s,()'#.`-]{0,255}$
R10 Billing City. ^[a-zA-Z0-9 ,'._-]{0,50}$
R11 Billing State/Province. ^[a-zA-Z0-9 ,'._-]{0,50}$
R12 Billing Postal Code. ^[a-zA-Z0-9 '.,-]{1,10}$
R13 Billing Country Code. ^[a-zA-Z]{2,3}$
R14 Vendor ID ^[a-zA-Z0-9 ,'._-]{0,50}$
R15 Successful URL ^(ht|f)tp(s?)\:\/\/(([a-zA-Z0-9\-\._]+(\.[a-zA-Z0-9\-\._]+)+)|localhost)(\/?)([a-zA-Z0-9\-\.\?\,\'\/\\\+&%\$#_]*)?([\d\w\.\/\%\+\-\=\&\?\:\\\"\'\,\|\~\;]*)$
R16 Non Successful URL ^(ht|f)tp(s?)\:\/\/(([a-zA-Z0-9\-\._]+(\.[a-zA-Z0-9\-\._]+)+)|localhost)(\/?)([a-zA-Z0-9\-\.\?\,\'\/\\\+&%\$#_]*)?([\d\w\.\/\%\+\-\=\&\?\:\\\"\'\,\|\~\;]*)$
R17 Originating Merchant URL. ^(ht|f)tp(s?)\:\/\/(([a-zA-Z0-9\-\._]+(\.[a-zA-Z0-9\-\._]+)+)|localhost)(\/?)([a-zA-Z0-9\-\.\?\,\'\/\\\+&%\$#_]*)?([\d\w\.\/\%\+\-\=\&\?\:\\\"\'\,\|\~\;]*)$
R18 Originating Merchant IP. ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$
R19 Consumer's Email Address. (^$|[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}$)
R20 Language Code. EN|FR|NL
R21 Back URL. ^(ht|f)tp(s?)\:\/\/(([a-zA-Z0-9\-\._]+(\.[a-zA-Z0-9\-\._]+)+)|localhost)(\/?)([a-zA-Z0-9\-\.\?\,\'\/\\\+&%\$#_]*)?([\d\w\.\/\%\+\-\=\&\?\:\\\"\'\,\|\~\;]*)$

Sample `Hosted Payments Page` 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.

<!-- Hosted Payments Page Request Demonstration -->
<R>
	<R1>43DAAL4B-78CF-4000-AC6B-EBA1F1116229</R1>
	<R3>978</R3>
	<R4>100</R4>
	<R5>Billing First Name</R5>
	<R6>Billing Middle Name</R6>
	<R7>Billing Last Name</R7>
	<R8>IDA Business and Technology Park</R8>
	<R9>Johnstown</R9>
	<R10>Navan</R10>
	<R12>Meath</R12>
	<R13>IE</R13>
	<R14>1000596</R14>
	<R15>http://domain.com/HostedPaymentsPage/Success/</R15> 
	<R16>http://domain.com/HostedPaymentsPage/Failure/</R16>
	<udf>
	  <I>eCOMM</I>
	  <I>435</I>
	</udf>
</R>

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.
AN(50)
R2 Description

Please see Appendix A for a list of descriptions.
AN(50)
R3 Merchants Transaction Code AN(50)
R4 The Hosted Payments Page URL To Complete The Transaction (Used For The iFrame). AN(2048)
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. 0038 - Successful request, the response includes the URL required to pass into the iFrame in the R4 field.

Sample XML Response (0038):
<!-- Sample XML Document -->
<?xml version="1.0"?>
<R>
	<R1>0038</R1>
	<R2>Register Payment Received</R2>
	<R3>43DAAL4B-78CF-4000-AC6B-EBA1F1116229</R3>
	<R4>https://www.somewebsite.com/acs?id=43DAAL4B-78CF-4000-AC6B-EBA1F1116229</R4>
</R>
Sample XML Response (Confirmation Notification):

The below is a sample of what to expect to be sent to the Notification URL if your notification method is setup to do so. Please note that Card Information can be included in this response once set at VID level, the merchant must request this to be turned on. Full reference of available fields is located here.

<!-- 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>
	
	<!-- Card Information returned, ONLY if enabled at VID level -->
	<CN>542432******0751</CN>
	<CardType>MSCP</CardType>
	<CardExpMM>12</CardExpMM>
	<CardExpYYYY>2025</CardExpYYYY>
	
	<udf>
		<I>eCOMM</I>
		<I>435</I>
	</udf>
</R>