The process of the sale API is real simple and straight forward. Below demonstrates the steps required in order to successfully process a sale.
If merchant is using 3DS version 2.x (EMV 3DS), process starts with collecting data from a device used by customer to perform transaction. As soon as customer inputs first 6 digits (BIN) of the card number on the merchant's web site, merchant should create a hidden html IFrame containing html form and POST it to our DDC endpoint. Our system will then perform DDC and for merchant there is no further action required.
Production Url for DDC endpoint will be provided when needed.
DDC form parameters are Amount, BIN, VendorId and TransactionCode:
FieldName | Description | Required | FieldDefinition |
---|---|---|---|
Amount | Total transaction amount without decimals (i.e.: €100.00 => 10000, €123.67 => 12367, €0.99 => 99). | Y | N(20) |
BIN | Bank Identification Number = first 6 digits of the card number. | Y | N(6) |
VendorId | ECOMM provided Vendor ID (VID). | Y | AN(50) |
TransactionCode | Merchant provided value that is unique for each transaction. | Y | AN(40) |
<!DOCTYPE html>
<html>
<body>
<form id="ddc" name="ddc" method="post" action="https://staging.ecomm365.com/SecureCustomerAuthentication/API/DeviceDataCollection">
<input type="hidden" name="Amount" value="100"/>
<input type="hidden" name="BIN" value="411111"/>
<input type="hidden" name="VendorId" value="100001"/>
<input type="hidden" name="TransactionCode" value="123456-1234-1234-123456"/>
</form>
<script>
window.onload = function () { document.getElementById("ddc").submit(); }
</script>
</body>
</html>
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: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.
https://staging.ecomm365.com/acqapi/service.ashx?Username=SomeName&Password=SomePassword&MessageID=30dd879c-ee2f-11db-8314-0800200c9a66&APISignature=register&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" => "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();
}
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.
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.
|
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]. |
N |
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.
|
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) |
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}$ |
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>
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.
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) |
R7 | Cardinal Transaction Reference Id | AN(20) |
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.
|
AN(50) |
R6 |
Result of the checks on the cardholders address numeric from the AVS/CV2 checks.
|
AN(20) |
R7 |
Result of the checks on the cardholders Postcode from the AVS/CV2 checks.
|
AN(20) |
R8 |
Result of the checks on the cardholders CV2 code from the AVS/CV2 checks.
|
AN(20) |
R9 |
Results of the 3D Secure Checks.
|
AN(50) |
R10 |
Confirmation Type.
|
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) |
This section demonstrates the expected XML document responses returned from the HTTP POST once the request has passed validations.
<!-- 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>
<R7>hrETn5Lu6UxoZry2VUJ1</R7>
</R>
<!-- 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 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>