Http Services REST API

The Http Services REST API is designed to be as flexible and easy to use as possible - it will accept either GET or POST parameters; and will return the result as either Query String (the default), XML or JSON.

Input parameter documentation can be found by visiting the service API endpoint in your browser without any parameters. For example:

https://connectpayadmin.co.uk/Services/SmartPos2/Http/Echo.ashx

You can use standard HTTP POST or GET for input parameters.

All services require a "Function" input parameter, which tells the service which method to call on the service - e.g. "GET", "ADD", or "UPDATE".

All services return a "Result" parameter, which will be set to "OK" if the call was successful, or else an error message.

Other parameters will be returned as either Query String (the default), XML or JSON data, according to the "Format" input parameter.

⚠️ Under some circumstances Http Services calls can trip the security on our firewall. If you are getting a security error with an 'Attack ID' returned by the services, you may need to spoof the User Agent in your web request.

Parameters

Dates

In addition to literal dates, you can pass:

• "D" for the current date
• "D+X" for the current date, plus "x" days
• "T" for the current time
• "T+X" for the current time, plus "x" hours

Booleans

You can pass either "T"/ "F" (true/ false) or "Y"/ "N" (yes/ no)

Enums

You can pass the string or numeric value

C# Example

This example uses the dummy "Echo" service.

using (var client = new System.Net.WebClient())
{
	// Service URL
	var service = "https://connectpayadmin.co.uk/Services/SmartPos2/Http/Echo.ashx";
	// Build "ECHO" Call
	client.QueryString["Function"] = "ECHO";
	client.QueryString["Account"] = "DEMO99";
	client.QueryString["User"] = "demo";
	client.QueryString["Password"] = "user";
	client.QueryString["Input"] = "Hello World";
	// Call Service
	var result = System.Web.HttpUtility.ParseQueryString(client.DownloadString(service));
	// Check Result
	if (result["Result"] != "OK")
	{
		// If Not 'OK' Will Be Error Message
		throw new ApplicationException(result["Result"]);
	}
	Console.WriteLine(result["Output"]);
}

PHP Example

This example uses the dummy "Echo" service.

$service = 'https://connectpayadmin.co.uk/Services/SmartPos2/Http/Echo.ashx?';
// Build "ECHO" Call
$data = array(
	'Function' =˃ 'ECHO',
	'Format' =˃ 'JSON', 
	'Account' =˃ 'DEMO99',
	'User' =˃ 'demo',
	'Password' =˃ 'user',
	'Input' =˃ 'Hello World');
// Call Service
$result = json_decode(file_get_contents($service . http_build_query($data)));
// Check Result
if($result-˃Result !== 'OK')
{
	// If Not 'OK' Will Be Error Message
	throw new Exception($result-˃Result);
}
echo($result-˃Output);

Signing

Where a signature is required, it is created by SHA256 hashing all parameters with an appended Pre-Shared Key.

You should hash just the parameter VALUES, except where you are posting an XML or JSON document, where you should hash the entire posted document - see below for an example of posting a JSON document in C#.

This C# function signs the query string parameter values of a .NET WebClient, as used in the example above.

using System.Security.Cryptography;
using System.Text;

// Usage: Sign(client)
private static void Sign(System.Net.WebClient client)
{
	var sb = new StringBuilder();
	foreach (var key in client.QueryString.AllKeys)
	{
		sb.Append(client.QueryString[key]);
	}
	// Store the key in your config file!
	sb.Append("PRE-SHARED-KEY");
	using (var sha = new SHA256CryptoServiceProvider())
	{
		client.QueryString["Signature"] = 
			Convert.ToBase64String(sha.ComputeHash(Encoding.UTF8.GetBytes(sb.ToString())));
	}
}

This PHP code signs an array, as used in the example above.

// Usage: Sign($data)
function Sign(& $data)
{
	$s = '';
	foreach($data as $v)
	{
		$s .= $v;
	}
	// Store the key in your config file!
	$s .= "PRE-SHARED-KEY";
	$data['Signature'] = base64_encode(hash("SHA256", $s, true));
}

Parameter Formats

Normally, we'd recommend using a standard HTTP GET Query String to send parameters to the service, as shown in the examples above. (Why? Because it is generally just easier, and simplicity is your friend!!)

However, you can also POST data using one of the following formats:

1) Form

Standard "URL Encoded" HTML form.

2) XML

Content Type = "text/xml"

˂Request˃
	˂User˃demo˂/User˃
	˂Password˃user˂/Password˃
	˂Function˃ECHO˂/Function˃ 
	˂Format˃XML˂/Format˃
	˂Input˃Hello World˂/Input˃
˂/Request˃

3) JSON

Content Type = "application/json"

{  
   "User":"demo",
   "Password":"user",
   "Function":"ECHO",
   "Format":"JSON",
   "Input":"Hello World"
}

NB - When using XML or JSON, the Signature should be appended to the Query String ("&Signature=XXX") as the signature of the POST body + the Pre-Shared Key.

C# JSON Call Wrapper With Signing

// Requires Newtonsoft.Json (via NuGet)
var service = "https://connectpayadmin.co.uk/services/smartpos2/http/Echo.ashx";
string json = @"{
				""Account"": ""DEMO66"",
				""User"": ""demo"",
				""Password"": ""user"",
				""Function"": ""ECHO"",
				""Input"": ""Hello World""
				}";
var psk = "XXXXXXXXXX";
var result = GetObject(service, json, psk);
Console.WriteLine(result.Output.ToString());

private static dynamic GetObject(string service, string json, string psk)
{
	using (var client = new WebClient())
	{
		client.Headers[HttpRequestHeader.ContentType] = "application/json";
		using (var sha = new System.Security.Cryptography.SHA256CryptoServiceProvider())
		{
			client.QueryString["Format"] = "JSON";
			client.QueryString["Signature"] = 
				Convert.ToBase64String(sha.ComputeHash(Encoding.UTF8.GetBytes(json + psk)));
		}
        dynamic result = JsonConvert.DeserializeObject(client.UploadString(service, json));
        if((string)result.Result != "OK")
        {
            throw new ApplicationException((string)result.Result);
        }
        return result;
	}
}