Sale & Pre-Auth

Overview

Our Sale API is the most flexible integration option out there. The Sale API allows the merchant to fully control the flow over the entire payment process allowing the merchant to provide a unique experience by designing their own payments page while also handling the payments process.

The information entered into the transaction form on the merchant site's payments page is collected and sent in XML format to the API by HTTP POST. This information is encapsulated in a parameter field called data when Making The Request.

Please Note The Following:

  1. The merchant will need to obtain the IP address of the consumer, this is where the request originates. Once obtained, please enter the IP in Field R37 in IPV4 format (e.g. 80.41.105.12).
  2. Fields, R5 → R14 & R22 → R31 are only required if AVS is enabled on the merchants account.
  3. If the merchant does not require specific 'required' fields, the merchant can always pass in the back end, 'NA' type data to pass validation such as 'NA' for 'Alpha' or '1234' for 'Numeric' however, we recommend all merchants to pass as much information where applicable.
  4. Field R15, the merchant can determine this by using the first digit of the card number however, the merchant must pass either [VSA], [MSC] or [MAE] when populating the R15 field. First digit of the card, 4 = [VSA], 5 = [MSC] & 6 = [MAE].

Sale Process

The process of the sale API is real simple and straight forward. Below demonstrates the steps required in order to successfully process a sale.

  1. The Consumer or Merchant determines if the transaction will be a Sale or a Pre-Auth. If the transaction is a Sale then the merchant will provide "C" in the R1 Field of the XML Document when making the request, if the transaction is going to be a Pre-Auth, the merchant will provide "CA" in the R1 Field of the XML Document when making the request.
  2. The collected form field data will be supplied into the XML Document fields for the data parameter of the POST request, once submitted the request will be sent to us and we will respond with useful information to determine the next step of that transaction.
  3. While using our Expected XML Documents as a guideline as to what results the merchant can expect, this is give the merchant the information required for the next steps for that transaction.
  4. If the transaction was a Pre-Auth, the funds will be frozen in a "Pending" state within their bank account. The merchant must then use our Complete Pre-Auth API to release the funds from the consumers account.

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, which could be either 3D Secure, Declined or A Successful Transaction. The response contains key information about the request and also contains the requested content.

The request string that is sent for the `Sale` 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 = Register
  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 the merchant 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=register&Data=<R>...</R>

Sample `Sale` 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" => "Register", //API Signature - Please notice the `Register` signature here for the sale 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=Register"; //API Signature - Please notice the `Register` signature here for the sale 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

When designing the payment form, the merchant needs to consider each field in the table below. In the XML document, the parent tag is called <R> and each child tag is called <R1>, <R2>, <R3> etc..

The table below describes each form field and what the API expects in each case. The merchant must study this carefully as they build the payment form and implement server side validation according to any guidelines in the description.

Referring to the table of field names (tags) below, if a form item is required, it is marked with 'Y', 'N' is not required & 'Y/AVS' means the field is only required if AVS is enabled on the merchants account. The merchants form will need to include all required field data and validated according to our validation.

Available Form Data Fields

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

FieldName Description Required FieldDefinition
R1 Transaction Type:

Sale = [C].
Sale With Pre-Auth = [CA].
Y AN(2)
R2 Transaction Code.

The merchant should provide a unique Transaction Code for each transaction.
Y AN(40)
R3 Total Transaction Amount (Without Decimals).

E.g: €100.00 = [10000], €123.67 = [12367], €0.99 = [99].
Y N(20)
R4 Tax Amount (Without Decimals).

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

E.g: Ireland = [IE], United Kingdom = [UK].
Y/AVS AN(3)
R14 Billing Phone Number (Without Hyphens).

E.g: 555-555-5555 = [5555555555].
Y/AVS N(20)
R15 Card Type.

Visa = [VSA].
MasterCard = [MSC].
Maestro = [MAE].
Y AN(20)
R16 Card Number. Y N(19)
R17 Card Expiration Month (Formatted MM).

