The Recurring Billing API allows the merchant to process transactions without the need of the consumers card information. The merchant must first register the consumers card details into eCOMM's system where the response will contain a RBID (Recurring Billing ID), the RBID is then used to process a transaction using our "processrecurringbilling" API. The RBID is required when using the "DeactivateRecurringBilling" & "ProcessRecurringBilling" API.

To generate the RBID, the merchant must supply additional fields to the existing Sale API or the Hosted Payments Page API Request in order to obtain the RBID. The RBID will store the card holders information so there is no need for the card information after the initial creation.

The merchant must process a transaction in order to successfully obtain the generated RBID. If the merchant wants to create an RBID without processing a payment, the only suitable solution (Quick Solution) for this would be to do a Sale of 0.01 (1 Cent) to generate the RBID, then refund that transaction. Another solution (Longer solution) would be to do a Pre-Auth of 0.01 (1 Cent), Complete the Pre-Auth and the RBID will be created, You can then refund the transaction. The merchant cannot pass a value of 0 for the amount as the request will fail.

Within this section the merchant can find three of our Recurring Billing APIs, below lists all three. Please note that the consumers card details are required to be entered the first time around when generating the RBID, for future transactions, only the RBID is required by supplying the RBID into the "processrecurringbilling" API.

1. Generate RBID - To generate a RBID the merchant must first enter additional fields at the end of the XML Document of the desired API Initial Request. If successful and the merchants notification method is set to Notification, the merchant will receive the RBID within the response of the confirmation notification that will be sent to the merchants Notification URL. If the notification method is set to Both or Server, the merchant will receive the RBID within the server response and depending if set to Both, the confirmation notification including the RBID will be sent to the merchants Notification URL. The RBID can be found inside the XML Document under a field called "RBID".
2. Deactivate / Activate RBID - This allows the merchant to activate / deactivate the RBID.
3. Process RBID - This allows the merchant to process a transaction using the RBID.

The Recurring Billing can work with the Sale API or the Hosted Payments Page API to generate the RBID. Please ensure that the documentation of the Sale and Hosted Payments Page API has been read to learn what information is required before proceeding. The Recurring Billing Process is real simple and straight forward, below demonstrates the steps required in order to successfully make the request.

1. The merchant makes the initial API request while suppling the additional RB tags for the XML Document within the data parameter. Once successful, the response will contain a unique RBID. This RBID will be used to process transactions without the need of consumer card information. The RBID can be found inside the XML Document under a field called "RBID" within the response. If Generating an RBID using a Pre-Auth, the RBID will only be generated once the Pre-Auth is complete, the Generated RBID will be included in the confirmation notification sent to the merchants Notification URL from the complete pre-auth request.

1. The merchant makes a request to the DeactivateRecurringBilling API while supplying the RBID they wish to Activate / Deactivate, the response will include "0043 - Activate RecurringBilling Successful" which indicates the RBID is now Activated, the response will include "0043 - Deactivate RecurringBilling Successful" which indicates the RBID is now Deactivated.

1. The merchant makes a request to the ProcessRecurringBilling API while supplying the RBID they wish to process, the response will include "0051 - Process Recurring Billing Received" if the notification method is set to: Notification, otherwise the response will contain: "0000 - Processed Successfully" if the notification method is set to: Server or Both. Confirmation notification including the transaction result will be sent to the merchants Notification URL.

To generate the RBID on a transaction, the following data needs to be supplied with the Sale/Hosted Payments Page API call. This data must be supplied at the bottom of the XML Document that the merchant supplies within the data parameter of each request.

Available Form Data Fields

Below is a table containing the fields encapsulated inside the RB tags.

Sample XML Document

The below sample demonstrates how to generate the RBID, the below is expected when passing POST data into the data parameter on either the sale or hosted payments page API.

When forming the data parameter, please refer to our guidelines above.

<!-- Generating RBID by supplying RB fields in an API Request Demonstration -->
<R>
	<R1>...</R1>
	...
	<RB>
	   <T>M</T>
	</RB>
</R>

Data Returned

The data returned depends on the initiated API however, the data returned should include the generated RBID in a field called RBID.

Expected XML Documents

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

