And it didn’t break a little bit, it broke a lot, to the point where we couldn’t get it working again, well, we probably could have, but since that would have meant un-installing the updates we have just installed, and that basically meant making our server less secure than it might have otherwise been, we decided to abandon the C version of the HSBC CPI installation and try something else. Not an easy decision considering how hard this was to set up in the first place, but now it’s working again it was absolutely definitely the right decision.

So, in the spirit of helpfulness, I’m going to tell you how we got this up and running again using a different method.

We (my business partner James and I) are 90% certain that an update to the GCC library on our Linux server was responsible for breaking the LibcCpiTools.so implementation of the HSBC CPI system.

The Java Implementation

After deciding that the GCC update we ran was the most likely candidate for breaking this system, we decided to try using Java.

Thankfully, I have some experience programming Java, and I think if it wasn’t for that I would have completely given up on this whole HSBC integration thing.  You’re not going to need to know anything about Java programming in order to get this up and running though so don’t worry.

What you’ll need

You are going to need a few things before you get started:

1. Your shared secret (as supplied by the HSBC)
2. A unique IP address (so you can use an SSL certificate for your domain)
3. An SSL certificate
4. A web hosting package with PHP enabled
5. The facility to use a Java server on your web hosting package (like Apache Tomcat)
6. WinRAR or WinZip (Mac users try Zipeg)
7. A .war file of the Java files supplied by the HSBC – this is a package of Java files, stored almost like a .zip file. (Don’t worry too much, I’ve got one I made earlier you can download later)
8. The scripts from my previous post regarding the HSBC CPI system.

Setting It Up

Web Hosting

You’ll need a hosting package with PHP enabled, a unique IP address, the facility to install SSL certificates and the facility to use a Java server (like Apache Tomcat).

Apache Tomcat

I can’t really tell you how to install this or get it working, unfortunately I had to rely on my colleague James setting this up for me, however I’m sure you’ll find everything you need on the Apache Tomcat website.

SSL Certificate

You’ll need a unique IP address for your SSL certificate, then ask your web hosting company for an SSL certificate. If they can’t supply you with one, you can get them from businesses like Thawte, Verisign or Globalsign. You’ll need to get it installed on your web server so you can serve pages over a secure socket (https://)

OrderHash.war

Once you’ve got everything else set up, you’ll need to download my OrderHash.war – this is simply the Java files supplied by the HSBC but packaged into a .war file. If you’re on Windows use WinRAR to browse the .war file (Mac users use Zipeg) You’ll be able to browse the folder structure, which should look something like this:

Putting it all together

You need to upload your new .war file into your Java server, the process may differ with different Java Servers, but with Tomcat and the Plesk web hosting control panel, it’s as simple as uploading the OrderHash.war file into Plesk.

Now you’re ready to go!

Try uploading the sample.html file supplied by the HSBC but changing the action of the form to point to the new Java Server Page:

<form name="cpiForm" action="http://www.example.com:9080/OrderHash/OrderHash.jsp" method="POST" onSubmit="singleSubmit(this)">

With luck you’ll be able to generate a valid Order Hash! Now, as before, the actual OrderHash generator creates some pretty ugly HTML, and you wouldn’t want your clients looking at it, but you can use the PHP files I wrote in my previous post on this subject to “wrap” the horrible HSBC pages in your own code.

Enjoy!

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

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