These things are far too hard

UPDATE: I have written some more information about setting up the HSBC CPI using the Java method rather than the C method outlined below.

I ran into a problem recently where a client of mine could not install the HSBC credit card payments, despite his best efforts at following the CPI specification document HSBC provided.

To cut a long(ish) story short, he ended up asking me to take a look at it. Since I managed to figure out the problem, and noticed that the HSBC documentation is somewhat lacking to say the least… (and the HSBC support staff don’t seem to know this either!) I thought I’d give something back by letting you know how to get this thing working on a Linux server. Sorry, anyone using any other type of server, I can’t help.

Right, to begin with you need to get all the files that HSBC send you. For completeness I’ve copied the text right out of the CPI Specification document below:

Linux

• Copy sample.html to a web enabled directory.
• Copy OrderHash.e to a web enabled directory with execute permissions and without “directory browse” permissions (the pages will need to be able to read from and write to a file in the local directory).
• Copy results.e to a secure (https) web enabled directory with execute permissions and without “directory browse” permissions (the pages will need to be able to read from and write to a file in the local directory).
• Add the path to libCcCpiTools.so to the LD_LIBRARY_PATH environment variable (either by suitable file location, or direct addition). It may be necessary for a merchant to speak to their host regarding suitable location / installation of this file.
• The executable sample files look for the shared secret in a file called ss.txt within the same folder.

Lets take this one step at a time.

• Copy sample.html to a web enabled directory.

Ok, why this is the first step, I don’t know, but it’s quite correct, just create a folder in your web space (or put it into the root of the website) and copy this file over. You don’t need to do anything special with this file just yet.

• Copy OrderHash.e to a web enabled directory with execute permissions and without “directory browse” permissions (the pages will need to be able to read from and write to a file in the local directory).

Ok, again, this is strange thing to ask for at the beginning of the document in my opinion, but that doesn’t matter too much. What REALLY DOES MATTER is the essential information that is missing here!!!

Copy this file into your CGI-BIN folder! I could not get this to work in any other folder, it needs to be located in your CGI-BIN (yes I know I’ve repeated myself).

Several people seem to have had problems with the CGI-BIN, I should explain, you don’t just create a folder on your server called /CGI-BIN/ you need to tell your Apache web server to use CGI scripts, instructions on this can be found here: http://httpd.apache.org/docs/1.3/howto/cgi.html – If your server already has a folder called /CGI-BIN/ then it probably already knows how to execute CGI scripts.

Then set the permissions for this file to 755

That information alone should be enough to help to figure out this (in my opinion) poorly documented system. Anyway, on with the rest:

• Copy results.e to a secure (https) web enabled directory with execute permissions and without “directory browse” permissions (the pages will need to be able to read from and write to a file in the local directory).

Again, this file must be placed in the CGI-BIN folder in your web space, and have 755 permissions.

• Add the path to libCcCpiTools.so to the LD_LIBRARY_PATH environment variable (either by suitable file location, or direct addition). It may be necessary for a merchant to speak to their host regarding suitable location / installation of this file.

What? I hear you asking. Well, don’t worry all they want you to do is ask your web host to install the libCcCpiTools.so binary file on your web hosts server … Not asking much then! anyone using a normal web host won’t be allowed to use this. Make sure your host will allow you to install this file.  The server administrator should be able to install this and setup the LD_LIBRARY_PATH for you. If they can, you can also get them to test that the libCcCpiTools.so file is working using the ‘testhash.e’ file that HSBC kindly supply. If that works, then we’re in business.

• The executable sample files look for the shared secret in a file called ss.txt within the same folder.

What? the same folder as what? What they hell are they talking about??? Well, the missing text is … within the same folder as the OrderHash.e file (your CGI-BIN, if you hadn’t figured that out.) You need to copy your shared secret into this SS.txt file.

So you think that’s it?

We’re almost there now, just some more missing information to fill you in on.

This one isn’t even covered in the CPI specification at all.

Now you have to edit the sample.html file.

Open up the sample.html using your favourite HTML editor, you should see something similar to the following:

<FORM name="cpiForm" action="http://www.yourdomain.com/cgi-bin/OrderHash.e" method="POST" onSubmit="singleSubmit(this)">
	<INPUT TYPE="submit" NAME= "submitButton" VALUE="Submit">

	<INPUT TYPE="button" NAME= "resetButton" VALUE="Reset" onClick="this.form.reset();resetDynamicFields();">

	<!-- Fill in the VALUE attribute below with the URL to the CPI. -->
	<INPUT type="hidden" name="CpiUrl" value="https://www.cpi.hsbc.com/servlet">
	<BR>
	<TABLE>
	<TR><TD>OrderId:</TD><TD><INPUT type="text" name="OrderId" value=""></TD></TR>

	<TR><TD>TimeStamp:</TD><TD><INPUT type="text" name="TimeStamp" value=""></TD></TR>
	<TR><TD> </TD></TR>

	<!-- Fill in the VALUE attribute below with the URL to the Results sample. -->

	<TR><TD>CpiReturnUrl:</TD><TD><INPUT type="text" name="CpiReturnUrl" value="https://www.yourdomain.com/cgi-bin/Results.e"></TD></TR>

Edit the bits I have highlighted in red so that they point to the files in your CGI-BIN. (Like I have done above.)

Now you’re nearly done!

Now, if you open up the sample.html file in your browser, you should be able to click submit, open OrderHash.e, click on Submit again and be taken through to the HSBC online ordering service.