Please note that the RBID can be returned in the server response or can be sent to the merchants Notification URL depending on what way the merchant has their Notification Method setup.

Sample XML Response:

<!-- Sample XML Document Including The Generated RBID -->
<?xml version="1.0"?>
<R>
	<R1>...</R1>
	...
	<RBID>1342</RBID>
</R>

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. 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 = DeactivateRecurringBilling
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.

https://staging.ecomm365.com/acqapi/service.ashx?Username=SomeName&Password=SomePassword&MessageID=30dd879c-ee2f-11db-8314-0800200c9a66&APISignature=deactivaterecurringbilling&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" => "DeactivateRecurringBilling", //API Signature - Please notice the `DeactivateRecurringBilling` signature here for the DeactivateRecurringBilling 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=DeactivateRecurringBilling"; //API Signature - Please notice the `DeactivateRecurringBilling` signature here for the DeactivateRecurringBilling 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();
}

Available Form Data Fields

Below is a table containing all the available fields for passing POST data into the data parameter within the `DeactivateRecurringBilling` request.

Available Form Data Fields - Validation

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

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

<!-- Sample of RBID Activation -->
<R>
	<R1>1342</R1>
	<R2>1</R2>
</R>

Data Returned

Below are the expected XML fields returned from the merchants request if the request passes validations.

Expected XML Documents

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

The successful error codes returned within this API is identical however, the R2 field contains information to identify which response corresponds to the action specified. The R2 field is key here when trying to distinguish the responses.

Expected error code responses:

1. 0043 - Activate RecurringBilling Successful. This response indicates a successful activation of the RBID.
2. 0043 - Deactivate RecurringBilling Successful. This response indicates a successful deactivation of the RBID.

Sample XML Response (0043 - Activate RBID):

<!-- Sample XML Document -->
<R>
	<R1>0043</R1>
	<R2>Activate RecurringBilling Successful</R2>
	<R3>1342</R3>
</R>

Sample XML Response (0043 - Deactivate RBID):

<!-- Sample XML Document -->
<R>
	<R1>0043</R1>
	<R2>Deactivate RecurringBilling Successful</R2>
	<R3>1342</R3>
</R>

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. 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 = ProcessRecurringBilling
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.

https://staging.ecomm365.com/acqapi/service.ashx?Username=SomeName&Password=SomePassword&MessageID=30dd879c-ee2f-11db-8314-0800200c9a66&APISignature=processrecurringbilling&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" => "ProcessRecurringBilling", //API Signature - Please notice the `ProcessRecurringBilling` signature here for the ProcessRecurringBilling 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=ProcessRecurringBilling"; //API Signature - Please notice the `ProcessRecurringBilling` signature here for the ProcessRecurringBilling 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();
}

Available Form Data Fields

Below is a table containing all the available fields for passing POST data into the data parameter within the `ProcessRecurringBilling` request.

Available Form Data Fields - Validation

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

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

<!-- ProcessRecurringBilling Request Demonstration -->
<R>
	<R1>1342</R1>
	<R2>500</R2>
	<udf>
		<I>eCOMM</I>
		<I>435</I>
	</udf>
</R>

Data Returned

Below are the expected XML fields returned from the merchants request. The confirmation notification will be sent if the request passes validations.

Please note that if the notification method is set to Server or Both, the merchant will receive the transaction result contained inside the XML Document server response.

Notification method: Notification:

Transaction Result:

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. 0051 - Process Recurring Billing Received. Confirmation notification will be sent to the merchants Notification URL with the overall result.

Sample XML Response (0051):

<!-- Sample XML Document server response if notification method is set to notification, confirmation notification will be sent to the merchants notifican url -->
<R>
	<R1>0051</R1>
	<R2>Process Recurring Billing Received</R2>
</R> 

Sample XML Response (Transaction Result):

The below is expected to return to the merchants Notification URL if setup to do so.

<!-- Sample Confirmation Notification, XML Document -->
<?xml version="1.0"?>
<R>
	<R1>0000</R1>
	<R2>Successful</R2>
	<R3>12345</R3>
	<R4>Successful</R4>
	<R5>12345_00001</R5>
	<R6>12345_00001_RB12345_1</R8>
	<udf>
		<I>eCOMM</I>
		<I>435</I>
	</udf>
</R>