E.g: [01].
Y N(2)
R18 Card Expiration Year (Formatted YYYY).

E.g: [2018].
Y N(4)
R19 Card CVV. Y N(3)
R20 Sale Amount Numeric Currency Code.
Complete list of ISO 4217 Numeric Currency Codes are available.

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

E.g: €123.67 = [12367], €1,500.00 = [150000].
Y N(20)
R22 Shipping First Name. Y/AVS AN(50)
R23 Shipping Middle Name. Y/AVS AN(50)
R24 Shipping Last Name. Y/AVS AN(50)
R25 Shipping Address Line 1. Y/AVS AN(50)
R26 Shipping Address Line 2. Y/AVS AN(50)
R27 Shipping City. Y/AVS AN(50)
R28 Shipping State/Province. Y/AVS AN(50)
R29 Shipping Postal Code. Y/AVS AN(10)
R30 Shipping Country Code.
Complete list of ISO 3166 Country Codes are available.

E.g: Ireland = [IE], United Kingdom = [UK].
Y/AVS AN(3)
R31 Shipping Phone Number (Without Hyphens).

E.g: 555-555-5555 = [5555555555].
Y/AVS N(20)
R32 Order Number or Transaction Identifier. Y AN(50)
R33 Order Channel.

  • Transaction initiated from the payment page = [MARK].
  • Transaction initiated from the cart page. = [CART].
  • Transaction initiated from the call center = [CALLCENTER].
  • Transaction initiated from the widget = [WIDGET].
  • Transaction initiated from the product = [PRODUCT].
  • Transaction initiated from 1 Click = [1CLICK].
Y A(16)
R35
Transaction Mode.

MOTO = [M].
e-Commerce = [S].

Y
A(1)
R36
Consumer's Email Address. N AN(255)
R37
Consumer IP Address.
Format NNN.NNN.NNN.NNN.

E.g: [80.41.105.12].
Y
AN(15)
R38
The Exact Content Of The HTTP Accept Header. Y
AN(256)
R39
The Exact Content Of The HTTP User Agent Header. Y AN(500)
R40 Merchant Data (Returned in the Transaction Result). N AN(20)
R41 Merchant Reference Number (Returned In The Transaction Result). N AN(20)
R42 Notification URL (Sends Confirmation Data).