OK great, but my web host won’t allow me to use exec().

If you’re on a shared server, for one thing, you’ve been lucky to get this far, most web hosts who run shared servers will not install the libCcCpiTools.so shared object. If yours did, you may not need this next bit of information. For those who do, now you’ll be starting to think to yourself, well yeah that’s great but how the hell do I customise these pages? I don’t want my customers looking at pages that say ‘Sample Order Hash Page’ (or whatever it says). So how am I meant to get a valid order hash from OrderHash.e, without sending my customers via the OrderHash.e file?

Well, now you’re expected to be able to execute the OrderHash.e file. Nice System …

Excuse me HSBC, but most shared hosts don’t allow me execute random binary files on their server …

I run a small shared hosting server with a colleague, for security reasons (good reasons) we don’t allow use of the PHP exec() function, it’s simply too dangerous

So when I was asked to find a way around this using PHP on my server without using the exec() function, at first I was stumped. But here’s how I got around the issue (there is possibly another way using curl, but I don’t know it, so this was my solution …)

PHP Code:

$postdata = array2String($_POST);

$fp = fsockopen("www.yourdomain.com", 80);

if (!$fp)
{
	echo "Couldn't open the connection to OrderHash.e file";
}
else
{
	/***************************
	|lets build our post request
	***************************/
	$out = "POST /cgi-bin/OrderHash.e HTTP/1.1\r\n";
	$out .= "Host: www.yourdomain.com\r\n";
	$out .= "Accept:text/xml,application/xml,application/zhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5\r\n";
	$out .= "Accept-Language: en\r\n";
	$out .= "Accept-Encoding: gzip,deflate\r\n";
	$out .= "Accept-Charset:ISO-8859-1,utf-8;q=0.7,*;q=0.7\r\n";
	$out .= "Keep-Alive: 300\r\n";
	//$out .= "Referer: http://www.yourdomain.com/hsbc/sample.html\r\n";
	$out .= "Content-Type:application/x-www-form-urlencoded\r\n";
	$out .= "Content-Length: ". strlen($postdata) ."\r\n";
	$out .= "Connection: close\r\n\r\n";
	$out .= $postdata;

	/*****************************
	|This passes our POST headers
	|to the OrderHash.e form
	*****************************/
	fwrite($fp, $out);
	...

			

Here is a copy of the full PHP script.

All credit to Ed Fowler, who ran up against the same problem as I did and came up with this version using Perl. It’s based on the same concept as my PHP script, and has the same pre-requisite (that you can generate a valid order hash). But I’m pleased to be able to offer the Perl version as well (Thanks Ed!) full Perl script

Why not take a look at Eds site: www.abodeHIP.co.uk

---

Ok, I’ve noticed that some of you who’ve emailed me have had problems understanding the array2String() function that I’ve mentioned in the code above. I probably should have added this in when I first wrote this page. What this function does is take all the post variables and concatenate them into a string. POST requests (if you could see them (which you can using LiveHTTPHeaders)) look exactly like GET requests. So if you just turn your $_POST array into a URL safe string, that is what we pass within our HTTP header to the OrderHash.e file.

Our variable $postdata should contain a string looking something like this (cut down) version:

CpiUrl=https%3A%2F%2Fwww.cpi.hsbc.com%2Fservlet&OrderId=123456789&TimeStamp=123456789&CpiReturnUrl=https%3A%2F%2Fwww.yourdomain.com%2Fthanks.php&CpiDirectResultUrl=https%3A%2F%2Fwww.yourdomain.com%2Fcgi-bin%2FResults.e&StorefrontId=UK123456789GBP&

I’ve also been asked “what next?”, well $fp can be treated like a file and read back into your script, if you read it into a string you will have an exact copy of the HTML output of the OrderHash.e file to play with, all you need to do then is strip out the stuff you don’t want and output the stuff you do. Hope that helps.

Other sources of helpful stuff to look at

• This doesn’t relate to anything I have written, but someone might find this useful. a tiny Php Module that sits between the HSBC library for generating Order Hash Codes, and PHP.
• CPI support telephone number: 08456 022880
• If you don’t already have a CGI-BIN or your server isn’t processing the OrderHash.e as an executable, you probably need to set Apache up to use CGI scripts, instructions on this can be found here:http://httpd.apache.org/docs/1.3/howto/cgi.html
• I haven’t tried this, but you might be able to execute the OrderHash.e file using the PHP backtick operator -> ` (look up how to do this)

You can see roughly what I did; open a connection to the OrderHash.e file in the CGI-Bin & send it some POST data via HTTP headers using my fsockopen() connection. Then I retrieve the result, which contains a valid order hash. Then I can do whatever I want with the returned result, which contains, among other things my valid Order Hash

_{In order to use this code, you need to have already got your libCcCpiTools.so file installed and have CGI and PHP scripting working. If you do already have the libCcCpiTools.so file installed and a working cgi-bin and PHP, then you should only need my code to get the project finished. You should be able to slot it into any html/css layout with relative ease.}

Disclaimer

I never said this would definitely work for you, I’m just trying to help. This worked for me, using my server, hopefully it’ll work for you, but I’m in no way responsible if you mess up your server or your website. I don’t work for HSBC, and don’t have any knowledge of their systems. I have reproduced their documents in this file, and am making their CPI specification document freely available. I’m not sure if that’s ok, but it remains HSBC’s property and if they want me to take it off this site, then please email me before you sue me.
Chris Cook