SmartPay > API

SmartPay implements an Http Services (REST) API, which is designed to be simple and flexible.

The Http Services API is widely compatible with almost any language or environment, and can be called using a standard query-string, json or xml.

For general information on using the Http Services API, including examples in C# and PHP, see here.

Each customer has their own implementation, which can be customised to meet their needs. A typical implementation example can be viewed here.

Security

All SmartPay Http Services API calls are validated with a User Name and Password, and signed with a Pre-Shared Key (sometimes known as a "shared secret") using SHA256 - a cryptographic hash function developed by the United States National Security Agency. This means the Http Services API is highly secure.

Getting Started - 3 Steps

👍 DO NOT IGNORE THIS BIT - IT WILL MAKE YOUR LIFE MUCH EASIER LATER ON!

We need to create two 'helper' functions to use later; and we will then make a call to the test 'ECHO' function.

1. Signing Helper

Your first job is to create a helper function to 'sign' your requests. This just creates an SHA256 hash of whatever string you pass.

VB.NET

Function Sign(ByVal json) As String
    Dim sha256 As SHA256 = SHA256Managed.Create()
    Dim bytes As Byte() = Encoding.UTF8.GetBytes(json)
    Return Convert.ToBase64String(sha256.ComputeHash(bytes))
End Function

PHP

function Sign($json)
{
	return base64_encode(hash("SHA256", $json, true));
}

To test your implementation, verify that the text "PASSWORD" (upper case, without the quote marks) produces the following (Base64 Encoded) hash:

C+ZK6J3dJOIlQ03pXVAXETObru4Y8Am6m0NpryfTDWA=

2. Posting Helper

Your next job is to create another helper function, to 'post' the document to the service endpoint.

Note that we are doing a number of things here:

1. Setting the Content Type HTTP Header to application/json - this tells the system that the incoming data is JSON.
2. Appending Format=JSON to the URL - this tells the system to return JSON.
3. Signing the json and appending the signature to the URL - all the other data is in the JSON 'body'.

💡 You may want to later extend this function to parse the response and check the value of 'Result' (it should be 'OK'), so you don't have to do this on every call!

VB.NET

Const PSK As String = "YOUR_PSK_GOES_HERE"

Function Request(url As String, json As String) As String
    Dim client = New WebClient()
    client.Headers(HttpRequestHeader.ContentType) = "application/json"
    Dim sig = Sign(json + PSK)
    Return client.UploadString(url + "?Format=JSON&Signature=" + sig, json)
End Function

PHP

$PSK = "YOUR_PSK_GOES_HERE";
function Request($url, $json) 
{
	$sig = sign($jsonString . $PSK);
	$options = array('http' =˃
		array(
			'method'  =˃ 'POST',
			'header'  =˃ 'Content-Type: application/json',
			'content' =˃ $json));
	$url = $url . "?Format=JSON&Signature=" . $sig;
	$context  = stream_context_create($options);
	return file_get_contents($url, false, $context);
}

3. Echo Test

We will now make a call to the test 'ECHO' service. This is a very simple service which we use to verify that we can connect ok and get a response.

We do this because it is much easier to fix 'plumbing' problems now, rather than when we are trying to make the more complex 'real' calls later!

(Don't forget to replace the "dummy" values in the BASE_URL, USER and PASSWROD constants!)

VB.NET

Const BASE_URL As String = "https://apps.adelante.co.uk/SmartPay/MY_SITE/Pay4/Services/Http/"
Const USER As String = "SERVICE_USER_EMAIL_ADDRESS"
Const PASSWORD As String = "PASSWORD"

Dim url As String = BASE_URL + "Echo.ashx"
Dim json As String = "
	{
    	'Function': 'ECHO',
    	'User': '" & USER & "',
    	'Password': '" & PASSWORD & "',
    	'Input': 'HELLO WORLD'
	}"
Console.WriteLine(Request(url, json))

PHP

$BASE_URL = "https://apps.adelante.co.uk/SmartPay/MY_SITE/Pay4/Services/Http/";
$USER = "SERVICE_USER_EMAIL_ADDRESS";
$PASSWORD = "PASSWORD";
$url = $BASE_URL . 'Echo.ashx';

$data = array(
	'Function' =˃ 'ECHO',
	'User' =˃ $USER,
	'Password' =˃ $PASSWORD,
	'Input' =˃ 'Hello World',
	);
$json = json_encode($data);

echo Request($url, $json);

Examples

NB - All amounts are in UNITS - i.e. PENNIES!

Adding a Payment

The most common use of the SmartPay API is to add a payment. Because payments can be multi-line, they must be POSTed using json or xml - for example:

{
	"UID":"60CB3C01F0E44B44",
	"Lines":[
		{
			"FundCode":"CT",
			"Ref1":"CT1001",
			"Amount":"1001"
		},
		{
			"FundCode":"CT",
			"Ref1":"CT1002",
			"Amount":"1002"
		}
	]
}

Or using xml:

˂Payment˃
	˂UID˃60CB3C01F0E44B44˂/UID˃
	˂Lines˃
		˂Line˃
			˂FundCode˃CT˂/FundCode˃
			˂Ref1˃CT1001˂/Ref1˃
			˂Amount˃1001˂/Amount˃
		˂/Line˃
		˂Line˃
			˂FundCode˃FundCode˂/FundCode˃
			˂Ref1˃CT1002˂/Ref1˃
			˂Amount˃1002˂/Amount˃
		˂/Line˃
	˂/Lines˃
˂/Payment˃

Getting a Payment

Because payments can be multi-line, they must be requested using json or xml - for example:

Payment.ashx?User=service%40example.com&Password=XXX&Function=GET&UID=60CB3C01F0E44B44&Signature=XXX&Format=JSON

Returning:

{
	"PaymentID":"1",
	"UID":"60CB3C01F0E44B44",
	"PaymentReference":"",
	"Lines":[
		{
			"Ref1":"CT1001",
			"Ref2":"",
			"Ref3":"",
			"Ref4":"",
			"FundCode":"CT",
			"Amount":"1001"
		},
		{
			"Ref1":"CT1002",
			"Ref2":"",
			"Ref3":"",
			"Ref4":"",
			"FundCode":"CT",
			"Amount":"1002"
		}
	],
	"Result":"OK"
}