E.g: [http://192.168.1.1/NotificationURL/]
or
[http://Domain.com/NotificationURL/]
Y AN(2000)
R44 Apply 3D Secure.

  • (Default) If 3D-Secure checks are possible, perform the checks and apply the authorisation rules = [0].
  • Force 3D-Secure checks for this transaction if possible and apply rules for authorisation = [1].
  • Do not perform 3D-Secure checks for this transaction and always authorise = [2].
  • Force 3D-Secure checks for this transaction if possible but ALWAYS obtain an auth code, irrespective of rule base. = [3].
N N(1)
R45 Vendor ID (VID) Y AN(50)
R46 Originating Merchant URL - Only required for PSPs. N AN(2000)
R47 Originating Merchant IP - Only required for PSPs. N AN(15)
udf UDF List N AN(50)

Available Form Data Fields - Validation

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

FieldName Description Validation
R1 Transaction Type. ^(C|D|CA|DA)$
R2 Transaction Code. ^[-_0-9A-Za-z]{0,40}$
R3 Amount. ^[0-9]{0,20}$
R4 Tax 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 Billing Phone Number. ^[0-9]{1,20}$
R15 Card Type. ^[a-zA-Z0-9]{1,20}$
R16 Card Number. Luhn Algorithm
R17 Card Expiry Month. ^((0[1-9])|(1[0-2]))$
R18 Card Expiry Year. ^(20)?(([1-2][0-9]))$
R19 CVV. ^[0-9]{3}$
R20 Shipping Amount Numeric Currency Code. ^[0-9]{3}$
R21 Shipping Amount. ^[0-9]{0,20}$
R22 Shipping First Name. ^[a-zA-Z0-9 ,'._-]{0,50}$
R23 Shipping Middle Name. ^[a-zA-Z0-9 ,'._-]{0,50}$
R24 Shipping Last Name. ^[a-zA-Z0-9 ,'._-]{0,50}$
R25 Shipping Address Line 1. ^[a-zA-Z0-9"/\s,()'#.`-]{1,255}$
R26 Shipping Address Line 2. ^[a-zA-Z0-9"/\s,()'#.`-]{0,255}$
R27 Shipping City. ^[a-zA-Z0-9 ,'._-]{0,50}$
R28 Shipping State/Province. ^[a-zA-Z0-9 ,'._-]{0,50}$
R29 Shipping Postal Code. ^[a-zA-Z0-9 '.,-]{1,10}$
R30 Shipping Country Code. ^[a-zA-Z]{2,3}$
R31 Shipping Phone Number. ^[0-9]{1,20}$
R32 Order Number or Transaction Identifier. ^[a-zA-Z0-9 ,'._-]{0,50}$
R33 Order Channel. \b(mark|cart|callcenter|widget|product|1click)\b
R35 Transaction Mode. \b(M|S|m|s){1}\b
R36 Consumer Email Address. (^$|[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}$)
R37 Consumers IP Address. ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$
R38 HTTP Accept Header. ^[a-zA-Z0-9\s,()./*+'\[\]_:;=-]{1,400}$
R39 User Agent Header. ^(?=.*?[A-Z])(?=.*?[a-z]).{8,500}$
R40 Merchant Data. ^$|^[a-zA-Z0-9|]{1,20}$
R41 Merchant Reference Number. ^$|^[a-zA-Z0-9]{1,20}$
R42 Notification URL. https?:\/\/?[-a-zA-Z0-9@:%._\+\~#=]{2,256}\b([-a-zA-Z0-9@:;%_\+.\~#?*\[\]{}()<>!&\/=]*)
R44 Apply 3D Secure. ^$|^[0-3]{1}$
R45 Vendor ID (VID). ^[a-zA-Z0-9 ,'._-]{0,50}$
R46 Originating Merchant URL. ^(ht|f)tp(s?)\:\/\/(([a-zA-Z0-9\-\._]+(\.[a-zA-Z0-9\-\._]+)+)|localhost)(\/?)([a-zA-Z0-9\-\.\?\,\'\/\\\+&%\$#_]*)?([\d\w\.\/\%\+\-\=\&\?\:\\\"\'\,\|\~\;]*)$
R47 Originating Merchant IP. ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$

Sample `Sale` 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.

<!-- Sale Request Demonstration -->
<R>
	<R1>C</R1>
	<R2>43DAAL4B-78CF-4000-AC6B-EBA1F1116229</R2>
	<R3>10000</R3>
	<R4>5000</R4>
	<R5>TestName</R5>
	<R6>TestMiddleName</R6>
	<R7>TestLastName</R7>
	<R8>4th Floor</R8>
	<R9>36 Carnaby Street</R9>
	<R10>London</R10>
	<R11>NA</R11>
	<R12>W1F 7DR</R12>
	<R13>UK</R13>
	<R14>123456789</R14>
	<R15>VSA</R15>
	<R16>1234567812341234</R16>
	<R17>02</R17>
	<R18>2018</R18>
	<R19>123</R19>
	<R20>826</R20>
	<R21>5000</R21>
	<R22>FirstName</R22>
	<R23>MiddleName</R23>
	<R24>LastName</R24>
	<R25>4th Floor</R25>
	<R26>36 Carnaby Street</R26>
	<R27>London</R27>
	<R28>NA</R28>
	<R29>W1F 7DR</R29>
	<R30>UK</R30>
	<R31>12346789</R31>
	<R32>678654687</R32>
	<R33>mark</R33>
	<R35>S</R35>
	<R36>test@test.com</R36>
	<R37>123.132.0.1</R37>
	<R38>*/*</R38>
	<R39>Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)</R39>
	<R40>MerchantData</R40>
	<R41>MerchantReferenceNumber</R41>
	<R42>www.test.com/test</R42>
	<R44>0</R44>
	<R45>1000596</R45>
	<udf>
	  <I>eCOMM</I>
	  <I>435</I>
	</udf>
</R>

Data Returned

Below are the expected XML fields returned from the merchants request, depending on what way the merchant has requested the notification method to be setup & if the provided card is 3D Secure, will determine what type of data is returned.

The merchant will receive 0008 - Confirmation received if the notification method is set to: Notification, the Confirmation Notification will be sent to the Notification URL. Otherwise, transaction result, 0044 - Successful Transaction will return 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.

If the provided card is 3D Secure, the merchant will receive 0000 - Successful within the server response after the request has been made. The merchant must now cater for 3D secure, please see Overview for more information.

Response from request (Card Is 3D Secure):

The merchant will receive this response if the provided card is 3D Secure. Please note that the ACSURL, PAReq & the MD are supplied within the XML Document. These must be supplied when catering for 3D secure.

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 ACSURL - Link to the 3D Secure service. AN(2048)
R4 PAReq - Message passed to the Issuing Bank. AN(2048)
R5 MD - Secret key between the Issuer, Acquirer and the Merchant. AN(2048)
R6 Merchants Transaction Code AN(40)
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. 0000 - Means that the used card is 3D Secure, the merchant must now cater for 3D Secure to continue processing this payment.
  2. 0008 - Means that the notification method is set to "Notification". The confirmation notification will be sent to the Notification URL however, this does not mean the transaction was successful or declined, the transaction result will be displayed in the notification sent.
  3. 0044 - Means the transaction was successful.

Sample XML Response If The Card Is 3D Secure (0000):
<!-- Sample XML Document If The Card Is 3D Secure -->
<?xml version="1.0"?>
<R>
	<R1>0000</R1>
	<R2>Successful</R2>
	<R3>https://3DSecureSite.com/Page.aspx</R3>
	<R4>eNpVUttSwjAQfc9XMDw7pGkLArNmBkVGdMBSvIynnV0lSNOStgz8vUnLRd/2nL3k7NnAy8ogjpcoK4McZlgU4htbKrlph+ywSxYTX+6D3tviWT+tPrw2h2gU45bDplwhMs1Zx+v4QE+Q2BFGroQuOQi5vZ3OOfODsNu77gM9EgRSNNPxn0SDCWiRIo8M5kIlrYnSQkslNq0lmp2SCLTOE5BZpUtz4P3QA3oCBCqz4auyzIeU5s2Mr9OIoplQdGSWAnWFBOhFaVS5qLAG7FXC5+NJN0njOF4/rnE88982k+jzp8zeX0Y3QF0FgUSUyH2P9b2B320xNgyDYbcHtOYJiNSp4vevMfOuPKvySBDI3VOjBjHPpf4ydrfKGNTywAfOmDMigPs802hrrNvn2G5x0X734DyXpbM2CMKBz5zlNa7blXWJ9VnTr2rLqOuhx5PS4/Vt9O9X/AIlllLC</R4>
	<R5>0003938b-f26d-45a5-98c6-l99c08e81230</R5>
	<R6>152D500P-8559-4FFF-B412-FFD255C09C56</R6>
</R>
Sample XML Response If Notification Method Set: Notification (0008):
<!-- Sample XML Document If Notification Method Set: Notification, Confirmation Notification will be sent to the Notification URL -->
<?xml version="1.0"?>
<R>
	<R1>0008</R1>
	<R2>Confirmation 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>eCOMM</I>
		<I>435</I>
	</udf>
</R>