Hi All,
Okay I have stripped out all the project specific code and created a project taht illustrates how to use the classes.
There has been a slight divergence in how it works comared to how I explained in my previous post. This has come about by my attempts to simplify the code a bit more to aid understanding.
Basically a quick summary of how things now work.
On the page that creates and submits the order for 3D secure verification:
1. Create an object of type Order, set its members (amoutInPence, orderDescription).
2. Create an object of type PaymentDetails and set its memebers
3. Assign the payment details to the order by setting the Order.paymentDetails member to your 'PaymentDetails' instance
4. Persit your order to a database by calling the persistToDatabase method on the order object
5. Encrypt and persist the payment details to the database by calling the 'serializeEncryptAndStorePaymentDetails' method on the order object
6. Get the HTML to create the PAS form by calling the 'renderPASForm' method of your order object
7. Render that form to the page (using Response.Write or setting the .Text value of a literal control).
You then need a page that will handle the reponse that the 3D secure site will return when the user is returned to your site. I have called this pasReponseHandler, in this page you need to:
8. Create an object of type PASInformation and set its members to the values returned by the PAS service
9. Retrieve your order from your database by calling the 'retrieveOrderFromDatabase' method on the order class
10. Retrieve the orders payment details from the database by calling the 'decryptAndDeserializePaymentDetails' method on your order object
11. get an instance of an hsbcRequest object by calling the 'createPaymentRequest' method of the order object
12. submit this request to HSBC by calling the 'submitForPayment' method of this hsbcRequest instance. This method will return an hsbcResponse object
13. Check the status of the hsbcResponse instance by examining it's members (in particular 'TransactionStatus') and then process your order according to whether the payment was accepted or not.
Hopefully the code and comments should explain it all but please let me know if you have any problems. I haven't tested this code live against HSBC as I haven't got a test account (and won't use our clients!). The code should be fine though.
You can download it from here
If you find it useful then I have added a 'donate' paypal button to this blog and any donation, no matter how small, would be appreciated to keep me in beer!
Thursday, 9 April 2009
Monday, 6 April 2009
.NET HSBC API PAS integration
Hi All,
Sorry I haven't blogged for months, i have been snowed under with exciting projects at work. I have had a few emails asking for the PAS examples I promised so long ago.
Well, it has been a while since I wrote the code and it is embedded into quite a sucesful project, however i have extracted the salient points herewhich shouldhelp illustrate how i integrate with the PAS system provided by HSBC.
Okay, first a quick over view of how the PAS process works (which I think is a daft way for reasons that will become clear).
First you collect all the customers payment details (i do this by instantiating an object of type Order and setting the various properties, one of which is of type PaymentDetails).
Then, we have to render a form to the users browser to submit the payment details off to the PAS server, for this I have a method called renderPASForm (which takes an Order object as an argument and returns a string containing the html form to be rendered to theclients browser).
The user then submits this form (or we do it on thier behalf using some clientside javascript) and goes of to the 3d secure site. Once they finish there, they are redirected back to your site to a page that needs to handle the PAS response.
Now the real gotcha is that before we sent the user off to the PAS site we needed to persist the order somewhere, as all we get back from the PAS service is the relevant PAS info and not all of our order information. So, before we can submit the actual order for processing by the HSBC api we must first retrieve it from whereever we persited it to, add in the additional PAS data we got back from the PAS server and pop it all into an XML object that we can then POST to the HSBC gateway.
Still following? good.
Now at this point i am sure you will agree that having to send the user off to the 3d secure site AFTER we have collected thier payment details is bad because it means we have to PERSIST THIER PAYMENT DETAILS, which goes against the best security practices and puts you into a whole different category when it comes to PCI-DSS compliance.
Okay, so anyway, from a programming perspective what I have is this;
A class 'Order' which holds details of what a customer has ordered (line items, quantities, cost etc) and also holds the customers payment details by means of a member of type 'PaymentDetails', it also has a member of type 'PASInformation'to store the information we recieve from the pas server.
I then have a class 'PaymentSystem' which has some members to hold all the config info (hsbcClientAlias, hsbcPASEndPointUrl, pasResponseHandlerUrl), and 2 methods; 'getPASFormHtml' and 'submitOrderForPayment', both of which take an object of type 'redr' as args.
The method getPASFormHtml returns an HTML string containing the PAS submission form as metioned above. The method submitOrderForPayment makes use of the 'hsbcApiRequest' and 'hsbcApiResponse' classes detailed in my previous posts but now augmented to use the PASInformation memen-ber of the Order class to set the relevant XML elements in the HSBC XML request.
Stringing it all together in a web-app therefore simply requires you to do the following:
Have a page that collects the order details and payment details.
Create an object of type order and set these details in it.
Call the static 'persistOrder' method of the Order class passing it your Order object.
Call the static method 'getPASFormHtml' of the PaymentSystem class passing it your Order object and Response.Write the resulting string (or use an asp:literal control to output the form to the page).
Create a PAS Response handler aspx page and in the onload of this retrieve your order (using the factory method retrieveOrder of the Order class).
Populate the properties of the PASDetails member of the order class with the values from the PAS Service site (i.e. via the Request.Form object).
Call the static method 'submitOrderForPayment' of the PaymentSystem class passing it your order object.
You can then use the order object as you see fit to alert you to the statusof theorder (e.g. generate an email, or display feedback to the user on the success or failure of thier payment).
I hope this helps someone with thier integartion. I will just tidy up the code and strip it downto the essentials (leaving out bits specific to my project) and post it here tomorrow. If for any reasonI forget, please feel free to bug me at ssu96ld at live dot co dot uk.
Cheers,
Lee.
Sorry I haven't blogged for months, i have been snowed under with exciting projects at work. I have had a few emails asking for the PAS examples I promised so long ago.
Well, it has been a while since I wrote the code and it is embedded into quite a sucesful project, however i have extracted the salient points herewhich shouldhelp illustrate how i integrate with the PAS system provided by HSBC.
Okay, first a quick over view of how the PAS process works (which I think is a daft way for reasons that will become clear).
First you collect all the customers payment details (i do this by instantiating an object of type Order and setting the various properties, one of which is of type PaymentDetails).
Then, we have to render a form to the users browser to submit the payment details off to the PAS server, for this I have a method called renderPASForm (which takes an Order object as an argument and returns a string containing the html form to be rendered to theclients browser).
The user then submits this form (or we do it on thier behalf using some clientside javascript) and goes of to the 3d secure site. Once they finish there, they are redirected back to your site to a page that needs to handle the PAS response.
Now the real gotcha is that before we sent the user off to the PAS site we needed to persist the order somewhere, as all we get back from the PAS service is the relevant PAS info and not all of our order information. So, before we can submit the actual order for processing by the HSBC api we must first retrieve it from whereever we persited it to, add in the additional PAS data we got back from the PAS server and pop it all into an XML object that we can then POST to the HSBC gateway.
Still following? good.
Now at this point i am sure you will agree that having to send the user off to the 3d secure site AFTER we have collected thier payment details is bad because it means we have to PERSIST THIER PAYMENT DETAILS, which goes against the best security practices and puts you into a whole different category when it comes to PCI-DSS compliance.
Okay, so anyway, from a programming perspective what I have is this;
A class 'Order' which holds details of what a customer has ordered (line items, quantities, cost etc) and also holds the customers payment details by means of a member of type 'PaymentDetails', it also has a member of type 'PASInformation'to store the information we recieve from the pas server.
I then have a class 'PaymentSystem' which has some members to hold all the config info (hsbcClientAlias, hsbcPASEndPointUrl, pasResponseHandlerUrl), and 2 methods; 'getPASFormHtml' and 'submitOrderForPayment', both of which take an object of type 'redr' as args.
The method getPASFormHtml returns an HTML string containing the PAS submission form as metioned above. The method submitOrderForPayment makes use of the 'hsbcApiRequest' and 'hsbcApiResponse' classes detailed in my previous posts but now augmented to use the PASInformation memen-ber of the Order class to set the relevant XML elements in the HSBC XML request.
Stringing it all together in a web-app therefore simply requires you to do the following:
Have a page that collects the order details and payment details.
Create an object of type order and set these details in it.
Call the static 'persistOrder' method of the Order class passing it your Order object.
Call the static method 'getPASFormHtml' of the PaymentSystem class passing it your Order object and Response.Write the resulting string (or use an asp:literal control to output the form to the page).
Create a PAS Response handler aspx page and in the onload of this retrieve your order (using the factory method retrieveOrder of the Order class).
Populate the properties of the PASDetails member of the order class with the values from the PAS Service site (i.e. via the Request.Form object).
Call the static method 'submitOrderForPayment' of the PaymentSystem class passing it your order object.
You can then use the order object as you see fit to alert you to the statusof theorder (e.g. generate an email, or display feedback to the user on the success or failure of thier payment).
I hope this helps someone with thier integartion. I will just tidy up the code and strip it downto the essentials (leaving out bits specific to my project) and post it here tomorrow. If for any reasonI forget, please feel free to bug me at ssu96ld at live dot co dot uk.
Cheers,
Lee.
Monday, 9 June 2008
HSBC XML API c# classes for .NET
As per my last post I have now made a general version of my HSBC XML API c# classes for .NET that I had developed as part of a larger project. I have simplified things to just 2 C# classes. This stripped down version should be able to be used as a jumping off point for using the HSBC XML API from any of the .NET lanaguages.
As you will see if you download the ZIP, I have incldued a sample ASP.NET page to show how the classes are to be used. Basically the solution uses a template XML file that contains elements for the key data fields required by the HSBC XML API. The classes I have created use this template to create an in memory XML document, populate the appropriate elements with the values you set and then submit the lot for processing (via the HSBC gateway).
The process is rather straight forward but I thought I would just outline the steps required here.
First off create an instance of the hsbcRequest class:
hsbcRequest req = new hsbcRequest();
This object has a number of publicly accessible properties that you can set which correspond to the data fields HSBC requires to process a transaction. Set each of these as required, e.g. :
req.orderID = "TESTORDER1";
req.paymentCardCode = 123;
req.paymentCardExpiryMonth = 10;
req.paymentCardExpiryYear = 08;
req.paymentCardHoldersName = "MR T E STING";
req.paymentCardNumber = "123456789";
// etc ....
Once you have set all of these and are ready to submit the request to the HSBC XML gateway you simply call the 'submitForPayment' which will submit the request and return an object of type 'hsbcResponse'
hsbcResponse res = req.submitForPayment();
this object liekwise has a number of properties corresponding to data sent back by HSBC in it's response, the most important of whcih is the 'TransactionStatus' whose possible values you will find defined in the HSBC documentation (e.g. 'A' for approved, 'F' for fraud, etc.).
string result = res.TransactionStatus;
Other than that the source code should be e self explanatory.
You can download a ZIP archive of the files here
As you will see if you download the ZIP, I have incldued a sample ASP.NET page to show how the classes are to be used. Basically the solution uses a template XML file that contains elements for the key data fields required by the HSBC XML API. The classes I have created use this template to create an in memory XML document, populate the appropriate elements with the values you set and then submit the lot for processing (via the HSBC gateway).
The process is rather straight forward but I thought I would just outline the steps required here.
First off create an instance of the hsbcRequest class:
hsbcRequest req = new hsbcRequest();
This object has a number of publicly accessible properties that you can set which correspond to the data fields HSBC requires to process a transaction. Set each of these as required, e.g. :
req.orderID = "TESTORDER1";
req.paymentCardCode = 123;
req.paymentCardExpiryMonth = 10;
req.paymentCardExpiryYear = 08;
req.paymentCardHoldersName = "MR T E STING";
req.paymentCardNumber = "123456789";
// etc ....
Once you have set all of these and are ready to submit the request to the HSBC XML gateway you simply call the 'submitForPayment' which will submit the request and return an object of type 'hsbcResponse'
hsbcResponse res = req.submitForPayment();
this object liekwise has a number of properties corresponding to data sent back by HSBC in it's response, the most important of whcih is the 'TransactionStatus' whose possible values you will find defined in the HSBC documentation (e.g. 'A' for approved, 'F' for fraud, etc.).
string result = res.TransactionStatus;
Other than that the source code should be e self explanatory.
You can download a ZIP archive of the files here
Wednesday, 5 March 2008
E Commerce, WSE and the HSBC API on .NET using C#
It has been a fair few months since my last post and so I thought i'd better pop something up here.
I have recently been working on an e-commerce site and I have been using microsofts web services extensions to implement message level security on the communications between the webapplication and a remote web service. Setting up the WSE policies is extreemly straight forward and I have been pleasantly surprised.
What was less simple was reading the documentation supplied by HSBC for thier XML API. There are no decent example messages shown and the XML messages that you are required to post to thier payment geteway do not even have a schema against which you can validate before submitting them. This is particular has caused a lot of time to be wastes as if you submit a message that does not conform to thier (rather complex) document structure, you do not get any helpful error message back, rather you simply get no response from thier server at all!
If anybody else needs to work with the HSBC payment XML API, I would be happy to supply some C# classes that I use to abstract away all the nastiness. (Please see my later post entitled HSBC XML API c# classes for .NET that contains these files for you)
On another subject I have also been working on a tool to allow a client to plot Polylines on Google Maps. I was surprised that I could not find a robust enough tool available on the web already. Most examples do not allow forcomplex editing of existing lines (such as chopping sections out of the middle of a line, etc). Anyway I have almost completed this work and may make a public version available if anyone is interested.
I have recently been working on an e-commerce site and I have been using microsofts web services extensions to implement message level security on the communications between the webapplication and a remote web service. Setting up the WSE policies is extreemly straight forward and I have been pleasantly surprised.
What was less simple was reading the documentation supplied by HSBC for thier XML API. There are no decent example messages shown and the XML messages that you are required to post to thier payment geteway do not even have a schema against which you can validate before submitting them. This is particular has caused a lot of time to be wastes as if you submit a message that does not conform to thier (rather complex) document structure, you do not get any helpful error message back, rather you simply get no response from thier server at all!
If anybody else needs to work with the HSBC payment XML API, I would be happy to supply some C# classes that I use to abstract away all the nastiness. (Please see my later post entitled HSBC XML API c# classes for .NET that contains these files for you)
On another subject I have also been working on a tool to allow a client to plot Polylines on Google Maps. I was surprised that I could not find a robust enough tool available on the web already. Most examples do not allow forcomplex editing of existing lines (such as chopping sections out of the middle of a line, etc). Anyway I have almost completed this work and may make a public version available if anyone is interested.
Friday, 14 December 2007
Using Jena in C# .NET
I have just realsied that I hadn't actually posted the link to my files in my previous post on using the Jena RDF library in .NET. I have now updated the article and the link to the files (in a single zip) is now there!
If you can't be bothered to find the original post here is the link again:
Files and example for using the Jena RDF library in .NET
If you can't be bothered to find the original post here is the link again:
Files and example for using the Jena RDF library in .NET
Monday, 10 December 2007
RDF METADATA GENERATION - MSc Dissertation
Below is the abstract of my 2006 dissertation as well as a link to the full PDF. Basically this was my first project aiming to apply a graph-centric to RDF models in order to glean additional information from them. This project presents an algorithm for comparing resources based on attribute similarities and use measures of such similarities to order all resource and object veritices in an RDF model. Such ordering of verticies allows for values of RDF properties to be ranked relative to a given Object and thus allow us to predict property values for said object.
Link to full version: RDF Metadata Generation Dissertation Project
IDENTIFICATION, GENERATION AND PROPAGATION OF
RDF METADATA ACROSS ONLINE RESOURCES
Abstract - The Semantic Web project being advanced by the World Wide Web Consortium aims to augment the existing World Wide Web in order to make available resources more easily understandable by machines or computer programs. The Semantic Web as a concept relies upon meaningful, machine comprehensible, metadata being assigned to the large volumes of resources available on the web. The Resource Description Framework (RDF) has been developed to enable such metadata to be represented in the form of predicate relations between resources.
The present World Wide Web contains a vast quantity of information in the form of electronic documents and files, ranging from semi-structured markup documents to various encoded image, sound and video files. In order that such existing resources may be included in the semantic web project a requirement exists for practical autonomous and semi-autonomous methods to be developed for the generation of metadata for such existing resources.
The Resource Description Framework’s data model is an inherently graph based structure, linking subject and object resources via resource predicates. This project explores a method of predicting metadata property values that exploits the graph structure of the RDF model to rank known property values relative to a given unseen resource. The method proposed and allows RDF models that assert known metadata statements about a collection of resources, to be
used to predict property values for unknown resources.
The outcome of this project is the implementation of a suite of Java classes that can be used to predict metadata property values for resources given any suitable RDF data model describing similar resources. A Java application was developed that demonstrates the use of the implemented classes to predict keyword values and category classification of resources based upon an sample RDF model describing 100 image files available on the Web. The results of this project show that graph centric approaches to metadata value prediction can be successfully applied to the wider problem of automatic RDF metadata generation.
Link to full version: RDF Metadata Generation Dissertation Project
IDENTIFICATION, GENERATION AND PROPAGATION OF
RDF METADATA ACROSS ONLINE RESOURCES
Abstract - The Semantic Web project being advanced by the World Wide Web Consortium aims to augment the existing World Wide Web in order to make available resources more easily understandable by machines or computer programs. The Semantic Web as a concept relies upon meaningful, machine comprehensible, metadata being assigned to the large volumes of resources available on the web. The Resource Description Framework (RDF) has been developed to enable such metadata to be represented in the form of predicate relations between resources.
The present World Wide Web contains a vast quantity of information in the form of electronic documents and files, ranging from semi-structured markup documents to various encoded image, sound and video files. In order that such existing resources may be included in the semantic web project a requirement exists for practical autonomous and semi-autonomous methods to be developed for the generation of metadata for such existing resources.
The Resource Description Framework’s data model is an inherently graph based structure, linking subject and object resources via resource predicates. This project explores a method of predicting metadata property values that exploits the graph structure of the RDF model to rank known property values relative to a given unseen resource. The method proposed and allows RDF models that assert known metadata statements about a collection of resources, to be
used to predict property values for unknown resources.
The outcome of this project is the implementation of a suite of Java classes that can be used to predict metadata property values for resources given any suitable RDF data model describing similar resources. A Java application was developed that demonstrates the use of the implemented classes to predict keyword values and category classification of resources based upon an sample RDF model describing 100 image files available on the Web. The results of this project show that graph centric approaches to metadata value prediction can be successfully applied to the wider problem of automatic RDF metadata generation.
Jena RDF Library for .NET (C#)
Last year a friend of mine was completing his BSc degree in I.T and Business. His dissertation project was an application that crawled webpages and generated RDF data via the application of XSL templates (applied to the tidied XHTML files downloaded). The project was written in C# on the .NET framework. When my friend asked me for a nice easy to use RDF framework I initially thought of my MSc disseration and it's use of the Jena framework.
Jena for .NET
A number of posts online (such as this one) showed how Jena could be used in a .NET project by using the IKVM project that includes a .NET implementation of the Java Virtual Machine (JVM). Basically this is what I did and then also wrote a very simple class that s you to easily create a Jena model in an MS SQL database (or MySQL if you prefer) and load RDF files into it and query it using SPARQL.
It is now one year on and there still doesn't seem to be any good examples of using Jena from .NET. As such I have posted my original class here as well as all required DLL libraries in the hope that they may be of benefit to others
Jena for .NET
A number of posts online (such as this one) showed how Jena could be used in a .NET project by using the IKVM project that includes a .NET implementation of the Java Virtual Machine (JVM). Basically this is what I did and then also wrote a very simple class that s you to easily create a Jena model in an MS SQL database (or MySQL if you prefer) and load RDF files into it and query it using SPARQL.
It is now one year on and there still doesn't seem to be any good examples of using Jena from .NET. As such I have posted my original class here as well as all required DLL libraries in the hope that they may be of benefit to others
Subscribe to:
Posts (Atom)
